Skip to main content

PVM Technical Reference

NEST PVM offers a variety of contract functions based on probabilistic assets, with which developers can quickly build their own DeFi, NFT, and GameFi projects. You can check dapp and the whitepaper to learn more about it.

The contract functions already available are futures, options.

This article is divided into 3 parts:

Contract details

Futures

The Futures contract includes four functions:

Open Futures

The Open Futures function allows users to buy a future product with the specific leverage ratio, direction and amount, without a trading fee. Users could open a future position of ETH/USDT or BTC/USDT directly through their wallet. The market price of futures is provided by the NEST oracle.

Futures' open price will be slightly different from the price provided by the NEST oracle, as the mechanism of the decentralized oracle will result in a little time lag between market price and the oracle price, thus, a certain amount of risk compensation is added to the futures' open price. For example, for long positions, the open price will be slightly higher than the price quoted by the NEST oracle.

    function buy(
address tokenAddress,
uint lever,
bool orientation,
uint nestAmount
) external payable override
InputtypeDetail
tokenAddressaddressTarget token address, 0 means eth
leveruintLever of future
orientationbooltrue: call, false: put
nestAmountuintAmount of paid NEST

Sell Future

When already having a NEST futures position, users could use the sell function to sell a futures position of any amount. Of course, the amount sold could not exceed the position held.

    function sell(uint index, uint amount) external payable override
InputtypeDetail
indexuintIndex of future
amountuintAmount to sell

Futures Liquidation

Futures contracts are cleared using a position-by-position mechanism, which means that each position in a futures contract is cleared independently. When the margin on a futures contract position falls below the liquidation price, a liquidator will liquidate it. Anyone can become a liquidator of NEST and the liquidator receives the residual value of the contract after it has been liquidated.

The liquidation price of a futures contract is calculated as follows.

NEST futures are using the isolated margin mode, which means each futures position is liquidated independently. When the margin on a futures position falls below the liquidation price, the liquidator will liquidate it. Anyone could become the liquidator of NEST and the liquidator receives the residual value of the contract after it has been liquidated.

The liquidation price of a futures contract is calculated as follows.

image4

  • P0: Futures open price
  • L: Leverage ratio
  • C: Liquidation rate
  • T: Position holding time
  • u: Risk free rate in NEST network
    function settle(uint index, address[] calldata addresses) external payable override
InputtypeDetail
indexuintIndex of future
addressesaddress[]Target addresses

Get Futures Index

Futures index contains leverage and direction information of the futures contract, and it can be used as an input parameter in other functions.

    function getFutureInfo(
address tokenAddress,
uint lever,
bool orientation
) external view override returns (FutureView memory)
InputtypeDetail
tokenAddressaddressTarget token address, 0 means eth
leveruintLever of future
orientationbooltrue: call, false: put
OutputtypeDetail
indexuintfuture index
tokenAddressaddressTarget token address, 0 means eth
leveruintLever of future
orientationbooltrue: call, false: put

Options

Options contracts include four functions:

Open Options

NEST provides infinite European options for users. Users could buy a NEST option without any commission. Most options market markers only have several expiry dates and strike amounts for users to choose, but NEST options ' expiry date and strike price are set by the user, which is much more flexible.

    function open(
address tokenAddress,
uint strikePrice,
bool orientation,
uint exerciseBlock,
uint nestAmount
) external payable override
InputtypeDetail
tokenAddressaddressTarget token address, 0 means eth
strikePriceuintThe exercise price set by the user. During settlement, the system will compare the current price of the subject matter with the exercise price to calculate the user's profit and loss
orientationbooltrue: call, false: put
exerciseBlockuintAfter reaching this block, the user will exercise manually, and the block will be recorded in the system using the block number
nestAmountuintAmount of paid NEST

Exercise Option

When there is already an option position and the option has expired, the user can choose to exercise the option at any subsequent time if the final payoff is greater than 0

    function exercise(uint index, uint amount) external payable override
InputtypeDetail
indexuintIndex of option
amountuintAmount of option to exercise

Sell Option

When there is already an option position and the option has not expired, the user could call the sell function and sell the option to the NEST network, and thereby receive an immediate gain.

    function sell(uint index, uint amount) external payable override
InputtypeDetail
indexuintIndex of option
amountuintAmount of option to sell

Find the Options

