docs: add more comments for contracts

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

contracts/SlashIndicator.sol

@@ -82,6 +82,11 @@ contract SlashIndicator is ISlashIndicator,System,IParamSubscriber, IApplication
   }
 
   /*********************** External func ********************************/
+  /**
+   * @dev Slash the validator who should have produced the current block
+   *
+   * @param validator The validator who should have produced the current block
+   */
   function slash(address validator) external onlyCoinbase onlyInit oncePerBlock onlyZeroGasPrice{
     if (!IBSCValidatorSet(VALIDATOR_CONTRACT_ADDR).isCurrentValidator(validator)) {
       return;
@@ -161,6 +166,11 @@ contract SlashIndicator is ISlashIndicator,System,IParamSubscriber, IApplication
     emit indicatorCleaned();
   }
 
+  /**
+   * @dev Send a felony cross-chain package to jail a validator
+   *
+   * @param validator Who will be jailed
+   */
   function sendFelonyPackage(address validator) external override(ISlashIndicator) onlyValidatorContract onlyInit {
     ICrossChain(CROSS_CHAIN_CONTRACT_ADDR).sendSynPackage(SLASH_CHANNELID, encodeSlashPackage(validator), 0);
   }

contracts/SlashIndicator.template

@@ -87,6 +87,11 @@ contract SlashIndicator is ISlashIndicator,System,IParamSubscriber, IApplication
   }
 
   /*********************** External func ********************************/
