Staking and Un-staking Mechanisms
What happens behind the scenes when a user stakes or unstakes with Kintsu
Last updated
What happens behind the scenes when a user stakes or unstakes with Kintsu
Last updated
Staking on Kintsu involves the following order of operations:
Gas Token Deposit: User deposits Gas Tokens into the Vault contract by initiating a stake transaction.
Nomination Pool Forwarding: Vault contract checks the Registry contract to retrieve the current Target Weights. Vault contract checks all participating Nomination Pools to see how many Gas Tokens are currently allocated to each. The Vault uses these sums to calculate the Current Weights (the percentage of the Total Pool held by each Nomination Pool). Vault contract uses the Constant Retargeting Algorithm to calculate how many of the newly submitted Gas Tokens to forward to each of the Nomination Pools, and forwards them accordingly.
Validator Forwarding: Nomination Pools forward the Gas Tokens to their respective Validators, who execute the bonding (staking) action on the network consensus level. This part happens outside the scope of Kintsu's contracts, and is enforced by the blockchain.
Receipt Token Issuance: Vault contract calculates the correct number of new shares (sTokens ) to create, using the current Redemption Ratio, and transfers them to the user. These sTokens serve as a receipt entitling the holder to their share of the Total Pooled. The sTokens are fungible, can be traded and used elsewhere on the network, and can be used to redeem Gas Tokens during the unstaking process. The number of new sTokens created, denoted here as newShares, is as follows:
where newStake is the number of newly deposited Gas Tokens, totalShares is the Total Shares and totalPooled is the Total Pooled.
To see how this translates into a user's experience staking on Kintsu, see our docs on Staking with Kintsu.
As the Vault accepts new Gas Tokens for staking it must delegate them across the participating Delegation Pools in such a way that aims to keep the amount delegated to each Delegation Pool consistent with the Target Weights stored in the Registry. In order to to do this, the Vault retrieves the Target Weights from the Registry and compares them to the current percentages of the Total Pool held by each of the participating Delegation Pools at that time. The Vault then calculates how much of the newly added Gas Tokens should be delegated to each Nomination Pool in order to bring the current weights closer to the Target Weights stored in the Registry.
During the un-staking process, the Vault again uses the Target Weights from the Registry to decide how many Gas Tokens to redeem from
Kintsu involves some clever mechanisms to enable unstaking at scale, despite network-level constraints such as the Cooldown Period and Daily Unbonding Request Limits.
In order to facilitate unstaking at scale despite the above constraints, the Kintsu protocol batches many users' unbonding requests together before submitting them downstream to the Validators. The batching period's length may vary from blockchain to blockchain, and depends on each blockchain's unbonding restrictions.
A user may cancel their unbonding request (and receive their sTokens back from escrow) at any time up until the end of the Batching Period during which they made the request. After that point, the request has been submitted to the Validators and the Gas Tokens will be unbonded.
Unstaking on Kintsu involves the following order of operations:
Initiation: User calls Request Unlock, during which they submit their sTokens to the Vault.
Batching Period: The Vault holds the user's sTokens in escrow until the Batching Period ends. The user can cancel their request at any time up until the batching is complete by calling cancelUnlockRequest.
Vault Sends Batch Unlock Requests: Once the batching period is complete, the Vault calls the sendBatchUnlockRequests function.
Cooldown Period: User must wait until Cooldown Period is over so that Validators are able to unbond the Gas Tokens.
Tokens returned to Vault: Anyone on the network can execute the delegateWithdrawUnbonded call, which forwards all newly unbonded Gas Tokens held by the Nomination Pools back to the Vault, which can return them to users. This will typically happen once per Batching Period.
Token redemption: This is where the user can redeem their Gas Tokens, including accrued yield. In order for this to happen, the Vault must have custody of the unbonded Gas Tokens. There are two scenarios here:
If the newly unbonded Gas Tokens are still held in Nomination Pools when a user tries to redeem theirs, the user must call redeemWithWithdraw. This first executes a delegateWithdrawUnbonded call, during which the Vault collects the unbonded Gas Tokens from each of the Nomination Pools, and then executes the redeem call, which forwards the user's entitled portion of those Gas Tokens from the Vault to the user's wallet.
If the Vault already has custody of the Gas Tokens, the user can make a redeem call to the Vault, which sends the user's newly unstaked Gas Tokens to their wallet. This scenario would happen when someone else has already executed the delegateWithdrawUnbonded call for the Batching Period.
Note: when a user uses the Kintsu GUI to redeem their claimable Gas Tokens after the Cooldown Period, the GUI will intelligently decide whether to call redeemWithWithdraw or whether to simply call redeem.
To see how this translates into a user's experience staking on Kintsu, see our docs on Unstaking with Kintsu.
In order for the user to receive Gas Tokens from the protocol, the Vault must make requests to each of the Nomination Pools, who in turn make requests to the Validators, to "unbond" (unstake) Gas Tokens from network staking. These requests are enforced by the network and by the protocol, but they don't happen immediately.