[WIP]BEP153: Native Staking Implementation #7

pythonberg1997 · 2022-06-13T02:59:12Z

BEP-153: Introduce Native Staking on BSC

1. Summary

This BEP introduces a native staking protocol onto BNB Smart Chain. With this BEP, individual or institution delegators can stake BNB to specified validators and get staking rewards on the BSC side directly.

2. Abstract

This BEP introduces a new staking system contract on the BSC side, all staking-related operations on the BSC side should be initiated through this contract, and then applied across-chain to BNB Beacon Chain through the native cross-chain communication mechanism. The cross-chain staking APP on the BNB Beacon Chain side reuses the previous staking mechanism to handle these staking-related operations.

The goals of this BEP is:

For decentralized applications (dApps), they can launch their own staking services on the BSC side base on this protocol;
For individuals, they can either directly stake their BNB through the staking system contract , or stake through the staking services provided by dApps on the BSC side.

3. Status

This BEP is a draft.

4.Motivation

Before this BEP, the BNB holders can only stake their assets on the BNB Beacon Chain side, which means that if their assets are on the BNB Smart Chain side, they have to transfer their assets across-chain to the BNB Beacon Chain first, which is not user-friendly enough.

With this BEP, the BNB holders can stake on the BSC side directly, and dApps can launch their staking service based on the protocol introduced by this BEP, which can diversify the BSC ecosystem.

5. Specification

5.1 Overview

There are mainly four components:

Staking System Contract: A newly designed system contract in charge of handling staking requests on BSC.
Cross-Chain Communication: Existing cross-chain infrastructures including cross chain contract, relayer and oracle module on BC.
Cross-Chain Staking APP: A newly designed app on BC in charge of handling cross-chain staking requests.
Staking Module on BC: Existing infrastructure in charge of BC’s staking delegation.

5.2 Staking System Contract

This is a new system contract deployed on BSC. It fulfills all the basic functionalities of staking service including delegation, undelegation, claiming reward and redelegation. It receives requests, encapsulates data and sends cross-chain packages. Specifically, the cross-chain package is normalized as a Cross-Chain Stake Event as below.

5.2.1 Cross-Chain Stake Event

The Cross-chain stake event will be emitted once a cross-chain stake transaction happens on BSC. It is mainly composed of channel ID, sequence ID and payload data.

The payload data is a sequence of RLP encoded bytes of {eventType, params}.

eventType: uint8, will determine the corresponding handler that handles staking requests, and also determine how to decode the data. It includes the following types.

Among them, distribute reward and distribute undelegated events will be emitted initially on BC.

Code	0x01	0x02	0x03	0x04	0x05
Event	Delegate	Undelegate	Redelegate	Distribute reward	Distribute undelegated

params: different requests have different parameters including but not limited to delegator address, staking amount, validator operator address and so on.

5.2.2 Data Structs

To keep track of delegators staking funds, we adopt multiple mappings to record data.

mapping(address => uint256) delegated
mapping(address => mapping(address => uint256)) delegatedOfValidator
mapping(address => uint256) distributedReward
mapping(address => mapping(address => uint256)) pendingUndelegateTime
mapping(address => uint256) undelegated
mapping(address => mapping(address => mapping(address => uint256))) pendingRedelegateTime

delegated records every delegator’s total staked amount. When a delegator submits undelegation, his/her delegated amount will decrease and after undelegation finishes, the undelegated increase the same number.

delegatedOfValidator records every delegator’s staked amount to a specific validator.

distributedReward records every delegator’s reward that is already distributed to BSC.

pendingUndelegateTime and pendingRedelegateTime records the estimated finish time of undelegation/redelegation. A new operation must wait until the previous operation is closed(until the time is up or receive an ack/failack package). Please be noted that this record will not always be accurate. The previous operation may end early.

undelegated records every delegator’s unlocked undelegate funds that is already distributed to BSC.

5.2.3 Staking System Contract APIs

delegate(address validator, uint256 amount) payable

This method will handle the cross-chain delegating requests. Here, the validator represents the BC operator address of the validator to be delegated to. Cross-chain relayer fee should be included in the msg.value. The following graph represents the workflow of delegation on BSC:

undelegate(address validator, uint256 amount) payable

This method will handle the cross-chain undelegating requests. The staked BNBs on BC will be unlocked after 7 days and transferred to the staking contract on BSC automatically. Delegators could claim undelegated BNBs by claimUndelegated(see below). The validator represents the BC operator address of the validator delegated to. Cross-chain relayer fee should be included in the msg.value.
redelegate(address validatorSrc, address validatorDst, uint256 amount) payable

Undelegate amount BNBs from validatorSrc and delegate to validatorDst.
claimReward() returns(uint256 amount)

Delegators can claim their distributed reward by this method. The returned amount is the number of funds that msg.sender received.
claimUndelegated() returns(uint256 amount)

Delegators can claim their undelegated funds by this method. The returned amount is the number of funds that msg.sender received.
getDelegated(address delegator, address validator) external view returns(uint256 amount)

This function allows the delegator to query how much he/she has delegated to the specific validator.
getTotalDelegated(address delegator) external view returns(uint256 amount)

This function allows the delegator to query how much he/she has delegated in all.
getDistributedReward(address delegator) external view returns(uint256 amount)

This function allows the delegator to view the amount of the distributed rewards.
getPendingRedelegateTime(address delegator, address valSrc, address valDst) external view returns(uint256 amount)

This function allows the delegator to view the estimated finish time of redelegation from valSrc to valDst.
getPendingUndelegateTime(address delegator, address validator) external view returns(uint256 amount)

This function allows the delegator to view the estimated finish time of undelegation from validator.
getUndelegated(address delegator) external view returns(uint256 amount)

This function allows the delegator to view the amount of the undelegated funds.

5.3 Cross-Chain Staking APP

This is a new cross-chain app on BC side. It will be called by the BC’s bridge once it receives cross-chain staking packages. The main function of this app is to parse the data and do the staking related tasks.

5.3.1 Staking

The native staking mechanism on the BC will stay almost the same as before. The only change is that the delegation will be tagged as native or not native(cross-chain). The Cross-Chain Staking app will decode the cross-chain package depending on the event type code and call corresponding functions.

5.3.2 Contract Address on BC(CAoB)

The delegator’s corresponding address on the BC will be the XOR result between a map hash of a specific constant string and its BSC address. So no one could control it except for the cross-chain app.

The delegate CAoB is calculated by sha256("Staking Delegate Address Anchor") ^ BSC Address. This address is the counterpart of normal delegation’s delegator address. It’s used to hold the delegator’s staking funds.
The reward CAoB is calculated by sha256("Staking Reward Address Anchor") ^ delegate CAoB. This address is used to hold the delegator’s reward. For convenience we add this extra address comparing to normal delegation.

5.3.3 Distribute Reward

The delegation reward will be released at each breath block to the reward CAoB, once the balance of the reward CAoB is larger than a threshold. The reward will be cross-chain transferred to the staking system contract on the BSC side automatically.

5.3.4 Distribute Undelegated

When undelegation finishes, the undelegated funds will be released to the delegate CAoB address, and the funds of the delegate CAoB will be cross-chain transferred to the staking system contract on the BSC side automatically in the next breath block.

5.4 Fees

The fees charged for the relevant transactions are based on the following principles:

For normal cross-chain communication, the gas and relayer fee shall be paid by the msg sender at once;
For the failed transactions, there may be extra gas and relayer fee as extra cross-chain communication is needed. This part will be covered by the system reward contract.
For reward and undelegated distribution, the relayer fee will be deducted from users' funds.

5.5 Error Handle

This BEP will reuse the existing cross-chain infrastructure as much as possible. This includes and is not limited to the separation of application and communication protocol layers, uniform error handling principle and cross-chain application coding principle. As the new system contract BSC and new app on BC are all parts of the application layer, the error handling of the communication layer will remain the same as before.

5.5.1 Normal Error

Normal errors means anticipated errors. For transactions that cross-chain communication is involved, all normal errors will be relayed back. So no errors will be missed. For this type of errors, we recommend that developers should check the returned reason for failure, modify the parameters and retry the transaction. All anticipated errors and success scenarios are listed below.

