Pool

This documentation provides an overview of the IPool.sol. This contract defines the functions and events for interacting with a liquidity pool in Maverick AMM.

Table of Contents

• Contract Details

• Events

  • Swap

  • AddLiquidity

  • MigrateBinsUpStack

  • TransferLiquidity

  • RemoveLiquidity

  • BinMerged

  • BinMoved

  • ProtocolFeeCollected

  • SetProtocolFeeRatio

• Structs

  • BinDelta

  • TwaState

  • BinState

  • AddLiquidityParams

  • RemoveLiquidityParams

  • State

• Functions

  • fee()

  • tickSpacing()

  • tokenA()

  • tokenB()

  • factory()

  • binMap()

  • binPositions()

  • binBalanceA()

  • binBalanceB()

  • getTwa()

  • getCurrentTwa()

  • getState()

  • addLiquidity()

  • transferLiquidity()

  • removeLiquidity()

  • migrateBinUpStack()

  • swap()

  • getBin()

  • balanceOf()

  • tokenAScale()

  • tokenBScale()

Contract Details

• Name : IPool

• Solidity Version : ^0.8.0

• SPDX License-Identifier : GPL-2.0-or-later

• Code: Github

Events

Swap

event Swap(address sender, address recipient, bool tokenAIn, bool exactOutput, uint256 amountIn, uint256 amountOut, int32 activeTick);

• sender : The address that executed this swap

• recipient : The address receiving this swap

• tokenAIn : A boolean to determine if there is any input for Token A

• exactOutput : A boolean to determine if there is any exact amount of tokens expected to receive

• amountIn : The uint256 amount of the input token

• amountOut : The uint256 amount of the output token

• activeTick : The active tick int32 value for the pool

AddLiquidity

event AddLiquidity(address indexed sender, uint256 indexed tokenId, BinDelta[] binDeltas);

• sender : The indexed sender address that executed addLiquidity()

• tokenId : The uint256 indexed ID of the receiving token

• binDeltas : An array of BinDelta structures

MigrateBinsUpStack

event MigrateBinsUpStack(address indexed sender, uint128 binId, uint32 maxRecursion);

• sender : The indexed sender address that executed MigrateBinsUpStack()

• binId : The uint128 bin ID that was migrated

• maxRecursion : Maximum recursion depth in uint32

TransferLiquidity

event TransferLiquidity(uint256 fromTokenId, uint256 toTokenId, RemoveLiquidityParams[] params);

• fromTokenId : Transfer liquidity from token ID uint256

• toTokenId : Transfer liquidity to token ID uint256

• params : Array of RemoveLiquidityParams that specify the bins and amounts

RemoveLiquidity

event RemoveLiquidity(address indexed sender, address indexed recipient, uint256 indexed tokenId, BinDelta[] binDeltas);

• sender : Remove liquidity from sender address

• recipient : Remove liquidity to receiver address

• tokenId : Current indexed uint256 tokenId to remove liquidity from

• binDeltas : Array of BinDelta that specify the bins and amounts

BinMerged

event BinMerged(uint128 indexed binId, uint128 reserveA, uint128 reserveB, uint128 mergeId);

• binId : The indexed bin ID uint128 that was merged.

• reserveA : amount of A token uint128 in bin.

• reserveB : amount of B token uint128 in bin.

• mergeId : The current active bin uint128.

BinMoved

event BinMoved(uint128 indexed binId, int128 previousTick, int128 newTick);

• binId : The indexed bin ID uint128 that was moved.

• previousTick : Previous tick value in int128.

• newTick : New tick value in uint128.

ProtocolFeeCollected

event ProtocolFeeCollected(uint256 protocolFee, bool isTokenA);

• protocolFee : Amount of Protocol fee collected in uint256.

• isTokenA : boolean check if Token A was used for Protocol fee.

SetProtocolFeeRatio

event SetProtocolFeeRatio(uint256 protocolFee);

• protocolFee : The new amount of Protocol fee set in uint256.

Structs

BinDelta

Return parameters for Add/Remove liquidity.

struct BinDelta {
        uint128 deltaA;
        uint128 deltaB;
        uint256 deltaLpBalance;
        uint128 binId;
        uint8 kind;
        int32 lowerTick;
        bool isActive;
    }

• deltaA : The amount of A token uint128 that has been added or removed

• deltaB : The amount of B token uint128 that has been added or removed

• deltaLpBalance : The amount of LP balance uint256 that has increase (add) or decreased (remove)

• binId : The bin ID uint128 of the bin that changed

• kind : One of the 4 Kinds (0=static, 1=right, 2=left, 3=both) in uint8

• lowerTick : The lower price tick int32 of the bin in its current state

