StakeManager Contract

Details about StakeManager Contract, function, service fee, reward distribution

What is StakeManager Contract

The StakeManager contract serves as the core of the Bitkub Chain's staking mechanism. All staking-related actions that users can interact with can be executed through this contract. It enables users to stake, unstake, restake, claim rewards, and configure their own ValidatorShare contracts. The contract also handles reward distribution and slashing, and the related information can be found in the events emitted for clarity. The StakeManager contract operates in tandem with StakeManagerStorage, StakeManagerVault, SlashManager, ValidatorShareFactory, and BKCValidatorSet contracts. It is not designed to hold any funds through its own abilities. As the StakeManager contract is merely an implementation, it can be replaced; all data and funds are stored in other contracts.

Functions

There are two main functions:

• Staking-related

• Claim Rewards-related

1. Staking-related

including the following method:

1.1 Stake

1.2 Unstake

1.3 Restake

1.1 Stake

stake(address signer, bool delegation) payable

• signer - The address of the EVM instance.

• delegation - If true, create a ValidatorShare contract and enable delegation. If false, stake in the solo node.

• payable - Native KUB required. Cannot exceed uint128.

This method requires native KUB to be sent as a value along with the transaction that calls this method.

Upon staking, an NFT will be minted and given to the staker (refer to validator staking), and the staked funds will be transferred to the StakeManagerVault contract. The NFT represents ownership of the newly created node, including the states, configurations, ValidatorShare contract, etc., but not the EVM instance running to operate the chain.

If the delegation flag is set to true, a pool node will be created, along with the ValidatorShare contract of the node, allowing delegators to delegate their funds to your newly created node. If the delegation flag is set to false, a solo node will be created, and delegation on the node will not be possible. The NFT of a solo node cannot be transferred, and the NFT of a pool node can only be transferred through special means.

On creation, the infrastructure fee and the commission fee of the pool node will be set to the default value 0%. You can change the commission fee by yourself after the node creation at StakeManager contract on the updateCommissionRate() method. The initial status of the node will be active. The signer's address of the newly created node will be added to the minimal validator set and can be selected as a block validator in a span.

The active status means the node is staked. It does not guarantee that the EVM instance of the node is running, nor that the signer's address is in the minimal validator set.

The signer address cannot be used or become a node again unless the node is unstaked first.

Summary

• If the delegation flag is set to true, and the value of KUB is 100,000 KUB or more. A pool node, as well as a ValidatorShare contract for delegation, will be created.

• If the delegation flag is set to false, and the value of KUB is 10 KUB or more. A solo node will be created.

• The infrastructure fee will not be applied to solo nodes.

• The token ID of the NFT minted to the staker upon creation is the node's validator ID.

• The default infrastructure fee of a node is 0% and cannot be set by the owner of the NFT.

• The default commission fee of a node is 0%, and the owner of the NFT can later set their commission fee.

• The signer address cannot be used if the validator node is still active.

Limitations:

• The total amount of pool nodes is limited to 50 nodes.

• The total amount of solo nodes is limited to 100 nodes.

1.2 Unstake

unstake(uint256 validatorId)

• validatorId - The token ID of the NFT received upon staking.

Only owners of the NFTs can invoke this function, and the input validator ID must correspond to the token ID of one of the NFTs in the caller’s possession.

Unstaking is not allowed for inactive nodes, and the official node cannot be unstaked using this function.

When a node is unstaked, the ownership NFT of the node will be burned (sent to address zero), and the staked funds will be transferred back from the StakeManagerVault contract to the owner. Additionally, the node will be removed from the minimal validator set, and its status will be set to unstaked, resulting in not being selected as a block validator anymore. The signer address will also now be available to be used again.

All rewards earned by the model's staker will be sent to the node owner, including validator rewards, validator commissions, and delegator commissions. In the case of an unstaked solo node, there will be no validator commission or delegator commission.

The delegation flag inside the ValidatorShare contract will be set to false, preventing further delegation on the ValidatorShare contract side. However, delegators can still claim their rewards and undelegate their funds. The number of nodes will decrease by one, based on the type of the unstaked node.

Summary

• Only NFT owners can use this function; the validator ID must match an NFT in their possession.

• When a node is unstaked, its ownership NFT is burned, and staked funds return to the owner from the StakeManagerVault.

• Unstaking removes the node from the minimal validator set, making it ineligible for block validation.

• Node owners receive all rewards, including validator and delegator commissions.

• Unstaking a solo node means no validator or delegator commission.

• The ValidatorShare contract's delegation flag is set to false, stopping further delegation, but rewards claiming and undelegation are still possible.

• The number of nodes decreases by one, depending on the type of unstaked node.

1.3 Restake

restake(uint256 validatorId) payable

• validatorId - The token ID of the NFT received upon staking.

• payable - Native KUB required.

Only owners of the NFTs can call this function, and the input validator ID must correspond to the token ID of one of the NFTs in the caller’s possession. The restaking of an inactive node is not possible.

This function increases the staked amount of the node with the funds sent in the transaction. If the node is not part of the minimal validator set before this function is called, and the final staked amount is greater than or equal to the minimum deposit amount, the signer address of the node will be included in the set. The funds will be transferred to the StakeManagerVault contract.

Warning: Retrieving a portion of your staked funds is not possible. The only way to retrieve your staked funds is to call the unstake() function.

Summary

• Only NFT owners can use this function; the validator ID must match an NFT in their possession.

• Inactive nodes cannot be restaked.

• The function increases the node's staked amount using the sent funds.

• If the node is not part of the minimal validator set before calling the function, and the final staked amount meets the minimum deposit requirement, the node's signer address is added to the set.

