NFTXInventoryStakingV3Upgradeable

NFTXInventoryStakingV3Upgradeable.sol

This contract allows users to stake vTokens to earn fees. Inventory staking positions are minted as xNFTs.

Table of Contents

Constants
Variables
Events
Public Write Functions
Owner Write Functions
Read Functions

Constants

MINIMUM_LIQUIDITY

uint256 public constant override MINIMUM_LIQUIDITY = 1_000

The minimum amount of vToken required to be staked if the total vToken shares are 0 for that vault.

VTOKEN_TIMELOCK

uint256 private constant VTOKEN_TIMELOCK = 1 hours

The timelock applied to all xNFTs made by depositing vToken, even if forceTimelock is false.

WETH

function WETH() external view returns (address)

Address of WETH contract.

PERMIT2

function PERMIT2() external returns (address)

Address of PERMIT2 contract.

nftxVaultFactory

function nftxVaultFactory() external view returns (address)

Address of NFTX Vault Factory.

timelockExcludeListYeah

function timelockExcludeList() external view returns (address)

List of addresses excluded from having timelocks enforced.

MAX_TIMELOCK

uint256 constant MAX_TIMELOCK = 14 days

Max timelock duration possible to have set.

MAX_EARLY_WITHDRAW_PENALTY

uint256 constant MAX_EARLY_WITHDRAW_PENALTY = 1 ether

Max early withdrawal penalty, 10e16 = 1%.

BASE

uint256 constant BASE = 1 ether

Equal to 10e18.

Variables

timelock

function timelock() external view returns (uint256)

The timelock duration applied to a position (when minted with NFTs or with forceTimelock).

earlyWithdrawPenaltyInWei

function earlyWithdrawPenaltyInWei() external view returns (uint256)

Early withdrawal penalty. 1e16 = 1%.

positions

function positions(
    uint256 positionId
)
    external
    view
    returns (
        uint256 nonce,
        uint256 vaultId,
        uint256 timelockedUntil,
        uint256 timelock,
        uint256 vTokenTimelockedUntil,
        uint256 vTokenShareBalance,
        uint256 wethFeesPerVTokenShareSnapshotX128,
        uint256 wethOwed
    )

Inventory staking data related to each positionId.

vaultGlobal

function vaultGlobal(
    uint256 vaultId
)
    external
    view
    returns (
        uint256 totalVTokenShares,
        uint256 globalWethFeesPerVTokenShareX128
    )

Inventory staking data related to each vaultId.

descriptor

function descriptor() external view returns (address)

Contract responsible for generating tokenURI for xNFT positions.

Events

Deposit

event Deposit(
    uint256 indexed vaultId,
    uint256 indexed positionId,
    uint256 amount,
    bool forceTimelock
)

Emitted by deposit().

ParametersTypeDescription

vaultId

uint256

ID of vault.

positionId

uint256

ID of staking position.

amount

uint256

Amount of vToken being deposited.

forceTimelock

bool

Whether to force a full timelock. Forcing a full timelock allows vToken inventory stakers to off-ramp to NFTs (without paying redeem fees) when they are done staking.

DepositWithNFT

event DepositWithNFT(
    uint256 indexed vaultId,
    uint256 indexed positionId,
    uint256[] tokenIds,
    uint256[] amounts
)

Emitted by depositWithNFF().

ParametersTypeDescription

vaultId

uint256

ID of vault.

positionId

uint256

ID of staking position.

tokenIds

uint256[]

Token IDs of NFTs being deposited.

amounts

uint256[]

Amounts of NFTs (for ERC1155).

CombinePositions

event CombinePositions(
    uint256 parentPositionId,
    uint256[] childPositionIds
)

Emitted by combinePosition().

ParametersTypeDescription

parentPositionId

uint256

ID number of parent position.

childPositionIds

uint256[]

ID numbers of child positions being merged into parent.

CollectWethFees

event CollectWethFees(uint256 indexed positionId, uint256 wethAmount)

