NonfungiblePositionManager

The NonfungiblePositionManager wraps VinuSwap liquidity positions as ERC721 NFTs for easier management.

Source: contracts/periphery/NonfungiblePositionManager.sol

Overview

The position manager:

• Mints ERC721 tokens representing liquidity positions

• Tracks position ownership, fees, and liquidity

• Provides functions to modify positions

• Supports position locking (VinuSwap extension)

Inheritance

NonfungiblePositionManager
├── INonfungiblePositionManager
├── Multicall
├── ERC721Permit
├── PeripheryImmutableState
├── LiquidityManagement
├── PeripheryValidation
└── SelfPermit

Position Struct

struct Position {
    uint96 nonce;                    // Permit nonce
    address operator;                // Approved operator
    uint80 poolId;                   // Pool identifier
    int24 tickLower;                 // Lower tick boundary
    int24 tickUpper;                 // Upper tick boundary
    uint128 liquidity;               // Liquidity amount
    uint256 feeGrowthInside0LastX128; // Fee snapshot token0
    uint256 feeGrowthInside1LastX128; // Fee snapshot token1
    uint256 lockedUntil;             // Lock timestamp (VinuSwap extension)
    uint128 tokensOwed0;             // Uncollected token0
    uint128 tokensOwed1;             // Uncollected token1
}

Functions

mint

function mint(MintParams calldata params)
    external
    payable
    override
    checkDeadline(params.deadline)
    returns (
        uint256 tokenId,
        uint128 liquidity,
        uint256 amount0,
        uint256 amount1
    )

Creates a new position and mints an NFT.

Parameters:

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

Field	Description
token0	First token address (must be < token1)
token1	Second token address
fee	Pool fee tier
tickLower	Lower tick boundary
tickUpper	Upper tick boundary
amount0Desired	Desired token0 amount
amount1Desired	Desired token1 amount
amount0Min	Minimum token0 (slippage protection)
amount1Min	Minimum token1 (slippage protection)
recipient	NFT recipient
deadline	Transaction deadline

Returns:

Name	Type	Description
tokenId	uint256	ID of minted NFT
liquidity	uint128	Liquidity added
amount0	uint256	Token0 used
amount1	uint256	Token1 used

Example:

const params = {
    token0: USDT,           // Must be sorted
    token1: WVC,
    fee: 3000,
    tickLower: -60000,      // Must be divisible by tickSpacing
    tickUpper: 60000,
    amount0Desired: ethers.utils.parseUnits('1000', 6),
    amount1Desired: ethers.utils.parseEther('0.5'),
    amount0Min: 0,
    amount1Min: 0,
    recipient: userAddress,
    deadline: Math.floor(Date.now() / 1000) + 1800
};

const { tokenId, liquidity, amount0, amount1 } = await positionManager.mint(params);

---

increaseLiquidity

function increaseLiquidity(IncreaseLiquidityParams calldata params)
    external
    payable
    override
    checkDeadline(params.deadline)
    returns (
        uint128 liquidity,
        uint256 amount0,
        uint256 amount1
    )

Adds liquidity to an existing position.

Parameters:

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

Note: Can be called even on locked positions.

---

decreaseLiquidity

function decreaseLiquidity(DecreaseLiquidityParams calldata params)
    external
    payable
    override
    checkDeadline(params.deadline)
    returns (uint256 amount0, uint256 amount1)

Removes liquidity from a position.

Parameters:

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

Requirements:

• Caller must be owner or approved

• Position must NOT be locked (block.timestamp >= lockedUntil)

Returns:

Name	Type	Description
amount0	uint256	Token0 amount withdrawn
amount1	uint256	Token1 amount withdrawn

Note: Tokens are not transferred automatically. Call collect() to receive tokens.

---

collect

function collect(CollectParams calldata params)
    external
    payable
    override
    returns (uint256 amount0, uint256 amount1)

Collects tokens owed from a position (from decreaseLiquidity and accumulated fees).

Parameters:

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

Field	Description
tokenId	Position NFT ID
recipient	Token recipient
amount0Max	Maximum token0 to collect
amount1Max	Maximum token1 to collect

Note: Can be called on locked positions (fee collection is always allowed).

Example:

// Collect all owed tokens
const params = {
    tokenId: positionId,
    recipient: userAddress,
    amount0Max: ethers.constants.MaxUint128,
    amount1Max: ethers.constants.MaxUint128
};

const { amount0, amount1 } = await positionManager.collect(params);

---

burn

function burn(uint256 tokenId) external payable override

Burns a position NFT.

Requirements:

• Caller must be owner or approved

• Position liquidity must be 0

• Position must NOT be locked

• All tokens must be collected (tokensOwed0 = tokensOwed1 = 0)

---

lock

