ValidatorSetAuRa
contract ValidatorSetAuRa
is UpgradeabilityAdmin, IValidatorSetAuRa
Stores the current validator set and contains the logic for choosing new validators before each staking epoch. The logic uses a random seed generated and stored by the `RandomAuRa` contract.
Index
- InitiateChange
- ReportedMalicious
- _banUntil
- _clearReportingCounter
- _finalizeNewValidators
- _getCurrentBlockNumber
- _getRandomIndex
- _incrementReportingCounter
- _removeMaliciousValidator
- _removeMaliciousValidators
- _savePreviousValidators
- _setPendingValidators
- _setPendingValidatorsChanged
- _setStakingAddress
- _unsetPendingValidatorsChanged
- areDelegatorsBanned
- clearUnremovableValidator
- emitInitiateChange
- emitInitiateChangeCallable
- finalizeChange
- getPendingValidators
- getPreviousValidators
- getValidators
- initialize
- initiateChangeAllowed
- isInitialized
- isReportValidatorValid
- isValidatorBanned
- isValidatorOrPending
- maliceReportedForBlock
- newValidatorSet
- onlyBlockRewardContract
- onlyInitialized
- onlyRandomContract
- onlyStakingContract
- onlySystem
- removeMaliciousValidators
- reportMalicious
- reportMaliciousCallable
- setStakingAddress
- shouldValidatorReport
- validatorsToBeFinalized
Reference
Events
InitiateChange
event InitiateChange(bytes32 parentHash, address[] newSet)
Emitted by the `emitInitiateChange` function when a new validator set needs to be applied by validator nodes. See https://openethereum.github.io/wiki/Validator-Set.html.
- Parameters:
parentHash
- Should be the parent block hash, otherwise the signal won't be recognized.newSet
- An array of new validators (their mining addresses).
ReportedMalicious
event ReportedMalicious(address reportingValidator, address maliciousValidator, uint256 blockNumber)
Emitted by the `reportMalicious` function to signal that a specified validator reported misbehavior by a specified malicious validator at a specified block number.
- Parameters:
reportingValidator
- The mining address of the reporting validator.maliciousValidator
- The mining address of the malicious validator.blockNumber
- The block number at which the `maliciousValidator` misbehaved.
Modifiers
onlyBlockRewardContract
modifier onlyBlockRewardContract()
Ensures the caller is the BlockRewardAuRa contract address.
onlyInitialized
modifier onlyInitialized()
Ensures the `initialize` function was called before.
onlyRandomContract
modifier onlyRandomContract()
Ensures the caller is the RandomAuRa contract address.
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/Validator-Set.html.
Functions
_banUntil
function _banUntil() internal view returns (uint256)
Returns the future block number until which a validator is banned. Used by the `_removeMaliciousValidator` internal function.
- Returns:
- uint256
_clearReportingCounter
function _clearReportingCounter(address _miningAddress) internal
Updates the total reporting counter (see the `reportingCounterTotal` public mapping) for the current staking epoch after the specified validator is removed as malicious. The `reportMaliciousCallable` getter uses this counter for reporting checks so it must be up-to-date. Called by the `_removeMaliciousValidators` internal function.
- Parameters:
_miningAddress
- The mining address of the removed malicious validator.
_finalizeNewValidators
function _finalizeNewValidators(bool _newStakingEpoch) internal
Sets a new validator set stored in `_finalizeValidators.list` array. Called by the `finalizeChange` function.
- Parameters:
_newStakingEpoch
- A boolean flag defining whether the validator set was formed by the `newValidatorSet` function.
_getCurrentBlockNumber
function _getCurrentBlockNumber() internal view returns (uint256)
Returns the current block number. Needed mostly for unit tests.
- Returns:
- uint256
_getRandomIndex
function _getRandomIndex(uint256[] _likelihood, uint256 _likelihoodSum, uint256 _randomNumber) internal pure returns (uint256)
Returns an index of a pool in the `poolsToBeElected` array (see the `StakingAuRa.getPoolsToBeElected` public getter) by a random number and the corresponding probability coefficients. Used by the `newValidatorSet` function.
- Parameters:
_likelihood
- An array of probability coefficients._likelihoodSum
- A sum of probability coefficients._randomNumber
- A random number.- Returns:
- uint256
_incrementReportingCounter
function _incrementReportingCounter(address _reportingMiningAddress) internal
Increments the reporting counter for the specified validator and the current staking epoch. See the `reportingCounter` and `reportingCounterTotal` public mappings. Called by the `reportMalicious` function when the validator reports a misbehavior.
- Parameters:
_reportingMiningAddress
- The mining address of reporting validator.
_removeMaliciousValidator
function _removeMaliciousValidator(address _miningAddress, bytes32 _reason) internal returns (bool)
Removes the specified validator as malicious. Used by the `_removeMaliciousValidators` internal function.
- Parameters:
_miningAddress
- The removed validator mining address._reason
- A short string of the reason why the mining address is treated as malicious: "unrevealed" - the validator didn't reveal their number at the end of staking epoch or skipped too many reveals during the staking epoch; "spam" - the validator made a lot of `reportMalicious` callings compared with other validators; "malicious" - the validator was reported as malicious by other validators with the `reportMalicious` function.- Returns:
- Returns `true` if the specified validator has been removed from the pending validator set. Otherwise returns `false` (if the specified validator has already been removed or cannot be removed).
_removeMaliciousValidators
function _removeMaliciousValidators(address[] _miningAddresses, bytes32 _reason) internal
Removes the specified validators as malicious from the pending validator set and marks the updated pending validator set as `changed` to be used by the `emitInitiateChange` function. Does nothing if the specified validators are already banned, non-removable, or don't exist in the pending validator set.
- Parameters:
_miningAddresses
- The mining addresses of the malicious validators._reason
- A short string of the reason why the mining addresses are treated as malicious, see the `_removeMaliciousValidator` internal function description for possible values.
_savePreviousValidators
function _savePreviousValidators() internal
Stores previous validators. Used by the `finalizeChange` function.
_setPendingValidators
function _setPendingValidators(address[] _stakingAddresses) internal
Sets a new validator set as a pending (which is not yet passed to the `InitiateChange` event). Called by the `newValidatorSet` function.
- Parameters:
_stakingAddresses
- The array of the new validators' staking addresses.
_setPendingValidatorsChanged
function _setPendingValidatorsChanged(bool _newStakingEpoch) internal
Marks the pending validator set as changed to be used later by the `emitInitiateChange` function. Called when a validator is removed from the set as malicious or when a new validator set is formed by the `newValidatorSet` function.
- Parameters:
_newStakingEpoch
- A boolean flag defining whether the pending validator set was formed by the `newValidatorSet` function. The `finalizeChange` function logic depends on this flag.
_setStakingAddress
function _setStakingAddress(address _miningAddress, address _stakingAddress) internal
Binds a mining address to the specified staking address. Used by the `setStakingAddress` function. See also the `miningByStakingAddress` and `stakingByMiningAddress` public mappings.
- Parameters:
_miningAddress
- The mining address of the newly created pool. Cannot be equal to the `_stakingAddress` and should never be used as a pool before._stakingAddress
- The staking address of the newly created pool. Cannot be equal to the `_miningAddress` and should never be used as a pool before.
_unsetPendingValidatorsChanged
function _unsetPendingValidatorsChanged() internal returns (bool)
Marks the pending validator set as unchanged before passing it to the `InitiateChange` event (and then to the `finalizeChange` function). Called by the `emitInitiateChange` function.
- Returns:
- bool
areDelegatorsBanned
function areDelegatorsBanned(address _miningAddress) public view returns (bool)
Returns a boolean flag indicating whether delegators of the specified pool are currently banned. A validator pool can be banned when they misbehave (see the `_removeMaliciousValidator` function).
- Parameters:
_miningAddress
- The mining address of the pool.- Returns:
- bool
clearUnremovableValidator
function clearUnremovableValidator() external
Makes the non-removable validator removable. Can only be called by the staking address of the non-removable validator or by the `owner`.
- Modifiers:
- onlyInitialized
emitInitiateChange
function emitInitiateChange() external
Emits the `InitiateChange` event to pass a new validator set to the validator nodes. Called automatically by one of the current validator's nodes when the `emitInitiateChangeCallable` getter returns `true` (when some validator needs to be removed as malicious or the validator set needs to be updated at the beginning of a new staking epoch). The new validator set is passed to the validator nodes through the `InitiateChange` event and saved for later use by the `finalizeChange` function. See https://openethereum.github.io/wiki/Validator-Set.html for more info about the `InitiateChange` event.
- Modifiers:
- onlyInitialized
emitInitiateChangeCallable
function emitInitiateChangeCallable() public view returns (bool)
Returns a boolean flag indicating whether the `emitInitiateChange` function can be called at the moment. Used by a validator's node and `TxPermission` contract (to deny dummy calling).
- Returns:
- bool
finalizeChange
function finalizeChange() external
Called by the system when an initiated validator set change reaches finality and is activated. This function is called at the beginning of a block (before all the block transactions). Only valid when msg.sender == SUPER_USER (EIP96, 2**160 - 2). Stores a new validator set saved before by the `emitInitiateChange` function and passed through the `InitiateChange` event. After this function is called, the `getValidators` getter returns the new validator set. If this function finalizes a new validator set formed by the `newValidatorSet` function, an old validator set is also stored and can be read by the `getPreviousValidators` getter. The `finalizeChange` is only called once for each `InitiateChange` event emitted. The next `InitiateChange` event is not emitted until the previous one is not yet finalized by the `finalizeChange` (see the code of `emitInitiateChangeCallable` getter).
- Modifiers:
- onlySystem
getPendingValidators
function getPendingValidators() public view returns (address[])
Returns the current array of validators which should be passed to the `InitiateChange` event. The pending array is changed when a validator is removed as malicious or the validator set is updated by the `newValidatorSet` function. Every time the pending array is changed, it is marked by the `_setPendingValidatorsChanged` and then used by the `emitInitiateChange` function which emits the `InitiateChange` event to all validator nodes.
- Returns:
- address[]
getPreviousValidators
function getPreviousValidators() public view returns (address[])
Returns the previous validator set (validators' mining addresses array). The array is stored by the `finalizeChange` function when a new staking epoch's validator set is finalized.
- Returns:
- address[]
getValidators
function getValidators() public view returns (address[])
Returns the current validator set (an array of mining addresses) which always matches the validator set kept in validator's node.
- Returns:
- address[]
initialize
function initialize(address _blockRewardContract, address _randomContract, address _stakingContract, address[] _initialMiningAddresses, address[] _initialStakingAddresses, bool _firstValidatorIsUnremovable) external
Initializes the network parameters. Used by the constructor of the `InitializerAuRa` contract.
- Parameters:
_blockRewardContract
- The address of the `BlockRewardAuRa` contract._randomContract
- The address of the `RandomAuRa` contract._stakingContract
- The address of the `StakingAuRa` contract._initialMiningAddresses
- The array of initial validators' mining addresses._initialStakingAddresses
- The array of initial validators' staking addresses._firstValidatorIsUnremovable
- The boolean flag defining whether the first validator in the `_initialMiningAddresses/_initialStakingAddresses` array is non-removable. Should be `false` for a production network.
initiateChangeAllowed
function initiateChangeAllowed() public view returns (bool)
A boolean flag indicating whether the `emitInitiateChange` can be called at the moment. Used by the `emitInitiateChangeCallable` getter. This flag is set to `false` by the `emitInitiateChange` and set to `true` by the `finalizeChange` function. When the `InitiateChange` event is emitted by `emitInitiateChange`, the next `emitInitiateChange` call is not possible until the validator set from the previous call is finalized by the `finalizeChange` function.
- Returns:
- bool
isInitialized
function isInitialized() public view returns (bool)
Returns a boolean flag indicating if the `initialize` function has been called.
- Returns:
- bool
isReportValidatorValid
function isReportValidatorValid(address _miningAddress) public view returns (bool)
Returns a boolean flag indicating whether the specified validator (mining address) is able to call the `reportMalicious` function or whether the specified validator (mining address) can be reported as malicious. This function also allows a validator to call the `reportMalicious` function several blocks after ceasing to be a validator. This is possible if a validator did not have the opportunity to call the `reportMalicious` function prior to the engine calling the `finalizeChange` function.
- Parameters:
_miningAddress
- The validator's mining address.- Returns:
- bool
isValidatorBanned
function isValidatorBanned(address _miningAddress) public view returns (bool)
Returns a boolean flag indicating whether the specified mining address is currently banned. A validator can be banned when they misbehave (see the `_removeMaliciousValidator` internal function).
- Parameters:
_miningAddress
- The mining address.- Returns:
- bool
isValidatorOrPending
function isValidatorOrPending(address _miningAddress) public view returns (bool)
Returns a boolean flag indicating whether the specified mining address is a validator or is in the `_pendingValidators` or `_finalizeValidators` array. Used by the `StakingAuRa.maxWithdrawAllowed` and `StakingAuRa.maxWithdrawOrderAllowed` getters.
- Parameters:
_miningAddress
- The mining address.- Returns:
- bool
maliceReportedForBlock
function maliceReportedForBlock(address _miningAddress, uint256 _blockNumber) public view returns (address[])
Returns an array of the validators (their mining addresses) which reported that the specified malicious validator misbehaved at the specified block.
- Parameters:
_miningAddress
- The mining address of malicious validator._blockNumber
- The block number.- Returns:
- address[]
newValidatorSet
function newValidatorSet() external
Implements the logic which forms a new validator set. If the number of active pools is greater than MAX_VALIDATORS, the logic chooses the validators randomly using a random seed generated and stored by the `RandomAuRa` contract. Automatically called by the `BlockRewardAuRa.reward` function at the latest block of the staking epoch.
- Modifiers:
- onlyBlockRewardContract
removeMaliciousValidators
function removeMaliciousValidators(address[] _miningAddresses) external
Removes malicious validators. Called by the `RandomAuRa.onFinishCollectRound` function.
- Modifiers:
- onlyRandomContract
- Parameters:
_miningAddresses
- The mining addresses of the malicious validators.
reportMalicious
function reportMalicious(address _maliciousMiningAddress, uint256 _blockNumber, bytes ) external
Reports that the malicious validator misbehaved at the specified block. Called by the node of each honest validator after the specified validator misbehaved. See https://openethereum.github.io/wiki/Validator-Set.html#reporting-contract Can only be called when the `reportMaliciousCallable` getter returns `true`.
- Modifiers:
- onlyInitialized
- Parameters:
_maliciousMiningAddress
- The mining address of the malicious validator._blockNumber
- The block number where the misbehavior was observed.- bytes
reportMaliciousCallable
function reportMaliciousCallable(address _reportingMiningAddress, address _maliciousMiningAddress, uint256 _blockNumber) public view returns (bool, bool)
Returns whether the `reportMalicious` function can be called by the specified validator with the given parameters. Used by the `reportMalicious` function and `TxPermission` contract. Also, returns a boolean flag indicating whether the reporting validator should be removed as malicious due to excessive reporting during the current staking epoch.
- Parameters:
_reportingMiningAddress
- The mining address of the reporting validator which is calling the `reportMalicious` function._maliciousMiningAddress
- The mining address of the malicious validator which is passed to the `reportMalicious` function._blockNumber
- The block number which is passed to the `reportMalicious` function.- Returns:
- `bool callable` - The boolean flag indicating whether the `reportMalicious` function can be called at the moment. `bool removeReportingValidator` - The boolean flag indicating whether the reporting validator should be removed as malicious due to excessive reporting. This flag is only used by the `reportMalicious` function.
setStakingAddress
function setStakingAddress(address _miningAddress, address _stakingAddress) external
Binds a mining address to the specified staking address. Called by the `StakingAuRa.addPool` function when a user wants to become a candidate and creates a pool. See also the `miningByStakingAddress` and `stakingByMiningAddress` public mappings.
- Modifiers:
- onlyStakingContract
- Parameters:
_miningAddress
- The mining address of the newly created pool. Cannot be equal to the `_stakingAddress` and should never be used as a pool before._stakingAddress
- The staking address of the newly created pool. Cannot be equal to the `_miningAddress` and should never be used as a pool before.
shouldValidatorReport
function shouldValidatorReport(address _reportingMiningAddress, address _maliciousMiningAddress, uint256 _blockNumber) public view returns (bool)
Only used by Ethereum client (see https://github.com/paritytech/parity-ethereum/pull/11245). Returns a boolean flag indicating whether the specified validator should report about some validator's misbehaviour at the specified block.
- Parameters:
_reportingMiningAddress
- The mining address of validator who reports._maliciousMiningAddress
- The mining address of malicious validator._blockNumber
- The block number at which the validator misbehaved.- Returns:
- bool
validatorsToBeFinalized
function validatorsToBeFinalized() public view returns (address[], bool)
Returns a validator set about to be finalized by the `finalizeChange` function.
- Returns:
- address[]
- bool