UniswapV3PoolUpgradeable

UniswapV3PoolUpgradeable.sol

NFTX AMM pool contract. Uses BeaconProxy for deployments.

Table of Contents

Variables

factory token0 token1 fee tickSpacing maxLiquidityPerTick slot0 feeGrowthGlobal0X128 feeGrowthGlobal1X128 protocolFees liquidity ticks tickBitmap positions observations

Events

Initialize Mint Collect Burn Swap Flash IncreaseObservationCardinalityNext SetFeeProtocol CollectProtocol

Public Write Functions

increaseObservationCardinalityNext Initialize mint collect burn swap distributeRewards swap distributeRewards

Owner Write Functions

setFeeProtocol collectProtocol

Read Functions

UniswapV3PoolUpgradeable UniswapV3PoolUpgradeable snapshotCumulativesInside observe

Variables

factory

function factory() external view returns (address)

Address of the NFTX AMM's UniswapV3FactoryUpgradeable contract.

token0

function token0() external view returns (address)

Address of "token0" (either WETH or vToken).

token1

function token1() external view returns (address)

Address of "token1" (either WETH or vToken).

fee

function fee() external view returns (uint24)

AMM swap fee tier.

tickSpacing

function tickSpacing() external view returns (int24)

Tick spacing of the pool.

maxLiquidityPerTick

function maxLiquidityPerTick() external view returns (uint128)

Maximum liquidity amount per tick.

slot0

function slot0()
    external
    view
    returns (
        uint160 sqrtPriceX96,
        int24 tick,
        uint16 observationIndex,
        uint16 observationCardinality,
        uint16 observationCardinalityNext,
        uint8 feeProtocol,
        bool unlocked
    )

Pool data.

feeGrowthGlobal0X128

function feeGrowthGlobal0X128() external view returns (uint256)

Represents the accumulated fees of token0 that have been earned per unit of liquidity since the contract was deployed, stored as a fixed-point number.

feeGrowthGlobal1X128

function feeGrowthGlobal1X128() external view returns (uint256)

Represents the accumulated fees of token1 that have been earned per unit of liquidity since the contract was deployed, stored as a fixed-point number.

protocolFees

function protocolFees() external view returns (uint128 token0, uint128 token1)

Accumulated fees owed to the protocol (for example, to the governance treasury).

liquidity

function liquidity() external view returns (uint128)

The total liquidity that's currently active in the pool.

ticks

function ticks(int24 tick)
    external
    view
    returns (
        uint128 liquidityGross,
        int128 liquidityNet,
        uint256 feeGrowthOutside0X128,
        uint256 feeGrowthOutside1X128,
        int56 tickCumulativeOutside,
        uint160 secondsPerLiquidityOutsideX128,
        uint32 secondsOutside,
        bool initialized
    )

Tick data.

tickBitmap

function tickBitmap(int16 wordPosition) external view returns (uint256)

A mapping that represents a sub-interval of ticks to help with gas-efficient calculations related to liquidity.

positions

function positions(bytes32 key)
    external
    view
    returns (
        uint128 liquidity,
        uint256 feeGrowthInside0LastX128,
        uint256 feeGrowthInside1LastX128,
        uint128 tokensOwed0,
        uint128 tokensOwed1
    )

A mapping that keeps track of individual liquidity provider positions. The key to this mapping is a bytes32 value derived from the liquidity provider's address and the tick range in which they've provided liquidity.

observations

function observations(uint256 index)
    external
    view
    returns (
        uint32 blockTimestamp,
        int56 tickCumulative,
        uint160 secondsPerLiquidityCumulativeX128,
        bool initialized
    )

An array used for calculating the time-weighted average price (TWAP).

Events

Initialize

event Initialize(uint160 sqrtPriceX96, int24 tick)

Emitted by initialize().

Parameters	Type	Description
sqrtPriceX96	uint160	Starting price.
tick	int24	Closest tick representing price.

Mint

event Mint(
    address sender,
    address indexed owner,
    int24 indexed tickLower,
    int24 indexed tickUpper,
    uint128 amount,
    uint256 amount0,
    uint256 amount1
)

Emitted by mint().

Parameters	Type	Description
sender	address	The address that called the mint function to add liquidity.
owner	address	The address that will own the liquidity position and can collect fees on it.
tickLower	int24	The lower price tick of the price range for which the liquidity is being provided.
tickUpper	int24	The upper price tick of the price range for which the liquidity is being provided.
amount	uint128	The amount of liquidity that was added.
amount0	uint256	The amount of token0 that was added as liquidity.
amount1	uint256	The amount of token1 that was added as liquidity.

Collect

event Collect(
    address indexed owner,
    address recipient,
    int24 indexed tickLower,
    int24 indexed tickUpper,
    uint128 amount0,
    uint128 amount1
)

