Merge pull request #249 from bnb-chain/develop

release: prepare for release v1.1.7

.gitignore

@@ -1,16 +1,16 @@
 node_modules/
 build/
-.idea
-pids
-logs
+out/
 .idea/
+pids/
+logs/
+cache/
+
 contracts/flattened/*.sol
 
-#Hardhat files
-cache
-artifacts
+# foundry lib
+lib/forge-std/
 
 .env
-
-types
-typechain-types
+package-lock.json
+yarn.lock

README.md

@@ -4,65 +4,88 @@ This repo hold all the genesis contracts on Binance Smart chain. More details in
 
 ## Prepare
 
-Install dependency:
+Install node.js dependency:
 ```shell script
 npm install
-``` 
+```
 
-Node: v12.18.3
-Truffle: Truffle v5.1.31 
-Solc: 0.6.4+commit.1dca32f3.Darwin.appleclang
-Ganache-cli: v6.10.1
+Install foundry:
+```shell script
+curl -L https://foundry.paradigm.xyz | bash
+foundryup
+forge install --no-git --no-commit foundry-rs/[email protected]
+```
 
+Please make sure your dependency version is as follows:
 
-## unit test
+Node: v12.18.3 
 
-Generate contracts for testing:
-```shell script
-# the first account of ganache
-node generate-system.js --mock true --network local
-node generate-systemReward.js --mock true
-node generate-validatorset.js --mock true
-node generate-slash.js --mock true
-node generate-crosschain.js --mock true
-node generate-tokenhub.js --mock true
-node generate-relayerhub.js --mock true
-node generate-tendermintlightclient.js --mock true
-node generate-relayerincentivizecontract.js --roundSize 30 --maximumWeight 3 --mock true
-```
+Truffle: v5.1.31 
 
-Start ganache:
-```shell script
-ganache-cli --mnemonic 'clock radar mass judge dismiss just intact mind resemble fringe diary casino' --gasLimit 100000000  -e 10000 --allowUnlimitedContractSize
+Solc: 0.6.4+commit.1dca32f3
+
+Tips: You can manage multi version of Solc and Node:
+```Shell
+## Install solc-select and solc
+pip3 install solc-select
+solc-select install 0.6.4 && solc-select use 0.6.4
+
+## Install nvm and node
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
+nvm install  12.18.3 && nvm use 12.18.3
 ```
 
-Run truffle test:
-```shell script
-truffle compile
-truffle migrate
-truffle test
+## Unit test
+
+Add follow line to .env file in project dir, replace `archive_node` with a valid bsc mainnet node url which should be in archive mode:
+
+```text
+RPC_BSC=${archive_node}
 ```
 
-Run hardhat test:
+You can get a free archive node endpoint from https://nodereal.io/.
+
+Run forge test:
 ```shell script
-npx hardhat compile
-npx hardhat test
+forge test
 ```
 
-Flatten all system contracts:
+## Flatten all system contracts
+
 ```shell script
 npm run flatten
 ```
 
-## how to generate genesis file.
-
+All system contracts will be flattened and output into `${workspace}/contracts/flattened/`.
+
+## How to generate genesis file
+
 1. Edit `init_holders.js` file to alloc the initial BNB holder.
 2. Edit `validators.js` file to alloc the initial validator set.
 3. Edit `generate-validatorset.js` file to change `fromChainId` and `toChainId`,
 4. Edit `generate-tokenhub.js` file to change `refundRelayReward`, `minimumRelayFee` and `maxGasForCallingBEP20`.
 5. Edit `generate-tendermintlightclient.js` file to change `chainID` and `initConsensusStateBytes`.
 6. run ` node generate-genesis.js` will generate genesis.json
 
+## How to generate mainnet/testnet/QA genesis file
+
+```shell 
+npm run generate-mainnet
+npm run generate-testnet
+npm run generate-QA
+```
+Check the `genesis.json` file and you can get the exact compiled bytecode for different network.
+
+## How to update contract interface for test
+
+```shell script
+// get metadata
+forge build
+
+// generate interface
+cast interface ${workspace}/out/{contract_name}.sol/${contract_name}.json -p ^0.8.10 -n ${contract_name} > ${workspace}/lib/interface/I${contract_name}.sol
+```
+
 ## License
 
 The library is licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0),

contracts/BSCValidatorSet.sol

@@ -189,6 +189,12 @@ contract BSCValidatorSet is IBSCValidatorSet, System, IParamSubscriber, IApplica
   }
 
   /*********************** External Functions **************************/
+
+  /**
+   * @dev Collect all fee of transactions from the current block and deposit it to the contract
+   *
+   * @param valAddr The validator address who produced the current block
+   */
   function deposit(address valAddr) external payable onlyCoinbase onlyInit noEmptyDeposit{
     uint256 value = msg.value;
     uint256 index = currentValidatorSetMap[valAddr];
@@ -362,6 +368,10 @@ contract BSCValidatorSet is IBSCValidatorSet, System, IParamSubscriber, IApplica
     return CODE_OK;
   }
 