Emitted by collectWethFees().

ParametersTypeDescription

positionId

uint256

ID of staking position.

wethAmount

uint256

Amount of WETH.

Withdraw

event Withdraw(
    uint256 indexed positionId,
    uint256 vTokenShares,
    uint256 vTokenAmount,
    uint256 wethAmount
)

Emitted by withdraw().

ParametersTypeDescription

positionId

uint256

ID of staking position.

vTokenShares

uint256

Amount of vToken shares subtracted from the position as a result of removing vToken.

vTokenAmount

uint256

Amount of vToken returned to sender.

wethAmount

uint256

Amount of WETH (fees) returned to sender.

UpdateTimelock

event UpdateTimelock(uint256 newTimelock)

Emitted by setTimelock().

ParametersTypeDescription

newTimelock

uint256

New timelock duration. In seconds.

UpdateEarlyWithdrawPenalty

event UpdateEarlyWithdrawPenalty(uint256 newEarlyWithdrawPenaltyInWei)

Emitted by setEarlyWithdrawPenalty().

ParametersTypeDescription

newEarlyWithdrawPenaltyInWei

uint256

New early withdrawal penalty. 1e16 = 1%.

Write Functions

deposit

function deposit(
    uint256 vaultId,
    uint256 amount,
    address recipient,
    bytes calldata encodedPermit2,
    bool viaPermit2,
    bool forceTimelock
) external returns (uint256 positionId)

Pulls vToken from the caller and returns an xNFT inventory staking position. Uses Uniswap's Permit2 contract for vToken approval and transfer, if specified. The xNFT position will have a 1-hour (hard) timelock, during which time the position cannot be withdrawn.

If the deposit is the first deposit that the inventory staking pool has ever received, then MINIMUM_LIQUIDITY (i.e, 1000 wei) of the vTokenShares are locked up forever to prevent front-running attacks.

If forceTimelock is set to false, then no regular timelock is applied and the position can be increased using increasePosition() but the owner of the position can only withdraw/off-ramp back to vToken (not NFTs).

If forceTimelock is set to true, then a regular 3-day timelock is applied in addition to the hard 1-hour timelock. Unlike the hard 1-hour time-lock, the regular 3-day timelock allows early withdrawals by charging a fee that begins at 10% and goes down linearly to zero over the duration of the timelock. The benefit of setting forceTimelock to true is that the owner of the position can withdraw/off-ramp to either vToken or NFTs.

ParametersTypeDescription

vaultId

uint256

The vault ID of the vToken being deposited.

amount

uint256

The amount of vToken to deposit.

recipient

address

The address which will receive the xNFT.

encodedPermit2

bytes

Encoded Permit2 data:

address owner,
IPermitAllowanceTransfer.PermitSingle,
bytes memory signature

viaPermit2

bool

Whether to use Permit2.

forceTimelock

bool

Whether to force a full 3-day timelock. See paragraph above for more details.

Return valuesTypeDescription

positionId

uint256

ID of the new inventory position.

depositWithNFT

function depositWithNFT(
    uint256 vaultId,
    uint256[] calldata tokenIds,
    uint256[] calldata amounts,
    address recipient
) external returns (uint256 positionId)

Pulls NFTs from sender, mints, and stakes vToken, and returns an xNFT inventory staking position. The xNFT position will have a 3-day timelock, during which time an early withdrawal penalty is charged in vToken if the owner of the position decides to withdraw. The early withdrawal penalty is 10% of the position and goes down linearly to zero over the duration of the timelock.

If the deposit is the first deposit that the inventory staking pool has ever received, then MINIMUM_LIQUIDITY (i.e, 1000 wei) of the vTokenShares are locked up forever to prevent front-running attacks.

ParametersTypeDescription

vaultId

uint256

Vault ID of the vToken to be minted and staked.

tokenIDs

uint256[]

Token IDs of NFTs being deposited.

amounts

uint256[]

Amounts of NFTs (for ERC1155).

recipient

address

Address which receives the xNFT.

