📃WitnetRadonRegistry

This contract contains a registry of validated data sources and data requests built up so far by any dapp interacting with the WitnetOracle singleton contract within a certain EVM chain, up to the present time. A unique identifier is generated for every Radon Retrieval (i.e. data sources) or Radon Request (i.e. retrieve-attestation-delivery part of Witnet-compliant data request objects) that gets successfully validated into this contract.

The address of this contract can be obtained by calling to the registry() method on the public domain Wit/Oracle artifact, as deployed by the Witnet Foundation on each supported chain.

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.

IWitnetAppliance

Methods
Description

= class():string

Returns the name of the actual contract implementing the underlying logic.

= specs():bytes4

Returns the immutable ERC-165 id that represents the expected functionality as for the WitnetRadonRegistry ABI.

IWitnetRadonRegistry

Methods
Description

:: bytecodeOf(bytes32)

Returns the Witnet-compliant RAD bytecode for some Radon Request identified by its unique RAD hash.

:: bytecodeOf(bytes32,Witnet.RadonSLA)

Returns the Witnet-compliant DRO bytecode for some data request object made out of the given Radon Request and Radon SLA security parameters.

:: bytecodeOf(bytes,Witnet.RadonSLA)

Returns the Witnet-compliant DRO bytecode for some data request object made out of the given RAD bytecode and Radon SLA security parameters.

:: hashOf(bytes)

Returns the hash of the given Witnet-compliant bytecode. Returned value can be used to trace back in the Witnet blockchain all past resolutions of the given data request payload.

:! lookupRadonRequest(bytes32)

Returns the whole Witnet.RadonRequest metadata struct for the given RAD hash value.

:! lookupRadonRequestAggregate(bytes32)

Returns the Aggregate reducer that is applied to the data extracted from the data sources (i.e. Radon Retrievals) whenever the given Radon Request gets solved on the Witnet blockchain. Reverts if unknown.

:! lookupRadonRequestDataType(bytes32)

Returns the deterministic data type returned by successful resolutions of the given Radon Request. Reverts if unknown.

:! lookupRadonRequestRetrievals(bytes32)

Returns an array (one or more items) containing the introspective metadata of the given Radon Request's data sources (i.e. Radon Retrievals). Reverts if unknown.

:! lookupRadonRequestTally(bytes32)

Returns the Tally reducer that is applied to aggregated values revealed by the witnessing nodes on the Witnet blockchain. Reverts if unknown.

:! lookupRadonRetrieval(bytes32)

Returns introspective metadata of some previously verified Radon Retrieval (i.e. public data source). Reverts if unknown.

:! lookupRadonRetrievalArgsCount(bytes32)

Returns the number of indexed parameters required to be fulfilled when eventually using the given Radon Retrieval. Reverts if unknown.

:! lookupRadonRetrievalDataType(bytes32)

Returns the type of the data that would be retrieved by the given Radon Retrieval (i.e. public data source). Reverts if unknown.

+! verifyRadonReducer(

Witnet.RadonReducer reducer

)

Verifies and registers the given sequence of dataset filters and reducing function to be potentially used as either Aggregate or Tally reducers within the resolution workflow of Radon Requests in the Wit/oracle blockchain. Returns a unique hash that identifies the given Radon Reducer in the registry. Reverts if unsupported reducing or filtering methods are specified.

+! verifyRadonRequest( bytes32[] retrievals, Witnet.RadonReducer aggregate, Witnet.RadonReducer tally )

Verifies and registers the specified Radon Request out of the given data sources (i.e. retrievals) and the aggregate and tally Radon Reducers. Returns a unique RAD hash that identifies the verified Radon Request. Reverts if: - unverified retrievals are passed; - retrievals return different data types; - any of passed retrievals is parameterized; - unsupported reducers are passed.

+! verifyRadonRequest( bytes32[] retrievals, string[][] retrievalsArgs, Witnet.RadonReducer aggregate, Witnet.RadonReducer tally )

Verifies and registers the specified Radon Request out of the given data sources (i.e. retrievals), data sources parameters (if required), and the aggregate and tally Radon Reducers. Returns a unique RAD hash that identifies the verified Radon Request. Reverts if: - unverified retrievals are passed; - retrievals return different data types; - ranks of passed args don't match with those required by each given retrieval; - unsupported reducers are passed.

+! verifyRadonRetrieval( Witnet.RadonRetrievalMethods, string requestURL, string requestBody, string[2][] requestHeaders, bytes requestRadonScript )

