Skip to main content

Periphery Core Contracts

Router​

The Router contract to handle swapping.

Struct: ExactInputSingleParams​

Contains data for swap exact input with a single pool.

ExactInputSingleParams
    address tokenIn;     // source token to swap
    address tokenOut;    // dest token to receive
    uint16 fee;          // fee of the pool to swap
    address recipient;   // the recipient of tokenOut
    uint256 deadline;    // deadline for the transaction
    uint256 amountIn;    // the amount of tokenIn to swap
    uint256 minAmountOut;// min acceptable amount of tokenOut
    uint160 limitSqrtP;  // the limit of sqrt price, partial swap if price reaches the limitation

Struct: ExactInputParams​

Contains data for swap exact input with one or multiple pools.

ExactInputParams
    bytes path;           // contains data to identify list of pools to use for the swap
    address recipient;    // the recipient of token out
    uint256 deadline;     // deadline for the transaction
    uint256 amountIn;     // the amount of token in to swap
    uint256 minAmountOut; // the min acceptable amount of token out

Struct: ExactOutputSingleParams​

Contains data for swap to an exact amount out of token out, using only one pool.

ExactOutputSingleParams:
    address tokenIn;    // source token to swap
    address tokenOut;   // dest token to receive
    uint16 fee;         // fee of the pool
    address recipient;  // the recipient of tokenOut
    uint256 deadline;   // deadline for the transaction
    uint256 amountOut;  // the amount of tokenOut to expect
    uint256 maxAmountIn;// the max amount of tokenIn that is allowed to use
    uint160 limitSqrtP; // the limit of sqrt price, partial swap if price reaches the limitation

Struct: ExactOutputParams​

Contains data for swap to an exact amount out of token out using one or multiple pools.

ExactOutputParams
    bytes path;
    address recipient;
    uint256 deadline;
    uint256 amountOut;
    uint256 maxAmountIn;

swapCallback()​

Params:
    int256 deltaQty0
    int256 deltaQty1
    bytes data

Callback function that is be triggerred by the pool when swapping tokens. Either deltaQty0 or deltaQty1 must be positive. Positive value means the pool (also the caller) is expecting to receive that amount of token.

swapExactInputSingle()​

Params:
    ExactInputSingleParams params
Returns:
    uint256 amountOut

Given the params of ExactInputSingleParams, it uses only one pool to swap exact an amountIn of tokenIn to tokenOut and return the amount of tokenOut from the swap. It calls the swap function in the pool contract, the pool will transfer the tokenOut to the Router, and expect to receive the corresponding tokenIn in the swap callback function.

swapExactInput()​

Params:
    ExactInputParams params
Returns:
    uint256 amountOut

Given the params of ExactInputParams, it uses only one or multiple pools that can be decoded from the path. It calls the swap function in each pool contract that is decoded from the path param, and uses callback to handle transferring tokens.

Flow:

  • Swap path: tokenIn -> token0 -> token1 -> ... -> tokenOut.
  • Call the first pool to borrow token0 to the Router, then transfer tokenIn from user's wallet to the first pool.
  • Call the second pool to borrow token1 to the Router, then transfer token0 from the Router to the second pool.
  • Repeat the action until the last pool, and transfer tokenOut directly to the recipient.

swapExactOutputSingle()​

Params:
    ExactOutputSingleParams params
Returns:
    uint256 amountIn

Given the params of ExactOutputSingleParams, it uses only one pool to swap to get exact amountOut of tokenOut (or stop if price limit reaches).

  • Call the swap function in the pool contract.
  • The pool transfers the tokenOut to the recipient, and make the swap callback.
  • The Router transfer the corresponding tokenIn from user's wallet to the pool. The required amount of tokenIn should not be greater than maxAmountIn.

swapExactOutput()​

Params:
    ExactOutputParams params
Returns:
    uint256 amountIn

Given the params of ExactOutputParams, it uses one or multiple pools that can be decoded from the path. It calls the swap function in each pool contract that is decoded from the path param, and uses callback to handle transferring tokens. The list of pools in the path params should be in the reverse order, i.e the last pool first since we don't know the exact amount of token in to be used.

Flow:

  • Origial swap path: tokenIn -> token0 -> token1 -> ... -> tokenN -> tokenOut.
  • Reverse swap path: tokenOut -> tokenN -> ... -> token1 -> token0 -> tokenIn.
  • Consider as we are swapping from amountOut of tokenOut to tokenIn.

BasePositionManager​

Inherit from an ERC721 contract, it stores all positions of all liquidity providers and mint corresponding NFT.

Users can use the PositionManager to create & unlock pool, mint new position, add/remove liquidity to/from an existing position and burn their reinvestment tokens to receive back the LP fees.

