Uniswap V3 Position Manager

---
name: Uniswap V3 Position Manager
description: This skill should be used when the user asks about "NonfungiblePositionManager", "NFT positions", "position NFT", "ERC721 positions", "mint position", "increase liquidity", "decrease liquidity", or needs to understand the NFT wrapper for V3 positions.
version: 0.1.0
---

# Uniswap V3 Position Manager

## Overview

The NonfungiblePositionManager (NPM) wraps Uniswap V3 positions as ERC721 NFTs, providing a user-friendly interface for creating and managing concentrated liquidity positions.

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                    NONFUNGIBLE POSITION MANAGER                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    Position NFT (ERC721)                              │   │
│  │  tokenId: 12345                                                       │   │
│  │  ┌────────────────────────────────────────────────────────────────┐  │   │
│  │  │ Position Data:                                                  │  │   │
│  │  │   nonce: 0                                                      │  │   │
│  │  │   operator: 0x...                                               │  │   │
│  │  │   poolId: 1                                                     │  │   │
│  │  │   tickLower: -887220                                            │  │   │
│  │  │   tickUpper: 887220                                             │  │   │
│  │  │   liquidity: 1000000000000                                      │  │   │
│  │  │   feeGrowthInside0LastX128: ...                                 │  │   │
│  │  │   feeGrowthInside1LastX128: ...                                 │  │   │
│  │  │   tokensOwed0: 5000                                             │  │   │
│  │  │   tokensOwed1: 3000                                             │  │   │
│  │  └────────────────────────────────────────────────────────────────┘  │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                              │                                               │
│                              │ References                                    │
│                              ▼                                               │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    Pool Position (in UniswapV3Pool)                   │   │
│  │  key: keccak256(NPM_address, tickLower, tickUpper)                   │   │
│  │  Aggregates all NPM positions at same tick range                      │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Position Data Structure

```solidity
struct Position {
    // Nonce for permits
    uint96 nonce;

    // Address approved to manage this position
    address operator;

    // Pool identifier (optimized storage vs storing full PoolKey)
    uint80 poolId;

    // Tick range
    int24 tickLower;
    int24 tickUpper;

    // Liquidity amount
    uint128 liquidity;

    // Fee growth snapshots for fee calculation
    uint256 feeGrowthInside0LastX128;
    uint256 feeGrowthInside1LastX128;

    // Fees owed to this position
    uint128 tokensOwed0;
    uint128 tokensOwed1;
}

// Pool key for efficient storage
struct PoolKey {
    address token0;
    address token1;
    uint24 fee;
}
```

## Core Operations

### Mint (Create Position)

```solidity
struct MintParams {
    address token0;
    address token1;
    uint24 fee;
    int24 tickLower;
    int24 tickUpper;
    uint256 amount0Desired;
    uint256 amount1Desired;
    uint256 amount0Min;
    uint256 amount1Min;
    address recipient;
    uint256 deadline;
}

function mint(MintParams calldata params)
    external payable
    checkDeadline(params.deadline)
    returns (
        uint256 tokenId,
        uint128 liquidity,
        uint256 amount0,
        uint256 amount1
    )
{
    IUniswapV3Pool pool;
    (liquidity, amount0, amount1, pool) = addLiquidity(
        AddLiquidityParams({
            token0: params.token0,
            token1: params.token1,
            fee: params.fee,
            recipient: address(this),
            tickLower: params.tickLower,
            tickUpper: params.tickUpper,
            amount0Desired: params.amount0Desired,
            amount1Desired: params.amount1Desired,
            amount0Min: params.amount0Min,
            amount1Min: params.amount1Min
        })
    );

    // Mint NFT
    _mint(params.recipient, (tokenId = _nextId++));

    // Get fee growth for position initialization
    bytes32 positionKey = PositionKey.compute(address(this), params.tickLower, params.tickUpper);
    (, uint256 feeGrowthInside0LastX128, uint256 feeGrowthInside1LastX128, , ) = pool.positions(positionKey);

    // Cache pool info
    uint80 poolId = cachePoolKey(
        address(pool),
        PoolKey({token0: params.token0, token1: params.token1, fee: params.fee})
    );

    // Store position data
    _positions[tokenId] = Position({
        nonce: 0,
        operator: address(0),
        poolId: poolId,
        tickLower: params.tickLower,
        tickUpper: params.tickUpper,
        liquidity: liquidity,
        feeGrowthInside0LastX128: feeGrowthInside0LastX128,
        feeGrowthInside1LastX128: feeGrowthInside1LastX128,
        tokensOwed0: 0,
        tokensOwed1: 0
    });

    emit IncreaseLiquidity(tokenId, liquidity, amount0, amount1);
}
```