Emitted by collect().

Parameters	Type	Description
owner	address	The address that called the mint function to add liquidity.
recipient	address	The address that will own the liquidity position and can collect fees on it.
tickLower	int24	The lower price tick of the price range for which the liquidity is being provided.
tickUpper	int24	The upper price tick of the price range for which the liquidity is being provided.
amount0	uint256	The amount of token0 that was added as liquidity.
amount1	uint256	The amount of token1 that was added as liquidity.

Burn

event Burn(
    address indexed owner,
    int24 indexed tickLower,
    int24 indexed tickUpper,
    uint128 amount,
    uint256 amount0,
    uint256 amount1
)

Emitted by burn().

Parameters	Type	Description
owner	address	The address that owned the liquidity position and called the function to remove liquidity.
tickLower	int24	The lower price tick of the price range for which the liquidity was provided.
tickUpper	int24	The lower price tick of the price range for which the liquidity was provided.
amount	uint128	The amount of liquidity that was removed.
amount0	uint256	The amount of token0 that was removed as liquidity.
amount1	uint256	The amount of token1 that was removed as liquidity.

Swap

event Swap(
    address indexed sender,
    address indexed recipient,
    int256 amount0,
    int256 amount1,
    uint160 sqrtPriceX96,
    uint128 liquidity,
    int24 tick
)

Emitted by swap().

Parameters	Type	Description
sender	address	The address that initiated the swap.
recipient	address	The address that received the output tokens from the swap.
amount0	uint256	The change in the token0 balance as a result of the swap. A negative value indicates token0 was sold, and a positive value indicates token0 was bought.
amount1	uint256	The change in the token1 balance as a result of the swap. A negative value indicates token1 was sold, and a positive value indicates token1 was bought.
sqrtPriceX96	uint160	The price of the pool after the swap has occurred. Encoded as the square root of the ratio of token amounts, and stored as a fixed-point number with 96 bits to the right of the decimal point.
liquidity	uint128	The active liquidity at the time the swap occurred.
tick	int24	Represents the tick index of the pool after the swap has occurred.

Flash

event Flash(
    address indexed sender,
    address indexed recipient,
    uint256 amount0,
    uint256 amount1,
    uint256 paid0,
    uint256 paid1
)

Emitted by flash().

Parameters	Type	Description
sender	address	The address that initiated the flash swap.
recipient	address	The address that received the tokens from the flash swap.
amount0	uint256	The amount of token0 that the recipient received in the flash swap.
amount1	uint256	The amount of token1 that the recipient received in the flash swap.
paid0	uint160	The amount of token0 that was paid back to the pool by the sender by the end of the transaction.
paid1	uint128	The amount of token1 that was paid back to the pool by the sender by the end of the transaction.

IncreaseObservationCardinalityNext

event IncreaseObservationCardinalityNext(
    uint16 observationCardinalityNextOld,
    uint16 observationCardinalityNextNew
)

Emitted by increaseObservationCardinalityNext().

Parameters	Type	Description
observationCardinalityNextOld	uint16	The previous value of the next maximum number of observations that the pool can store.
observationCardinalityNextNew	uint16	The updated value of the next maximum number of observations that the pool will store.

SetFeeProtocol

event SetFeeProtocol(
    uint8 feeProtocol0Old, 
    uint8 feeProtocol1Old, 
    uint8 feeProtocol0New, 
    uint8 feeProtocol1New
)

Emitted by setProtocolFee().

Parameters	Type	Description
feeProtocol0Old	uint8	The previous value of the fee protocol setting for token0.
feeProtocol1Old	uint8	The previous value of the fee protocol setting for token1.
feeProtocol0New	uint8	The updated value of the fee protocol setting for token0.
feeProtocol1New	uint8	The updated value of the fee protocol setting for token1.

CollectProtocol

event CollectProtocol(
    address indexed sender, 
    address indexed recipient, 
    uint128 amount0, 
    uint128 amount1
)

Emitted by collectProtocol().

Parameters	Type	Description
sender	address	The address that initiated the collection of the protocol fees.
recipient	address	The address that received the collected protocol fees.
amount0	uint256	The amount of token0 that was collected as a protocol fee.
amount1	uint256	The amount of token1 that was collected as a protocol fee.

Write Functions

increaseObservationCardinalityNext

function increaseObservationCardinalityNext(
    uint16 observationCardinalityNext
) external

Used to schedule an increase in the maximum number of observations that the pool can store. Observations are utilized in the AMM pool for computing TWAPs. By invoking this function, the caller is expressing the intent to expand the observation capacity in the future. The actual expansion of capacity takes effect the next time the pool undergoes significant interaction, like when liquidity is added or when a swap occurs that moves the price.

Parameters	Type	Description
observationCardinalityNext	uint26	Specifies the desired future maximum number of observations the pool should be able to store. It should be set to a value greater than the current observationCardinalityNext.

