# UniswapV3PoolUpgradeable
NFTX AMM pool contract. Uses BeaconProxy for deployments.
## Table of Contents
Variables
[#factory](#factory "mention")\
[#token0](#token0 "mention")\
[#token1](#token1 "mention")\
[#fee](#fee "mention")\
[#tickspacing](#tickspacing "mention")\
[#maxliquiditypertick](#maxliquiditypertick "mention")\
[#slot0](#slot0 "mention")\
[#feegrowthglobal0x128](#feegrowthglobal0x128 "mention")\
[#feegrowthglobal1x128](#feegrowthglobal1x128 "mention")\
[#protocolfees](#protocolfees "mention")\
[#liquidity](#liquidity "mention")\
[#ticks](#ticks "mention")\
[#tickbitmap](#tickbitmap "mention")\
[#positions](#positions "mention")\
[#observations](#observations "mention")
Events
[#initialize](#initialize "mention")\
[#mint](#mint "mention")\
[#collect](#collect "mention")\
[#burn](#burn "mention")\
[#swap](#swap "mention")\
[#flash](#flash "mention")\
[#increaseobservationcardinalitynext](#increaseobservationcardinalitynext "mention")\
[#setfeeprotocol](#setfeeprotocol "mention")\
[#collectprotocol](#collectprotocol "mention")
Public Write Functions
[#increaseobservationcardinalitynext-1](#increaseobservationcardinalitynext-1 "mention")\
[#initialize](#initialize "mention")\
[#mint-1](#mint-1 "mention")\
[#collect-1](#collect-1 "mention")\
[#burn-1](#burn-1 "mention")\
[#swap-1](#swap-1 "mention")\
[#distributerewards](#distributerewards "mention")\
[#swap-1](#swap-1 "mention")\
[#distributerewards](#distributerewards "mention")
Owner Write Functions
[#setfeeprotocol-1](#setfeeprotocol-1 "mention")\
[#collectprotocol-1](#collectprotocol-1 "mention")
Read Functions
[#balance0](#balance0 "mention")\
[#balance1](#balance1 "mention")\
[#snapshotcumulativesinside](#snapshotcumulativesinside "mention")\
[#observe](#observe "mention")
## Variables
#### factory
```solidity
function factory() external view returns (address)
```
Address of the NFTX AMM's `UniswapV3FactoryUpgradeable` contract.
#### token0
```solidity
function token0() external view returns (address)
```
Address of "token0" (either WETH or vToken).
#### token1
```solidity
function token1() external view returns (address)
```
Address of "token1" (either WETH or vToken).
#### fee
```solidity
function fee() external view returns (uint24)
```
AMM swap fee tier.
#### tickSpacing
```solidity
function tickSpacing() external view returns (int24)
```
Tick spacing of the pool.
#### maxLiquidityPerTick
```solidity
function maxLiquidityPerTick() external view returns (uint128)
```
Maximum liquidity amount per tick.
#### slot0
```solidity
function slot0()
external
view
returns (
uint160 sqrtPriceX96,
int24 tick,
uint16 observationIndex,
uint16 observationCardinality,
uint16 observationCardinalityNext,
uint8 feeProtocol,
bool unlocked
)
```
Pool data.
#### feeGrowthGlobal0X128
```solidity
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
```solidity
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
```solidity
function protocolFees() external view returns (uint128 token0, uint128 token1)
```
Accumulated fees owed to the protocol (for example, to the governance treasury).
#### liquidity
```solidity
function liquidity() external view returns (uint128)
```
The total liquidity that's currently active in the pool.
#### ticks
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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
```solidity
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. |