### Add Liquidity (Internal)

```solidity
function addLiquidity(AddLiquidityParams memory params)
    internal
    returns (
        uint128 liquidity,
        uint256 amount0,
        uint256 amount1,
        IUniswapV3Pool pool
    )
{
    PoolKey memory poolKey = PoolKey({
        token0: params.token0,
        token1: params.token1,
        fee: params.fee
    });

    pool = IUniswapV3Pool(PoolAddress.computeAddress(factory, poolKey));

    // Compute optimal liquidity amount
    (uint160 sqrtPriceX96, , , , , , ) = pool.slot0();
    uint160 sqrtRatioAX96 = TickMath.getSqrtRatioAtTick(params.tickLower);
    uint160 sqrtRatioBX96 = TickMath.getSqrtRatioAtTick(params.tickUpper);

    liquidity = LiquidityAmounts.getLiquidityForAmounts(
        sqrtPriceX96,
        sqrtRatioAX96,
        sqrtRatioBX96,
        params.amount0Desired,
        params.amount1Desired
    );

    // Call pool.mint()
    (amount0, amount1) = pool.mint(
        params.recipient,
        params.tickLower,
        params.tickUpper,
        liquidity,
        abi.encode(MintCallbackData({poolKey: poolKey, payer: msg.sender}))
    );

    require(amount0 >= params.amount0Min && amount1 >= params.amount1Min, 'Price slippage check');
}
```

### Increase Liquidity

```solidity
struct IncreaseLiquidityParams {
    uint256 tokenId;
    uint256 amount0Desired;
    uint256 amount1Desired;
    uint256 amount0Min;
    uint256 amount1Min;
    uint256 deadline;
}

function increaseLiquidity(IncreaseLiquidityParams calldata params)
    external payable
    checkDeadline(params.deadline)
    returns (uint128 liquidity, uint256 amount0, uint256 amount1)
{
    Position storage position = _positions[params.tokenId];

    PoolKey memory poolKey = _poolIdToPoolKey[position.poolId];

    IUniswapV3Pool pool;
    (liquidity, amount0, amount1, pool) = addLiquidity(
        AddLiquidityParams({
            token0: poolKey.token0,
            token1: poolKey.token1,
            fee: poolKey.fee,
            tickLower: position.tickLower,
            tickUpper: position.tickUpper,
            amount0Desired: params.amount0Desired,
            amount1Desired: params.amount1Desired,
            amount0Min: params.amount0Min,
            amount1Min: params.amount1Min,
            recipient: address(this)
        })
    );

    // Update fee growth and owed tokens
    bytes32 positionKey = PositionKey.compute(address(this), position.tickLower, position.tickUpper);
    (, uint256 feeGrowthInside0LastX128, uint256 feeGrowthInside1LastX128, , ) = pool.positions(positionKey);

    // Calculate new fees owed
    position.tokensOwed0 += uint128(
        FullMath.mulDiv(
            feeGrowthInside0LastX128 - position.feeGrowthInside0LastX128,
            position.liquidity,
            FixedPoint128.Q128
        )
    );
    position.tokensOwed1 += uint128(
        FullMath.mulDiv(
            feeGrowthInside1LastX128 - position.feeGrowthInside1LastX128,
            position.liquidity,
            FixedPoint128.Q128
        )
    );

    // Update position
    position.feeGrowthInside0LastX128 = feeGrowthInside0LastX128;
    position.feeGrowthInside1LastX128 = feeGrowthInside1LastX128;
    position.liquidity += liquidity;

    emit IncreaseLiquidity(params.tokenId, liquidity, amount0, amount1);
}
```

