📃WitnetRequestTemplate

Built from the WitnetRequestFactory, contracts of this kind contain references to one or more parameterized data sources (i.e. Radon Retrievals). Concrete parameters can be provided on-the-fly from a smart contract, producing WitnetRequest instances.

Did you know?

WitnetRequestTemplate addresses are counter-factual to the data sources (i.e. Radon Retrievals) they rely on.

Meaning that if you try to build a WitnetRequestTemplate with exactly the same sources as someone else did in the past, you will get exactly the same address. The underlying minimal-proxy contract would get constructed only once, of course. Building an already built request template works, and it requires less gas than building it for the first time.

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.

IWitnetRequestFactoryAppliance

Methods	Description
= class(): string	Returns the name of the contract that's actually implementing the ABI's specs() logic.
= factory(): WitnetRequestFactory	Address of the WitnetRequestFactory contract from which this template was created.
= specs(): bytes4	Returns the immutable ERC-165 id of the expected functionality as for the WitnetRequestTemplate ABI.
= witnet(): WitnetOracle	Address of the WitnetOracle contract that WitnetRequest instances created by this template will be compliant with.

IWitnetRequestTemplate

Methods	Description
:: getArgsCount():uint256[]	Returns an array of integers telling the number of parameters required by every single data source (i.e. Radon Retrievals) that compose this WitnetRequestTemplate. The length of the returned array tells the number of data sources that compose this instance.
:: getResultDataType():RadonDataTypes	Returns the expected data type produced by successful resolutions of any WitnetRequest that gets built out of this WitnetRequestTemplate.
:: getAggregateReducer():RadonReducer	Returns the filters and reducing function to be applied by witnessing nodes on the Witnet blockchain when aggregating data extracted from the public data sources (i.e. Radon Retrievals) of the data requests that get eventually built out of this WitnetRequestTemplate.
:! getRetrievalByIndex(uint256):RRet.	Returns metadata concerning the data source specified by the given index.
:: getRetrievals():RadonRetrievals[]	Returns the array of one or more parameterized data sources that compose this WitnetRequestTemplate.
:: getTallyReducer():RadonReducer	Returns the slashing filters and reducing function to be applied to the values revealed by the witnessing nodes on the Witnet blockchain that contribute to solve data requests built out of this WitnetRequestTemplate.
+! buildWitnetRequest(string[][]):addr	Build a WitnetRequest instance that will provide the bytecode and RAD hash of some Witnet-compliant Radon Request, provably made out of the data sources, aggregate and tally Radon Reducers that compose this WitnetRequestTemplate. Produced addresses are counter-factual to the given values. Reverts if the ranks of passed array don't match either the number of this template's data sources, or the number of required parameters by each one of those.
+! verifyRadonRequest(string[][]):b32	Verifies into the WitnetRadonRegistry bound to the witnet() contract the actual bytecode and RAD hash of the Witnet-compliant Radon Request that gets provably made out of the data sources, aggregate and tally Radon Reducers that compose this WitnetRequestTemplate. While no WitnetRequest instance is actually constructed, the returned bytes32 value will be accepted as a valid RAD hash on the witnet() contract from now on. Reverts if the ranks of passed array don't match either the number of this template's data sources, or the number of required parameters by each one of those. This method requires less gas than buildWitnetRequest(string[][]), and it's usually preferred when parameterized data requests made out of this template are intended to be used just once in lifetime.
:: version()	If built out of an upgradable factory, returns the SemVer tag of the factory implementation at the time when this WitnetRequestTemplate got built.

Events

IWitnetRadonRegistryEvents

Events	Arguments	Description
NewRadonRequest	bytes32 radHash	Emitted every time a new Witnet.RadonRequest gets successfully verified and stored into the WitnetRadonRegistry.

IWitnetRequestFactoryEvents

Events	Arguments	Description
WitnetRequestBuilt	address request	Emitted every time a new counter-factual WitnetRequest gets verified or built out of this template.

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

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

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.

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, out of their respective VRF-eligibility proofs.
0x03	HttpPost	Data shall be retrieved from HTTP-POST requests.
0x04	HttpHead	Data shall be retrieved from HTTP-HEAD requests.