Skip to content

Witnet requests

Witnet requests are the cornerstone of the Witnet protocol. They allow clients to have witness nodes retrieve, aggregate and deliver data on their behalf on demand.

Request life cycle

Once a Witnet request has been published by a client, it will go through 4 distinct stages: retrieval, aggregation and tally . These stages are linear and constitute a single, unidirectional data flow.

╔═════════╗    ╔════════════════════════════╗    ╔═══════════╗
║ Client  ║    ║ Witnesses                  ║    ║ Miner     ║
╠═════════╣    ╠════════════════════════════╣    ╠═══════════╣
║ Publish ║ => ║ Retrieve => Aggregate      ║ => ║ Tally     ║
╚═════════╝    ╠────────────────────────────╣    ╚═══════════╝
               ║ Retrieve => Aggregate      ║
               ╠────────────────────────────╣
               ║ ... (as many as requested) ║
               ╚════════════════════════════╝

For the sake of deterministic execution, data flowing through the different stages is strongly typed. The type of a value or data structure defines the operations that can be done on the data.

For each stage, the data type of the input is the same as the data type of the output of previous stage. Particularly, the aggregation and tally stages gather multiple values or structures emitted by their precedent stages, so they always receive an Array, i.e. if the retrieval stage returned an Integer, the aggregation stage will start with an Array<Integer>, that is, an array of Integers.

The RAD Engine

The RAD Engine is the component in charge of processing Witnet requests. That is, coordinating retrieval, aggregation, tally and delivery of data strictly as specified in the requests.

All Witnet requests contain explicit instructions on what the RAD Engine must do during every stage. These instructions, specified using RAD Object Notation (RADON), are interpreted by the RAD Engine.

Just in case you were wondering, RAD stands for Retrieve, Attest and Deliver.

RAD Object Notation (RADON)

The RAD Object Notation (RADON) is a declarative, functional, strongly-typed, Non-Turing complete domain-specific language.

A RADON script is formed by a list of ordered calls (tuples of operator byte codes and arguments) that are sequentially interpreted and applied by the RAD Engine on the output of the previous call.

Example

When applied on an Array<Integer>, this very simple 4-bytes RADON script will compute the average mean of all the Integers:

91 92 56 03

[
    [ OP_ARRAY_REDUCE, REDUCER_AVG_MEAN ]   // [ 0x56, 0x03 ]
]

Do not worry if you do not understand this script just yet. Keep on reading and then head yourself to the RADON encoding section for an explanation on how scripts are codified and formatted.

Creating Witnet requests

The RAD Engine is only capable of interpreting well-formed RADON scripts.

Even though human beings can write RADON, it's not the best method. The standard way to compose Witnet requests is using the Witnet Truffle box, which you can learn about by following the price feed tutorial.

The Sheikah desktop app (currently under heavy development) is also intended to be used as an IDE for visually and safely composing and testing Witnet requests.