initialize

function initialize(uint160 sqrtPriceX96) external

Used to set the initial price of the pool when it's first created. This function can only be called once for a pool, when it's transitioning from an uninitialized to an initialized state. Typically called by the AMM pool factory contract during the creation of a new pool.

Parameters	Type	Description
sqrtPriceX96	uint160	The starting price for the pool. Represented as the square root of the ratio of token amounts, stored as a fixed-point number with 96 bits to the right of the decimal point.

mint

function mint(
    address recipient,
    int24 tickLower,
    int24 tickUpper,
    uint128 amount,
    bytes calldata data
) external returns (uint256 amount0, uint256 amount1)

Adds liquidity to a specific price range within the AMM pool.

Parameters	Type	Description
recipient	address	The address that will receive the liquidity position NFT.
tickLower	int24	The lower bound (in tick terms) of the price range for which liquidity is being provided.
tickUpper	int24	The upper bound (in tick terms) of the price range for which liquidity is being provided.
amount	uint128	The amount of liquidity being added to the pool within the specified tick range.
data	bytes	Arbitrary calldata that is forwarded to a callback function.

Return values	Type	Description
amount0	uint256	The amount of token0 that the liquidity provider added to the pool.
amount1	uint256	The amount of token1 that the liquidity provider added to the pool.

collect

function collect(
    address recipient,
    int24 tickLower,
    int24 tickUpper,
    uint128 amount0Requested,
    uint128 amount1Requested
) external returns (uint128 amount0, uint128 amount1)

Allows liquidity providers to retrieve tokens owed from one or both of the two following scenarios:

1. To remove accumulated fees from their specified liquidity range.

2. To retrieve tokens from liquidity that has previously been removed from the position.

The function can be used to collect either or both of the pool tokens, up to amounts specified by the caller.

Parameters	Type	Description
recipient	address	The address that will receive the collected tokens (either fees or tokens from removed liquidity).
tickLower	int24	The lower tick bound of the price range.
tickUpper	int24	The upper tick bound of the price range.
amount0Requested	uint128	The maximum amount of token0 that the caller wishes to collect.
amount1Requested	uint128	The maximum amount of token1 that the caller wishes to collect.

Return values	Type	Description
amount0	uint256	The amount of token0 collected.
amount1	uint256	The amount of token1 collected.

burn

function burn(
    int24 tickLower,
    int24 tickUpper,
    uint128 amount
) external returns (uint256 amount0, uint256 amount1)

Allows liquidity providers to remove, or "burn," a specified amount of liquidity from a particular price range in the pool. After burning liquidity, the underlying tokens aren't immediately returned to the caller. Instead, the tokens can be later collected using the collect function

Parameters	Type	Description
tickLower	int24	The lower tick bound of the price range of the specific liquidity position from which liquidity is being removed.
tickUpper	int24	The upper tick bound of the price range of the specific liquidity position from which liquidity is being removed.
amount	uint128	The amount of liquidity that the caller wishes to remove from the specified position within the tick range.

Return values	Type	Description
amount0	uint256	The amount of token0 that was removed and is available for collection.
amount1	uint256	The amount of token1 that was removed and is available for collection.

swap

function swap(
    address recipient,
    bool zeroForOne,
    int256 amountSpecified,
    uint160 sqrtPriceLimitX96,
    bytes calldata data
) external returns (int256 amount0, int256 amount1)

Swaps one token for another, taking slippage, price limits, and other factors into account.

Parameters	Type	Description
recipient	int24	The address that will receive the tokens resulting from the swap.
zeroForOne	int24	True to swap token0 for token1, false to swap token1 for token0.
amountSpecified	int128	The exact amount of the token being sold (if positive) or the maximum amount of token one is willing to buy (if negative).
sqrtPriceLimitX96	uint160	A price constraint for the trade. If zeroForOne is true, the trade will only execute if the pool's price doesn't go above this value (representing a price floor). If zeroForOne is false, the trade will only execute if the pool's price doesn't go below this value (representing a price ceiling). It's represented as the square root of the price ratio encoded in a 96-bit fixed-point format. If set to zero, it means no price constraint is enforced.
data	bytes	Arbitrary calldata sent along with the function call, allowing for more complex logic or interactions if required by the recipient. It can be used for custom callbacks, which the pool will call after the core swap logic runs.

Name	Type	Description
amount0	uint256	The amount of token0 that was either paid (if negative) or received (if positive).
amount1	uint256	The amount of token1 that was either paid (if negative) or received (if positive).

distributeRewards

function distributeRewards(
    uint256 rewardsAmount,
    bool isToken0
) external

Distributes the received vault fees among the current LPs, proportional to their liquidity contribution. Can only be called by feeDistributor, after it sends the reward tokens to this pool.

