LogoLogo
WebsiteDiscordTelegramTwitter
  • 🏠Witnet Oracle Docs
  • Introduction
    • ❓What is Witnet?
      • ⚙️Oracle Architecture
      • 🪙The Witnet Coin (Wit)
      • 👛Wallets
      • 🤔Frequently Asked Questions
      • 😎Awesome Witnet
    • 🚀Quick Tutorials
      • 📈Price Feeds
      • 🎲Randomness
      • 🌐APIs and HTTP GET/POST
      • ⛏️Mining Wit
  • Smart contracts developers
    • ⛓️Supported chains
    • 🔮Wit/Oracle
      • HTTP GET Requests in Solidity
      • HTTP POST Requests in Solidity
      • Query GraphQL APIs in Solidity
      • Dynamic Requests in Solidity
      • UsingWitnet Inheritance
      • API Reference
        • Solidity API
          • Solidity Contracts
            • WitnetRequestBoard
        • Javascript API
        • RADON API
          • RADON Type System
          • RADON Errors
      • Multi-chain Addresses
    • 💹Wit/Price Feeds
      • How To Use Witnet Price Feeds
      • Update Conditions
      • Code Examples
      • API Reference
      • Multi-chain Addresses
        • Arbitrum Price Feeds
        • Avalanche Price Feeds
        • Base Price Feeds
        • Boba Price Feeds
        • Celo Price Feeds
        • Conflux Price Feeds
        • Cronos Price Feeds
        • Dogechain Price Feeds
        • Elastos Price Feeds
        • Ethereum Price Feeds
        • Gnosis Chain Price Feeds
        • Kaia Price Feeds
        • Kava Price Feeds
        • KCC Price Feeds
        • Mantle Price Feeds
        • Meter Price Feeds
        • Metis Price Feeds
        • Moonbeam Price Feeds
        • OKX Price Feeds
        • Optimism Price Feeds
        • Polygon Price Feeds
        • Reef Price Feeds
        • Scroll Price Feeds
        • Syscoin Price Feeds
        • Ultron Price Feeds
        • Request new price feed or chain support
    • 🎲Wit/Randomness
      • Generating Randomness
      • WitnetRandomness Contract
      • Low-level Requests
      • Code Examples
      • API Reference
      • Multi-chain Addresses
    • 🏗️Guides
      • 📖Solidity Contracts
        • Appliances
          • 📃WitnetPriceFeeds
          • 📃WitnetRandomness
        • Core
          • 📃WitnetOracle
          • 📃WitnetRadonRegistry
          • 📃WitnetRequest
          • 📃WitnetRequestFactory
          • 📃WitnetRequestTemplate
        • Mockups
          • 📃UsingWitnet
          • 📃UsingWitnetRandomness
          • 📃UsingWitnetRequest
          • 📃UsingWitnetRequestTemplate
          • 📃WitnetRandomnessRequestConsumer
          • 📃WitnetRequestConsumer
          • 📃WitnetRequestTemplateConsumer
      • 🧙Solidity Wizard
    • 🎓Tutorials
      • Building a Satoshi/Wei custom price feed
  • Witnet Node Operators
    • 🖥️Requirements
    • 🚀Witnet Node Quick Start Guide (Docker)
    • 🔎Next steps
    • 📄CLI Reference
    • 🤓Advanced Setups
      • Run Witnet as a systemd service
      • Run Witnet as a docker compose service
      • Paranoid mode (Witnet over proxies and Tor)
      • Configuration file
  • Witnet Node Developers
    • 🏗️Integration Guide
      • Node API Reference
      • Wallet API Reference
    • 🗜️Compile witnet-rust from Source Code
Powered by GitBook
On this page
  • Interfaces
  • IWitnetOracleAppliance
  • IWitnetRandomness
  • Events
  • IWitnetOracleEvents
  • IWitnetRandomnessEvents
  • Structs
  • Witnet.RadonSLA
  • Enums
  • Witnet.ResponseStatus

Was this helpful?

Edit on GitHub
  1. Smart contracts developers
  2. Guides
  3. Solidity Contracts
  4. Appliances

WitnetRandomness

PreviousWitnetPriceFeedsNextCore

Last updated 5 months ago

Was this helpful?

Bound to the 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.

Interfaces

^ 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.

IWitnetOracleAppliance

Methods
Description

= 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

IWitnetRandomness

Methods
Description

:: 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.

Events

IWitnetOracleEvents

Events
Arguments
Description

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.

IWitnetRandomnessEvents

Events
Arguments
Description

Randomizing

address evmOrigin

address evmSender

uint256 witOracleQueryId

Emitted every time randomize() gets called.

Structs

Witnet.RadonSLA

Field
Type
Description

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.

Enums

Witnet.ResponseStatus

Possible response status of some given randomize request, as returned by getRandomizeStatus(uint256).

Hex
Caption
Description

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.

🏗️
📖
📃
WitnetOracle
WitnetOracle
WitnetOracle
⛓️Supported chains