function lock(
    uint256 tokenId,
    uint256 lockedUntil,
    uint256 deadline
) external checkDeadline(deadline)

VinuSwap Extension

Locks a position until a specified timestamp.

Parameters:

Name	Type	Description
tokenId	uint256	Position NFT ID
lockedUntil	uint256	Unix timestamp until which position is locked
deadline	uint256	Transaction deadline

Requirements:

• Caller must be owner or approved

• lockedUntil must be in the future or extend current lock

Effects:

• Position cannot call decreaseLiquidity() until lock expires

• Position cannot call burn() until lock expires

• Position CAN still call collect() and increaseLiquidity()

Events Emitted:

• Lock(tokenId, lockedUntil)

Example:

// Lock position for 30 days
const lockUntil = Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60);
const deadline = Math.floor(Date.now() / 1000) + 1800;

await positionManager.lock(tokenId, lockUntil, deadline);

---

positions

function positions(uint256 tokenId)
    external
    view
    override
    returns (
        uint96 nonce,
        address operator,
        address token0,
        address token1,
        uint24 fee,
        int24 tickLower,
        int24 tickUpper,
        uint128 liquidity,
        uint256 feeGrowthInside0LastX128,
        uint256 feeGrowthInside1LastX128,
        uint256 lockedUntil
    )

Returns position data for a given NFT ID.

Note: Returns lockedUntil instead of tokensOwed. Use tokensOwed(tokenId) to get uncollected token amounts.

---

tokensOwed

function tokensOwed(uint256 tokenId)
    external
    view
    returns (
        uint128 tokensOwed0,
        uint128 tokensOwed1
    )

Returns uncollected tokens for a position.

Parameters:

Name	Type	Description
tokenId	uint256	Position NFT ID

Returns:

Name	Type	Description
tokensOwed0	uint128	Uncollected token0
tokensOwed1	uint128	Uncollected token1

Events

IncreaseLiquidity

event IncreaseLiquidity(
    uint256 indexed tokenId,
    uint128 liquidity,
    uint256 amount0,
    uint256 amount1
);

DecreaseLiquidity

event DecreaseLiquidity(
    uint256 indexed tokenId,
    uint128 liquidity,
    uint256 amount0,
    uint256 amount1
);

Collect

event Collect(
    uint256 indexed tokenId,
    address recipient,
    uint256 amount0,
    uint256 amount1
);

Lock

event Lock(
    uint256 indexed tokenId,
    uint256 lockedUntil
);

VinuSwap Extension

Error Messages

Error	Meaning
Invalid token ID	NFT does not exist
Not approved	Caller lacks permission
Locked	Position is locked
Not cleared	Position has uncollected tokens
Price slippage check	Slippage bounds exceeded

Common Patterns

Create Position with VC

// Token0 is WVC
const params = {
    token0: WVC,
    token1: USDT,
    fee: 3000,
    tickLower: -60000,
    tickUpper: 60000,
    amount0Desired: ethers.utils.parseEther('1'),
    amount1Desired: ethers.utils.parseUnits('2000', 6),
    amount0Min: 0,
    amount1Min: 0,
    recipient: userAddress,
    deadline: deadline
};

// Send VC with transaction
await positionManager.mint(params, { value: params.amount0Desired });

Remove All Liquidity

// Get current position
const position = await positionManager.positions(tokenId);

// Decrease full liquidity
await positionManager.decreaseLiquidity({
    tokenId,
    liquidity: position.liquidity,
    amount0Min: 0,
    amount1Min: 0,
    deadline
});

// Collect tokens
await positionManager.collect({
    tokenId,
    recipient: userAddress,
    amount0Max: ethers.constants.MaxUint128,
    amount1Max: ethers.constants.MaxUint128
});

// Burn NFT (if unlocked)
await positionManager.burn(tokenId);

Lock and Provide Liquidity

// Mint position
const { tokenId } = await positionManager.mint(mintParams);

// Lock for 6 months
const sixMonths = 6 * 30 * 24 * 60 * 60;
const lockUntil = Math.floor(Date.now() / 1000) + sixMonths;

await positionManager.lock(tokenId, lockUntil, deadline);

Interface

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

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

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

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

    function positions(uint256 tokenId) external view returns (...);
    function mint(MintParams calldata params) external payable returns (...);
    function increaseLiquidity(IncreaseLiquidityParams calldata params) external payable returns (...);
    function decreaseLiquidity(DecreaseLiquidityParams calldata params) external payable returns (...);
    function collect(CollectParams calldata params) external payable returns (...);
    function burn(uint256 tokenId) external payable;
    function lock(uint256 tokenId, uint256 lockedUntil, uint256 deadline) external;
}

Related

• Providing Liquidity Guide

• Position Locking Guide

• VinuSwapPool