From ffc7ce6bd53e578f4204214d793e609a4c834e3e Mon Sep 17 00:00:00 2001 From: forcodedancing Date: Sun, 4 Feb 2024 09:29:08 +0800 Subject: [PATCH] docs: add docs for BSC staking and gov (#271) * docs: add docs for BSC staking and gov * fix review comments * add docs and fix review comments --- .../developers/crosschain-redelegation.md | 31 ++++ docs/bcfusion/developers/gov.md | 107 +++++++++++++ docs/bcfusion/developers/staking.md | 140 +++++++++++++++++ docs/bcfusion/validators/gov.md | 104 +++++++++++++ docs/bcfusion/validators/slash.md | 55 +++++++ docs/bcfusion/validators/staking.md | 143 ++++++++++++++++++ sidebars.js | 17 +++ 7 files changed, 597 insertions(+) create mode 100644 docs/bcfusion/developers/crosschain-redelegation.md create mode 100644 docs/bcfusion/developers/gov.md create mode 100644 docs/bcfusion/developers/staking.md create mode 100644 docs/bcfusion/validators/gov.md create mode 100644 docs/bcfusion/validators/slash.md create mode 100644 docs/bcfusion/validators/staking.md diff --git a/docs/bcfusion/developers/crosschain-redelegation.md b/docs/bcfusion/developers/crosschain-redelegation.md new file mode 100644 index 0000000000..e29eb974b2 --- /dev/null +++ b/docs/bcfusion/developers/crosschain-redelegation.md @@ -0,0 +1,31 @@ +# Crosschain Redelgation + +To migrate the exisiting delegation from BNB Beacon chain (the old BSC staking) to the new BNB smart chain native +staking, crosschain redelegation cal be used. +A user can submit a message called `MsgSideChainStakeMigration` to the Beacon chain. Underlying, it will unbound +the delegation immediately on BC (without wating unbond period), sends a cross-chain transaction to BSC to delegate +to a native BSC validator. + +The defination of `MsgSideChainStakeMigration` is as the blow. + +```go +type MsgSideChainStakeMigration struct { + ValidatorSrcAddr sdk.ValAddress `json:"validator_src_addr"` + ValidatorDstAddr sdk.SmartChainAddress `json:"validator_dst_addr"` + DelegatorAddr sdk.SmartChainAddress `json:"delegator_addr"` + RefundAddr sdk.AccAddress `json:"refund_addr"` + Amount sdk.Coin `json:"amount"` +} +``` + +- `ValidatorSrcAddr`: validator address on the BC (bech32 format) +- `ValidatorDstAddr`: new validator operator address on the BSC (eth format) +- `DelegatorAddr`: delegation beneficiary address on the BSC (eth format) +- `RefundAddr`: delegator (message sender) address on the BC (bech32 format) +- `Amount`: the BNB amount for redelgation (decimal 8) + +**Be noted**: please make sure input the `DelegatorAddr` correctly, otherwise you will lose the fund permanently. + +For more details, please refer to the codes: +https://github.com/bnb-chain/bnc-cosmos-sdk/blob/bc-fusion/x/stake/types/stake_migration.go#L29 + diff --git a/docs/bcfusion/developers/gov.md b/docs/bcfusion/developers/gov.md new file mode 100644 index 0000000000..d6e07c4f7b --- /dev/null +++ b/docs/bcfusion/developers/gov.md @@ -0,0 +1,107 @@ +# Governance + +This guide provides an overview of the key operations of governance, including creating proposals, +casting votes, and executing proposals. For the general introduction of governance, +please refer to [Governance Mechanism](../validators/gov.md). + +## Contract + +The BSC governance facilitates decentralized decision-making within the BSC ecosystem, utilizing two primary +smart contracts: `GovToken` for governance token management and `Governor` for proposal management and voting. + +- `GovToken`: Manages governance tokens, enabling holders to participate in governance decisions. It supports syncing + token balances with staked assets and delegating voting rights. ( + Address: `0x0000000000000000000000000000000000002005`) + +- `Governor`: Manages the creation, voting, and execution of governance proposals. It also ensurs only eligible + participants can propose changes and vote. (Address: `0x0000000000000000000000000000000000002004`) + +## Create Proposal + +To create a proposal, you need to call the `propose` function of `Governor` with the following parameters: + +```solidity +function propose(address[] memory targets, uint256[] memory values, bytes[] memory calldatas, string memory + description) public returns (uint256 proposalId) +``` + +- `targets`: Contract addresses the proposal will interact with. +- `values`: BNB values (in wei) for each call. +- `calldatas`: Encoded function calls. +- `description`: Description of the proposal. + +## Cast Vote + +To cast a vote, you need to call the `castVote` function of `Governor` with the following parameters: + +```solidity +function castVote(uint256 proposalId, uint8 support, string memory reason) public returns (uint256) +``` + +- `proposalId`: ID of the proposal. +- `support`: Vote choice (e.g., for, against, abstain). +- `reason`: (Optional) Reason for your vote. + +## Check Proposal State + +To get the state of a proposal, you need to call the `state` function of `Governor` with the following parameters: + +```solidity +function state(uint256 proposalId) public view returns (ProposalState) +``` + +- `proposalId`: ID of the proposal. + +## Queue Proposal + +To schedules the proposal for execution, you need to call the `queue` function of `Governor` with the following +parameters: + +```solidity +function queue(address[] memory targets, uint256[] memory values, bytes[] memory calldatas, bytes32 descriptionHash) +public returns (uint256 proposalId) +``` + +- `targets`: Contract addresses the proposal will interact with. +- `values`: Ether values (in wei) for each call. +- `calldatas`: Encoded function calls. +- `descriptionHash`: Hash of the description of the proposal. + +## Execute Proposal + +To apply the changes after the timelock delay, you need to call the `execute` function of `Governor` with the following +parameters: + +```solidity +function execute(address[] memory targets, uint256[] memory values, bytes[] memory calldatas, bytes32 descriptionHash) +public payable returns (uint256) +``` + +- `targets`: Contract addresses the proposal will interact with. +- `values`: Ether values (in wei) for each call. +- `calldatas`: Encoded function calls. +- `descriptionHash`: Hash of the description of the proposal. + +## Delegate Vote + +To delegate voting power to someoneles, you need to call the `delegateVote` function of `GovToken` with the following +parameters: + +- **Delegator address**: The address of the delegator, who delegates their voting power to another address. +- **Delegatee address**: The address of the delegatee, who receives the voting power from the delegator and + participates in governance on their behalf. + +```solidity +function delegateVote(address delegator, address delegatee) external +``` + +- `delegator`: The address of the delegator, who delegates their voting power to another address. +- `delegatee`: The address of the delegatee, who receives the voting power from the delegator. + +## Contract ABI + +For the full interfaces of `Governor`, please refer +to [the ABI file](https://github.com/bnb-chain/bsc-genesis-contract/blob/bc-fusion/abi/Governor.abi). + +For the full interfaces of `GovToken`, please refer +to [the ABI file](https://github.com/bnb-chain/bsc-genesis-contract/blob/bc-fusion/abi/govtoken.abi). \ No newline at end of file diff --git a/docs/bcfusion/developers/staking.md b/docs/bcfusion/developers/staking.md new file mode 100644 index 0000000000..92dcc25b94 --- /dev/null +++ b/docs/bcfusion/developers/staking.md @@ -0,0 +1,140 @@ +# Staking + +This guide provides an overview of the key operations of staking, including creating validators, +editing validator information, and performing delegation operations. +For the general introduction of staking, please refer to [Staking Mechanism](../validators/staking.md). + +## Contract + +The BSC staking mainly uses the smart contracts `StakeHub` for validator management and delegation management. + +- `StakeHub`: Manages validator creations, user delegations, and executs penalty for validator slash. + (Address: `0x0000000000000000000000000000000000002002`) + +## Creating a Validator + +To create a validator, use the `createValidator` function with the following parameters: + +```solidity + function createValidator( + address consensusAddress, + bytes calldata voteAddress, + bytes calldata blsProof, + Commission calldata commission, + Description calldata description +) external payable +``` + +- `consensusAddress`: The consensus address of the validator. +- `voteAddress`: The vote address of the validator. +- `blsProof`: The BLS signature as proof of the vote address. +- `commission`: The commission structure, including rate, maxRate, and maxChangeRate. +- `description`: The description of the validator, including moniker, identity, website, and details. + +**Note**: Creating a validator requires locking 1 BNB, and the transaction must be sent with a sufficient BNB amount to +cover this lock amount plus any self-delegation, in total 2001BNB. + +## Editing Validator Information + +### Edit Consensus Address + +To change the consensus address of a validator, use the `editConsensusAddress` function with the following paramters: + +```solidity +function editConsensusAddress(address newConsensusAddress) external +``` + +- `newConsensusAddress`: The new consensus address of the validator. + +### Edit Commission Rate + +To update the commission rate of a validator, use the `editCommissionRate` function with the following paramters: + +```solidity +function editCommissionRate(uint64 newCommissionRate) external +``` + +- `newCommissionRate`: The new commission structure, including rate, maxRate, and maxChangeRate. + +### Edit Description + +To update the description of a validator, use the `editDescription` function with the following parameters: + +```solidity +function editDescription(Description memory newDescription) external +``` + +- `newDescription`: The new description of the validator, including moniker, identity, website, and details. + +### Edit Vote Address + +To change the vote address of a validator, use the `editVoteAddress` function with the following parameters: + +```solidity +function editVoteAddress(bytes calldata newVoteAddress, bytes calldata blsProof) external +``` + +- `newVoteAddress`: The new vote address of the validator. +- `blsProof`: The BLS signature as proof of the vote address. + +## Delegation Operations + +### Delegate + +To delegate BNB to a validator, call the `delegate` function with the following parameters: + +```solidity +function delegate(address operatorAddress, bool delegateVotePower) external payable +``` + +- `operatorAddress`: The operator address of the validator. +- `delegateVotePower`: The flag to indicate whether the delegator would like to delegate his/her voting power + to the validator for governance. + +### Undelegate + +To undelegate BNB from a validator, use the `undelegate` function with the following parameters: + +```solidity +function undelegate(address operatorAddress, uint256 shares) external +``` + +- `operatorAddress`: The operator address of the validator. +- `shares`: The amount of shares to undelegate from the validator. + +### Redelegate + +To redelegate BNB from one validator to another, use the `redelegate` function with the following parameters: + +```solidity +function redelegate(address srcValidator, address dstValidator, uint256 shares, bool delegateVotePower) external +``` + +- `srcValidator`: The operator address of the source validator to redelegate from. +- `dstValidator`: The operator address of the destination validator to redelegate to. +- `delegateVotePower`: The flag to indicate whether the delegator would like to delegate his/her voting power + to the destination validator for governance. + +## Claim + +To claim undelegated BNB after the unbonding period, use the `claim` function for a single request or `claimBatch` for +multiple requests: + +```solidity +function claim(address operatorAddress, uint256 requestNumber) external +``` + +- `operatorAddress`: The operator address of the validator. +- `requestNumber`: The number of unbonding requests to claim from. `0` means claiming from all unbonding requests. + +```solidity +function claimBatch(address[] calldata operatorAddresses, uint256[] calldata requestNumbers) external +``` + +- `operatorAddress`: The operator addresses of the validatores. +- `requestNumber`: The numbers of unbonding requests to claim from the validators. + +## Contract ABI + +For the full interfaces of `StakeHub`, please refer +to [the ABI file](https://github.com/bnb-chain/bsc-genesis-contract/blob/bc-fusion/abi/stakehub.abi). \ No newline at end of file diff --git a/docs/bcfusion/validators/gov.md b/docs/bcfusion/validators/gov.md new file mode 100644 index 0000000000..93ee18530a --- /dev/null +++ b/docs/bcfusion/validators/gov.md @@ -0,0 +1,104 @@ +# Governance + +[BEP-297](https://github.com/bnb-chain/BEPs/pull/297) introduces the native governance module for BNB smart chain after +BNB chain fusion. The governance module is derived +from [OpenZeppelin Governor](https://docs.openzeppelin.com/contracts/4.x/governance), with the following +features: + +- Any staking credit holder is allowed to propose and vote. +- Voters can continue to earn staking rewards during the voting period. +- Users can delegate someone else to participate in governance on their behalf. +- A time lock period is introduced before the proposal is executed. +- If the proposal is rejected, the proposer does not incur any financial losses. + +## Workflow + +The workflow of the governance module consists of three stages: submit proposal, cast vote, and execute proposal. Each +stage has its own requirements and parameters, which can be configured by the BNB smart chain governance parameters. + +### Submit Proposal + +To submit a proposal, a staking credit holder needs to send a `propose` transaction to the `Governor` contract, +which is a system contract and the address is `0x0000000000000000000000000000000000002004`, +specifying the following information: + +- **Proposer address**: The address of the proposer, who initiates the proposal and pays the proposal fee. +- **Targets**: The list of addresses of the contracts or accounts that the proposal wants to interact with. +- **Values**: The list of amounts of BNB or other tokens that the proposal wants to transfer to the targets. +- **Signatures**: The list of function signatures of the contracts that the proposal wants to call on the targets. +- **Calldatas**: The list of encoded arguments of the functions that the proposal wants to call on the targets. +- **Description**: The description of the proposal, which provides more details and rationale for the proposal. + +A delegator should delegate more the 200 staked BNB as the minimal requirement for submitting a proposal. +Meanwhile, a delegator can only submit a new propopal if there is no pending proposal created by him/her. +The `propose` transaction will create a new proposal on the BNB smart chain. +The proposal will have a unique proposal ID, and a proposal status of `Pending`. The proposal will then +enter the voting period, which is the time window for the staking credit holders to cast their votes on the proposal. + +### Cast Vote + +To cast a vote on a proposal, a staking credit holder needs to send a `castVote` transaction to the `Governor` contract, +specifying the following information: + +- **Voter address**: The address of the voter, who casts the vote on the proposal. The voter address can be the + same as the staking credit holder address, or a different address that is delegated by the staking credit holder to + participate in governance on their behalf. +- **Proposal ID**: The ID of the proposal, which identifies the proposal that the voter wants to vote on. +- **Support**: The boolean value of the vote, which indicates the voter's preference on the proposal. `True` means that + the voter supports the proposal, and `False` means that the voter opposes the proposal. + +The `castVote` transaction will record the support value and the voting power of the voter on the BNB smart chain. The +voting power is the amount of staking credit that the voter has at the time of the vote. The voting power can change due +to staking operations, such as delegate, undelegate, or redelegate, but the support value will remain the same. The +voter can change their support value at any time during the voting period, by sending another `castVote` transaction +with a different support value. + +After submitting a proposal, the staking credit holders can cast their votes on the proposal until the voting period +ends. The voting period is one of the BNB smart chain governance parameters, and it is currently set to 7 days. + +### Execute Proposal + +To execute a proposal, anyone can send an `execute` transaction to the `Governor` contract, specifying the following +information: + +- **Proposal ID**: The ID of the proposal, which identifies the proposal that wants to be executed. + +The `execute` transaction will check the proposal status and the voting results on the BNB smart chain, and determine +whether the proposal can be executed or not. The proposal can be executed if the following conditions are met: + +- The proposal status is `Pending`, which means that the proposal has not been executed or expired yet. +- The voting period is over, which means that the time window for casting votes on the proposal has ended. +- The proposal has reached the quorum, which means that the total voting power of the voters who cast `True` or `False` + votes is greater than or equal to a certain percentage of the total staking credit on the BNB smart chain. The quorum + is one of the BNB smart chain governance parameters, and it is currently set to 10%. +- The proposal has reached the threshold, which means that the voting power of the voters who cast `True` votes is + greater than or equal to a certain percentage of the voting power of the voters who cast `True` or `False` votes. + +Once the voting period is over, the proposal can be executed if it meets the required conditions. However, the proposal +cannot be executed immediately, as there is a time lock period before the proposal is executed. The time lock period is +another BNB smart chain governance parameter, and it is currently set to 1 day. The time lock period is designed to +prevent sudden and irreversible changes on the BNB smart chain, and to give the stakeholders a chance to react or +prepare for the proposal execution. + +## Voting Power Delegation + +In addition to casting votes, the staking credit holders can also delegate their voting power to someone else to +participate in governance on their behalf. This can be useful for staking credit holders who do not have the time, +interest, or expertise to follow and vote on the proposals, but still want to have a say in the governance process. By +delegating their voting power to a trusted party, such as a validator, a friend, or a professional service, they can +benefit from their knowledge and experience, and also avoid the risk of losing their staking rewards due to abstaining +from voting. + +To delegate their voting power, a staking credit holder needs to send a `delegateVote` transaction to the `GovToekn` +contract, which is a system contract and the address is `0x0000000000000000000000000000000000002005`, +specifying the following information: + +- **Delegator address**: The address of the delegator, who delegates their voting power to another address. +- **Delegatee address**: The address of the delegatee, who receives the voting power from the delegator and + participates in governance on their behalf. + +The `delegateVote` transaction will record the delegation relationship and the voting power of the delegator on +the BNB smart chain. The voting power is the amount of staking credit that the delegator has at the time of the +delegation. The voting power can change due to staking operations, such as delegate, undelegate, or redelegate, but the +delegation relationship will remain the same. The delegator can change their delegatee address at any time, by sending +another `delegateVote` transaction with a different delegatee address. \ No newline at end of file diff --git a/docs/bcfusion/validators/slash.md b/docs/bcfusion/validators/slash.md new file mode 100644 index 0000000000..4aff0b2212 --- /dev/null +++ b/docs/bcfusion/validators/slash.md @@ -0,0 +1,55 @@ +# Slash + +The BNB smart chain (BSC) is a blockchain network that aims to provide fast, secure, and reliable transactions. To +achieve this, the BSC relies on a set of validators who are responsible for producing and validating blocks. Validators +stake their BNB tokens to participate in the network and earn rewards. + +However, validators also face the risk of losing their stakes if they behave in ways that could harm the network's +integrity and reliability. This is where the slashing mechanism comes in. The slashing mechanism is a set of rules and +functions implemented in the `SlashIndicator` contract +(which is a system contract and the address is `0x0000000000000000000000000000000000001001`) +that penalizes validators for violating certain conditions. The `SlashIndicator` contract will also calls +the `StakeHub` contract, +another system contract with address `0x0000000000000000000000000000000000002002`, for slashing. + +The slashing mechanism covers three types of offenses: downtime, double signing, and malicious voting. Each offense has +a different severity and penalty, depending on the impact it has on the network. In this document, we will explain the +slashing conditions and mechanisms for each offense in detail. + +## Downtime Slash + +Validators are expected to maintain high availability to ensure the network's smooth operation. Validators failing to +meet these uptime requirements are subject to slashing. + +- A internal contract tracks validator uptime by measuring the number of blocks they sign within a certain window. +- If a validator fails to sign at least a minimum number of blocks within the window, they are considered offline and + will be slashed for 10BNB and be moved to a "jailed" state for 2 days. + +## Double Sign Slash + +A critical offense within the BSC network is when a validator signs two different blocks at the same height. Such +actions can lead to network forks, undermining the blockchain's security and consistency. +Anyone can send a `submitDoubleSignEvidence` transaction to the `SlashIndicator` contract, +specifying the following information: + +- **Header 1**: A header of BSC with a the validator's signed signature. +- **Header 2**: Another header of BSC signed by the validator. The two headers have the same height. + +- The off-chain services monitor for double signing by validators by comparing the signatures and hashes of the blocks + they sign. +- If a validator is caught double signing, the contract executes a slashing function, reducing the validator's stake for + 200BNB and moving them to a "jailed" state for 30 days, preventing them from participating in consensus until manual + intervention is taken. + +## Malicious Vote Slash + +Validators who violates the [fast finality vote rules](https://github.com/bnb-chain/BEPs/blob/master/BEPs/BEP126.md) +will be also slashed. +Anyone can send a `submitFinalityViolationEvidence` transaction to the `SlashIndicator` contract, +specifying the following information: + +- **Evidence**: The evidence proves the valiator violates the fast finality rules. + +- The off-chain services monitor fast finality vote data to identify malicious votes. +- If a validator is caught for malicious vote, the validator will be slashed for 200BNB and move to "jailed" status for + 30 days. diff --git a/docs/bcfusion/validators/staking.md b/docs/bcfusion/validators/staking.md new file mode 100644 index 0000000000..3997007ac8 --- /dev/null +++ b/docs/bcfusion/validators/staking.md @@ -0,0 +1,143 @@ +# Staking + +BNB smart chain (BSC) is a Proof-of-Staked-Authority (PoSA) blockchain, which means that staking is one of the most +important parts of the system. [BEP-294](https://github.com/bnb-chain/BEPs/pull/294) introduces the new native staking +mechanism after BNB chain fusion, which has several differences: + +- Users are able to participate in staking on the BSC directly, without moving BNB to Beacon chain. +- Staking credit, as the proof of BNB staked to a specified validator, cannot be transferred. Different validators issue + different staking credits. +- Staking reward will not be distributed automatically. + +In this section, we will explain the basic concepts and operations of staking on the BSC. + +## Validator Set + +The validator set is the group of nodes that are responsible for validating transactions and producing blocks on the +BSC. The validator set is determined by the amount of staking credit each validator has, which reflects the amount of +BNB staked by the validator and its delegators. The top validators with the most staking credit are selected as the +active validator set, and they take turns to propose and vote on blocks. The rest of the validators are in the standby +validator set, and they can join the active validator set if their staking credit increases or if some active validators +drop out. + +The validator set is updated every 24 hours, based on the latest staking information. Validators can join or leave the +validator set by creating or editing their validator information. Validators can also be removed from the validator set +by slashing, which is a penalty for misbehaving or being offline. + +## Validator Operations + +Validators are the nodes that run the BNB smart chain software and participate in the consensus process. Validators need +to have a minimum amount of BNB staked to their own validator address, and they can also accept delegations from other +BNB holders who want to stake with them. Validators earn rewards from the transaction fees, and +they share a portion of their rewards with their delegators. + +### Create Validator + +To create a validator, a BNB holder needs to send a `CreateValidator` transaction to the `StakeHub` contract, +which is a system contract and the address is `0x0000000000000000000000000000000000002002`, +with minimum amount of BNB that the validator needs to stake to their own validator +address (2000 BNB), specifying the following information: + +- **Operator address**: The address of the validator, which will receive the staking credit and the rewards. +- **Consensus address**: The consensus address of the validator's node. +- **Vote Address**: The address for participating fast finality voting. +- **BLS Proof**: A BLS signature to prove that the validator owns the vote address. +- **Commission**: The commission rate defines the percentage of the rewards that the validator will keep for themselves, + and the rest will be distributed to the delegators. It also contains the max commison rate, the max change rate during + a predefined timespan for validator to set. +- **Description**: The optional information about the validator, such as moniker, identiy, website, etc. + +The `CreateValidator` transaction will deduct the minimum self-delegation amount from the validator address and issue +the corresponding staking credit to the validator. The validator will then join the standby validator set, and wait for +the next validator set update to see if they can enter the active validator set. + +### Edit Validator + +A validator can edit their validator information by sending `EditConsensusAddress`, `EditCommissionRate`, +`EditDescription`, `EditVoteAddress` transactions to the `StakeHub` contract, specifying the following information +accordingly: + +- **New consensus address**: The new consensus address of the validator's node. +- **New commission**: The new percentage of the rewards that the validator will keep for themselves, which can + only be increased within a maximum change rate limit. +- **New description**: The new information about the validator, such as moniker, identiy, website, etc. +- **New vote address**: The new vote address for participating fast finality. + +These transactions will update the validator information on the BNB smart chain, and the changes will take +effect immediately. However, the new commission rate will only apply to the rewards earned after the transaction, and +the previous rewards will be distributed according to the previous commission rate. + +## Delegator Operations + +Delegators are the BNB holders who stake their BNB to a validator of their choice, and share the rewards and the risks +with the validator. Delegators can choose any validator from the active or the standby validator set, and they can +switch between validators at any time. Delegators can also undelegate their BNB from a validator, and claim their +rewards at any time. + +### Delegate + +To delegate BNB to a validator, a BNB holder needs to send a `Delegate` transaction to the `StakeHub` contract, +specifying +the following information: + +- **Operator address**: The address of the validator, which will receive the BNB from the delegator. +- **Delegate Voting Power**: The flag to indicate whether the delegator would like to delegate his/her voting power + to the validator for governance. + +The `Delegate` transaction will deduct the amount of BNB from the delegator address and issue the corresponding staking +credit to the validator. The delegator will then share the rewards and the risks with the validator, according to the +commission rate and the slashing rate of the validator. + +The credit tokens (or share) a delgator will get is calculated +as - `delegation amount` * `total supply of credit token` / `total pooled BNB`. +The `total pooled BNB` includes the delegation BNB and unclaimed reaward BNB of of the vlidator. It means that a +delegator will get credit tokens based on the ratio of his/her delegation BNB amount to the total staked and reward BNB. +When the validator gets block reward the `total pooled BNB` amount will increase, which means that when unbonding +the delegator will get his delegation, as well as reward BNB from the pool. + +### Redelegate + +To redelegate BNB from one validator to another, a delegator needs to send a `Redelegate` transaction to the `StakeHub` +contract, specifying the following information: + +- **Source operator address**: The address of the source validator, which will send the BNB to the destination + validator. +- **Destination operator address**: The address of the destination validator, which will receive the BNB from the + source validator. +- **Amount**: The amount of BNB that the delegator wants to redelegate from the source validator to the destination + validator. +- **Delegate Voting Power**: The flag to indicate whether the delegator would like to delegate his/her voting power + to the destination validator for governance. + +The `Redelegate` transaction will deduct the amount of staking credit from the source validator and issue the +corresponding staking credit to the destination validator. The delegator will then share the rewards and the risks with +the destination validator, according to the commission rate and the slashing rate of the destination validator. +The `Redelegate` transaction does not incur the unbonding period, but it will incur the redelegation fee, +which is designed to prevent delegators from frequently switching between validators to chase +the highest rewards or avoid the highest risks. The current fee rate is 0.02%. + +### Undelegate + +To undelegate BNB from a validator, a delegator needs to send an `Undelegate` transaction to the `StakeHub` contract, +specifying the following information: + +- **Operator address**: The address of the validator, which will send the BNB to the delegator. +- **Amount**: The amount of BNB that the delegator wants to unstake from the validator. + +The `Undelegate` transaction will deduct the amount of staking credit from the validator and return the corresponding +BNB to the delegator address. However, the BNB will be locked for a period of time, called the **unbonding period**, +before the delegator can use it. The unbonding period is currently set to 7 days, and it is designed to prevent +delegators from quickly withdrawing their BNB in case of a validator misbehavior or a network attack. + +### Claim + +To claim the unbond BNB and the rewards, a delegator should send a `Claim` transaction to the `StakeHub` contract, +specifying the following information: + +- **Delegator address**: The BEP20 address of the delegator, which will receive the rewards from the validator. +- **Queued unbond number**: The number of unbond requests to be claimed, and 0 means claim BNB and rewards from + all the unbond requests. + +The `Claim` transaction will return the delegated BNB and rewards to the delegator. Be noted, a delegator can only get +the rewards after unbond. Before undelegation, the reward will be furthur staked to boost a delegator's income. + diff --git a/sidebars.js b/sidebars.js index f46992535d..a0a859a54c 100644 --- a/sidebars.js +++ b/sidebars.js @@ -326,6 +326,23 @@ const sidebars = { {type:'doc', id:'bcfusion/validators/creation', label:'Create New Validators'}, ] }, + { + type: 'category', + label:'For Developers', + items:[ + {type:'doc', id:'bcfusion/developers/staking', label:'New Staking'}, + {type:'doc', id:'bcfusion/developers/gov', label:'New Governance'}, + {type:'doc', id:'bcfusion/developers/crosschain-redelegation', label:'Cross Chain Redelegation'}, + ] + }, + { + type: 'category', + label:'New Staking & Governance', + items:[ + {type:'doc', id:'bcfusion/validators/staking', label:'Staking'}, + {type:'doc', id:'bcfusion/validators/gov', label:'Governance'}, + ] + }, ], },