Parameters	Type	Description
rewardsAmount	int24	The amount of reward tokens to distribute
isToken0	int24	True if reward token is token0, false if it is token1.

flash

function flash(
    address recipient,
    uint256 amount0,
    uint256 amount1,
    bytes calldata data
) external

Executes a flash swap within the AMM pool. Allows a smart contract to borrow tokens from the pool, execute specific logic, and then either repay the borrowed amount with fees or provide equivalent value in the other token—all within a single transaction.

Parameters	Type	Description
recipient	address	The address that receives the borrowed tokens and is responsible for ensuring their return within the same transaction. This should ideally be a smart contract that implements the necessary callback logic to repay the borrowed funds.
amount0	uint256	The amount of token0 to be borrowed from the pool.
amount1	uint256	The amount of token1 to be borrowed from the pool.
data	bytes	Arbitrary calldata forwarded to the recipient's callback function. This allows the recipient smart contract to specify additional parameters or custom logic that should be executed after the tokens are borrowed and before they are returned.

Owner Functions

setFeeProtocol

function setFeeProtocol(
    uint8 feeProtocol0,
    uint8 feeProtocol1
) external

Allows the factory owner to set or update the fee protocol values for the pool. This function doesn't directly set the protocol fee rate (i.e., the fraction of LP fees that become protocol fees—which is set on the SwapRouter). Instead, it sets how these collected protocol fees are allocated. This function can be seen as a way to change the internal allocation mechanism or beneficiaries without affecting the global setting at the factory level.

Parameters	Type	Description
feeProtocol0	uint8	The fee protocol value for token0.
feeProtocol1	uint8	The fee protocol value for token1.

collectProtocol

function collectProtocol(
    address recipient,
    uint128 amount0Requested,
    uint128 amount1Requested
) external

Collects protocol fees that have accrued in the pool. Protocol fees are distinct from the fees accrued by individual liquidity providers; they're set at the protocol level and typically go to a treasury or another protocol-specific address.

Parameters	Type	Description
recipient	address	The address that will receive the collected protocol fees. This is typically a treasury or another designated address decided upon by the protocol's governance.
amount0Requested	uint128	The maximum amount of token0 fees that the caller wishes to collect from the protocol's accumulated fees.
amount1Requested	uint128	The maximum amount of token1 fees that the caller wishes to collect from the protocol's accumulated fees.

Read Functions

snapshotCumulativesInside

function snapshotCumulativesInside(
    int24 tickLower,
    int24 tickUpper
)
    external
    view
    returns (
        int56 tickCumulativeInside,
        uint160 secondsPerLiquidityInsideX128,
        uint32 secondsInside
    )

Provides a snapshot of the cumulative tick and liquidity values inside a specific tick range. It's designed to give insights and facilitate calculations related to accrued fees and other operations for positions within that range.

Parameters	Type	Description
tickLower	int24	The lower tick bound of the specific tick range for which the cumulative values are to be fetched.
tickUpper	int24	The upper tick bound of the specific tick range for which the cumulative values are to be fetched.

Return values	Type	Description
tickCumulativeInside	int56	The cumulative tick value within the specified range. This value represents the sum of all tick values each time liquidity was added or removed in the given range, up to the current moment. It's useful for calculating price changes over time.
secondsPerLiquidityInsideX128	uint160	A cumulative value representing the seconds per liquidity within the specified tick range, encoded in a 128-bit fixed-point format. It's useful for determining how long, on average, liquidity has been available in the tick range, helping in calculations related to fee accrual.
secondsInside	uint32	The total time in seconds that the pool's current tick has been within the specified tick range. This is useful for determining how long the current price has been within a certain range.

observe

function observe(
    uint32[] calldata secondsAgos
)
    external
    view
    returns (
        int56[] memory tickCumulatives,
        uint160[] memory secondsPerLiquidityCumulativeX128s
    )

Retrieves historical data on the pool's tick and liquidity based on a set of specified past timestamps. It's designed to facilitate off-chain computations, particularly for time-weighted averages and other time-dependent metrics.

Parameters	Type	Description
secondsAgos	uint32[]	An array of time durations in seconds. Each duration represents how far in the past the data should be fetched. For instance, if one of the durations is 3600, it means the function should return the cumulative values from 1 hour ago.

Return values	Type	Description
tickCumulatives	int56[]	An array of cumulative tick values corresponding to each of the durations in the secondsAgos array. Each value represents the sum of all tick values up to the respective historical point. Useful for assessing price movements over multiple historical points.
secondsPerLiquidityCumulativeX128s	uint160	An array of cumulative values representing the seconds per liquidity up to each of the durations in the secondsAgos array, encoded in a 128-bit fixed-point format. This metric provides insights into how liquidity has changed over each of the specified durations.