RNG explainer (AuRa + RandomAura Contract)

The following example uses methods from the RandomAura contract. A RANDAO methodology implemented by the validator nodes generates pseudorandom numbers.

The following is designed to work with Parity's AuRa consensus protocol v2.7.2+, slated for implementation on Kovan, Sokol, POA Core and/or xDai. In this protocol, validators take turns sealing blocks, one after the other, in a prescribed order.

Collection Rounds

A series of collection rounds are used for random number generation. The collection round length is configurable - in this example we use 38 blocks for a round, split into two equal 19 block phases:

• commit phase

• reveal phase

The length of each phase is 19 blocks ( 38 / 2 = 19). When one collection round finishes, the next collection round starts, and so on. For example:

Block number   |   Phase
...
101                Commit phase     <-- collection round #1 started here
102                Commit phase
103                Commit phase
...
117                Commit phase
118                Commit phase
119                Commit phase
120                Reveal phase
121                Reveal phase
122                Reveal phase
...
136                Reveal phase
137                Reveal phase
138                Reveal phase     <-- collection round #1 finished here
139                Commit phase     <-- collection round #2 started here
140                Commit phase
141                Commit phase
...

During each collection round, the RandomAura contract (see below) collects the random numbers generated during that round.

Commit Phase

1) Each validator in the set generates a random number locally with their node, hashes the secret, and calls the commitHash function when it is their turn to create a block.

/// @dev Called by the validator's node to store a hash and a cipher of the validator's number on each collection
/// round. The validator's node must use its mining address (engine_signer) to call this function.
/// This function can only be called once per collection round (during the `commit phase`).
/// @param _numberHash The Keccak-256 hash of the validator's number.
/// @param _cipher The cipher of the validator's number. Can be used by the node to restore the lost number after
/// the node is restarted (see the `getCipher` getter).
function commitHash(bytes32 _numberHash, bytes calldata _cipher) external {
    address miningAddress = msg.sender;

    require(block.coinbase == miningAddress);
    require(isCommitPhase()); // must only be called in `commit phase`
    require(_numberHash != bytes32(0));
    require(!isCommitted(currentCollectRound(), miningAddress)); // cannot commit more than once

    uint256 collectRound = currentCollectRound();

    _commits[collectRound][miningAddress] = _numberHash;
    _ciphers[collectRound][miningAddress] = _cipher;
}

2) This function accepts the hash of the secret number and its cipher. The cipher is the number encrypted with a validator's key, and is needed for the reveal phase (see below).

For example, if there are three validators, they will call commitHash in the following order (for the sample case above):

Block number   |   Phase   |       What happens
...
101             Commit phase    Validator1 calls `commitHash`
102             Commit phase    Validator2 calls `commitHash`
103             Commit phase    Validator3 calls `commitHash`
104             Commit phase    Nothing happens
105             Commit phase    Nothing happens
106             Commit phase    Nothing happens
...
117             Commit phase    Nothing happens
118             Commit phase    Nothing happens
119             Commit phase    Nothing happens
120             Reveal phase    Validator1 calls `revealSecret`
121             Reveal phase    Validator2 calls `revealSecret`
122             Reveal phase    Validator3 calls `revealSecret`
123             Reveal phase    Nothing happens
125             Reveal phase    Nothing happens
126             Reveal phase    Nothing happens
...
136             Reveal phase    Nothing happens
137             Reveal phase    Nothing happens
138             Reveal phase    Nothing happens
139             Commit phase    Validator1 calls `commitHash`
140             Commit phase    Validator2 calls `commitHash`
141             Commit phase    Validator3 calls `commitHash`
...

When the commit phase finishes, the reveal phase starts.

Reveal Phase

When a validator's turn arrives to create a block:

1) The validator gets the cipher of the number using the getCommitAndCipher public getter.