+  /**
+   * @dev Slash the validator who should have produced the current block
+   *
+   * @param validator The validator who should have produced the current block
+   */
   function slash(address validator) external onlyCoinbase onlyInit oncePerBlock onlyZeroGasPrice{
     if (!IBSCValidatorSet(VALIDATOR_CONTRACT_ADDR).isCurrentValidator(validator)) {
       return;
@@ -166,6 +171,11 @@ contract SlashIndicator is ISlashIndicator,System,IParamSubscriber, IApplication
     emit indicatorCleaned();
   }
 
+  /**
+   * @dev Send a felony cross-chain package to jail a validator
+   *
+   * @param validator Who will be jailed
+   */
   function sendFelonyPackage(address validator) external override(ISlashIndicator) onlyValidatorContract onlyInit {
     ICrossChain(CROSS_CHAIN_CONTRACT_ADDR).sendSynPackage(SLASH_CHANNELID, encodeSlashPackage(validator), 0);
   }

contracts/Staking.sol

@@ -193,6 +193,12 @@ contract Staking is IStaking, System, IParamSubscriber, IApplication {
   }
 
   /***************************** External functions *****************************/
+  /**
+   * @dev Delegate BNB from BSC to BC
+   *
+   * @param validator BC validator address encoded to evm address
+   * @param amount Amount user delegate to BC validator
+   */
   function delegate(address validator, uint256 amount) override external payable noReentrant tenDecimalPrecision(amount) initParams {
     require(amount >= minDelegation, "invalid delegate amount");
     require(msg.value >= amount.add(relayerFee), "not enough msg value");
@@ -219,6 +225,12 @@ contract Staking is IStaking, System, IParamSubscriber, IApplication {
     emit delegateSubmitted(msg.sender, validator, amount, oracleRelayerFee);
   }
 
+  /**
+   * @dev Undelegate BNB from BC to BSC
+   *
+   * @param validator BC validator encoded address the user delegated
+   * @param amount BNB amount the user undelegates
+   */
   function undelegate(address validator, uint256 amount) override external payable noReentrant tenDecimalPrecision(amount) initParams {
     require(msg.value >= relayerFee, "not enough relay fee");
     if (amount < minDelegation) {
@@ -253,6 +265,11 @@ contract Staking is IStaking, System, IParamSubscriber, IApplication {
     emit undelegateSubmitted(msg.sender, validator, amount, oracleRelayerFee);
   }
 
+  /**
+   * @dev Redelegate from validatorSrc to validatorDst on BC
+   *
+   * @param amount Amount that the user redelegates
+   */
   function redelegate(address validatorSrc, address validatorDst, uint256 amount) override external noReentrant payable tenDecimalPrecision(amount) initParams {
     require(validatorSrc != validatorDst, "invalid redelegation");
     require(msg.value >= relayerFee, "not enough relay fee");
@@ -288,6 +305,10 @@ contract Staking is IStaking, System, IParamSubscriber, IApplication {
     emit redelegateSubmitted(msg.sender, validatorSrc, validatorDst, amount, oracleRelayerFee);
   }
 
+  /**
+   * @dev claim delegated reward from BC staking
+   *
+   */
   function claimReward() override external noReentrant returns(uint256 amount) {
     amount = distributedReward[msg.sender];
     require(amount > 0, "no pending reward");
@@ -298,6 +319,10 @@ contract Staking is IStaking, System, IParamSubscriber, IApplication {
     emit rewardClaimed(msg.sender, amount);
   }
 
+  /**
+   * @dev claim undelegated BNB from BC staking
+   *
+   */
   function claimUndelegated() override external noReentrant returns(uint256 amount) {
     amount = undelegated[msg.sender];
     require(amount > 0, "no undelegated funds");

contracts/Staking.template

@@ -193,6 +193,12 @@ contract Staking is IStaking, System, IParamSubscriber, IApplication {
   }
 
   /***************************** External functions *****************************/
+  /**
+   * @dev Delegate BNB from BSC to BC
+   *
+   * @param validator BC validator address encoded to evm address
+   * @param amount Amount user delegate to BC validator
+   */
   function delegate(address validator, uint256 amount) override external payable noReentrant tenDecimalPrecision(amount) initParams {
     require(amount >= minDelegation, "invalid delegate amount");
     require(msg.value >= amount.add(relayerFee), "not enough msg value");
@@ -219,6 +225,12 @@ contract Staking is IStaking, System, IParamSubscriber, IApplication {
     emit delegateSubmitted(msg.sender, validator, amount, oracleRelayerFee);
   }
 
+  /**
+   * @dev Undelegate BNB from BC to BSC
+   *
+   * @param validator BC validator encoded address the user delegated
+   * @param amount BNB amount the user undelegates
+   */
   function undelegate(address validator, uint256 amount) override external payable noReentrant tenDecimalPrecision(amount) initParams {
     require(msg.value >= relayerFee, "not enough relay fee");
     if (amount < minDelegation) {
@@ -253,6 +265,11 @@ contract Staking is IStaking, System, IParamSubscriber, IApplication {
     emit undelegateSubmitted(msg.sender, validator, amount, oracleRelayerFee);
   }
 
+  /**
+   * @dev Redelegate from validatorSrc to validatorDst on BC
+   *
+   * @param amount Amount that the user redelegates
+   */
   function redelegate(address validatorSrc, address validatorDst, uint256 amount) override external noReentrant payable tenDecimalPrecision(amount) initParams {
     require(validatorSrc != validatorDst, "invalid redelegation");
     require(msg.value >= relayerFee, "not enough relay fee");
@@ -288,6 +305,10 @@ contract Staking is IStaking, System, IParamSubscriber, IApplication {
     emit redelegateSubmitted(msg.sender, validatorSrc, validatorDst, amount, oracleRelayerFee);
   }
 
+  /**
+   * @dev claim delegated reward from BC staking
+   *
+   */
   function claimReward() override external noReentrant returns(uint256 amount) {
     amount = distributedReward[msg.sender];
     require(amount > 0, "no pending reward");
@@ -298,6 +319,10 @@ contract Staking is IStaking, System, IParamSubscriber, IApplication {
     emit rewardClaimed(msg.sender, amount);
   }
 
+  /**
+   * @dev claim undelegated BNB from BC staking
+   *
+   */
   function claimUndelegated() override external noReentrant returns(uint256 amount) {
     amount = undelegated[msg.sender];
     require(amount > 0, "no undelegated funds");

contracts/TokenHub.sol

@@ -106,6 +106,13 @@ contract TokenHub is ITokenHub, System, IParamSubscriber, IApplication, ISystemR
     }
   }
 
+
+  /**
+   * @dev Claim relayer reward to target account
+   *
+   * @param to Whose relay reward will be claimed.
+   * @param amount Reward amount
+   */
   function claimRewards(address payable to, uint256 amount) onlyInit onlyRelayerIncentivize external override returns(uint256) {
     uint256 actualAmount = amount < address(this).balance ? amount : address(this).balance;
     if (actualAmount > REWARD_UPPER_LIMIT) {
@@ -122,6 +129,12 @@ contract TokenHub is ITokenHub, System, IParamSubscriber, IApplication, ISystemR
     return relayFee;
   }
 
+  /**
+   * @dev handle sync cross-chain package from BC
+   *
+   * @param channelId The channel for cross-chain communication
+   * @param msgBytes The rlp encoded message bytes sent from BC
+   */
   function handleSynPackage(uint8 channelId, bytes calldata msgBytes) onlyInit onlyCrossChainContract external override returns(bytes memory) {
     if (channelId == TRANSFER_IN_CHANNELID) {
       return handleTransferInSynPackage(msgBytes);
@@ -132,6 +145,13 @@ contract TokenHub is ITokenHub, System, IParamSubscriber, IApplication, ISystemR
     }
   }
 
+  /**
+   * @dev handle ack cross-chain package from BC，it means cross-chain transfer successfully to BC
+   * and will refund the remaining token caused by different decimals between BSC and BC.
+   *
+   * @param channelId The channel for cross-chain communication
+   * @param msgBytes The rlp encoded message bytes sent from BC
+   */
   function handleAckPackage(uint8 channelId, bytes calldata msgBytes) onlyInit onlyCrossChainContract external override {
     if (channelId == TRANSFER_OUT_CHANNELID) {
       handleTransferOutAckPackage(msgBytes);
@@ -140,6 +160,12 @@ contract TokenHub is ITokenHub, System, IParamSubscriber, IApplication, ISystemR
     }
   }
 
+  /**
+   * @dev handle failed ack cross-chain package from BC, it means failed to cross-chain transfer to BC and will refund the token.
+   *
+   * @param channelId The channel for cross-chain communication
+   * @param msgBytes The rlp encoded message bytes sent from BC
+   */
   function handleFailAckPackage(uint8 channelId, bytes calldata msgBytes) onlyInit onlyCrossChainContract external override {
     if (channelId == TRANSFER_OUT_CHANNELID) {
       handleTransferOutFailAckPackage(msgBytes);
@@ -381,6 +407,14 @@ contract TokenHub is ITokenHub, System, IParamSubscriber, IApplication, ISystemR
     return elements.encodeList();
   }
 
+  /**
+   * @dev request a cross-chain transfer from BSC to BC
+   *
+   * @param contractAddr The token contract which is transferred
+   * @param recipient The destination address of the cross-chain transfer on BC.
+   * @param amount The amount to transfer
+   * @param expireTime The expire time for the cross-chain transfer
+   */
   function transferOut(address contractAddr, address recipient, uint256 amount, uint64 expireTime) external override onlyInit payable returns (bool) {
     require(expireTime>=block.timestamp + 120, "expireTime must be two minutes later");
     require(msg.value%TEN_DECIMALS==0, "invalid received BNB amount: precision loss in amount conversion");
@@ -424,6 +458,14 @@ contract TokenHub is ITokenHub, System, IParamSubscriber, IApplication, ISystemR
     return true;
   }
 
+  /**
+   * @dev request a batch cross-chain BNB transfers from BSC to BC
+   *
+   * @param recipientAddrs The destination address of the cross-chain transfer on BC.
+   * @param amounts The amounts to transfer
+   * @param refundAddrs The refund addresses that receive the refund funds while failed to cross-chain transfer
+   * @param expireTime The expire time for these cross-chain transfers
+   */
   function batchTransferOutBNB(address[] calldata recipientAddrs, uint256[] calldata amounts, address[] calldata refundAddrs, uint64 expireTime) external override onlyInit payable returns (bool) {
     require(recipientAddrs.length == amounts.length, "Length of recipientAddrs doesn't equal to length of amounts");
     require(recipientAddrs.length == refundAddrs.length, "Length of recipientAddrs doesn't equal to length of refundAddrs");