NFTXInventoryStakingV3Upgradeable

NFTXInventoryStakingV3Upgradeable.sol

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

Table of Contents

Constants

MINIMUM_LIQUIDITY VTOKEN_TIMELOCK WETH PERMIT2 nftxVaultFactory NFTXInventoryStakingV3Upgradeable MAX_TIMELOCK MAX_EARLY_WITHDRAW_PENALTY BASE

Variables

timelock earlyWithdrawPenaltyInWei positions vaultGlobal descriptor

Events

Deposit DepositWithNFT CombinePositions CollectWethFees Withdraw UpdateTimelock UpdateEarlyWithdrawPenalty

Public Write Functions

deposit depositWithNFT increasePosition withdraw combinePositions collectWethFees receiveWethRewards

Owner Write Functions

setTimelock setEarlyWithdrawPenalty

Read Functions

pricePerShareVToken

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().

Parameters	Type	Description
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().

Parameters	Type	Description
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().

Parameters	Type	Description
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().

Parameters	Type	Description
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().

Parameters	Type	Description
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().

Parameters	Type	Description
newTimelock	uint256	New timelock duration. In seconds.

UpdateEarlyWithdrawPenalty

event UpdateEarlyWithdrawPenalty(uint256 newEarlyWithdrawPenaltyInWei)

Emitted by setEarlyWithdrawPenalty().

Parameters	Type	Description
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.

Parameters	Type	Description
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 values	Type	Description
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.

Parameters	Type	Description
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 values	Type	Description
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.

Parameters	Type	Description
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,

Parameters	Type	Description
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.

Parameters	Type	Description
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.

Parameters	Type	Description
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.

Parameters	Type	Description
vaultId	uint256	ID number of vault.
wethAmount	uint256	Amount of WETH.

Return values	Type	Description
rewardsDistributed	bool	True if function completes successfully.

Owner Functions

setTimelock

function setTimelock(uint256 timelock_) external

Sets the timelock duration for future deposits.

Parameters	Type	Description
timelock_	uint256	New timelock duration, in seconds.

setEarlyWithdrawPenalty

function setEarlyWithdrawPenalty(
    uint256 earlyWithdrawPenaltyInWei_
) external

Sets the early withdraw penalty for current and future deposits.

Parameters	Type	Description
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.

Parameters	Type	Description
vaultId	uint256	Vault ID of the vToken.

Name	Type	Description
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.

Parameters	Type	Description
positionID	uint256	ID of position.

Return values	Type	Description
unnamed	uint256	WETH balance of position.