Return valuesTypeDescription

positionId

uint256

ID of the newly minted xNFT inventory position.

increasePosition

function increasePosition(
    uint256 positionId,
    uint256 amount,
    bytes calldata encodedPermit2,
    bool viaPermit2,
    bool forceTimelock
) external

Increases the size of an inventory staking position that was created using vToken and did not force a regular 3-day timelock. Positions can be increased more than once as long as forceTimelock is false. After a position is increased with forceTimelock as true, then it can no longer be increased. It can, however, still be combined with other positions.

ParametersTypeDescription

positionId

uint256

ID number of staking position.

amount

uint256

Amount of vToken.

encodedPermit2

bytes

Encoded Permit2 data:

address owner,
IPermitAllowanceTransfer.PermitSingle,
bytes memory signature

viaPermit2

bool

Whether to use Permit2.

forceTimelock

bool

Whether to force a regular timelock. If a full timelock is enforced, then the position can not be increased again; however, it can still be combined with other positions.

withdraw

function withdraw(
    uint256 positionId,
    uint256 vTokenShares,
    uint256[] calldata nftIds,
    uint256 vTokenPremiumLimit
) external payable override nonReentrant

Reduces a position's vTokenShares and returns vToken/NFTs and ETH to the caller. Charges an early withdrawal penalty, paid in vToken, if the position has an active timelock. The penalty begins at 10% and goes down linearly to zero over the 3-day timelock duration. Early withdrawals are not possible for vToken -created positions unless they forced a full 3-day timelock,

ParametersTypeDescription

positionId

uint256

ID of the position.

vTokenShares

uint256

Number of vTokenShares to withdraw.

nftIds

uint256[]

NFT IDs to redeem.

vTokenPremiumLimit

uint256

Max total premium fee (denominated in vToken) to be paid.

msg.value

uint256

Amount of ETH to send.

combinePositions

function combinePositions(
    uint256 parentPositionId,
    uint256[] calldata childPositionIds
) external

Merges one or more child positions into a parent position. Requires that there are no timelocks remaining on any of the child positions.

ParametersTypeDescription

parentPositionId

uint256

The position that child positions merge into.

childPositionIds

uint256[]

The positions being merged into a parent position.

collectWethFees

function collectWethFees(uint256[] calldata positionIds) external

Claims WETH fees from one or more positions.

ParametersTypeDescription

positionIds

uint256[]

IDs of the positions.

receiveWethRewards

function receiveWethRewards(
    uint256 vaultId,
    uint256 wethAmount
) external returns (bool rewardsDistributed)

Retrieves WETH rewards. Only callable by fee distributor.

ParametersTypeDescription

vaultId

uint256

ID number of vault.

wethAmount

uint256

Amount of WETH.

Return valuesTypeDescription

rewardsDistributed

bool

True if function completes successfully.

Owner Functions

setTimelock

function setTimelock(uint256 timelock_) external

Sets the timelock duration for future deposits.

ParametersTypeDescription

timelock_

uint256

New timelock duration, in seconds.

setEarlyWithdrawPenalty

function setEarlyWithdrawPenalty(
    uint256 earlyWithdrawPenaltyInWei_
) external

Sets the early withdraw penalty for current and future deposits.

ParametersTypeDescription

earlyWithdrawPenaltyInWei_

uint256

New early withdraw penalty. 10e16 = 1%.

Read Functions

pricePerShareVToken

function pricePerShareVToken(uint256 vaultId) external view returns (uint256)

Returns the ratio of vTokens per share.

ParametersTypeDescription

vaultId

uint256

Vault ID of the vToken.

NameTypeDescription

unnamed

uint256

vTokens per share.

wethBalance

function wethBalance(uint256 positionId) external view returns (uint256)

Returns the amount of WETH that can be claimed by the xNFT with positionId.

ParametersTypeDescription

positionID

uint256

ID of position.

Return valuesTypeDescription

unnamed

uint256

WETH balance of position.

Last updated