PoolBase

Git Source Inherits: IPool, CalculatorBase, Ownable, Pausable, Constants, CumulativePrice Author: @oscarsernarosero @mpetersoCode55 @cirsteve This contract implements the core of the Pool interface and is meant to be an abstract base for all the pools. Any pool implementation must inherits this contract and implement all the functions from CalculatorBase.

State Variables

xToken

address public immutable xToken;

yToken

address public immutable yToken;

liquidityRemovalAllowed

bool public immutable liquidityRemovalAllowed;

yDecimalDiff

difference in decimal precision between y token and x token

uint256 public immutable yDecimalDiff;

xMin

the lower bound of x

uint256 public xMin;

x

balance of x token that has been swapped out of the Pool

uint256 public x;

R

lifetime revenue collected by the pool

uint256 public R = 0;

lpFee

fee percentage for swaps for the LP

uint16 public lpFee;

protocolFee

fee percentage for swaps for the protocol

uint16 public protocolFee;

protocolFeeCollector

protocol-fee collector address

address public protocolFeeCollector;

proposedProtocolFeeCollector

proposed protocol-fee collector address

address public proposedProtocolFeeCollector;

collectedLPFees

currently claimable fee balance

uint256 public collectedLPFees;

collectedProtocolFees

currently claimable protocol fee balance

uint256 public collectedProtocolFees;

Functions

ifLiquidityRemovalAllowed

modifier ifLiquidityRemovalAllowed();

onlyProtocolFeeCollector

modifier onlyProtocolFeeCollector();

onlyProposedProtocolFeeCollector

modifier onlyProposedProtocolFeeCollector();

constructor

constructor

constructor(address _xToken, address _yToken, FeeInfo memory fees, bool _liquidityRemovalAllowed, address sender)
    Ownable(_msgSender());

Parameters

Name	Type	Description
`_xToken`	`address`	address of the X token (x axis)
`_yToken`	`address`	address of the Y token (y axis)
`fees`	`FeeInfo`	fee information
`_liquidityRemovalAllowed`	`bool`	if true, liquidity can be removed at any time. Removal of liquidity forbidden otherwise.
`sender`	`address`	address of the to-be owner

swap

implementation contract must emit a PoolDeployed event This is the main function of the pool to swap.

function swap(address _tokenIn, uint256 _amountIn, uint256 _minOut)
    external
    whenNotPaused
    returns (uint256 amountOut, uint256 lpFeeAmount, uint256 protocolFeeAmount);

Parameters

Name	Type	Description
`_tokenIn`	`address`	the address of the token being given to the pool in exchange for another token
`_amountIn`	`uint256`	the amount of the ERC20 _tokenIn to exchange into the Pool
`_minOut`	`uint256`	the amount of the other token in the pair minimum to be received for the _amountIn of _tokenIn.

Returns

Name	Type	Description
`amountOut`	`uint256`	the actual amount of the token coming out of the Pool as result of the swap
`lpFeeAmount`	`uint256`	the amount of the Y token that’s being dedicated to fees for the LP
`protocolFeeAmount`	`uint256`	the amount of the Y token that’s being dedicated to fees for the protocol

simSwap

This is a simulation of the swap function. Useful to get marginal prices

function simSwap(address _tokenIn, uint256 _amountIn)
    public
    view
    returns (uint256 amountOut, uint256 lpFeeAmount, uint256 protocolFeeAmount);

Parameters

Name	Type	Description
`_tokenIn`	`address`	the address of the token being sold
`_amountIn`	`uint256`	the amount of the ERC20 _tokenIn to sell to the Pool

Returns

Name	Type	Description
`amountOut`	`uint256`	the amount of the token coming out of the Pool as result of the swap (main returned value)
`lpFeeAmount`	`uint256`	the amount of the Y token that’s being dedicated to fees for the LP
`protocolFeeAmount`	`uint256`	the amount of the Y token that’s being dedicated to fees for the protocol

simSwapReversed

lpFeeAmount and protocolFeeAmount are already factored in the amountIn. This is useful only to know how much of the amountIn will go towards fees. This is a simulation of the swap function from the perspective of purchasing a specific amount. Useful to get marginal price.

function simSwapReversed(address _tokenout, uint256 _amountOut)
    public
    view
    returns (uint256 amountIn, uint256 lpFeeAmount, uint256 protocolFeeAmount);

Parameters

Name	Type	Description
`_tokenout`	`address`	the address of the token being bought
`_amountOut`	`uint256`	the amount of the ERC20 _tokenOut to buy from the Pool

