Uniswap V3 Positions

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