• isActive : A boolean to indicate whether the bin is still active

TwaState

Time weighted average state.

    struct TwaState {
        int96 twa;
        int96 value;
        uint64 lastTimestamp;
    }

• twa : The twa int96 at the last update instant

• value : The new value int96 that was passed in at the last update

• lastTimestamp : The timestamp uint64 of the last update in seconds

BinState

The bin state parameters.

    struct BinState {
        uint128 reserveA;
        uint128 reserveB;
        uint128 mergeBinBalance;
        uint128 mergeId;
        uint128 totalSupply;
        uint8 kind;
        int32 lowerTick;
    }

• reserveA : The amount of A token uint128 in bin

• reserveB : The amount of B token uint128 in bin

• mergeBinBalance : The LP token balance uint128 that this bin possesses after merge

• mergeId : The binId that this bin uint128 has merged in to

• totalSupply : The total amount of LP tokens uint128 in this bin

• kind : one of the 4 Kinds (0=static, 1=right, 2=left, 3=both) in uint8

• lowerTick : The lower price tick int32 of the bin in its current state

AddLiquidityParams

Parameters for each bin that will get new liquidity.

    struct AddLiquidityParams {
        uint8 kind;
        int32 pos;
        bool isDelta;
        uint128 deltaA;
        uint128 deltaB;
    }

• kind : one of the 4 Kinds (0=static, 1=right, 2=left, 3=both) in uint8

• pos : The bin position in int32

• isDelta : A boolean that indicates whether the bin position is relative to the current bin or an absolute position

• deltaA : The amount of A token uint128 to add

• deltaB : The amount of B token uint128 to add

RemoveLiquidityParams

Parameters for each bin that will have liquidity removed.

    struct RemoveLiquidityParams {
        uint128 binId;
        uint128 amount;
    }

• binId : The index of the bin uint128 losing liquidity

• amount : The LP balance amount uint128 to remove

State

The state of the pool.

    struct State {
        int32 activeTick;
        uint8 status;
        uint128 binCounter;
        uint64 protocolFeeRatio;
    }

• activeTick : The current bin position int32 that contains the active bins

• status : The status values uint8 defined in Pool.sol e.g. locked or unlocked;

• binCounter : The index uint128 of the last bin created

• protocolFeeRatio : The ratio of the swap fee that is kept for the protocol in uint64

Functions

fee()

Retrieves the fee for the pool in 18 decimal format.

function fee() external view returns (uint256);

• Returns :

  • The fee uint256 for the pool as a uint256 value

tickSpacing()

Retrieves the tick spacing of the pool. The tick spacing is used to calculate the bin width.

function tickSpacing() external view returns (uint256);

• Returns :

  • The tick spacing as a uint256 value

tokenA()

Retrieves the address of token A associated with the pool.

function tokenA() external view returns (IERC20);

• Returns :

  • The address of token A as an IERC20 interface

tokenB()

Retrieves the address of token B associated with the pool.

function tokenB() external view returns (IERC20);

• Returns :

  • The address of token B as an IERC20 interface

factory()

Retrieves the address of the factory contract associated with the pool.

function factory() external view returns (IFactory);

• Returns :

  • The address of the factory contract as an IFactory interface

binMap()

Retrieves the bitmap of active bins at the given tick.

function binMap(int32 tick) external view returns (uint256);

• Parameters :

  • tick : The tick int32 for which to retrieve the active bin map

• Returns :

  • The bitmap of active bins as a uint256 value

binPositions()

Retrieves the bin ID for the given tick and bin kind

function binPositions(int32 tick, uint256 kind) external view returns (uint128);

• Parameters:

  • tick: The tick int32 for which to retrieve the bin ID

  • kind: The kind uint256 of the bin (0=static, 1=right, 2=left, 3=both)

• Returns:

  • The bin ID as a uint128 value

binBalanceA()

Retrieves the internal accounting of the sum of token A balances across bins.

function binBalanceA() external view returns (uint128);

• Returns: The sum of token A balances as a uint128 value

binBalanceB()

Retrieves the internal accounting of the sum of token B balances across bins.

function binBalanceB() external view returns (uint128);

• Returns:

  • The sum of token B balances as a uint128 value

getTwa()

Retrieves the time-weighted average (TWA) state values.

function getTwa() external view returns (TwaState memory);

• Returns:

  • A TwaState structure containing the TWA, value, last timestamp, and look back

getCurrentTwa()

Retrieves the log base binWidth of the time-weighted average price.

function getCurrentTwa() external view returns (int256);

• Returns:

  • The log base binWidth of the TWA as an int256 value.

getState()

Retrieves the state of the pool.

function getState() external view returns (State memory);