### Decrease Liquidity

```solidity
struct DecreaseLiquidityParams {
    uint256 tokenId;
    uint128 liquidity;
    uint256 amount0Min;
    uint256 amount1Min;
    uint256 deadline;
}

function decreaseLiquidity(DecreaseLiquidityParams calldata params)
    external payable
    isAuthorizedForToken(params.tokenId)
    checkDeadline(params.deadline)
    returns (uint256 amount0, uint256 amount1)
{
    require(params.liquidity > 0);
    Position storage position = _positions[params.tokenId];

    uint128 positionLiquidity = position.liquidity;
    require(positionLiquidity >= params.liquidity);

    PoolKey memory poolKey = _poolIdToPoolKey[position.poolId];
    IUniswapV3Pool pool = IUniswapV3Pool(PoolAddress.computeAddress(factory, poolKey));

    // Burn liquidity from pool
    (amount0, amount1) = pool.burn(position.tickLower, position.tickUpper, params.liquidity);

    require(amount0 >= params.amount0Min && amount1 >= params.amount1Min, 'Price slippage check');

    // Update fee growth and calculate new fees
    bytes32 positionKey = PositionKey.compute(address(this), position.tickLower, position.tickUpper);
    (, uint256 feeGrowthInside0LastX128, uint256 feeGrowthInside1LastX128, , ) = pool.positions(positionKey);

    position.tokensOwed0 += uint128(amount0) + uint128(
        FullMath.mulDiv(
            feeGrowthInside0LastX128 - position.feeGrowthInside0LastX128,
            positionLiquidity,
            FixedPoint128.Q128
        )
    );
    position.tokensOwed1 += uint128(amount1) + uint128(
        FullMath.mulDiv(
            feeGrowthInside1LastX128 - position.feeGrowthInside1LastX128,
            positionLiquidity,
            FixedPoint128.Q128
        )
    );

    position.feeGrowthInside0LastX128 = feeGrowthInside0LastX128;
    position.feeGrowthInside1LastX128 = feeGrowthInside1LastX128;
    position.liquidity = positionLiquidity - params.liquidity;

    emit DecreaseLiquidity(params.tokenId, params.liquidity, amount0, amount1);
}
```

### Collect Fees

```solidity
struct CollectParams {
    uint256 tokenId;
    address recipient;
    uint128 amount0Max;
    uint128 amount1Max;
}

function collect(CollectParams calldata params)
    external payable
    isAuthorizedForToken(params.tokenId)
    returns (uint256 amount0, uint256 amount1)
{
    require(params.recipient != address(0));
    Position storage position = _positions[params.tokenId];

    PoolKey memory poolKey = _poolIdToPoolKey[position.poolId];
    IUniswapV3Pool pool = IUniswapV3Pool(PoolAddress.computeAddress(factory, poolKey));

    (uint128 tokensOwed0, uint128 tokensOwed1) = (position.tokensOwed0, position.tokensOwed1);

    // Trigger fee update by burning 0 liquidity
    if (position.liquidity > 0) {
        pool.burn(position.tickLower, position.tickUpper, 0);

        bytes32 positionKey = PositionKey.compute(address(this), position.tickLower, position.tickUpper);
        (, uint256 feeGrowthInside0LastX128, uint256 feeGrowthInside1LastX128, , ) = pool.positions(positionKey);

        tokensOwed0 += uint128(
            FullMath.mulDiv(
                feeGrowthInside0LastX128 - position.feeGrowthInside0LastX128,
                position.liquidity,
                FixedPoint128.Q128
            )
        );
        tokensOwed1 += uint128(
            FullMath.mulDiv(
                feeGrowthInside1LastX128 - position.feeGrowthInside1LastX128,
                position.liquidity,
                FixedPoint128.Q128
            )
        );

        position.feeGrowthInside0LastX128 = feeGrowthInside0LastX128;
        position.feeGrowthInside1LastX128 = feeGrowthInside1LastX128;
    }

    // Cap at available amounts
    (uint128 amount0Collect, uint128 amount1Collect) = (
        params.amount0Max > tokensOwed0 ? tokensOwed0 : params.amount0Max,
        params.amount1Max > tokensOwed1 ? tokensOwed1 : params.amount1Max
    );

    // Collect from pool
    (amount0, amount1) = pool.collect(
        params.recipient,
        position.tickLower,
        position.tickUpper,
        amount0Collect,
        amount1Collect
    );

    // Update position
    (position.tokensOwed0, position.tokensOwed1) = (tokensOwed0 - amount0Collect, tokensOwed1 - amount1Collect);

    emit Collect(params.tokenId, params.recipient, amount0Collect, amount1Collect);
}
```

