📃WitnetRandomness
Last updated
Last updated
Bound to the WitnetOracle address, this contract provides easy-to-use, unpredictable and tamper-proof randomness to your smart contracts. Randomize requests requires paying a fee in EVM's native currency. The WitnetRandomness contract provides 256-bit of pure entropy from the Witnet oracle blockchain upon every single randomize request. Randomize requests take from 5 to 10 minutes to be solved and reported from Witnet into the EVM storage. Every randomize request gets ultimately solved by a different VRF-based selection of witnessing nodes in the Witnet oracle blockchain.
^ Pure methods that neither write nor read from storage.
= View methods that read from immutable code storage.
:: View methods that read from storage.
+ Methods that may potentially alter storage.
$ Payable methods that may potentially alter storage.
[]! Methods that may revert under certain conditions.
= class(): string
Returns the name of the contract that's actually implementing the ABI's specs() logic.
= specs(): bytes4
Returns the immutable ERC-165 id of the expected functionality as for the WitnetOracle ABI.
= witnet(): WitnetOracle
:: estimateRandomizeFee(uint256)
Returns amount of Wei required to be paid as fee when calling randomize() with a transaction gas price as the one given.
:! fetchRandomnessAfter(uint256)
Retrieves the result of Keccak256-hashing the given block number with the randomness value generated by the Witnet oracle blockchain in response to the first non-failing randomize request solved after such block number. Reverts if:
- no randomize() was requested on neither the given block, nor afterwards;
- the first non-failingrandomize() request found on or after the given block is not solved yet;
- all randomize() requests that took place on or after the given block were solved with errors.
:! fetchRandomnessAfterProof(u256)
Retrieves the actual random value, unique hash and timestamp of the witnessing commit/reveal act that took place in the Witnet oracle blockchain in response to the first non-failing randomize request solved after the given block number. Reverts under same conditions as fetchRandomnessAfter(uint256).
:: getLastRandomizeBlock()
Returns the last block number on which randomize() was called.
:: getRandomizeData(uint256)
:: getRandomizeNextBlock(uint256)
Returns the block number in which the next randomize request took place after the given block number, if any.
:: getRandomizePrevBlock(uint256)
Returns the block number in which the previous randomize request took place before the given block number, if any.
:: getRandomizeStatus(uint256)
Gets the current status of the first non-failing randomize request posted on or after the given block number.
:: isRandomized(uint256)
Tells whether there is a successful resolution to the first non-failing randomize request posted on, or after, the given block number.
:! random(uint32,uint256,uint256)
This method helps generating pseudo-random numbers uniformly distributed within the range [0 .. _range), by using the _nonce and the randomness seed returned by fetchRandomnessAfter(_blockNumber). Reverts under same conditions as fetchRandomnessAfter(uint256).
$! randomize()
Request the WitnetOracle to generate an EVM-agnostic, unbiased and unpredictable source of randomness. Only one randomness request per EVM block will be actually relayed to the Witnet blockchain. Returns amount of Wei actually paid as randomize fee. Unused EVM funds will be transferred back to the requester. Reverts if not paying enough fee, or paying a fee 10x times higher than the expected minimum fee (ultimately depending on the EVM transaction gas price).
:: witnetQuerySLA()
Returns the data SLA security parameters required for the Witnet blockchain to fulfill when solving randomness requests: - the number of witnessing nodes that will be randomly selected on the Witnet oracle blockchain; - the reward in $nanoWit that each witnessing node will get on the Witnet blockchain.
:: witnetRadHash()
Returns the RAD hash that uniquely identifies the underlying randomness request that gets solved on the Witnet oracle blockchain upon every new randomize.
WitnetQuery
address evmRequester
uint256 evmGasPrice
uint256 evmReward
uint256 queryId
bytes32 queryRadHash
RadonSLA querySLA
Emitted every time a call to randomize() triggers a new randomness request on the Witnet oracle blockchain.
Randomizing
address evmOrigin
address evmSender
uint256 witOracleQueryId
Emitted every time randomize() gets called.
committeeSize
uint8
Number of randomly selected nodes in the Witnet blockchain that will take part in solving some randomness request.
witnessingFeeNanoWit
uint256
Reward in nanowits that will be paid to every node in the Witnet blockchain involved in solving some randomness request. Randomly selected nodes in the Witnet blockchain will have to stake a collateral 100x this amount in order to participate as witnesses.
Possible response status of some given randomize request, as returned by getRandomizeStatus(uint256).
0x01
Awaiting
The underlying randomize request is being solved on the Witnet oracle blockchain and its result has not yet been reported to the EVM storage.
0x02
Ready
The underlying randomize request was successfully solved on Witnet, and the reported result can be considered to be final.
0x03
Error
The underlying randomize request was solved with errors on the Witnet blockchain, and the reported error can be considered to be final.
0x04
Finalizing
The result to the underlying randomize request is being bridged from the Witnet oracle blockchain but it cannot yet be considered to be final.
0x05
Delivered
The result to the underlying randomize request, either successful or with errors, was already delivered to the requesting contract that paid for it.
Address of the underlying singleton contract used for posting randomness requests to be solved on the Witnet blockchain.
Retrieves the metadata related to the randomize request that got posted to the on the given block number: - the underlying Witnet query id, if any; - block number of previous randomize, if any; - block number of next randomize, if any.
