This documentation portal is currently undergoing updates to align with the IoTeX 2.0 Whitepaper release. Information provided here may be incomplete, or out-of-date. Please use this portal for preliminary reference only, and check out the official IoTeX 2.0 Whitepaper for updated information.
With the adoption of IIP13, that allows representing IoTeX staking buckets as Non-fungible Tokens (NFTs), liquid staking solutions that rely on smart contracts to manage their stakes via system-level smart contracts can now be developed on IoTeX.
Staking in the IoTeX blockchain was originally implemented as part of the protocol, which prevents direct interaction of smart contracts with staking functionalities. While IIP12 addressed the the possibility of accessing the full staking protocol from the Ethereum JSON API by means of a virtual contract, that one is not an actual EVM smart contract, and thus it is not visible and cannot be called by other smart contracts.
In this section we will highlight the details of how Staking as NFT works and provide documentation on how to engage with staking buckets to offer liquid staking solutions on IoTeX.
How it works
Liquid Staking has been enabled with the implementation of a so called "System Staking Contract". This is the primary contract responsible for providing the functionalities laid out in IIP-13. It manages tasks such as creating, modifying, transferring, and querying staking Buckets and their associated NFT tokens.
In the context of staking as NFT, a "Bucket Type" represent a specific staking configuration, including the deposit amount, the preset lock duration, and the status of the StakeLock option. Currently, three bucket types are supported in the implementation, that are listed below:
Examples
In this section we explore in details how to interact with the SystemStaking contract from another contract to enable liquid staking functionalities.
Setting up the Environment
When developing your Liquid Staking contract, ensure you include the ISystemStaking contract interface from the IIP13 repository.
Ensure your client contract implements IERC721Receiver, as it will receive the NFT Bucket from the SystemStaking contract upon staking creation.
import"./ISystemStaking.sol"; import"@openzeppelin/contracts/token/ERC721/IERC721Receiver.sol";contract MyLiquidStaking is IERC721Receiver {// Holds the System staking contract address ISystemStaking public SystemStakingContract;// Constructor// Address for IoTeX Testnet: 0x52ab0fe2c3a94644de0888a3ba9ea1443672e61f// Address for IoTeX Mainnet: 0x68db92a6a78a39dcaff1745da9e89e230ef49d3dconstructor(address _SystemStakingContractAddress) {// Set the System staking contract address SystemStakingContract =ISystemStaking(_SystemStakingContractAddress);...
Staking IOTX from your Contract
The SystemStaking contract provides three stake functions that enable the creation of a new staking bucket in different scenarios. Each of them returns the id assigned to the newly created bucket, which coincides with the NFT token id:
// Create a single staking bucket with a specific duration and delegatefunctionstake(uint256_duration,address_delegate) externalpayablereturns (uint256);// Create multiple staking buckets, each with the same amount and duration, for different delegates:functionstake(uint256_amount,uint256_duration,address[] memory_delegates) externalpayablereturns (uint256);// Create several staking buckets, each with the same amount and duration, all assigned to a single delegatefunction stake(uint256 _amount, uint256 _duration, address _delegate, uint256 _count) external payable returns (uint256);
For instance, to generate a new NFT bucket with a 100 IOTX deposit, assigned to an eligible IoTeX delegate, you would use:
uint256 tokenId = SystemStakingContract.stake{value: msg.value}(1572480,// 91 days in IoTeX blocks0xCD397ac1364676d8553D9ce78e4B0d27f236926d// Owner address of the delegate );
Note on Staking Amount and Duration
When creating a new staking bucket, it's important to ensure that the chosen stake amount and duration match one of the combinations the SystemStaking contract supports, otherwise the action will revert. These combinations are called "Bucket Types". For the best user experience, consider fetching the list of all supported bucket types from your dApp frontend to guide users during the staking process.
To obtain the current list of bucket types, use the following methods from the SystemStaking contract:
Copy
// Get the total number of bucket typesfunctionnumOfBucketTypes() externalviewreturns (uint256);// Retrieve the paginated list of supported bucket typesfunctionbucketTypes(uint256_offset,uint256_size) externalviewreturns (BucketType[] memory);
Note on Delegate Owner Addresses
When creating a new staking bucket or changing the delegate of an existing bucket, it's important to input the delegate's "owner address," also referred to as the delegate's "profile address." This address uniquely identifies each IoTeX delegate. Ensure that the addresses you utilize actually belong to delegates and that they are eligible (meaning their self-stake amount is at least 1.2M IOTX). Failing to do so will cause a contract action revert.
To facilitate this process in your frontend, leverage the IoTeX Staking virtual contract to access details regarding delegate names, addresses, and self-staking data. The relevant method is listed below, but for comprehensive details, please refer to the IoTeX Staking Integration section ->
When a new staking bucket is created using the SystemStaking contract, the StakeLock option is enabled by default. In this state, the bucket remains locked for its designated lock duration, and this duration does not decrease over time. While the activated StakeLock option ensures higher rewards, if you plan to unstake a bucket at a specific time, you must deactivate the StakeLock option for that bucket well in advance, specifically the same number of days as the lock duration.
// Disables StakeLock for a bucketfunctionunlock(uint256_tokenId) external// DisablesStakeLockformultiplebuckets (mustbeownedbythesameowner)functionunlock(uint256[] calldata_tokenIds) external// EnablesStakeLockforabucketandsetsanewlockduration (mustbe >= totheremaininglocktime)functionlock(uint256_tokenId,uint256_duration) external;// Enables StakeLock for multiple bucket and sets a new lock duration (same for all)functionlock(uint256[] calldata_tokenIds,uint256_duration) external;
Unstaking a bucket
Before you can withdraw the IOTX deposit, unstaking a bucket is a prerequisite. For a bucket to qualify for unstaking, it must be in the "unlocked" status. This indicates that the StakeLock option for that specific bucket must have remained deactivated throughout the entire lock duration of the bucket. Once initiated, the unstaking process lasts 3 days (equivalent to 51,840 IoTeX blocks). During this period, the bucket remains locked, does not generate staking rewards, and is immune to any operations.
// Unstakes a bucketfunctionunstake(uint256_tokenId) external;// Unstakes multiple bucketsfunctionunstake(uint256[] calldata_tokenIds) external;
Withdrawing a bucket
Before you can withdraw a deposit, it must have completed the unstaking process.
// Withdraws a staking bucket deposit to a certain recipient addressfunctionwithdraw(uint256_tokenId,address payable _recipient) external;// Withdraws multiple staking bucket deposits to a certain recipient addressfunctionwithdraw(uint256[] calldata_tokenIds,address payable _recipient) external;
These are the foundational steps for interacting with IIP-13 contracts, that allows the creation of Liquid Staking solutions. Liquid staking allows users to access the benefits of staking in a blockchain network while still maintaining liquidity and flexibility over their staked assets, which create a more attractive and versatile staking experience.
For more advanced operations and deeper insights, please refer to