| layout | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Bound to the WitnetOracle contract, this artifact enables smart contracts and offchain worfklows to programmatically build both WitnetRequest and WitnetRequestTemplate instances, based on a provided list of data sources, attestation filters and computational Radon scripts that transform and aggregate the data as extracted from those sources.
{% hint style="info" %}
The address of this appliance can be obtained by calling to the factory() method on the public domain Wit/Oracle artifact, as deployed by the Witnet Foundation on each supported chain.
{% endhint %}
{% hint style="info" %} ^ 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. {% endhint %}
| 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 WitnetRequestFactory ABI. |
= witnet(): WitnetOracle | Address of the WitnetOracle contract that produced WitnetRequest and WitnetRequestTemplate instances will be compliant with. |
| Methods | Description |
|---|---|
+! buildWitnetRequest(bytes32[] retrieveHashes,Witnet.RadonReducer aggregate,Witnet.RadonReducer tally): address | Builds a WitnetRequest instance that will provide the bytecode and RAD hash of some Witnet-compliant Radon Request, provably made out of some previously verified data sources (i.e. Radon Retrievals), aggregate and tally Radon Reducers. Produced addresses are counter-factual to the given values. Reverts if: |
+! buildWitnetRequestTemplate(bytes32[] retrieveHashes,Witnet.RadonReducer aggregate,Witnet.RadonReducer tally): address | Builds a WitnetRequestTemplate instance made out of one or more parameterized data sources (i.e. Radon Retrievals), aggregate and tally Radon Reducers. Produced addresses are counter-factual to the given values. Reverts if: |
+! verifyRadonRetrieval(Witnet.RadonRetrievalMethods,string requestURL,string requestBody,string[2][] requestHeaders,bytes requestRadonScript): bytes32 | Verifies and registers the specified Radon Retrieval (i.e. public data source) into the WitnetRadonRegistry of the WitnetOracle attached to this factory. Returns a unique hash that identifies the verified Radon Retrieval. All parameters but the retrieval method are parameterizable (i.e. by using embedded wildcard |
| 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 in the WitnetRadonRegistry. |
NewRadonRequest | bytes32 radHash | Emitted every time a new Witnet.RadonRequest gets successfully verified and stored in the WitnetRadonRegistry. |
| Events | Arguments | Description |
|---|---|---|
WitnetRequestBuilt | address request | Emitted every time a new counter-factual WitnetRequest gets verified and built. |
WitnetRequestTemplateBuilt | address template | Emitted every time a new counter-factual WitnetRequestTemplate gets verified and built. |
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. |
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. |
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 request's data sources. |
tally | Witnet.RadonReducer | Filtering and reduce operations that will be applied to the aggregated data revealed by each witnessing node. Witnessing nodes revealing data that gets ultimately filtered out, will get slashed. |
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. |
Primitive data types that can be contained in successful results to Witnet data requests.
| Hex | Caption | Description |
|---|---|---|
0x00 | Any | CBOR-encoded value of undetermined type. |
0x01 | Array | An array of CBOR values. |
0x02 | Bool | A CBOR-encoded boolean value. |
0x03 | Bytes | A CBOR-encoded bytes buffer. |
0x04 | Integer | A CBOR-encoded integer value. |
0x05 | Float | A CBOR-encoded float value. |
0x06 | Map | A key/value map of CBOR values. |
0x07 | String | A CBOR-encoded string value. |
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. |
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. |
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. |