It also inherits from Multicall contract, thus, users can make multiple function/method calls to the PositionManager in a single transaction.

All reinvestment tokens will be held in the contract, thus, it blocks anyone from transferring reinvestment tokens out. As a result, the contract can not support pools with any reinvestment tokens.

Struct: MintParams​

Params for the first time adding liquidity, mint new nft to sender

MintParams
    address token0; // the token0 of the pool
    address token1; // token1 of the pool, must make sure that token0 < token1
    uint16 fee; // the pool's fee in bps
    int24 tickLower; // the position's lower tick
    int24 tickUpper; // the position's upper tick
    int24[2] ticksPrevious; // the nearest tick that has been initialized and lower than or equal to the

tickLower and tickUpper, use to help insert the tickLower and tickUpper if haven't initialized uint256 amount0Desired; // the desired amount for token0 uint256 amount1Desired; // the desired amount for token1 uint256 amount0Min; // min amount of token 0 to add uint256 amount1Min; // min amount of token 1 to add address recipient; // the owner of the position uint256 deadline; // time that the transaction will be expired

Struct: IncreaseLiquidityParams​

Params for adding liquidity to the existing position

IncreaseLiquidityParams
    uint256 tokenId // id of the position to increase its liquidity
    uint256 amount0Desired // the desired amount for token0
    uint256 amount1Desired // the desired amount for token1
    uint256 amount0Min // min amount of token 0 to add
    uint256 amount1Min // min amount of token 1 to add
    uint256 deadline // time that the transaction will be expired

Struct: RemoveLiquidityParams​

Params for remove liquidity from the existing position

RemoveLiquidityParams
    uint256 tokenId // id of the position to remove its liquidity
    uint256 amount0Min // min amount of token 0 to receive
    uint256 amount1Min // min amount of token 1 to receive
    uint256 deadline // time that the transaction will be expired

Struct: BurnRTokenParams​

Burn the rTokens to get back token0 + token1 as fees

BurnRTokenParams
    uint256 tokenId // id of the position to burn r token
    uint256 amount0Min // min amount of token 0 to receive
    uint256 amount1Min // min amount of token 1 to receive
    uint256 deadline // time that the transaction will be expired

createAndUnlockPoolIfNecessary()​

Params:
    address token0;
    address token1;
    uint16 fee;
    uint160 currentSqrtP
Returns:
    address pool // deployed pool given the set of params

Use this function to create & unlock a pool if needed given (token0, token1, fee) params and the initial sqrt price. Required: token0 < token1

mint()​

Params:
    MintParams params
Returns:
    uint256 tokenId;
    uint128 liquidity,
    uint256 amount0,
    uint256 amount1

Call the _addLiquidity function in the LiquidityHelper contract with the data from *params. It mints a new NFT token represents the position to the recipient, stores the position data and pool information.

addLiquidity()​

Params:
    IncreaseLiquidityParams params
Returns:
    uint128 liquidity,
    uint256 amount0,
    uint256 amount1,
    uint256 additionalRTokenOwed

Call the _addLiquidity function in the LiquidityHelper contract with the data from params to add more liquidity to a given position (i.e tokenId). Calculate and update the additional reinvestment tokens that the position should have earned.

removeLiquidity()​

Params:
    RemoveLiquidityParams params
Returns:
    uint256 amount0,
    uint256 amount1,
    uint256 additionalRTokenOwed

Call the burn function in the pool contract with the data from params to remove liquidity and get back 2 tokens. Calculate and update the additional reinvestment tokens that the position should have earned.

burnRTokens()​

Params:
    BurnRTokenParams params
Returns:
    uint256 rTokenQty,
    uint256 amount0,
    uint256 amount1

Call the burnRTokens function in the pool contract to burn all reinvestment tokens from the position and get back 2 tokens. Return the amount of reinvestment tokens to burn and expected amounts of 2 tokens to receive

Functions: tokenURI(), getApproved(), _approve(), _getAndIncrementNonce()​

Overriding functions for the inherited ERC721 and permit contracts.

AntiSnipAttackPositionManager​

Inherits BasePositionManager and adds the anti-snipping attack feature into addLiquidity and removeLiquidity functions.

Reinvestment tokens of a position will be locked and vested to prevent LPs from adding then removing liquidity within a small period of time.

The motivation, mechanism and formula for Anti-Snipping Attack can be found [here](https://docs.google.com/ document/d/1F50RWQRRyaNxnW5RvKgw09fN2FofIVLVccijgcOt-Iw/edit#heading=h.trv8zmis8u4c). The AntiSnippingAttack library will be of interest as well.