Comment on page
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.
Router
Factory
Last modified 6mo ago