Verifies and registers the specified Radon Retrieval (i.e. public data source) into this registry contract. Returns a unique retrieval hash that identifies the verified Radon Retrieval. All parameters but the retrieval method are parameterizable by using embedded wildcard \x\ substrings (with x='0'..'9'). Reverts if: - unsupported retrieval method is given; - no URL is provided Http/* requests; - non-empty strings given on RNG reqs.

Events

IWitnetRadonRegistryEvents

Events
Arguments
Description

NewRadonReducer

bytes16 hash

Emitted every time a new Witnet.RadonReducer gets successfully verified and stored into the WitnetRadonRegistry.

NewRadonRetrieval

bytes32 hash

Emitted every time a new Witnet.RadonRetrieval gets successfully verified and stored into the WitnetRadonRegistry.

NewRadonRequest

bytes32 radHash

Emitted every time a new Witnet.RadonRequest gets successfully verified and stored into the WitnetRadonRegistry.

Structs

Witnet.RadonFilter

Struct defining the data filtering to be applied at either the Aggregate or Tally stages within the resolution of a data request within the Witnet blockchain.

Field
Type
Description

opcode

Witnet.RadonFilterOpcodes

Filtering function.

cborArgs

bytes

CBOR-encoded array of filter parameters. Empty if no parameters are to be specified.

Witnet.RadonReducer

Struct defining the array of filters, if any, and reduce function to be applied at either the Aggregate or Tally stages within the resolution of a data request within the Witnet blockchain.

Field
Type
Description

opcode

Witnet.RadonReducerOpcodes

Reducing function.

filters

Witnet.RadonFilter[]

Zero, one or more filters to be orderly applied to input dataset before actually executing the reduce function.

Witnet.RadonRequest

Struct containing the Retrieve-Attestation-Delivery parts of a Witnet-compliant Data Request Object.

Field
Type
Description

retrieve

Witnet.RadonRetrieval[]

One or more public data sources (i.e. Radon Retrievals) out from where data will be retrieved by all witnessing nodes in the Witnet-blockchain attending the resolution of this data request.

aggregate

Witnet.RadonReducer

Filtering and reduce operations that will executed by every single witnessing node as to aggregate the data extracted from the sources.

tally

Witnet.RadonReducer

Filtering and reduce operations that will be applied to the aggregated data revealed by each witnessing node. Witnessing nodes revealing results that get ultimately filtered out, will get slashed.

Witnet.RadonRetrieval

Struct containing all parameters that fully describe the Radon Retrievals that can form part of Witnet-compliant Data Request Objects.

Field
Type
Description

argsCount

uint8

Number of indexed parameters to be provided whenever this Radon Retrieval is to be included into a Radon Request.

method

Witnet.RadonRetrievalMethods

Immutable method to be used for retrieving data.

dataType

Witnet.RadonDataTypes

Deterministic data type that successful executions will return.

url

string

Request URL. Mandatory on HttpGet, HttpPost and HttpHead retrieving methods.

body

string

Request body. Optional on HttpGet and HttpPost retrieving methods.

headers

string[2][]

Request key/value headers. Optional on HttpGet and HttpPost retrieving methods.

radonScript

bytes

Optional CBOR-encoded Radon Script that will transform whatever value is returned from the source. Not supported on RNG retrievals.

Enums

Witnet.RadonFilterOpcodes

Dataset filtering methods currently supported on the Witnet blockchain.

Hex
Caption
Description

0x05

StandardDeviation

Filters out all input items that deviates from the average more than a threshold. Requires a CBOR-encoded float as single but mandatory filter parameter. Works only with arrays of numbers (integers or floats) as input datasets.

0x08

Mode

Filters out all input items that diverge from the mode.

Witnet.RadonReducerOpcodes

Reducing functions currently supported on the Witnet blockchain.

Hex
Caption
Description

0x02

Mode

Returns the mode value from the input dataset.

0x03

AverageMean

Returns the average mean from the input dataset. Works only with arrays of numbers as input datasets.

0x05

AverageMedian

Returns the median from the input dataset. Works only with arrays of numbers as input datasets.

0x07

StandardDeviation

Returns the standard deviation calculated out from the input dataset. Works only with arrays of numbers as input datasets.

0x0B

ConcatenateAndHash

Returns the SHA-256 hash of the concatenation of the input buffers. Works only with arrays of buffers as input datasets. Used mainly on RNG requests for mixing randomness produced by independent and randomly selected witnessing nodes.

Witnet.RadonRetrievalMethods

Possible data request methods that can be specified on a Radon Retrieval.

Hex
Caption
Description

0x01

HttpGet

Data shall be retrieved from HTTP-GET requests.

0x02

RNG

Random seeds shall be independently produced by the witnessing nodes themselves.

0x03

HttpPost

Data shall be retrieved from HTTP-POST requests.

0x04

HttpHead

Data shall be retrieved from HTTP-HEAD requests.

Last updated