Uniswap V3 Positions — Управление ликвидностью в DeFi протоколе

--- name: Uniswap V3 Positions description: This skill should be used when the user asks about "positions", "Position.Info", "fee growth", "tokensOwed", "liquidity positions", "mint", "burn", "collect fees", or needs to understand position management and fee accumulation. version: 0.1.0 --- # Uniswap V3 Positions ## Overview Positions in Uniswap V3 represent a liquidity provider's stake within a specific tick range. Each position tracks the liquidity amount and accumulated fees using a sophisticated fee growth accounting system. ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ POSITION ARCHITECTURE │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ Position Key = keccak256(owner, tickLower, tickUpper) │ │ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ Position.Info │ │ │ ├──────────────────────────────────────────────────────────────────────┤ │ │ │ liquidity: uint128 │ Amount of liquidity in position │ │ │ ├──────────────────────────────────┼───────────────────────────────────│ │ │ │ feeGrowthInside0LastX128: u256 │ Snapshot of fee growth for token0 │ │ │ ├──────────────────────────────────┼───────────────────────────────────│ │ │ │ feeGrowthInside1LastX128: u256 │ Snapshot of fee growth for token1 │ │ │ ├──────────────────────────────────┼───────────────────────────────────│ │ │ │ tokensOwed0: uint128 │ Uncollected fees in token0 │ │ │ ├──────────────────────────────────┼───────────────────────────────────│ │ │ │ tokensOwed1: uint128 │ Uncollected fees in token1 │ │ │ └──────────────────────────────────┴───────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ## Position Library ```solidity library Position { struct Info { // Amount of liquidity owned by this position uint128 liquidity; // Fee growth per unit of liquidity as of last update // Used to calculate fees owed uint256 feeGrowthInside0LastX128; uint256 feeGrowthInside1LastX128; // Fees owed to the position owner in token0/token1 uint128 tokensOwed0; uint128 tokensOwed1; } /// @notice Returns the position key for the given parameters function get( mapping(bytes32 => Info) storage self, address owner, int24 tickLower, int24 tickUpper ) internal view returns (Info storage position) { position = self[keccak256(abi.encodePacked(owner, tickLower, tickUpper))]; } /// @notice Updates a position with new liquidity and fee growth function update( Info storage self, int128 liquidityDelta, uint256 feeGrowthInside0X128, uint256 feeGrowthInside1X128 ) internal { Info memory _self = self; uint128 liquidityNext; if (liquidityDelta == 0) { require(_self.liquidity > 0, 'NP'); // No position exists liquidityNext = _self.liquidity; } else { liquidityNext = LiquidityMath.addDelta(_self.liquidity, liquidityDelta); } // Calculate fees accumulated since last update uint128 tokensOwed0 = uint128( FullMath.mulDiv( feeGrowthInside0X128 - _self.feeGrowthInside0LastX128, _self.liquidity, FixedPoint128.Q128 ) ); uint128 tokensOwed1 = uint128( FullMath.mulDiv( feeGrowthInside1X128 - _self.feeGrowthInside1LastX128, _self.liquidity, FixedPoint128.Q128 ) ); // Update position state if (liquidityDelta != 0) self.liquidity = liquidityNext; self.feeGrowthInside0LastX128 = feeGrowthInside0X128; self.feeGrowthInside1LastX128 = feeGrowthInside1X128; // Add newly accrued fees to owed amounts if (tokensOwed0 > 0 || tokensOwed1 > 0) { self.tokensOwed0 += tokensOwed0; self.tokensOwed1 += tokensOwed1; } } } ``` ## Fee Accumulation Mechanism ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ FEE GROWTH ACCOUNTING │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ Global State (Pool): │ │ ┌────────────────────────────────────────────────────────────────────┐ │ │ │ feeGrowthGlobal0X128 = total fees token0 / total liquidity │ │ │ │ feeGrowthGlobal1X128 = total fees token1 / total liquidity │ │ │ └────────────────────────────────────────────────────────────────────┘ │ │ │ │ Per-Tick State (each initialized tick): │ │ ┌────────────────────────────────────────────────────────────────────┐ │ │ │ feeGrowthOutside0X128 = fees when price was on "other side" │ │ │ │ feeGrowthOutside1X128 │ │ │ └────────────────────────────────────────────────────────────────────┘ │ │ │ │ Per-Position Calculation: │ │ ┌────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ feeGrowthInside = feeGrowthGlobal │ │ │ │ - feeGrowthBelow(tickLower) │ │ │ │ - feeGrowthAbove(tickUpper) │ │ │ │ │ │ │ │ feesOwed = (feeGrowthInside - feeGrowthInsideLast) × liquidity │ │ │ │ │ │ │ └────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ Fee Growth Visualization: tickLower tickUpper │ │ ▼ ▼ ┌──────────┼────────────────────────────┼──────────┐ │ │ Position Range │ │ │ OUTSIDE │ (INSIDE) │ OUTSIDE │ │ (L) │ │ (R) │ └──────────┴────────────────────────────┴──────────┘ if tick >= tickLower: feeGrowthBelow = tick.feeGrowthOutside else: feeGrowthBelow = feeGrowthGlobal - tick.feeGrowthOutside if tick < tickUpper: feeGrowthAbove = tick.feeGrowthOutside else: feeGrowthAbove = feeGrowthGlobal - tick.feeGrowthOutside ``` ## Position Lifecycle ### 1. Create Position (Mint) ```solidity // In UniswapV3Pool function _modifyPosition(ModifyPositionParams memory params) private returns (Position.Info storage position, int256 amount0, int256 amount1) { // Check ticks are valid checkTicks(params.tickLower, params.tickUpper); Slot0 memory _slot0 = slot0; // Update position and ticks position = _updatePosition( params.owner, params.tickLower, params.tickUpper, params.liquidityDelta, _slot0.tick ); if (params.liquidityDelta != 0) { if (_slot0.tick < params.tickLower) { // Current price below range: need only token0 amount0 = SqrtPriceMath.getAmount0Delta( TickMath.getSqrtRatioAtTick(params.tickLower), TickMath.getSqrtRatioAtTick(params.tickUpper), params.liquidityDelta ); } else if (_slot0.tick < params.tickUpper) { // Current price inside range: need both tokens amount0 = SqrtPriceMath.getAmount0Delta( _slot0.sqrtPriceX96, TickMath.getSqrtRatioAtTick(params.tickUpper), params.liquidityDelta ); amount1 = SqrtPriceMath.getAmount1Delta( TickMath.getSqrtRatioAtTick(params.tickLower), _slot0.sqrtPriceX96, params.liquidityDelta ); // Update global liquidity if in range liquidity = LiquidityMath.addDelta(liquidity, params.liquidityDelta); } else { // Current price above range: need only token1 amount1 = SqrtPriceMath.getAmount1Delta( TickMath.getSqrtRatioAtTick(params.tickLower), TickMath.getSqrtRatioAtTick(params.tickUpper), params.liquidityDelta ); } } } ``` ### 2. Update Position State ```solidity function _updatePosition( address owner, int24 tickLower, int24 tickUpper, int128 liquidityDelta, int24 tick ) private returns (Position.Info storage position) { position = positions.get(owner, tickLower, tickUpper); uint256 _feeGrowthGlobal0X128 = feeGrowthGlobal0X128; uint256 _feeGrowthGlobal1X128 = feeGrowthGlobal1X128; // Update tick states if liquidity changes bool flippedLower; bool flippedUpper; if (liquidityDelta != 0) { flippedLower = ticks.update( tickLower, tick, liquidityDelta, _feeGrowthGlobal0X128, _feeGrowthGlobal1X128, false, // isUpper = false maxLiquidityPerTick ); flippedUpper = ticks.update( tickUpper, tick, liquidityDelta, _feeGrowthGlobal0X128, _feeGrowthGlobal1X128, true, // isUpper = true maxLiquidityPerTick ); // Update bitmap if tick was initialized/uninitialized if (flippedLower) tickBitmap.flipTick(tickLower, tickSpacing); if (flippedUpper) tickBitmap.flipTick(tickUpper, tickSpacing); } // Calculate fee growth inside the position's range (uint256 feeGrowthInside0X128, uint256 feeGrowthInside1X128) = ticks.getFeeGrowthInside(tickLower, tickUpper, tick, _feeGrowthGlobal0X128, _feeGrowthGlobal1X128); // Update position with new fee growth position.update(liquidityDelta, feeGrowthInside0X128, feeGrowthInside1X128); // Clear tick state if liquidity removed completely if (liquidityDelta < 0) { if (flippedLower) ticks.clear(tickLower); if (flippedUpper) ticks.clear(tickUpper); } } ``` ### 3. Remove Liquidity (Burn) ```solidity function burn( int24 tickLower, int24 tickUpper, uint128 amount ) external lock returns (uint256 amount0, uint256 amount1) { (Position.Info storage position, int256 amount0Int, int256 amount1Int) = _modifyPosition( ModifyPositionParams({ owner: msg.sender, tickLower: tickLower, tickUpper: tickUpper, liquidityDelta: -int256(uint256(amount)).toInt128() }) ); amount0 = uint256(-amount0Int); amount1 = uint256(-amount1Int); // Add to tokens owed (tokens + fees) if (amount0 > 0 || amount1 > 0) { (position.tokensOwed0, position.tokensOwed1) = ( position.tokensOwed0 + uint128(amount0), position.tokensOwed1 + uint128(amount1) ); } emit Burn(msg.sender, tickLower, tickUpper, amount, amount0, amount1); } ``` ### 4. Collect Fees ```solidity function collect( address recipient, int24 tickLower, int24 tickUpper, uint128 amount0Requested, uint128 amount1Requested ) external lock returns (uint128 amount0, uint128 amount1) { Position.Info storage position = positions.get(msg.sender, tickLower, tickUpper); // First burn 0 liquidity to trigger fee update // This updates tokensOwed based on current fee growth amount0 = amount0Requested > position.tokensOwed0 ? position.tokensOwed0 : amount0Requested; amount1 = amount1Requested > position.tokensOwed1 ? position.tokensOwed1 : amount1Requested; if (amount0 > 0) { position.tokensOwed0 -= amount0; TransferHelper.safeTransfer(token0, recipient, amount0); } if (amount1 > 0) { position.tokensOwed1 -= amount1; TransferHelper.safeTransfer(token1, recipient, amount1); } emit Collect(msg.sender, recipient, tickLower, tickUpper, amount0, amount1); } ``` ## Liquidity Amount Calculations ```solidity library LiquidityAmounts { /// @notice Computes liquidity from token0 amount function getLiquidityForAmount0( uint160 sqrtRatioAX96, uint160 sqrtRatioBX96, uint256 amount0 ) internal pure returns (uint128 liquidity) { if (sqrtRatioAX96 > sqrtRatioBX96) (sqrtRatioAX96, sqrtRatioBX96) = (sqrtRatioBX96, sqrtRatioAX96); uint256 intermediate = FullMath.mulDiv(sqrtRatioAX96, sqrtRatioBX96, FixedPoint96.Q96); return toUint128(FullMath.mulDiv(amount0, intermediate, sqrtRatioBX96 - sqrtRatioAX96)); } /// @notice Computes liquidity from token1 amount function getLiquidityForAmount1( uint160 sqrtRatioAX96, uint160 sqrtRatioBX96, uint256 amount1 ) internal pure returns (uint128 liquidity) { if (sqrtRatioAX96 > sqrtRatioBX96) (sqrtRatioAX96, sqrtRatioBX96) = (sqrtRatioBX96, sqrtRatioAX96); return toUint128(FullMath.mulDiv(amount1, FixedPoint96.Q96, sqrtRatioBX96 - sqrtRatioAX96)); } /// @notice Computes liquidity from both token amounts based on current price function getLiquidityForAmounts( uint160 sqrtRatioX96, uint160 sqrtRatioAX96, uint160 sqrtRatioBX96, uint256 amount0, uint256 amount1 ) internal pure returns (uint128 liquidity) { if (sqrtRatioAX96 > sqrtRatioBX96) (sqrtRatioAX96, sqrtRatioBX96) = (sqrtRatioBX96, sqrtRatioAX96); if (sqrtRatioX96 <= sqrtRatioAX96) { // Below range: only token0 needed liquidity = getLiquidityForAmount0(sqrtRatioAX96, sqrtRatioBX96, amount0); } else if (sqrtRatioX96 < sqrtRatioBX96) { // In range: use smaller of two calculated liquidities uint128 liquidity0 = getLiquidityForAmount0(sqrtRatioX96, sqrtRatioBX96, amount0); uint128 liquidity1 = getLiquidityForAmount1(sqrtRatioAX96, sqrtRatioX96, amount1); liquidity = liquidity0 < liquidity1 ? liquidity0 : liquidity1; } else { // Above range: only token1 needed liquidity = getLiquidityForAmount1(sqrtRatioAX96, sqrtRatioBX96, amount1); } } } ``` ## Position Key Calculation ```solidity library PositionKey { /// @notice Returns the key for a position function compute( address owner, int24 tickLower, int24 tickUpper ) internal pure returns (bytes32) { return keccak256(abi.encodePacked(owner, tickLower, tickUpper)); } } ``` ## Events ```solidity event Mint( address sender, address indexed owner, int24 indexed tickLower, int24 indexed tickUpper, uint128 amount, uint256 amount0, uint256 amount1 ); event Burn( address indexed owner, int24 indexed tickLower, int24 indexed tickUpper, uint128 amount, uint256 amount0, uint256 amount1 ); event Collect( address indexed owner, address recipient, int24 indexed tickLower, int24 indexed tickUpper, uint128 amount0, uint128 amount1 ); ``` ## Reference Files ### v3-core - `contracts/libraries/Position.sol` - Position data structure and update logic - `contracts/libraries/LiquidityMath.sol` - Liquidity delta operations - `contracts/libraries/FullMath.sol` - High-precision multiplication ### v3-periphery - `contracts/libraries/LiquidityAmounts.sol` - Token↔Liquidity conversions - `contracts/libraries/PositionKey.sol` - Position key computation - `contracts/libraries/PositionValue.sol` - Position valuation helpers