Imported from cyotee/indexedex (.opencode/skills/uniswap-v3-positions/SKILL.md). Install upstream with npx skills add cyotee/indexedex --skill uniswap-v3-positions. Copyright stays with the author.

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

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)

// 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

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)

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

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

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

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

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