/// @dev Returns the Keccak-256 hash and cipher of the validator's number for the specified collection round
/// and the specified validator stored by the validator through the `commitHash` function.
/// @param _collectRound The serial number of the collection round for which hash and cipher should be retrieved.
/// @param _miningAddress The mining address of validator (engine_signer).
function getCommitAndCipher(
    uint256 _collectRound,
    address _miningAddress
) public view returns(bytes32, bytes memory) {
    return (_commits[_collectRound][_miningAddress], _ciphers[_collectRound][_miningAddress]);
}

2) The validator decrypts the cipher with their key and retrieves the number.

3) The validator calls the revealNumberfunction to reveal their committed number (the function XORs the number with the previous seed to create a new random seed stored in the currentSeed state variable).

/// @dev Called by the validator's node to XOR its number with the current random seed.
/// The validator's node must use its mining address (engine_signer) to call this function.
/// This function can only be called once per collection round (during the `reveal phase`).
/// @param _number The validator's number.
function revealNumber(uint256 _number) external {
    address miningAddress = msg.sender;

    bytes32 numberHash = keccak256(abi.encodePacked(_number));
    uint256 collectRound = currentCollectRound();

    require(block.coinbase == miningAddress);
    require(!isCommitPhase()); // must only be called in `reveal phase`
    require(numberHash != bytes32(0));
    require(numberHash == _commits[collectRound][miningAddress]); // the hash must be commited
    require(!_sentReveal[collectRound][miningAddress]); // cannot reveal more than once during the same collect round

    currentSeed = currentSeed ^ _number;

    _sentReveal[collectRound][miningAddress] = true;
    delete _commits[collectRound][miningAddress];
    delete _ciphers[collectRound][miningAddress];
}

Note: Randomness created in a deterministic manner, through computerized means, it is called pseudorandomness. Pseudorandom numbers exhibit the same properties as random numbers. The method described above is technically a pseudorandom number generator (PRNG)

RandomAura Contract Code

The RandomAura Contract interfaces with the Authority Round consensus process to store and iterate the currentSeed , control when the seed is revealed, and report on skipped reveals by Validators.