Function	Error	BSC result	BC result	Feedback
Delegate	Any errors happened on BSC	Transaction reverted	N/A	Error message
Delegate	Validator jailed/not exist	Success	AckPackage	Event with error message emitted
Delegate	N/A (Success)	Success	N/A	N/A
Undelegate	Any errors happened on BSC	Transaction reverted	N/A	Error message
Undelegate	Amount greater than delegated shares/Validator not found/No delegation to the validator/Undelegate amount is too small	Success	AckPackage	Event with error message emitted
Undelegate	N/A (Success)	Success	N/A	N/A
Redelegate	Any errors happened on BSC	Transaction reverted	N/A	Error message
Redelegate	Validator jailed/not exist	Success	AckPackage	Event with error message emitted
Redelegate	N/A (Success)	Success	N/A	N/A

Therefore, if any errors happen on BSC, the transaction will be reverted and the msg sender will know it at once. But if an error happens on BC, the msg sender will not get feedback immediately. So we recommend dApp developers run some robots to monitor related events to get informed.

5.5.2 Crash in Application Layer

The communication layer will catch the crash error of the application, record it in store or emit an event for debugging. The crash error will use the FAIL_ACK type of package if needed, and the payload of FAIL_ACK is the same as the payload of the SYNC package.

For contracts in BSC, the crash of Application will revert state change automatically, but for Application on BC we need to build another sandbox for it, only commit store after it did not crash.

When receiving the FAIL_ACK package, the communication layer will invoke a different method of Application, like handleFailAckPackage or ExecuteFailAckClaim. We will ensure the safety of users’ assets(see 5.5.4).

5.5.3 Error in Communication Layer

Communication layer only plays around with these inputs: Type, Sequence, ChannelId, RelayerFee. The simplicity of these inputs helps us build a robust system.

However, once an error happens, the communication of a channel may be blocked. We have to hard fork the chain when errors occur in the communication layer.

5.5.4 How Funds are Handled When Errors Occur During Delegation

It is very important to protect the safety of actors’ funds. As funds need to be transferred across the chain, this BEP will reuse the cross-chain transfer design as before. The key points are that funds transferred from BSC to BC will be locked in the tokenHub system contract and funds transferred from BC to BSC will be locked in the pegAccount. Necessary mechanism is employed to ensure the cross-chain reconciliation.

When a delegation request fails, an extra cross-chain package will be sent back to BSC. The funds will be unlocked from the tokenhub system contract, transferred to the staking system contract and be recorded as a part of the delegator’s pending undelegated. The delegator can get his/her funds back by claimUndelegated later. However, if the msg sender is a contract without a receive/fallback method, the transfer will fail and the funds may be lost forever. So make sure your dApp implements the receive/fallback method.

contracts/Staking.sol

realuncle · 2022-07-15T11:31:32Z

contracts/Staking.sol