### Burn NFT

```solidity
function burn(uint256 tokenId) external payable isAuthorizedForToken(tokenId) {
    Position storage position = _positions[tokenId];
    require(position.liquidity == 0 && position.tokensOwed0 == 0 && position.tokensOwed1 == 0, 'Not cleared');
    delete _positions[tokenId];
    _burn(tokenId);
}
```

## View Functions

```solidity
function positions(uint256 tokenId)
    external view
    returns (
        uint96 nonce,
        address operator,
        address token0,
        address token1,
        uint24 fee,
        int24 tickLower,
        int24 tickUpper,
        uint128 liquidity,
        uint256 feeGrowthInside0LastX128,
        uint256 feeGrowthInside1LastX128,
        uint128 tokensOwed0,
        uint128 tokensOwed1
    )
{
    Position memory position = _positions[tokenId];
    require(position.poolId != 0, 'Invalid token ID');
    PoolKey memory poolKey = _poolIdToPoolKey[position.poolId];

    return (
        position.nonce,
        position.operator,
        poolKey.token0,
        poolKey.token1,
        poolKey.fee,
        position.tickLower,
        position.tickUpper,
        position.liquidity,
        position.feeGrowthInside0LastX128,
        position.feeGrowthInside1LastX128,
        position.tokensOwed0,
        position.tokensOwed1
    );
}
```

## ERC721 Permit

Supports gasless approvals via ERC721Permit.

```solidity
function permit(
    address spender,
    uint256 tokenId,
    uint256 deadline,
    uint8 v,
    bytes32 r,
    bytes32 s
) external payable {
    require(block.timestamp <= deadline, 'Permit expired');

    bytes32 digest = keccak256(
        abi.encodePacked(
            '\x19\x01',
            DOMAIN_SEPARATOR,
            keccak256(abi.encode(PERMIT_TYPEHASH, spender, tokenId, _positions[tokenId].nonce++, deadline))
        )
    );

    address owner = ownerOf(tokenId);
    require(spender != owner, 'Approval to current owner');

    address recoveredAddress = ecrecover(digest, v, r, s);
    require(recoveredAddress != address(0) && recoveredAddress == owner, 'Invalid signature');

    _approve(spender, tokenId);
}
```

## Events

```solidity
event IncreaseLiquidity(uint256 indexed tokenId, uint128 liquidity, uint256 amount0, uint256 amount1);
event DecreaseLiquidity(uint256 indexed tokenId, uint128 liquidity, uint256 amount0, uint256 amount1);
event Collect(uint256 indexed tokenId, address recipient, uint256 amount0, uint256 amount1);
```

## Multicall Support

NPM inherits Multicall for batching operations.

```solidity
// Example: Decrease liquidity + collect in one transaction
bytes[] memory calls = new bytes[](2);
calls[0] = abi.encodeCall(npm.decreaseLiquidity, (decreaseParams));
calls[1] = abi.encodeCall(npm.collect, (collectParams));
npm.multicall(calls);
```

## Reference Files

- `contracts/NonfungiblePositionManager.sol` - Main implementation
- `contracts/base/LiquidityManagement.sol` - Liquidity operations
- `contracts/base/ERC721Permit.sol` - Gasless approvals
- `contracts/base/Multicall.sol` - Batch operations
- `contracts/base/PeripheryPayments.sol` - Token transfers
- `contracts/libraries/PositionKey.sol` - Position key computation