Returns

Name	Type	Description
`amountIn`	`uint256`	the amount necessary of the token coming into the Pool for the desired amountOut of the swap (main returned value)
`lpFeeAmount`	`uint256`	the amount of the Y token that’s being dedicated to fees for the LP
`protocolFeeAmount`	`uint256`	the amount of the Y token that’s being dedicated to fees for the protocol

enableSwaps

This is the function to activate/deactivate trading.

function enableSwaps(bool _enable) external virtual onlyOwner;

Parameters

Name	Type	Description
`_enable`	`bool`	pass True to enable or False to disable

setLPFee

This is the function to update the LP fees per trading.

function setLPFee(uint16 _fee) public onlyOwner;

Parameters

Name	Type	Description
`_fee`	`uint16`	percentage of the transaction that will get collected as fees (in percentage basis points: 1500 -> 15.00%; 500 -> 5.00%; 1 -> 0.01%)

setProtocolFee

This is the function to update the protocol fees per trading.

function setProtocolFee(uint16 _protocolFee) public onlyProtocolFeeCollector;

Parameters

Name	Type	Description
`_protocolFee`	`uint16`	percentage of the transaction that will get collected as fees (in percentage basis points: 10000 -> 100.00%; 500 -> 5.00%; 1 -> 0.01%)

addXSupply

This is the function to add XToken liquidity to the pool.

function addXSupply(uint256 _amount) external virtual onlyOwner;

Parameters

Name	Type	Description
`_amount`	`uint256`	the amount of X token to transfer from the sender to the pool

closePool

This function can be called only if the flag liquidityRemovalAllowed was set to true at construction time. This function closes the pool by removing all liquidity from it.

function closePool() external virtual onlyOwner ifLiquidityRemovalAllowed;

collectLPFees

yBalance will include LPFees, Q and yLiquidity This function collects the LP fees from the Pool.

function collectLPFees() external onlyOwner;

collectProtocolFees

This function collects the protocol fees from the Pool.

function collectProtocolFees() external onlyProtocolFeeCollector;

proposeProtocolFeeCollector

that only the current fee collector address can call this function function to propose a new protocol fee collector

function proposeProtocolFeeCollector(address _protocolFeeCollector) external onlyProtocolFeeCollector;

Parameters

Name	Type	Description
`_protocolFeeCollector`	`address`	the new fee collector

confirmProtocolFeeCollector

that only the already proposed fee collector can call this function function to confirm a new protocol fee collector

function confirmProtocolFeeCollector() external onlyProposedProtocolFeeCollector;

xTokenLiquidity

This function gets the liquidity in the pool for xToken in WAD.

function xTokenLiquidity() external view returns (uint256);

Returns

Name	Type	Description
`<none>`	`uint256`	the liquidity in the pool for xToken in WAD

yTokenLiquidity

This function gets the liquidity in the pool for yToken in WAD

function yTokenLiquidity() external view virtual returns (uint256);

Returns

Name	Type	Description
`<none>`	`uint256`	the liquidity in the pool for yToken in WAD

spotPrice

This is the function to retrieve the current spot price of the x token.

function spotPrice() public view returns (uint256 sPrice);

Returns

Name	Type	Description
`sPrice`	`uint256`	the price in YToken Decimals

_validateInput

A helper function to validate most of constructor’s inputs.

function _validateInput(address _xToken, address _yToken, address _protocolFeeCollector) internal view;

Parameters

Name	Type	Description
`_xToken`	`address`	address of the X token (x axis)
`_yToken`	`address`	address of the Y token (y axis)
`_protocolFeeCollector`	`address`

_normalizeTokenDecimals

This function normalizes an input amount to or from native decimal value.

function _normalizeTokenDecimals(bool isInput, uint256 rawAmount) internal view returns (uint256 normalizedAmount);

Parameters

Name	Type	Description
`isInput`	`bool`	if true, it assumes that the tokens are being received into the pool and therefore it multiplies/adds the zeros necessary to make it a native-decimal value. It divides otherwise.
`rawAmount`	`uint256`	amount to normalize

Returns

Name	Type	Description
`normalizedAmount`	`uint256`	the normalized value

_determineFeeAmountSell

This function determines the amount of fees when doing a simSwap (Sell simulation).

function _determineFeeAmountSell(uint256 amountOfY, uint16 _fee) private pure returns (uint256 feeAmount);

Parameters

Name	Type	Description
`amountOfY`	`uint256`	the amount to calculate the fees from
`_fee`	`uint16`

