Skip to main content

AMM

The AMM.sol contract is the main contract of the AMM. It exposes all Traders and Liquidity providers oriented methods. It also contains methods to control the pools - e.g. creating the initial liquidity pausing, unpausing the AMM, switching periods. These functions can be invoked using web3 libraries and browser wallets such as Metamask.

Information#

PairID#

The _pairID argument is used to select the pool. At V1 launch two pools are available per AMM instance, the PT/Underlying pool and the PT/FYT pool.

_pairIDPool
0PT/Underlying
1PT/FYT
nN,n>1n \in \mathbb{N}, n > 1Pairs (or Pools) that might be added in the future...

For more information on the AMM design architecture check this section.

Methods#

switchPeriod#

function switchPeriod()

This function is called to reinitialize all pools at the end of a future period. Once a future expires, new FYTs are minted for each Principal Token. Old FYTs are no longer traded as their price is fixed.

getPTWeightInPair#

function getPTWeightInPair()
returns (uint256)

Get the PT weight in the PT/Underlying pair.

withdrawExpiredToken#

function withdrawExpiredToken(address _user, uint256 _pairID)

Withdraw all redeemable expired tokens in pool _pairID of user _user.

ℹ️ Expired Tokens are iBT and Underlying assets. Liquidity Providers can claim the expired liquidity burning their LP Tokens:

  • Interest Bearing Tokens (iBT): PT and FYT liquidity is converted into iBT at the end of a period. Yield is claimed from expired FYTs and PTs are unlocked from the protocol
  • Underlying: The underlying liqudity is removed from the pool at the end of the period.

getRedeemableExpiredTokens#

function getRedeemableExpiredTokens(address _user, uint256 _pairID)
(uint256)

Get the amount of expired tokens a liquidity provider can withdraw from the pool. It checks when was the last time user _user withdrew their expired tokens from the pool with ID _pairID. It applies compounding per period to take into account the yield generated between the last period renewed and now.

ℹ️ Expired Tokens are iBT and Underlying assets. Liquidity Providers can claim the expired liquidity burning their LP Tokens:

  • Interest Bearing Tokens (iBT): PT and FYT liquidity is converted into iBT at the end of a period. Yield is claimed from expired FYTs and PTs are unlocked from the protocol
  • Underlying: The underlying liqudity is removed from the pool at the end of the period.

swapExactAmountIn#

function swapExactAmountIn(    uint256 _pairID,    uint256 _tokenIn,    uint256 _tokenAmountIn,    uint256 _tokenOut,    uint256 _minAmountOut)
returns (uint256 tokenAmountOut, uint256 spotPriceAfter)

Swap _tokenAmountIn of _tokenIn for at least _minAmountOut of _tokenOut in the pool with _pairID. Returns the tokenAmountOut the user will get and the resulting spotPriceAfter after the trade.

calcOutAndSpotGivenIn#

function calcOutAndSpotGivenIn(    uint256 _pairID,    uint256 _tokenIn,    uint256 _tokenAmountIn,    uint256 _tokenOut,    uint256 _minAmountOut)
returns (uint256 tokenAmountOut, uint256 spotPriceAfter)

Get the amount of _tokenOut and the spotPriceAfter resulting in trading exactly _tokenAmountIn of _tokenIn for at least _minAmountOut of _tokenOut in the pool with _pairID.

swapExactAmountOut#

function swapExactAmountOut(    uint256 _pairID,    uint256 _tokenIn,    uint256 _maxAmountIn,    uint256 _tokenOut,    uint256 _tokenAmountOut,)
returns (uint256 tokenAmountIn, uint256 spotPriceAfter)

Swap at most _maxAmountIn of _tokenIn for exactly _tokenAmountOut of _tokenOut in the pool with _pairID. Returns the tokenAmountIn the user needed to perform the trade and the resulting spotPriceAfter after the trade.

calcInAndSpotGivenOut#

function calcInAndSpotGivenOut(    uint256 _pairID,    uint256 _tokenIn,    uint256 _maxAmountIn,    uint256 _tokenOut,    uint256 _tokenAmountOut,)
returns (uint256 tokenAmountIn, uint256 spotPriceAfter)

Get the amount tokenAmountIn and the spotPriceAfter resulting in trading at most _maxAmountIn of _tokenIn for exactly _tokenAmountOut of _tokenOut in the pool with _pairID.

joinSwapExternAmountIn#

function joinSwapExternAmountIn(    uint256 _pairID,    uint256 _tokenIn,    uint256 _tokenAmountIn,    uint256 _minPoolAmountOut)
returns (uint256 poolAmountOut)

Pay _tokenAmountIn of token _tokenIn to join the pool _pairID, getting poolAmountOut of the pool shares.

The transaction completes only if poolAmountOut \geq _minPoolAmountOut

joinSwapPoolAmountOut#

function joinSwapPoolAmountOut(    uint256 _pairID,    uint256 _tokenIn,    uint256 _poolAmountOut,    uint256 _maxAmountIn)
returns (uint256 tokenAmountIn)

