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

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
+

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).

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).

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.