+  struct TransferInUndelegatedSynPackage {
+    uint256 amount;
+    address recipient;
+    address refundAddr;


So be here, refundAddr is redundant.

contracts/Staking.sol

contracts/System.sol

NashBC · 2022-07-18T03:32:23Z

contracts/TokenHub.sol

@@ -79,6 +79,8 @@ contract TokenHub is ITokenHub, System, IParamSubscriber, IApplication, ISystemR

  uint256 public relayFee;

+  uint256 public totalStakingBNB;


The newly defined variable should be at the end of the variables declarations, so I think you should move this behind line86

NashBC · 2022-07-18T04:09:05Z

contracts/Staking.sol

+  }
+
+  function undelegate(address validator, uint256 amount) override external payable tenDecimalPrecision(amount) initParams {
+    require(pendingUndelegated[msg.sender][validator] == 0, "pending undelegation exist");


Is this necessary?

Yes. BC will not accept two undeledation at one time. So we'd better check that on BSC in advance

NashBC · 2022-07-18T04:16:15Z

contracts/Staking.sol

+    require(validatorSrc!=validatorDst, "invalid redelegation");
+    amount = amount != 0 ? amount : delegatedOfValidator[msg.sender][validatorSrc];
+    if (amount < minDelegationChange) {
+      require(amount == delegatedOfValidator[msg.sender][validatorSrc],


I would better like that when the delegatedOfValidator[msg.sender][validatorSrc] is little than minDelegationChange, the reldelegate action should be forbidden.

If so, then when the balance is less than minDelegationChange, the delegator must undelegate first to get his balance back

I think so.

NashBC · 2022-07-18T04:18:23Z

contracts/Staking.sol

+
+  function undelegate(address validator, uint256 amount) override external payable tenDecimalPrecision(amount) initParams {
+    require(pendingUndelegated[msg.sender][validator] == 0, "pending undelegation exist");
+    amount = amount != 0 ? amount : delegatedOfValidator[msg.sender][validator];


Because the msg.sender can get the exact value, the amount should be specified precisely. I think there is no need special case for 0 amount, just forbid it.

NashBC · 2022-07-18T04:18:48Z

contracts/Staking.sol

+
+  function redelegate(address validatorSrc, address validatorDst, uint256 amount) override external payable tenDecimalPrecision(amount) initParams {
+    require(validatorSrc!=validatorDst, "invalid redelegation");
+    amount = amount != 0 ? amount : delegatedOfValidator[msg.sender][validatorSrc];


The same here.

NashBC · 2022-07-18T04:21:04Z

contracts/Staking.sol

+
+    amount = distributedReward[msg.sender];
+    payable(msg.sender).transfer(amount);
+    distributedReward[msg.sender] = 0;


Better first set distributedReward[msg.sender] = 0; then payable(msg.sender).transfer(amount);

NashBC · 2022-07-18T04:21:27Z

contracts/Staking.sol

+
+    amount = undelegated[msg.sender];
+    payable(msg.sender).transfer(amount);
+    undelegated[msg.sender] = 0;


The same here.

NashBC · 2022-07-26T10:36:21Z

contracts/Staking.sol

+
+  uint256 constant public TEN_DECIMALS = 1e10;
+
+  uint256 public constant INIT_ORACLE_RELAYER_FEE = 2e16; //TODO


Delete TODO

It's to be decided

2e16 is fine.

NashBC · 2022-07-26T10:37:38Z

contracts/Staking.sol

+  uint256 constant public TEN_DECIMALS = 1e10;
+
+  uint256 public constant INIT_ORACLE_RELAYER_FEE = 2e16; //TODO
+  uint256 public constant INIT_MIN_DELEGATION_CHANGE = 1e20;


100 * 1e18 is more readable?

NashBC · 2022-07-26T11:06:13Z

contracts/Staking.sol

+    require(success, "rlp decode ack package failed");
+
+    delegated[pack.delegator] = delegated[pack.delegator].add(pack.amount);
+    pendingUndelegated[pack.delegator][pack.validator] = 0;


Better protect, require( pendingUndelegated[pack.delegator][pack.validator] == pack.amount, "")

contracts/Staking.sol

realuncle · 2022-08-02T11:15:54Z

contracts/Staking.sol

@@ -18,19 +18,24 @@ contract Staking is IStaking, System, IParamSubscriber, IApplication {
  using RLPEncode for *;
  using RLPDecode for *;

-  // Cross-Chain Stake Event type
+  // Package type
+  uint8 constant public SYN_PACKAGE = 0x00;


we can delete this.

NashBC

LGTM

gothery001 · 2022-08-25T02:43:51Z

contracts/Staking.sol

+    } else if (eventType == EVENT_DISTRIBUTE_UNDELEGATED) {
+      (resCode, ackPackage) = _handleDistributeUndelegatedSynPackage(iter);
+    } else {
+      require(false, "unknown event type");


it's better to use revert("unknown event type");

gothery001 · 2022-08-25T02:45:07Z

contracts/Staking.sol

+    if (paramBytes.hasNext()) {
+      iter = paramBytes.next().toBytes().toRLPItem().iterator();
+    } else {
+      require(false, "empty fail ack package");


gothery001 · 2022-08-25T02:45:21Z

contracts/Staking.sol

+    if (paramBytes.hasNext()) {
+      iter = paramBytes.next().toBytes().toRLPItem().iterator();
+    } else {
+      require(false, "empty fail ack package");


gothery001 · 2022-08-25T02:45:34Z

contracts/Staking.sol

+    if (paramBytes.hasNext()) {
+      iter = paramBytes.next().toBytes().toRLPItem().iterator();
+    } else {
+      require(false, "empty fail ack package");


gothery001 · 2022-08-25T02:45:58Z

contracts/Staking.sol

+      require(newMinDelegation > 0, "the minDelegation must be greater than 0");
+      minDelegation = newMinDelegation;
+    } else {
+      require(false, "unknown param");


gothery001 · 2022-08-26T05:42:08Z

contracts/Staking.sol

+  uint32 public constant ERROR_WITHDRAW_BNB = 101;
+
+  uint256 public constant TEN_DECIMALS = 1e10;
+  uint256 public constant LOCK_TIME = 691200; // 8*24*3600


it may be better to use 8 days to replace 691200

gothery001 · 2022-08-30T02:44:50Z

contracts/Staking.sol

+
+    uint256 convertedAmount = amount.div(TEN_DECIMALS); // native bnb decimals is 8 on BBC, while the native bnb decimals on BSC is 18
+    uint256 _relayerFee = (msg.value).sub(amount);
+    uint256 oracleRelayerFee = _relayerFee-bSCRelayerFee;


better to use SafeMath

gothery001 · 2022-08-30T02:46:02Z

contracts/Staking.sol

+
+    uint256 convertedAmount = amount.div(TEN_DECIMALS); // native bnb decimals is 8 on BBC, while the native bnb decimals on BSC is 18
+    uint256 _relayerFee = msg.value;
+    uint256 oracleRelayerFee = _relayerFee-bSCRelayerFee;


better to use SafeMath

gothery001 · 2022-08-30T02:46:04Z

contracts/Staking.sol

+    delegateInFly[msg.sender] += 1;
+
+    ICrossChain(CROSS_CHAIN_CONTRACT_ADDR).sendSynPackage(CROSS_STAKE_CHANNELID, msgBytes, oracleRelayerFee.div(TEN_DECIMALS));
+    payable(TOKEN_HUB_ADDR).transfer(amount+oracleRelayerFee);


better to use SafeMath

gothery001 · 2022-08-30T02:46:15Z

contracts/Staking.sol

+
+    uint256 convertedAmount = amount.div(TEN_DECIMALS);// native bnb decimals is 8 on BBC, while the native bnb decimals on BSC is 18
+    uint256 _relayerFee = msg.value;
+    uint256 oracleRelayerFee = _relayerFee-bSCRelayerFee;


better to use SafeMath

musk-j · 2022-09-15T03:34:09Z

genesis-template.json

+    "0x88cb4D8F77742c24d647BEf8049D3f3C56067cDD": {
+      "balance": "0x100000000000000000000"
+    },
+    "0x42D596440775C90db8d9187b47650986E1063493": {


I am wondering if of most the BSC validators will use this genesis-template.json to generate genesis Genesis. If yes, does that mean wallet 0x42D596440775C90db8d9187b47650986E1063493 will have 1000 BNB in their balance?

musk-j · 2022-09-15T04:57:32Z

contracts/Staking.sol

+      return false;
+    }
+    delete packageQueue[leftIndex];
+    ++leftIndex;


_checkPackHash requires strict timing[one after another] of these events:

BSC sending "EVENT_DELEGATE 1" to BC

BC sending AckPackage/FailAckPackage 1 to BSC

BSC sending "EVENT_DELEGATE 2" to BC

BC sending AckPackage/FailAckPackage 2 to BSC

BSC sending "EVENT_DELEGATE 3" to BC

BC sending AckPackage/FailAckPackage 3 to BSC

Not sure if there is a scenario: events can be processed in a different order. For example:

BSC sending "EVENT_DELEGATE 1" to BC

BSC sending "EVENT_DELEGATE 2" to BC

BC sending AckPackage/FailAckPackage 2 to BSC <=AckPackage 2 received before AckPackage 1.

BC sending AckPackage/FailAckPackage 1 to BSC

BSC sending "EVENT_DELEGATE 3" to BC

BC sending AckPackage/FailAckPackage 3 to BSC

If this happens, _checkPackHash will always return false and handleAckPackage will revert forever.

Updated Links to docs.bnbchain.org (bnb-chain#147)

7100748

realuncle reviewed Jul 15, 2022

View reviewed changes