DiamondSwap V3 Pool State Interface (IDiamondSwapV3PoolState)

The DiamondSwap V3 Pool State Interface (IDiamondSwapV3PoolState) defines the functions that allow users to query the current state of a pool. These functions provide detailed information about the pool’s current price, liquidity, fee growth, and more. Below is a detailed breakdown of the functions associated with the DiamondSwap V3 Pool State Interface.

Functions

liquidity() → uint128

This function returns the current liquidity in the pool. Liquidity is a key metric that represents the total amount of assets available for trading within the specified price range.

• Returns: The current liquidity as a uint128.

Liquidity is central to the pool's functioning, affecting slippage, price stability, and the ability to execute trades.

slot0() → (uint160 sqrtPriceX96, int24 tick, uint16 observationIndex, uint16 observationCardinality, uint16 observationCardinalityNext, uint8 feeProtocol, bool unlocked)

This function returns multiple state variables that describe the current state of the pool. These variables include the current price, tick, and observation data.

• sqrtPriceX96: The current price of the pool, represented as the square root of the price ratio of the two tokens (token1/token0) as a Q64.96 fixed-point number.
• tick: The current tick of the pool, representing the price range in which the pool is operating.
• observationIndex: The index of the last observation in the pool's observation array.
• observationCardinality: The current maximum number of observations stored in the pool's observation array.
• observationCardinalityNext: The next maximum number of observations to be stored in the pool's observation array, after an increase.
• feeProtocol: The protocol fee as a percentage of the swap fee.
• unlocked: A boolean indicating whether the pool is currently unlocked for trading (i.e., not in a locked state).

This function provides a comprehensive snapshot of the pool's state, which is essential for understanding its current behavior and for calculating price-related metrics.

tickSpacing() → int24

This function returns the tick spacing of the pool. Tick spacing determines the granularity of price increments within the pool and affects how liquidity can be distributed across price ranges.

• Returns: The tick spacing as an int24.

Tick spacing is critical for liquidity providers, as it defines how closely they can concentrate their liquidity positions within the pool.

feeGrowthGlobal0X128() → uint256

This function returns the total fee growth in token0 across all liquidity positions in the pool since the pool's inception, as a Q128.128 fixed-point number.

• Returns: The total fee growth in token0 as a uint256.

This value represents the cumulative fees earned by liquidity providers in token0, helping users understand the pool's fee-generating performance.

feeGrowthGlobal1X128() → uint256

This function returns the total fee growth in token1 across all liquidity positions in the pool since the pool's inception, as a Q128.128 fixed-point number.

• Returns: The total fee growth in token1 as a uint256.

Similar to feeGrowthGlobal0X128, this value tracks the cumulative fees earned by liquidity providers in token1.

protocolFees() → (uint128 token0, uint128 token1)

This function returns the amounts of token0 and token1 that are owed to the protocol as fees.

• Returns:
  • token0: The amount of token0 owed to the protocol as fees.
  • token1: The amount of token1 owed to the protocol as fees.

These values are important for tracking the protocol’s earnings from the pool, separate from the fees earned by liquidity providers.

liquidityGross(int24 tick) → uint128

This function returns the total amount of liquidity that is currently active at a specific tick.

• tick: The tick for which the liquidity is being queried.
• Returns: The total liquidity at the specified tick as a uint128.

Liquidity at specific ticks helps to understand how liquidity is distributed across different price ranges within the pool.

liquidityNet(int24 tick) → int128

This function returns the net liquidity at a specific tick, which represents the difference between liquidity added and removed at that tick.

• tick: The tick for which the net liquidity is being queried.
• Returns: The net liquidity at the specified tick as an int128.

Net liquidity is useful for understanding the balance of liquidity at a given tick, providing insights into market participants' behavior.

positions(bytes32 key) → (uint128 liquidity, uint256 feeGrowthInside0LastX128, uint256 feeGrowthInside1LastX128, uint128 tokensOwed0, uint128 tokensOwed1)

This function returns information about a specific liquidity position in the pool.

• key: A unique identifier for the position, derived from the liquidity provider's address and the position's tick range.
• Returns:
  • liquidity: The amount of liquidity in the position.
  • feeGrowthInside0LastX128: The fee growth in token0 inside the position's tick range since the last update.
  • feeGrowthInside1LastX128: The fee growth in token1 inside the position's tick range since the last update.
  • tokensOwed0: The amount of token0 owed to the position as uncollected fees.
  • tokensOwed1: The amount of token1 owed to the position as uncollected fees.

This function is essential for liquidity providers who need to monitor their positions, track their earnings, and manage their liquidity.

observations(uint256 index) → (uint32 blockTimestamp, int56 tickCumulative, uint160 secondsPerLiquidityCumulativeX128, bool initialized)

This function returns data from a specific observation in the pool's observation array. Observations are used to calculate time-weighted average prices (TWAP) and other historical metrics.

• index: The index of the observation in the observation array.
• Returns:
  • blockTimestamp: The timestamp of the observation.
  • tickCumulative: The cumulative tick at the time of the observation.
  • secondsPerLiquidityCumulativeX128: The cumulative seconds per liquidity at the time of the observation.
  • initialized: A boolean indicating whether the observation has been initialized.

Observations are crucial for analyzing the pool's historical behavior and calculating TWAP for price feeds and other applications.

Conclusion

The DiamondSwap V3 Pool State Interface (IDiamondSwapV3PoolState) provides detailed information about the current state of the pool, including liquidity, pricing, fee growth, and position data. These functions are essential for users and developers who need to interact with the pool, analyze its performance, or manage liquidity positions. Understanding this interface is crucial for anyone looking to effectively participate in the DiamondSwap ecosystem, whether as a trader, liquidity provider, or developer.