Skip to content

Commit

Permalink
docs: add more comments for contracts (#218)
Browse files Browse the repository at this point in the history
  • Loading branch information
@cosinlink
cosinlink authored Jan 12, 2023
1 parent d98c857 commit a7915a1
Show file tree
Hide file tree
Showing 8 changed files with 208 additions and 0 deletions.
27 changes: 27 additions & 0 deletions contracts/BSCValidatorSet.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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];
Expand Down Expand Up @@ -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;
Expand All @@ -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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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) {
Expand All @@ -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);

Expand Down
27 changes: 27 additions & 0 deletions contracts/BSCValidatorSet.template
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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];
Expand Down Expand Up @@ -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;
Expand All @@ -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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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) {
Expand All @@ -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);

Expand Down
10 changes: 10 additions & 0 deletions contracts/SlashIndicator.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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);
}
Expand Down
10 changes: 10 additions & 0 deletions contracts/SlashIndicator.template
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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);
}
Expand Down
25 changes: 25 additions & 0 deletions contracts/Staking.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand All @@ -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) {
Expand Down Expand Up @@ -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");
Expand Down Expand Up @@ -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");
Expand All @@ -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");
Expand Down
25 changes: 25 additions & 0 deletions contracts/Staking.template
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand All @@ -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) {
Expand Down Expand Up @@ -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");
Expand Down Expand Up @@ -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");
Expand All @@ -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");
Expand Down
42 changes: 42 additions & 0 deletions contracts/TokenHub.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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);
Expand All @@ -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);
Expand All @@ -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);
Expand Down Expand Up @@ -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");
Expand Down Expand Up @@ -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");
Expand Down
Loading

0 comments on commit a7915a1

Please sign in to comment.