BlockRewardAuRaBase
contract BlockRewardAuRaBase
is UpgradeableOwned, IBlockRewardAuRa
Generates and distributes rewards according to the logic and formulas described in the POSDAO white paper.
Index
- AddedReceiver
- BridgeNativeRewardAdded
- MintedNative
- _coinInflationAmount
- _dequeueExtraReceiver
- _distributeNativeRewards
- _distributeRewards
- _distributeTokenRewards
- _enqueueExtraReceiver
- _getCurrentBlockNumber
- _inflationAmount
- _migrateMintingStatistics
- _mintNativeCoins
- _setMinted
- _snapshotPoolStakeAmounts
- _transferNativeReward
- addBridgeNativeFeeReceivers
- addBridgeNativeRewardReceivers
- addExtraReceiver
- blockRewardContractId
- clearBlocksCreated
- delegatorShare
- epochsPoolGotRewardFor
- epochsToClaimRewardFrom
- ercToNativeBridgesAllowed
- extraReceiversQueueSize
- fallback
- initialize
- isInitialized
- onTokenTransfer
- onlyErcToNativeBridge
- onlyInitialized
- onlyStakingContract
- onlySystem
- onlyValidatorSetContract
- reward
- setErcToNativeBridgesAllowed
- validatorRewardPercent
- validatorShare
Reference
Events
AddedReceiver
event AddedReceiver(uint256 amount, address receiver, address bridge)
Emitted by the `addExtraReceiver` function.
- Parameters:
amount
- The amount of native coins which must be minted for the `receiver` by the `erc-to-native` `bridge` with the `reward` function.receiver
- The address for which the `amount` of native coins must be minted.bridge
- The bridge address which called the `addExtraReceiver` function.
BridgeNativeRewardAdded
event BridgeNativeRewardAdded(uint256 amount, uint256 cumulativeAmount, address bridge)
Emitted by the `addBridgeNativeRewardReceivers` function.
- Parameters:
amount
- The fee/reward amount in native coins passed to the `addBridgeNativeRewardReceivers` function as a parameter.cumulativeAmount
- The value of `bridgeNativeReward` state variable after adding the `amount` to it.bridge
- The bridge address which called the `addBridgeNativeRewardReceivers` function.
MintedNative
event MintedNative(address[] receivers, uint256[] rewards)
Emitted by the `_mintNativeCoins` function which is called by the `reward` function. This event is only used by the unit tests because the `reward` function cannot emit events.
- Parameters:
receivers
- The array of receiver addresses for which native coins are minted. The length of this array is equal to the length of the `rewards` array.rewards
- The array of amounts minted for the relevant `receivers`. The length of this array is equal to the length of the `receivers` array.
Modifiers
onlyErcToNativeBridge
modifier onlyErcToNativeBridge()
Ensures the caller is the `erc-to-native` bridge contract address.
onlyInitialized
modifier onlyInitialized()
Ensures the `initialize` function was called before.
onlyStakingContract
modifier onlyStakingContract()
Ensures the caller is the StakingAuRa contract address.
onlySystem
modifier onlySystem()
Ensures the caller is the SYSTEM_ADDRESS. See https://openethereum.github.io/wiki/Block-Reward-Contract.html.
onlyValidatorSetContract
modifier onlyValidatorSetContract()
Ensures the caller is the ValidatorSetAuRa contract address.
Functions
_coinInflationAmount
abstract function _coinInflationAmount(uint256 , address[] ) internal view returns (uint256)
- Parameters:
- uint256
- address[]
- Returns:
- uint256
_dequeueExtraReceiver
function _dequeueExtraReceiver() internal returns (uint256, address, address)
Dequeues the information about the native coins receiver enqueued with the `addExtraReceiver` function by the `erc-to-native` bridge. This function is used by `_mintNativeCoins`.
- Returns:
- `uint256 amount` - The amount to be minted for the `receiver` address. `address receiver` - The address for which the `amount` is minted. `address bridge` - The address of the bridge contract which called the `addExtraReceiver` function.
_distributeNativeRewards
function _distributeNativeRewards(uint256 _stakingEpoch, uint256 _totalRewardShareNum, uint256 _totalRewardShareDenom, address[] _validators, uint256[] _blocksCreatedShareNum, uint256 _blocksCreatedShareDenom) internal returns (uint256)
Distributes rewards in native coins among pools at the latest block of a staking epoch. This function is called by the `_distributeRewards` function.
- Parameters:
_stakingEpoch
- The number of the current staking epoch._totalRewardShareNum
- Numerator of the total reward share._totalRewardShareDenom
- Denominator of the total reward share._validators
- The array of the current validators (their mining addresses)._blocksCreatedShareNum
- Numerators of blockCreated share for each of the validators._blocksCreatedShareDenom
- Denominator of blockCreated share.- Returns:
- Returns the amount of native coins which need to be minted.
_distributeRewards
function _distributeRewards(IStakingAuRa _stakingContract, uint256 _stakingEpoch, uint256 _stakingEpochEndBlock) internal returns (uint256)
Distributes rewards among pools at the latest block of a staking epoch. This function is called by the `reward` function.
- Parameters:
_stakingContract
- The address of the StakingAuRa contract._stakingEpoch
- The number of the current staking epoch._stakingEpochEndBlock
- The number of the latest block of the current staking epoch.- Returns:
- Returns the reward amount in native coins needed to be minted and accrued to the balance of this contract.
_distributeTokenRewards
abstract function _distributeTokenRewards(address , uint256 , uint256 , uint256 , address[] , uint256[] , uint256 ) internal
- Parameters:
- address
- uint256
- uint256
- uint256
- address[]
- uint256[]
- uint256
_enqueueExtraReceiver
function _enqueueExtraReceiver(uint256 _amount, address _receiver, address _bridge) internal
Enqueues the information about the receiver of native coins which must be minted for the specified `erc-to-native` bridge. This function is used by the `addExtraReceiver` function.
- Parameters:
_amount
- The amount of native coins which must be minted for the `_receiver` address._receiver
- The address for which the `_amount` of native coins must be minted._bridge
- The address of the bridge contract which requested the minting of native coins.
_getCurrentBlockNumber
function _getCurrentBlockNumber() internal view returns (uint256)
Returns the current block number. Needed mostly for unit tests.
- Returns:
- uint256
_inflationAmount
function _inflationAmount(uint256 _stakingEpoch, address[] _validators, uint256 _inflationRate) internal view returns (uint256)
Calculates and returns inflation amount based on the specified staking epoch, validator set, and inflation rate. Used by `_coinInflationAmount` and `_distributeTokenRewards` functions.
- Parameters:
_stakingEpoch
- The number of the current staking epoch._validators
- The array of the current validators (their mining addresses)._inflationRate
- Inflation rate.- Returns:
- uint256
_migrateMintingStatistics
function _migrateMintingStatistics() internal
Copies the minting statistics from the previous BlockReward contract for the `mintedTotally` and `mintedTotallyByBridge` getters. Called only once by the `reward` function.
_mintNativeCoins
function _mintNativeCoins(uint256 _nativeTotalRewardAmount, uint256 _queueLimit) internal returns (address[], uint256[])
Joins two native coin receiver elements into a single set and returns the result to the `reward` function: the first element comes from the `erc-to-native` bridge fee distribution, the second - from the `erc-to-native` bridge when native coins are minted for the specified addresses. Dequeues the addresses enqueued with the `addExtraReceiver` function by the `erc-to-native` bridge. Accumulates minting statistics for the `erc-to-native` bridges.
- Parameters:
_nativeTotalRewardAmount
- The native coins amount which should be accrued to the balance of this contract (as a total reward for the finished staking epoch)._queueLimit
- Max number of addresses which can be dequeued from the queue formed by the `addExtraReceiver` function.- Returns:
- address[]
- uint256[]
_setMinted
function _setMinted(uint256 _amount, address _account, address _bridge) internal
Accumulates minting statistics for the `erc-to-native` bridge. This function is used by the `_mintNativeCoins` function.
- Parameters:
_amount
- The amount minted for the `_account` address._account
- The address for which the `_amount` is minted._bridge
- The address of the bridge contract which called the `addExtraReceiver` function.
_snapshotPoolStakeAmounts
function _snapshotPoolStakeAmounts(IStakingAuRa _stakingContract, uint256 _stakingEpoch, address _miningAddress) internal
Makes snapshots of total amount staked into the specified pool before the specified staking epoch. Used by the `reward` function.
- Parameters:
_stakingContract
- The address of the `StakingAuRa` contract._stakingEpoch
- The number of upcoming staking epoch._miningAddress
- The mining address of the pool.
_transferNativeReward
function _transferNativeReward(uint256 _amount, address _to) internal
Called by the `transferReward` of a child contract to transfer native coins from the balance of the `BlockRewardAuRa` contract to the specified address as a reward.
- Parameters:
_amount
- The amount of native coins to transfer as a reward._to
- The target address to transfer the amounts to.
addBridgeNativeFeeReceivers
function addBridgeNativeFeeReceivers(uint256 _amount) external
An alias for `addBridgeNativeRewardReceivers` (for backward compatibility with the previous bridge contract).
- Parameters:
_amount
- uint256
addBridgeNativeRewardReceivers
function addBridgeNativeRewardReceivers(uint256 _amount) public
Called by the `erc-to-native` bridge contract when a portion of the bridge fee/reward should be minted and distributed to participants (validators and their delegators) in native coins. The specified amount is used by the `_distributeRewards` function.
- Modifiers:
- onlyErcToNativeBridge
- Parameters:
_amount
- The fee/reward amount distributed to participants.
addExtraReceiver
function addExtraReceiver(uint256 _amount, address _receiver) external
Called by the `erc-to-native` bridge contract when the bridge needs to mint a specified amount of native coins for a specified address using the `reward` function.
- Modifiers:
- onlyErcToNativeBridge
- Parameters:
_amount
- The amount of native coins which must be minted for the `_receiver` address._receiver
- The address for which the `_amount` of native coins must be minted.
blockRewardContractId
function blockRewardContractId() public pure returns (bytes4)
Returns an identifier for the bridge contract so that the latter could ensure it works with the BlockReward contract.
- Returns:
- bytes4
clearBlocksCreated
function clearBlocksCreated() external
Called by the `ValidatorSetAuRa.finalizeChange` to clear the values in the `blocksCreated` mapping for the current staking epoch and a new validator set.
- Modifiers:
- onlyValidatorSetContract
delegatorShare
function delegatorShare(uint256 _stakingEpoch, uint256 _delegatorStaked, uint256 _validatorStaked, uint256 _totalStaked, uint256 _poolReward) public view returns (uint256)
Calculates delegator's share for the given pool reward amount and the specified staking epoch. Used by the `StakingAuRa.claimReward` function.
- Parameters:
_stakingEpoch
- The number of staking epoch._delegatorStaked
- The amount staked by a delegator._validatorStaked
- The amount staked by a validator._totalStaked
- The total amount staked by a validator and their delegators._poolReward
- The value of pool reward.- Returns:
- uint256
epochsPoolGotRewardFor
function epochsPoolGotRewardFor(address _miningAddress) public view returns (uint256[])
Returns an array of epoch numbers for which the specified pool (mining address) got a non-zero reward.
- Parameters:
_miningAddress
- address- Returns:
- uint256[]
epochsToClaimRewardFrom
function epochsToClaimRewardFrom(address _poolStakingAddress, address _staker) public view returns (uint256[])
Returns an array of epoch numbers for which the specified staker can claim a reward from the specified pool by the `StakingAuRa.claimReward` function.
- Parameters:
_poolStakingAddress
- The pool staking address._staker
- The staker's address (delegator or candidate/validator).- Returns:
- uint256[]
ercToNativeBridgesAllowed
function ercToNativeBridgesAllowed() public view returns (address[])
Returns the array of `erc-to-native` bridge addresses set by the `setErcToNativeBridgesAllowed` setter.
- Returns:
- address[]
extraReceiversQueueSize
function extraReceiversQueueSize() public view returns (uint256)
Returns the current size of the address queue created by the `addExtraReceiver` function.
- Returns:
- uint256
fallback
function () external payable
Fallback function. Prevents direct sending native coins to this contract.
initialize
function initialize(address _validatorSet, address _prevBlockReward) external
Initializes the contract at network startup. Can only be called by the constructor of the `InitializerAuRa` contract or owner.
- Parameters:
_validatorSet
- The address of the `ValidatorSetAuRa` contract._prevBlockReward
- The address of the previous BlockReward contract (for statistics migration purposes).
isInitialized
function isInitialized() public view returns (bool)
Returns a boolean flag indicating if the `initialize` function has been called.
- Returns:
- bool
onTokenTransfer
function onTokenTransfer(address , uint256 , bytes ) public pure returns (bool)
Prevents sending tokens directly to the `BlockRewardAuRa` contract address by the `ERC677BridgeTokenRewardable.transferAndCall` function.
- Parameters:
- address
- uint256
- bytes
- Returns:
- bool
reward
function reward(address[] benefactors, uint16[] kind) external returns (address[], uint256[])
Called by the validator's node when producing and closing a block, see https://openethereum.github.io/wiki/Block-Reward-Contract.html. This function performs all of the automatic operations needed for controlling numbers revealing by validators, accumulating block producing statistics, starting a new staking epoch, snapshotting staking amounts for the upcoming staking epoch, rewards distributing at the end of a staking epoch, and minting native coins needed for the `erc-to-native` bridge.
- Modifiers:
- onlySystem
- Parameters:
benefactors
- address[]kind
- uint16[]- Returns:
- address[]
- uint256[]
setErcToNativeBridgesAllowed
function setErcToNativeBridgesAllowed(address[] _bridgesAllowed) external
Sets the array of `erc-to-native` bridge addresses which are allowed to call some of the functions with the `onlyErcToNativeBridge` modifier. This setter can only be called by the `owner`.
- Modifiers:
- onlyOwner onlyInitialized
- Parameters:
_bridgesAllowed
- The array of bridge addresses.
validatorRewardPercent
function validatorRewardPercent(address _stakingAddress) public view returns (uint256)
Returns the reward coefficient for the specified validator. The given value should be divided by 10000 to get the value of the reward percent (since EVM doesn't support float values). If the specified staking address is an address of a candidate that is not about to be a validator on the current staking epoch the potentially possible reward coefficient is returned.
- Parameters:
_stakingAddress
- The staking address of the validator/candidate pool for which the getter must return the coefficient.- Returns:
- uint256
validatorShare
function validatorShare(uint256 _stakingEpoch, uint256 _validatorStaked, uint256 _totalStaked, uint256 _poolReward) public view returns (uint256)
Calculates validator's share for the given pool reward amount and the specified staking epoch. Used by the `validatorRewardPercent` and `StakingAuRa.claimReward` functions.
- Parameters:
_stakingEpoch
- The number of staking epoch._validatorStaked
- The amount staked by a validator._totalStaked
- The total amount staked by a validator and their delegators._poolReward
- The value of pool reward.- Returns:
- uint256