Returns

Name	Type	Description
`feeAmount`	`uint256`	the amount of fees

_determineFeeAmountBuy

_This function determines the adjusted amount of y tokens needed accounting for fees when doing a simSwapReverse (buy simulation). Equation: yAmount - yAmount _ fee = realYAmount, in other words: yAmount _ (1 - fee) = realYAmount Thefore, adjustedYAmount = yAmount / (1 - fee), and yAmount _ fee = adjustedYAmount - yAmount, which gives us yAmount _ fee = yAmount / (1 - fee) - yAmount = (yAmount _ fee) / (1 - fee)*

function _determineFeeAmountBuy(uint256 originalAmountOfY, uint16 _fee) private pure returns (uint256 yFees);

Parameters

Name	Type	Description
`originalAmountOfY`	`uint256`	the amount to adjust with fees
`_fee`	`uint16`

Returns

Name	Type	Description
`yFees`	`uint256`	the amount necessary to add to yAmount to get the expected yAmount after fees

_determineProtocolAndLPFeesBuy

this functions returns the value of both protocol and LP fees that need to be added to the original amount of yTokens in order for it to have the desired effect in simSwapReversed (buy simulation).

function _determineProtocolAndLPFeesBuy(uint256 originalAmountOfY)
    internal
    view
    returns (uint256 amountProtocolFee, uint256 amountLPFee);

Parameters

Name	Type	Description
`originalAmountOfY`	`uint256`	the net amount of yTokens expressed in its native decimals that are desired to be used in a buy operation.

Returns

Name	Type	Description
`amountProtocolFee`	`uint256`	the amount of yTokens that will be destined towards protocol fees expressed in WADs of yTokens. This value should be added to originalAmountOfY for it to have the desired effect.
`amountLPFee`	`uint256`	the amount of yTokens that will be destined towards LP fees expressed in WADs of yTokens. This value should be added to originalAmountOfY for it to have the desired effect.

_checkSlippage

This function checks to verify the amount out will be greater than or equal to the minimum expected amount out.

function _checkSlippage(uint256 _amountOut, uint256 _minOut) internal pure;

Parameters

Name	Type	Description
`_amountOut`	`uint256`	the actual amount being provided out by the swap
`_minOut`	`uint256`	the expected amount out to compare against

_getRevenueAvailable

This function calculates current revenue available to be pulled by the owner of the pool.

function _getRevenueAvailable() internal view returns (uint256 Rmax);

Returns

Name	Type	Description
`Rmax`	`uint256`	the amount of revenue available to be pulled in native yToken decimals

Reference

​PoolBase

​State Variables

​xToken

​yToken

​liquidityRemovalAllowed

​yDecimalDiff

​xMin

​x

​R

​lpFee

​protocolFee

​protocolFeeCollector

​proposedProtocolFeeCollector

​collectedLPFees

​collectedProtocolFees

​Functions

​ifLiquidityRemovalAllowed

​onlyProtocolFeeCollector

​onlyProposedProtocolFeeCollector

​constructor

​swap

​simSwap

​simSwapReversed

​enableSwaps

​setLPFee

​setProtocolFee

​addXSupply

​closePool

​collectLPFees

​collectProtocolFees

​proposeProtocolFeeCollector

​confirmProtocolFeeCollector

​xTokenLiquidity

​yTokenLiquidity

​spotPrice

​_validateInput

​_normalizeTokenDecimals

​_determineFeeAmountSell

​_determineFeeAmountBuy

​_determineProtocolAndLPFeesBuy

​_checkSlippage

​_getRevenueAvailable

PoolBase

State Variables

xToken

yToken

liquidityRemovalAllowed

yDecimalDiff

xMin

x

R

lpFee

protocolFee

protocolFeeCollector

proposedProtocolFeeCollector

collectedLPFees

collectedProtocolFees

Functions

ifLiquidityRemovalAllowed

onlyProtocolFeeCollector

onlyProposedProtocolFeeCollector

constructor

swap

simSwap

simSwapReversed

enableSwaps

setLPFee

setProtocolFee

addXSupply

closePool

collectLPFees

collectProtocolFees

proposeProtocolFeeCollector

confirmProtocolFeeCollector

xTokenLiquidity

yTokenLiquidity

spotPrice

_validateInput

_normalizeTokenDecimals

_determineFeeAmountSell

_determineFeeAmountBuy

_determineProtocolAndLPFeesBuy

_checkSlippage

_getRevenueAvailable