The following example uses methods from the contract. A methodology implemented by the validator nodes generates pseudorandom numbers.
The following is designed to work with 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:
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):
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.
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;
}
}
}
Below is the full RandomAura contract code (its POSDAO implementation is located at )