• Returns:

  • A State structure containing the active tick, status, bin counter, and protocol fee ratio

addLiquidity()

Adds liquidity to a pool.

function addLiquidity(uint256 tokenId, AddLiquidityParams[] calldata params, bytes calldata data)
    external
    returns (uint256 tokenAAmount, uint256 tokenBAmount, BinDelta[] memory binDeltas);

• Parameters:

  • tokenId: The NFT token ID uint256 that will hold the position.

  • params: An array of AddLiquidityParams structures that specify the mode, position, and liquidity details.

  • data: A callback function that addLiquidity will call to transfer tokens.

• Returns:

  • tokenAAmount: The amount of token A added as a uint256 value.

  • tokenBAmount: The amount of token B added as a uint256 value.

  • binDeltas: An array of BinDelta structures representing the changes in bin states.

transferLiquidity()

Transfers liquidity from one NFT token ID to another using an array of bins.

function transferLiquidity(uint256 fromTokenId, uint256 toTokenId, RemoveLiquidityParams[] calldata params) external;

• Parameters:

  • fromTokenId: The NFT token ID uint256 that holds the position being transferred.

  • toTokenId: The NFT token ID uint256 that is receiving the liquidity.

  • params: An array of RemoveLiquidityParams structures specifying the bins and amounts to transfer.

removeLiquidity()

Removes liquidity from a pool.

function removeLiquidity(address recipient, uint256 tokenId, RemoveLiquidityParams[] calldata params)
    external
    returns (uint256 tokenAOut, uint256 tokenBOut, BinDelta[] memory binDeltas);

• Parameters:

  • recipient: The address that will receive the removed tokens.

  • tokenId: The NFT token ID uint256 that holds the position being removed.

  • params: An array of RemoveLiquidityParams structures specifying the bins and amounts to remove.

• Returns:

  • tokenAOut: The amount of token A uin256 received as a result of removing liquidity.

  • tokenBOut: The amount of token B uin256 received as a result of removing liquidity.

  • binDeltas: An array of BinDelta structures representing the changes in bin states.

migrateBinUpStack()

Migrates bins up the linked list of merged bins so that its mergeId is the current active bin.

function migrateBinUpStack(uint128 binId, uint32 maxRecursion) external;

• Parameters:

  • binId: An array of the bin IDs uint128 to be migrated.

  • maxRecursion: The maximum recursion depth uint32 of the migration. Set to zero to recurse until the active bin is found.

swap()

Swaps tokens.

function swap(
    address recipient,
    uint256 amount,
    bool tokenAIn,
    bool exactOutput,
    uint256 sqrtPriceLimit,
    bytes calldata data
) external returns (uint256 amountIn, uint256 amountOut);

• Parameters:

  • recipient: The address that will receive the output tokens.

  • amount: The amount of tokens uint256 to swap.

  • tokenAIn: A boolean indicating whether token A is the input.

  • exactOutput: A boolean indicating whether the amount specified is the exact output amount (true).

  • sqrtPriceLimit: The limiting square root price uint256 of the swap. A value of 0 indicates no limit. The limit is only engaged for exactOutput=false. If the limit is reached, only part of the input amount will be swapped, and the callback will only require that amount of the swap to be paid.

  • data: A callback function bytes that swap will call to transfer tokens.

• Returns:

  • amountIn: The amount of tokens uint256 swapped as input.

  • amountOut: The amount of tokens uint256 received as output.

getBin()

Retrieves the bin information for a given bin ID.

function getBin(uint128 binId) external view returns (BinState memory bin);

• Parameters:

  • binId: The index of the bin uint128.

• Returns:

  • A BinState structure containing the details of the bin.

balanceOf()

Retrieves the LP token balance for a given tokenId at a specific binId.

function balanceOf(uint256 tokenId, uint128 binId) external view returns (uint256 lpToken);

• Parameters:

  • tokenId: The NFT token ID uint256.

  • binId: The index of the bin uint128.

• Returns:

  • The LP token balance as a uint256 value.

tokenAScale()

Retrieves the tokenA scale value.

function tokenAScale() external view returns (uint256);

msb is a flag to indicate whether tokenA has more or less than 18 decimals. Scale is used in conjuction with Math.toScale/Math.fromScale functions to convert from token amounts to D18 scale internal pool accounting.

• Returns:

  • The tokenA scale value as a uint256.

tokenBScale()

Retrieves the tokenB scale value.

function tokenBScale() external view returns (uint256);

msb is a flag to indicate whether tokenA has more or less than 18 decimals. Scale is used in conjuction with Math.toScale/Math.fromScale functions to convert from token amounts to D18 scale internal pool accounting.

• Returns:

  • The tokenB scale value as a uint256.