+  /**
+   * @dev With each epoch, there will be a partial rotation between cabinets and candidates. Rotation is determined by this function
+   *
+   */
   function shuffle(address[] memory validators, uint256 epochNumber, uint startIdx, uint offset, uint limit, uint modNumber) internal pure {
     for (uint i; i<limit; ++i) {
       uint random = uint(keccak256(abi.encodePacked(epochNumber, startIdx+i))) % modNumber;
@@ -373,6 +383,10 @@ contract BSCValidatorSet is IBSCValidatorSet, System, IParamSubscriber, IApplica
     }
   }
 
+  /**
+   * @dev Get mining validators that are block producers in the current epoch, including most of the cabinets and a few of the candidates
+   *
+   */
   function getMiningValidators() public view returns(address[] memory) {
     uint256 _maxNumOfWorkingCandidates = maxNumOfWorkingCandidates;
     uint256 _numOfCabinets = numOfCabinets;
@@ -401,6 +415,10 @@ contract BSCValidatorSet is IBSCValidatorSet, System, IParamSubscriber, IApplica
     return miningValidators;
   }
 
+  /**
+   * @dev Get all validators, including all of the cabinets and all of the candidates
+   *
+   */
   function getValidators() public view returns(address[] memory) {
     uint n = currentValidatorSet.length;
     uint valid = 0;
@@ -514,6 +532,11 @@ contract BSCValidatorSet is IBSCValidatorSet, System, IParamSubscriber, IApplica
     return true;
   }
 
+
+  /**
+   * @dev Enter maintenance for current validators. refer to https://github.com/bnb-chain/BEPs/blob/master/BEP127.md
+   *
+   */
   function enterMaintenance() external initValidatorExtraSet {
     // check maintain config
     if (maxNumOfMaintaining == 0) {
@@ -528,6 +551,10 @@ contract BSCValidatorSet is IBSCValidatorSet, System, IParamSubscriber, IApplica
     _enterMaintenance(msg.sender, index);
   }
 
+  /**
+   * @dev Exit maintenance for current validators. refer to https://github.com/bnb-chain/BEPs/blob/master/BEP127.md
+   *
+   */
   function exitMaintenance() external {
     uint256 index = getCurrentValidatorIndex(msg.sender);
 

contracts/BSCValidatorSet.template

@@ -189,6 +189,12 @@ contract BSCValidatorSet is IBSCValidatorSet, System, IParamSubscriber, IApplica
   }
 
   /*********************** External Functions **************************/
+
+  /**
+   * @dev Collect all fee of transactions from the current block and deposit it to the contract
+   *
+   * @param valAddr The validator address who produced the current block
+   */
   function deposit(address valAddr) external payable onlyCoinbase onlyInit noEmptyDeposit{
     uint256 value = msg.value;
     uint256 index = currentValidatorSetMap[valAddr];
@@ -362,6 +368,10 @@ contract BSCValidatorSet is IBSCValidatorSet, System, IParamSubscriber, IApplica
     return CODE_OK;
   }
 
+  /**
+   * @dev With each epoch, there will be a partial rotation between cabinets and candidates. Rotation is determined by this function
+   *
+   */
   function shuffle(address[] memory validators, uint256 epochNumber, uint startIdx, uint offset, uint limit, uint modNumber) internal pure {
     for (uint i; i<limit; ++i) {
       uint random = uint(keccak256(abi.encodePacked(epochNumber, startIdx+i))) % modNumber;
@@ -373,6 +383,10 @@ contract BSCValidatorSet is IBSCValidatorSet, System, IParamSubscriber, IApplica
     }
   }
 
+  /**
+   * @dev Get mining validators that are block producers in the current epoch, including most of the cabinets and a few of the candidates
+   *
+   */
   function getMiningValidators() public view returns(address[] memory) {
     uint256 _maxNumOfWorkingCandidates = maxNumOfWorkingCandidates;
     uint256 _numOfCabinets = numOfCabinets;
@@ -401,6 +415,10 @@ contract BSCValidatorSet is IBSCValidatorSet, System, IParamSubscriber, IApplica
     return miningValidators;
   }
 
+  /**
+   * @dev Get all validators, including all of the cabinets and all of the candidates
+   *
+   */
   function getValidators() public view returns(address[] memory) {
     uint n = currentValidatorSet.length;
     uint valid = 0;
@@ -514,6 +532,11 @@ contract BSCValidatorSet is IBSCValidatorSet, System, IParamSubscriber, IApplica
     return true;
   }
 
+
+  /**
+   * @dev Enter maintenance for current validators. refer to https://github.com/bnb-chain/BEPs/blob/master/BEP127.md
+   *
+   */
   function enterMaintenance() external initValidatorExtraSet {
     // check maintain config
     if (maxNumOfMaintaining == 0) {
@@ -528,6 +551,10 @@ contract BSCValidatorSet is IBSCValidatorSet, System, IParamSubscriber, IApplica
     _enterMaintenance(msg.sender, index);
   }
 
+  /**
+   * @dev Exit maintenance for current validators. refer to https://github.com/bnb-chain/BEPs/blob/master/BEP127.md
+   *
+   */
   function exitMaintenance() external {
     uint256 index = getCurrentValidatorIndex(msg.sender);