2. Claim Rewards-related

including the following sub-function:

2.1 ClaimRewards

2.2 ClaimCommissionRewards

2.1 ClaimRewards

claimRewards(uint256 validatorId) 

• validatorId - The token ID of the NFT received upon staking.

Only owners of the NFTs can call this function, and the input validator ID must be the token ID of one of the NFTs in the caller’s possession.

The reward from the node that is not active cannot be claimed. The function is solely for claiming the validator reward, which will be transferred only to the owner.

2.2 ClaimCommissionRewards

claimCommissionRewards(uint256 validatorId) 

• validatorId - The token ID of the NFT received upon staking.

Only owners of the NFTs can call this function, and the input validator ID must be the token ID of one of the NFTs in the caller’s possession.

The reward from the node that is not active cannot be claimed. The function is solely for claiming the commission reward, which will be transferred only to the owner.

Service Fees

There are two types of service fees: the infrastructure fee and the commission fee. The rates of both service fees will be combined through addition, not multiplication. This means that it is possible for a delegator to receive no reward at all when both the infrastructure fee and the commission fee are set at 50.00%.

1. Infrastructure Fee

This fee is only applied to the official node and pool nodes. The rewards for solo nodes remain unaffected by the infrastructure fee. The maximum value for the infrastructure fee is 50.00%. The rate's default value is 0%, and it can only be modified by the committee and cannot be altered by the owner of the node. The fee is solely claimable by the committee.

2. Commission Fee

This fee is applied to every node. The maximum value for the commission fee is 50.00%. The default value of the rate is 0%, and only the node owner can modify it. The fee can be claimed solely by the owner of the node.

Reward Distribution

The Distribution Reward Function in the StakeManager contract plays a crucial role in distributing rewards earned by validators during block validation. Validators receive incentives for their services but are required to distribute a portion of these rewards to delegators. Before distribution, deductions such as infrastructure and validator staking fees are accounted for. The function then allocates the remaining rewards to delegators based on their stake in the network.

1. Original Rewards Calculation:

The distribution first calculates rewards without any deductions for validators and delegators. These rewards are determined by the ratio of funds between the staker's own funds and the delegated funds.

After calculating the original rewards, the distribution process applies deductions if necessary.

uint128 originalValidatorReward = uint128(
      (uint256(validatorsStake_) * reward_) / combinedStakePower_
 ); 
uint128 originalDelegatorReward = reward_ - originalValidatorReward;

The original rewards are saved and used for future calculations.

2. Infrastructure Fee:

If the infrastructure fee is set, a part of the rewards is allocated to support the network's infrastructure.

The infrastructure fee for each portion is calculated by multiplying the infrastructure fee by the original reward. The total infrastructure fee is calculated by combining the validator reward portion with the delegator reward portion. The actual validator reward and delegator reward are calculated by subtracting their respective infrastructure fees from the original rewards.

if (infraCommissionRate_ > 0) {
     {
        uint128 validatorInfraCommission = uint128(
         (uint256(originalValidatorReward) *         
             infraCommissionRate_) / MAX_RATE);
        uint128 delegatorInfraCommission = uint128(
            (uint256(originalDelegatorReward) *                            
             infraCommissionRate_) / MAX_RATE);

        actualValidatorReward -= validatorInfraCommission;
        actualDelegatorReward -= delegatorInfraCommission;

        infraCommission +=
            validatorInfraCommission +
            delegatorInfraCommission;
    }
}

3. Commission Fee:

If the commission fee is set, the same process as the infrastructure fee calculation will be applied in the same manner to the remaining rewards.

The fee for each portion is combined in the infrastructure fee calculation process, but in this calculation, the fee from each portion is separated into two: the commission fee from the validator reward portion and the commission fee from the delegator reward portion.

ValidatorShare Contract’s Configurations

There are three settings that an owner of a node can configure in the ValidatorShare contract through the StakeManager contract: validator commission rate, minimum delegated amount, and delegation flag.

UpdateCommissionRate

updateCommissionRate(uint256 validatorId, uint256 newCommissionRate)

• validatorId - The token ID of the NFT received upon staking.

• newCommissionRate - The new value of the commission rate.

This function allows you to change the validator commission rate. The minimum value is 0 (0%), and the maximum value is 5000 (50%). If the value is 1234, it will result in 12.34%.

or commission rate affects both the validator and delegator rewards. The higher this value, the more the rewards are reduced. The taken portions are combined and referred to as the commission fee.

UpdateMinDelegated

updateMinDelegated(uint256 validatorId, uint256 newMinDelegated)

• validatorId - The token ID of the NFT received upon staking.

• newMinDelegated - wei - The new value of the minimum delegated amount.

This function allows you to change the minimum delegated amount. The minimum delegated amount is the expected minimum amount of delegated funds within a node.

This value is considered during delegation and undelegation. For delegation, if the final total delegated amount is less than the minimum delegated amount, the transaction will be reverted. For undelegation, if the final total delegated amount is less than this value, all delegated amounts will be undelegated instead of the desired value. The minimum delegated amount does not affect the existing delegated amounts of the users until delegation or undelegation is carried out by the users.

UpdateValidatorDelegation

updateValidatorDelegation(uint256 validatorId, bool delegation)

• validatorId - The token ID of the NFT received upon staking.

• delegation - If this flag is true, more delegation is allowed. If false no more delegation is allowed.

This function allows you to change the delegation flag of a node. The delegation flag indicates whether a node allows delegation by delegators.

If the delegation flag is set to false, no more delegations will be possible. However, the existing users, before the delegation flag was set to false, will still be able to undelegate and claim their rewards.