Specify the amount _poolAmountOut of pool shares that you want to get by providing at most _maxAmountIn of _tokenIn liquidity in the pool _pairID. Returns the amount tokenAmountIn of tokens needed to get the shares.

exitSwapPoolAmountIn#

function exitSwapPoolAmountIn(    uint256 _pairID,    uint256 _tokenOut,    uint256 _poolAmountIn,    uint256 _minAmountOut)
returns (uint256 tokenAmountOut)

Pay _poolAmountIn pool shares into the pool, getting at least _minAmountOut tokenAmountOut of the given token _tokenOut out of the pool _pairID.

exitSwapExternAmountOut#

function exitSwapExternAmountOut(    uint256 _pairID,    uint256 _tokenOut,    uint256 _tokenAmountOut,    uint256 _maxPoolAmountIn)
returns (uint256 poolAmountIn)

Specify the amount _tokenAmountOut of token _tokenOut that you want to get out of the pool pairID by providing at most _maxPoolAmountIn of LPTokens liquidity from the pool _pairID. Returns the amount poolAmountIn of LP tokens needed to get the shares.

createLiquidity#

function createLiquidity(uint256 _pairID, uint256[2] memory _tokenAmounts)

This function is called to initiate the liquidity at the beginning of a period. The first liquidity provider specify the pool with the _pairID and the _tokenAmounts of tokens to provide.

_tokenAmounts is an array containing the amount of each tokens of the pair. (Element 0 being the amount of Principal tokens and 1 the amount of either underlying or Future Yield Tokens depending on the pair)

At the beginning of each period both pool start with 50/50 weights (see this section for more informations about the AMM architecture). Therefore the spotPrice of each asset for the other can be computed as PAB=AmountAAmountBP_{AB} = \frac{Amount_A}{Amount_B}

addLiquidity#

function addLiquidity(    uint256 _pairID,    uint256 _poolAmountOut,    uint256[2] memory _maxAmountsIn)

Join the pool _pairID, getting _poolAmountOut pool tokens. This will pull some of each of the currently trading tokens in the pool, meaning you must have called approve for each token for this pool. These values are limited by the array of _maxAmountsIn in the order of the pool tokens.

removeLiquidity#

function removeLiquidity(    uint256 _pairID,    uint256 _poolAmountIn,    uint256[2] memory _minAmountsOut)

Exit the pool _pairID, paying _poolAmountIn pool tokens and getting some of each of the currently trading tokens in return. These values are limited by the array of _minAmountsOut in the order of the pool tokens.

getSpotPrice#

function getSpotPrice(    uint256 _pairID,    uint256 _tokenIn,    uint256 _tokenOut)
returns (uint256)

Get the spot price of asset _tokenIn for _tokenOut based on the liquidity of pool _pairID.

getSwappingFees#

function getSwappingFees()
returns (uint256)

Returns the swapping fees currently set up in this AMM instance.

getAMMState#

function getAMMState()
returns (AMMGlobalState)

Returns the state of the AMM.

AMM can be:

  • Created: When it has been initialized
  • Activated: When it has been finalized
  • Paused: When it has been paused (for emergency situations or when there is a period switch)

getFutureAddress#

function getFutureAddress()
returns (address)

Returns the Future Vault address corresponding to the future of this AMM instance.

getAPWIBTAddress#

function getAPWIBTAddress()
returns (address)

Returns the address of the Principal Token corresponding to the future of this AMM instance.

getUnderlyingOfIBTAddress#

function getUnderlyingOfIBTAddress()
returns (address)

Returns the address of the underlying asset of the iBT deposited in the future corresponding to this AMM instance.

getIBTAddress#

function getIBTAddress()
returns (address)

Returns the address of the iBT deposited in the future corresponding to this AMM instance.

getFYTAddress#

function getFYTAddress()
returns (address)

Returns the address of the Future Yield Token corresponding to the ongoing period of the future of this AMM instance.

getPoolTokenAddress#

function getPoolTokenAddress()
returns (address)

Returns the address of the LPToken contract.

getPairWithID#

function getPairWithID(uint256 _pairID)
returns (Pair memory)

Returns the Pair corresponding to the _pairID. The Pair contains the tokenAddress of the second token of the pair (the first one is always the Principal Token), the weights, the balances and a boolean flag indicating if the liquidity for this pair has been initialized.

    struct Pair {    address tokenAddress; // first is always PT    uint256[2] weights;    uint256[2] balances;    bool liquidityIsInitialized;}

getPairIDForToken#

function getPairIDForToken(address _tokenAddress)
returns (uint256)

Returns the _pairID corresponding to the token with _tokenAddress. 0 for underlying, 1 for FYT.

getLPTokenId#

function getLPTokenId(    uint256 _ammId,    uint256 _periodIndex,    uint256 _pairID)returns returns (uint256)

Construct the LPToken ID based on the _ammId, _periodIndex and _pairID.