POSDAO Smart Contracts Docs

ValidatorSetBase

contract ValidatorSetBase

is OwnedEternalStorage, IValidatorSet

The base contract for the ValidatorSetAuRa and ValidatorSetHBBFT contracts.

Source: contracts/abstracts/ValidatorSetBase.sol

Index

Reference

Events

  • InitiateChange

    event InitiateChange(bytes32 parentHash, address[] newSet)

    Emitted by the `emitInitiateChange` function when a new validator set needs to be applied in the Parity engine. See https://wiki.parity.io/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).

Modifiers

  • onlyInitialized

    modifier onlyInitialized()

    Ensures the `initialize` function was called before.

  • onlyStakingContract

    modifier onlyStakingContract()

    Ensures the caller is the Staking contract address (EternalStorageProxy proxy contract for Staking).

  • onlySystem

    modifier onlySystem()

    Ensures the caller is the SYSTEM_ADDRESS. See https://wiki.parity.io/Validator-Set.html.

Functions

  • _applyQueueValidators

    function _applyQueueValidators(address[] _queueValidators) internal

    Sets a new validator set returned by the `getValidators` getter. Called by the `finalizeChange` function.

    Parameters:
    _queueValidators - An array of new validators (their mining addresses).

  • _banStart

    abstract function _banStart() internal view returns (uint256)

    Returns the current block number or unix timestamp (depending on the consensus algorithm). Used by the `isValidatorBanned`, `_banUntil`, and `_banValidator` functions.

    Returns:
    uint256

  • _banUntil

    abstract function _banUntil() internal view returns (uint256)

    Returns the future block number or unix timestamp (depending on the consensus algorithm) until which a validator is banned.

    Returns:
    uint256

  • _banValidator

    function _banValidator(address _miningAddress) internal

    Sets the future block number or unix timestamp (depending on the consensus algorithm) until which the specified mining address is banned. Updates the banning statistics. Called by the `_removeMaliciousValidator` function.

    Parameters:
    _miningAddress - The banned mining address.

  • _dequeuePendingValidators

    function _dequeuePendingValidators() internal returns (address[], bool)

    Dequeues the pending validator set to pass it to the `InitiateChange` event (and then to the `finalizeChange` function). Called by the `emitInitiateChange` function.

    Returns:
    address[]
    bool

  • _enqueuePendingValidators

    function _enqueuePendingValidators(bool _newStakingEpoch) internal

    Enqueues the pending validator set which is returned by the `getPendingValidators` getter to be dequeued 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.

  • _getCurrentBlockNumber

    function _getCurrentBlockNumber() internal view returns (uint256)

    Returns the current block number. Needed mostly for unit tests.

    Returns:
    uint256

  • _getRandomIndex

    function _getRandomIndex(int256[] _likelihood, int256 _likelihoodSum, uint256 _randomNumber) internal pure returns (uint256)

    Returns an index of a pool in the `poolsToBeElected` array (see the `Staking.getPoolsToBeElected` getter) by a random number and the corresponding probability coefficients.

    Parameters:
    _likelihood - An array of probability coefficients.
    _likelihoodSum - A sum of probability coefficients.
    _randomNumber - A random number.
    Returns:
    uint256

  • _incrementChangeRequestCount

    function _incrementChangeRequestCount() internal

    Increments the serial number of a validator set changing request. The counter is incremented every time a validator set needs to be changed.

  • _newValidatorSet

    function _newValidatorSet() internal returns (uint256)

    An internal function implementing 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 `Random` contract. This function is called by the `newValidatorSet` function of a child contract.

    Returns:
    The number of pools ready to be elected (see the `Staking.getPoolsToBeElected` function).

  • _removeMaliciousValidator

    function _removeMaliciousValidator(address _miningAddress) internal returns (bool)

    Removes the specified validator as malicious. Used by a child contract.

    Parameters:
    _miningAddress - The removed validator mining address.
    Returns:
    Returns `true` if the specified validator has been removed from the pending validator set. Otherwise returns `false` (if the specified validator was already removed).

  • _setInitiateChangeAllowed

    function _setInitiateChangeAllowed(bool _allowed) internal

    Sets a boolean flag defining whether the `emitInitiateChange` can be called. Called by the `emitInitiateChange` and `finalizeChange` functions. See the `initiateChangeAllowed` getter.

    Parameters:
    _allowed - The boolean flag.

  • _setIsValidator

    function _setIsValidator(address _miningAddress, bool _isValidator) internal

    Sets a boolean flag defining whether the specified mining address is a validator (whether it is existed in the array returned by the `getValidators` getter). See the `_applyQueueValidators` function and `isValidator`/`getValidators` getters.

    Parameters:
    _miningAddress - The mining address.
    _isValidator - The boolean flag.

  • _setIsValidatorOnPreviousEpoch

    function _setIsValidatorOnPreviousEpoch(address _miningAddress, bool _isValidator) internal

    Sets a boolean flag indicating whether the specified mining address was a validator at the end of the previous staking epoch. See the `getPreviousValidators` and `isValidatorOnPreviousEpoch` getters.

    Parameters:
    _miningAddress - The mining address.
    _isValidator - The boolean flag.

  • _setPendingValidators

    function _setPendingValidators(IStaking _stakingContract, address[] _stakingAddresses, address _unremovableStakingAddress) internal

    Sets a new validator set as a pending (which is not yet finalized by the `finalizeChange` function). Removes the pools in the `poolsToBeRemoved` array (see the `Staking.getPoolsToBeRemoved` function). Called by the `_newValidatorSet` function.

    Parameters:
    _stakingContract - The `Staking` contract address.
    _stakingAddresses - The array of the new validators' staking addresses.
    _unremovableStakingAddress - The staking address of a non-removable validator. See the `unremovableValidator` getter.

  • _setQueueValidators

    function _setQueueValidators(address[] _miningAddresses, bool _newStakingEpoch) internal

    Sets a validator set for the `finalizeChange` function. Called by the `emitInitiateChange` function.

    Parameters:
    _miningAddresses - An array of the new validator set mining addresses.
    _newStakingEpoch - A boolean flag indicating whether the `_miningAddresses` array 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` getters.

    Parameters:
    _miningAddress - The mining address of a newly created pool. Cannot be equal to the `_stakingAddress`.
    _stakingAddress - The staking address of a newly created pool. Cannot be equal to the `_miningAddress`.

  • _setUnremovableValidator

    function _setUnremovableValidator(address _stakingAddress) internal

    Sets the staking address of a non-removable validator. Used by the `initialize` and `clearUnremovableValidator` functions.

    Parameters:
    _stakingAddress - The staking address of a non-removable validator.

  • _setValidatorIndex

    function _setValidatorIndex(address _miningAddress, uint256 _index) internal

    Stores the index of the specified validator in the current validator set returned by the `getValidators` getter. Used by the `_applyQueueValidators` function.

    Parameters:
    _miningAddress - The mining address the index is saved for.
    _index - The index value.

  • _setValidatorSetApplyBlock

    function _setValidatorSetApplyBlock(uint256 _blockNumber) internal

    Sets the block number at which the `finalizeChange` function was called to apply the current validator set formed by the `_newValidatorSet` function. Called by the `finalizeChange` and `_newValidatorSet` functions.

    Parameters:
    _blockNumber - The current block number. Set to zero when calling with `_newValidatorSet`.

  • banCounter

    function banCounter(address _miningAddress) public view returns (uint256)

    Returns how many times a given mining address was banned.

    Parameters:
    _miningAddress - The mining address of a candidate or validator.
    Returns:
    uint256

  • bannedUntil

    function bannedUntil(address _miningAddress) public view returns (uint256)

    Returns the block number or unix timestamp (depending on the consensus algorithm) when the ban will be lifted for the specified mining address.

    Parameters:
    _miningAddress - The mining address of a participant.
    Returns:
    The block number (for AuRa) or unix timestamp (for HBBFT) from which the ban will be lifted for the specified address.

  • blockRewardContract

    function blockRewardContract() public view returns (address)

    Returns the address of the `BlockReward` contract.

    Returns:
    address

  • changeRequestCount

    function changeRequestCount() public view returns (uint256)

    Returns the serial number of a validator set change request. The counter is incremented by the `_incrementChangeRequestCount` function every time a validator set needs to be changed.

    Returns:
    uint256

  • 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://wiki.parity.io/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. 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` (this is achieved by the queue, `emitInitiateChange` function, and `initiateChangeAllowed` boolean flag - see the `_setInitiateChangeAllowed` function).

    Modifiers:
    onlySystem

  • getPendingValidators

    function getPendingValidators() public view returns (address[])

    Returns the current array of validators which is not yet finalized by the `finalizeChange` function. The pending array is changed when a validator is removed as malicious or the validator set is updated at the beginning of a new staking epoch (see the `_newValidatorSet` function). Every time the pending array is updated, it is enqueued by the `_enqueuePendingValidators` and then dequeued by the `emitInitiateChange` function which emits the `InitiateChange` event to all validator nodes.

    Returns:
    address[]

  • getPreviousValidators

    function getPreviousValidators() public view returns (address[])

    Returns the validator set (validators' mining addresses array) which was active at the end of the previous staking epoch. The array is stored by the `finalizeChange` function when a new staking epoch's validator set is finalized.

    Returns:
    address[]

  • getQueueValidators

    function getQueueValidators() public view returns (address[], bool)

    Returns a validator set to be finalized by the `finalizeChange` function. Used by the `finalizeChange` function.

    Returns:
    address[]
    bool

  • getValidators

    function getValidators() public view returns (address[])

    Returns the current validator set (an array of mining addresses) which always matches the validator set in the Parity engine.

    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` or `InitializerHBBFT` contract.

    Parameters:
    _blockRewardContract - The address of the `BlockReward` contract.
    _randomContract - The address of the `Random` contract.
    _stakingContract - The address of the `Staking` 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. Must be `false` for a production network.

  • initiateChangeAllowed

    function initiateChangeAllowed() public view returns (bool)

    Returns 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 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) can 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

  • isValidator

    function isValidator(address _miningAddress) public view returns (bool)

    Returns a boolean flag indicating whether the specified mining address is in the current validator set. See the `getValidators` getter.

    Parameters:
    _miningAddress - The 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 `_banValidator` function).

    Parameters:
    _miningAddress - The mining address.
    Returns:
    bool

  • isValidatorOnPreviousEpoch

    function isValidatorOnPreviousEpoch(address _miningAddress) public view returns (bool)

    Returns a boolean flag indicating whether the specified mining address was a validator at the end of the previous staking epoch. See the `getPreviousValidators` getter.

    Parameters:
    _miningAddress - The mining address.
    Returns:
    bool

  • miningByStakingAddress

    function miningByStakingAddress(address _stakingAddress) public view returns (address)

    Returns a mining address bound to a specified staking address. See the `_setStakingAddress` function.

    Parameters:
    _stakingAddress - The staking address for which the function must return the corresponding mining address.
    Returns:
    address

  • randomContract

    function randomContract() public view returns (address)

    Returns the `Random` contract address.

    Returns:
    address

  • setStakingAddress

    function setStakingAddress(address _miningAddress, address _stakingAddress) external

    Binds a mining address to the specified staking address. Called by the `Staking.addPool` function when a user wants to become a candidate and create a pool. See also the `miningByStakingAddress` and `stakingByMiningAddress` getters.

    Modifiers:
    onlyStakingContract
    Parameters:
    _miningAddress - The mining address of the newly created pool. Cannot be equal to the `_stakingAddress`.
    _stakingAddress - The staking address of the newly created pool. Cannot be equal to the `_miningAddress`.

  • stakingByMiningAddress

    function stakingByMiningAddress(address _miningAddress) public view returns (address)

    Returns a staking address bound to a specified mining address. See the `_setStakingAddress` function.

    Parameters:
    _miningAddress - The mining address for which the function must return the corresponding staking address.
    Returns:
    address

  • stakingContract

    function stakingContract() public view returns (address)

    Returns the `Staking` contract address.

    Returns:
    address

  • unremovableValidator

    function unremovableValidator() public view returns (address)

    Returns the staking address of the non-removable validator. Returns zero if a non-removable validator is not defined.

    Returns:
    address

  • validatorCounter

    function validatorCounter(address _miningAddress) public view returns (uint256)

    Returns how many times the given address has become a validator.

    Parameters:
    _miningAddress - The mining address.
    Returns:
    uint256

  • validatorIndex

    function validatorIndex(address _miningAddress) public view returns (uint256)

    Returns the index of the specified validator in the current validator set returned by the `getValidators` getter.

    Parameters:
    _miningAddress - The mining address the index is returned for.
    Returns:
    If the returned value is zero, it may mean the array doesn't contain the address. Check the address is in the current validator set using the `isValidator` getter.

  • validatorSetApplyBlock

    function validatorSetApplyBlock() public view returns (uint256)

    Returns the block number when the `finalizeChange` function was called to apply the current validator set formed by the `_newValidatorSet` function. If it returns zero, it means the `_newValidatorSet` function has already been called (a new staking epoch has been started), but the new staking epoch's validator set hasn't yet been finalized by the `finalizeChange` function. See the `_setValidatorSetApplyBlock` function which is called by the `finalizeChange` and `_newValidatorSet` functions.

    Returns:
    uint256
← StakingBaseEternalStorage →