The find function allows users to find the options order data for a specific address.

    function find(
uint start,
uint count,
uint maxFindCount,
address owner
) external view override returns (OptionView[] memory optionArray)
InputtypeDetail
startuintGiven the order index of the address, and it will return all the options bought after this given order.
countuintMaximum number of records returned
maxFindCountuintFind records at most
owneraddressTarget address
OutputtypeDetail
indexuintOption index
tokenAddressaddressaddress Target token address, 0 means eth
strikePriceuintThe price set by the user. The system will compare the current price with the strike price to calculate the user's profit and loss
orientationboolTrue: call, False: put
exerciseBlockuintAfter reaching this block, the user will exercise manually, and the block will be recorded in the system using the block number
balanceuintOption shares
owneraddressTarget address

Contract Address

NEST Contract deployment addresses are as follows:

Ethereum Mainnet

ContractContract Address
nestOptions0x10F7f08A278e495CBCa66388A2400fF0deFe3122
nestFutures0x0E48e068958b3E683a664FB81697F7046f83C3A8
nestBuybackPool0x7b65629A811eBB0d6CC99bDc4d1d606f8F707125

BNB Smart Chain Mainnet

ContractContract Address
nestOptions0x12858F7f24AA830EeAdab2437480277E92B0723a
nestFutures0x8e32C33814271bD64D5138bE9d47Cd55025074CD
nestBuybackPool0x8AA36CF9CD7e88b63F32c53C66BFaDd409367B2f

Error Codes

NestFutures.sol

CodeMeaning
NF:too much tokenConfigsThis error occurs when the cumulative number of registered tokens exceeds 65535. Only governance rights are available, this interface is not available to normal users.
NF:existsOpen futures supported leverage, including call and put directions. This error occurs when futures with the same token, same leverage ratio and same direction are already registered. This interface is only available for governance usage, not available to normal users.
NF:not existThis error occurs when the futures attempt to be bought, sold or liquidated but the futures position does not exist.
NF:at least 50 NESTThis error occurs when the number of NEST is less than 50 when buying futures.
NF:lever must greater than 1This error occurs when attempting to liquidate futures with a leverage ratio not greater than 1.
NF:lever too largeThis error occurs when attempting to open a futures product with a leverage ratio over 2^32 (in the application the highest futures' leverage ratio is x5)
NF:can't convert to uint128This error occurs when attempting to transform to uint128 for a value that exceeds the maximum range that can be represented by uint128. The user's futures balance exceeding this range will result in this error.

NestOptions.sol

CodeMeaning
NO:too much tokenRegistrationsThis error occurs when the cumulative number of registered tokens exceeds 65535. Only governance rights are available, this interface is not available to normal users.
NO:at maturityThis error occurs when the block number has not reached the expiry date's block number.
NO:not ownerThis error occurs when trying to sell an option whose owner is not the account that initiated the trade.
NO:can't convert to 64bitsThis error occurs when the user specifies a strike block that is too large, resulting in the product of volatility and time exceeding 0x6F05B59D3B2000000000000000000000000.
NO:can't convert to int128This error can occur when the intermediate result is too large (larger than the maximum value that can be represented by int128) when calculating the option price (value). This could result from a large strike block, a big gap between the option strike price and the current price.
NO:can't convert to uintThe ABDKMath64x64 library is referenced when calculating options and the intermediate results may logically be negative. To avoid underflow errors, this error will occur when calculating option prices with negative numbers.
NO:can't convert to uint112This error occurs when attempting to transform to uint112 for a value that exceeds the maximum range that can be represented by uint112. When the user option balance exceeds this range, it will occur.
NO:exerciseBlock too smallThis error occurs when the interval between the strike block number and the current block number is too small (should be more than one month in time approximately) when buying options or estimating option prices.
NO:!accountsThis exception occurs when the number of users participating in the option exceeds 2^32 (approximately 4 billion) and there are too many user accounts.

NestVault.sol

CodeMeaning
NV: exceeded allowanceThis error occurs when the Options and Futures modules have set the maximum number of NSET that can be won on a single trade (10 million for Options and Futures).

Note: The error codes listed above does not list all possible errors

  1. Error messages in common libraries referenced by the contract are not listed, e.g. TransferHelper.
  2. Arithmetic overflow is not listed, e.g. divided by 0 errors.
  3. External causes are not listed, e.g. out of gas, unspecified interface (such as transferring to a non-ERC20 address)