Below is the full RandomAura contract code (its POSDAO implementation is located at https://github.com/poanetwork/posdao-contracts/blob/master/contracts/RandomAuRa.sol)

pragma solidity 0.5.16;


/// @dev Generates and stores random numbers in a RANDAO manner (and controls when they are revealed by AuRa
/// validators) and accumulates a random seed.
contract RandomAuRa {

    mapping(uint256 => mapping(address => bytes)) internal _ciphers;
    mapping(uint256 => mapping(address => bytes32)) internal _commits;
    mapping(uint256 => mapping(address => bool)) internal _sentReveal;

    /// @dev The length of the collection round (in blocks).
    uint256 public constant collectRoundLength = 38;

    /// @dev The current random seed accumulated.
    uint256 public currentSeed;

    /// @dev Called by the validator's node to store a hash and a cipher of the validator's number on each collection
    /// round. The validator's node must use its mining address (engine_signer) to call this function.
    /// This function can only be called once per collection round (during the `commit phase`).
    /// @param _numberHash The Keccak-256 hash of the validator's number.
    /// @param _cipher The cipher of the validator's number. Can be used by the node to restore the lost number after
    /// the node is restarted (see the `getCipher` getter).
    function commitHash(bytes32 _numberHash, bytes calldata _cipher) external {
        address miningAddress = msg.sender;

        require(block.coinbase == miningAddress);
        require(isCommitPhase()); // must only be called in `commit phase`
        require(_numberHash != bytes32(0));
        require(!isCommitted(currentCollectRound(), miningAddress)); // cannot commit more than once

        uint256 collectRound = currentCollectRound();

        _commits[collectRound][miningAddress] = _numberHash;
        _ciphers[collectRound][miningAddress] = _cipher;
    }

    /// @dev Called by the validator's node to XOR its number with the current random seed.
    /// The validator's node must use its mining address (engine_signer) to call this function.
    /// This function can only be called once per collection round (during the `reveal phase`).
    /// @param _number The validator's number.
    function revealNumber(uint256 _number) external {
        address miningAddress = msg.sender;

        bytes32 numberHash = keccak256(abi.encodePacked(_number));
        uint256 collectRound = currentCollectRound();

        require(block.coinbase == miningAddress);
        require(!isCommitPhase()); // must only be called in `reveal phase`
        require(numberHash != bytes32(0));
        require(numberHash == _commits[collectRound][miningAddress]); // the hash must be commited
        require(!_sentReveal[collectRound][miningAddress]); // cannot reveal more than once during the same collect round

        currentSeed = currentSeed ^ _number;

        _sentReveal[collectRound][miningAddress] = true;
        delete _commits[collectRound][miningAddress];
        delete _ciphers[collectRound][miningAddress];
    }

    /// @dev Returns the serial number of the current collection round.
    /// Needed when using `getCommit`, `isCommitted`, `sentReveal`, or `getCipher` getters (see below).
    function currentCollectRound() public view returns(uint256) {
        return (block.number - 1) / collectRoundLength;
    }

    /// @dev Returns the Keccak-256 hash and cipher of the validator's number for the specified collection round
    /// and the specified validator stored by the validator through the `commitHash` function.
    /// @param _collectRound The serial number of the collection round for which hash and cipher should be retrieved.
    /// @param _miningAddress The mining address of validator (engine_signer).
    function getCommitAndCipher(
        uint256 _collectRound,
        address _miningAddress
    ) public view returns(bytes32, bytes memory) {
        return (_commits[_collectRound][_miningAddress], _ciphers[_collectRound][_miningAddress]);
    }

    /// @dev Returns a boolean flag indicating whether the specified validator has committed their number's hash for the
    /// specified collection round.
    /// @param _collectRound The serial number of the collection round for which the checkup should be done.
    /// Should be read with `currentCollectRound()` getter.
    /// @param _miningAddress The mining address of the validator (engine_signer).
    function isCommitted(uint256 _collectRound, address _miningAddress) public view returns(bool) {
        return _commits[_collectRound][_miningAddress] != bytes32(0);
    }

    /// @dev Returns a boolean flag of whether the specified validator has revealed their number for the
    /// specified collection round.
    /// @param _collectRound The serial number of the collection round for which the checkup should be done.
    /// Should be read with `currentCollectRound()` getter.
    /// @param _miningAddress The mining address of the validator (engine_signer).
    function sentReveal(uint256 _collectRound, address _miningAddress) public view returns(bool) {
        return _sentReveal[_collectRound][_miningAddress];
    }

    /// @dev Returns a boolean flag indicating whether the current phase of the current collection round
    /// is a `commit phase`. Used by the validator's node to determine if it should commit the hash of
    /// the number during the current collection round.
    function isCommitPhase() public view returns(bool) {
        uint256 commitPhaseLength = collectRoundLength / 2;
        return ((block.number - 1) % collectRoundLength) < commitPhaseLength;
    }
    
    /// @dev Returns the number of the first block of the current collection round.
    function currentCollectRoundStartBlock() public view returns(uint256) {
        return currentCollectRound() * collectRoundLength + 1;
    }

    /// @dev Returns the number of the first block of the next (future) collection round.
    function nextCollectRoundStartBlock() public view returns(uint256) {
        uint256 remainingBlocksToNextRound = collectRoundLength - (block.number - 1) % collectRoundLength;
        return block.number + remainingBlocksToNextRound;
    }

    /// @dev Returns the number of the first block of the next (future) commit phase.
    function nextCommitPhaseStartBlock() public view returns(uint256) {
        return nextCollectRoundStartBlock();
    }

    /// @dev Returns the number of the first block of the next (future) reveal phase.
    function nextRevealPhaseStartBlock() public view returns(uint256) {
        uint256 commitPhaseLength = collectRoundLength / 2;
        if (isCommitPhase()) {
            return currentCollectRoundStartBlock() + commitPhaseLength;
        } else {
            return nextCollectRoundStartBlock() + commitPhaseLength;
        }
    }

}