WitnetRequestBoard

This section is under construction. If you need more information, you can ask in Discord or Telegram.

IWitnetRequestBoardEvents

• PostedRequest(queryId, from)

• PostedResult(queryId, from)

• DeletedQuery(queryId, from)

IWitnetRequestBoardReporter

• reportResult(_queryId, _drTxHash, _result)

• reportResult(_queryId, _timestamp, _drTxHash, _result)

• reportResultBatch(_batchResults, _verbose)

IWitnetRequestBoardRequestor

• deleteQuery(_queryId)

• postRequest(_addr)

• upgradeReward(_queryId)

IWitnetRequestBoardView

• estimateReward(_gasPrice)

• getNextQueryId()

• getQueryData(_queryId)

• getQueryStatus(_queryId)

• readRequest(_queryId)

• readRequestBytecode(_queryId)

• readRequestGasPrice(_queryId)

• readRequestReward(_queryId)

• readResponse(_queryId)

• readResponseDrTxHash(_queryId)

• readResponseReporter(_queryId)

• readResponseResult(_queryId)

• readResponseTimestamp(_queryId)

IWitnetRequestParser

• resultFromCborBytes(_cborBytes)

• resultFromCborValue(_cborValue)

• isOk(_result)

• isError(_result)

• asBytes(_result)

• asBytes32(_result)

• asErrorCode(_result)

• asErrorMessage(_result)

• asRawError(_result)

• asBool(_result)

• asFixed16(_result)

• asFixed16Array(_result)

• asInt128(_result)

• asInt128Array(_result)

• asString(_result)

• asStringArray(_result)

• asUint64(_result)

• asUint64Array(_result)

IWitnetRequestBoardEvents

DeletedQuery

event DeletedQuery(uint256 queryId, address from);

Emitted when all data related to given query is deleted from the WRB.

Method Paramaters:

• queryId uint256: the query id assigned to this new posting.

• from address: the address from which the Witnet Data Request was posted.

PostedRequest

Emitted when a Witnet Data Request is posted to the WRB.

event PostedRequest(uint256 queryId, address from);

Method Paramaters:

• queryId: the id of the query the result refers to.

• from: the address from which the result was reported.

PostedResult

event PostedResult(uint256 queryId, address from);

Emitted when a Witnet-solved result is reported to the WRB.

Method Paramaters:

• queryId: the id of the query the result refers to.

• from: the address from which the result was reported.

IWitnetRequestBoardReporter

The Witnet Request Board Reporter interface.

reportResult

function reportResult(
        uint256 _queryId,
        bytes32 _drTxHash,
        bytes calldata _result
    ) external;

Reports the Witnet-provided result to a previously posted request.

Method Paramaters:

• uint256 _queryId: The unique identifier of the data request.

• bytes32 _drTxHash: The hash of the corresponding data request transaction in Witnet.

• bytes calldata _result: The result itself as bytes.

Fails if:

• called from unauthorized address

• the _queryId is not in 'Posted' status

• provided _drTxHash is zero

• length of provided _result is zero

reportResult

function reportResult(
        uint256 _queryId,
        uint256 _timestamp,
        bytes32 _drTxHash,
        bytes calldata _result
    ) external;

Reports the Witnet-provided result to a previously posted request.

Method Paramaters:

• _queryId: The unique identifier of the data request.

• _timestamp: The timestamp of the solving tally transaction in Witnet.

• _drTxHash: The hash of the corresponding data request transaction in Witnet.

• _result: The result itself as bytes.

reportResultBatch

function reportResultBatch(
        BatchResult[] calldata _batchResults,
        bool _verbose
    ) external;

Reports Witnet-provided results to multiple requests within a single EVM tx. Must emit a PostedResult event for every succesfully reported result.

Method Paramaters:

• BatchResult[] calldata _batchResults: Array of BatchResult structs, every one containing:

  • unique query identifier

  • timestamp of the solving tally txs in Witnet. If zero is provided, EVM-timestamp will be used instead

  • hash of the corresponding data request tx at the Witnet side-chain level

  • data request result in raw bytes.

• bool _verbose: If true, must emit a BatchReportError event for every failing report, if any.

IWitnetRequestBoardRequestor

The Witnet Requestor Interface defines how to interact with the Witnet Request Board in order to:

• request the execution of Witnet Radon scripts (data request);

• upgrade the resolution reward of any previously posted request, in case gas price raises in mainnet;

• read the result of any previously posted request, eventually reported by the Witnet DON.

• remove from storage all data related to past and solved data requests, and results.

deleteQuery

function deleteQuery(uint256 _queryId) external returns (Witnet.Response memory);

Retrieves copy of all Witnet-provided data related to a previously posted request, removing the whole query from the WRB storage. Fails if the _queryId is not in 'Reported' status, or called from an address different to the one that actually posted the given request.

Method Paramaters:

• _queryId uint256: the unique identifier of a previously posted Witnet data request.

postRequest

function postRequest(IWitnetRequest _addr) 
    external payable returns (uint256 _queryId);

Requests the execution of the given Witnet Data Request in expectation that it will be relayed and solved by the Witnet DON.

A reward amount is escrowed by the Witnet Request Board that will be transferred to the reporter who relays back the Witnet-provided result to this request.

Method Paramaters:

• _addr: the actual IWitnetRequest contract address which provided the Witnet Data Request bytecode.

Returns:

• uint256 _queryId: the unique identifier of the data request.

Fails if:

• provided reward is too low

• provided script is zero address.

• provided script bytecode is empty.

postRequest

function postRequest(IWitnetRequest _addr)
    external payable returns (uint256 _queryId);

Method Paramaters:

Returns:

• uint256 _queryId: The unique query identifier.

upgradeReward

function upgradeReward(uint256 _queryId) external payable;

Increments the reward of a Witnet data request by adding more value to it. The new data request reward will be increased by msg.value.

Updates request gasPrice in case this method is called with a higher gas price value than the one used in previous calls to postRequest or upgradeReward.

Method Paramaters:

• uint256 _queryId: The unique query identifier.

Fails if:

• the _queryId is not in 'Posted' status.

• the request gasPrice is increased

• the new reward value gets below new recalculated threshold

IWitnetRequestBoardView

estimateReward

function estimateReward(uint256 _gasPrice) external view returns (uint256);

Estimates the minimal amount of reward needed to post a Witnet data request into the WRB, for a given gas price.

Method Paramaters:

• uint256 _gasPrice: The gas price for which we need to calculate the rewards.

getNextQueryId

function getNextQueryId() external view returns (uint256);

Returns next query id to be generated by the Witnet Request Board.

Returns:

• uint256 _queryId

getQueryData

function getQueryData(uint256 _queryId) external view returns (Witnet.Query memory);

Gets the whole Query data contents, if any, no matter its current status.

Method Paramaters:

• uint256 _queryId: The unique identifier of a previously posted query.

Returns:

• Witnet.Query memory _queryData

getQueryStatus

function getQueryStatus(uint256 _queryId) external view returns (Witnet.QueryStatus);

Gets current status of given query.

Method Paramaters:

• uint256 _queryId: The unique identifier of a previously posted query.

Returns:

• Witnet.QueryStatus _status

readRequest

function readRequest(uint256 _queryId) external view returns (Witnet.Request memory);

Retrieves the whole Request record posted to the Witnet Request Board.

Method Paramaters:

• uint256 _queryId: The unique identifier of a previously posted query.

Returns:

• WitnetRequest memory _requestRecord

readRequestBytecode

function readRequestBytecode(uint256 _queryId) external view returns (bytes memory);

Retrieves the serialized bytecode of a previously posted Witnet Data Request.

Method Paramaters:

• uint256 _queryId: The unique query identifier.

Returns:

• bytes memory _byteCode

readRequestGasPrice

 function readRequestGasPrice(uint256 _queryId) external view returns (uint256);

Retrieves the gas price that any assigned reporter will have to pay when reporting result to a previously posted Witnet data request.

Method Paramaters:

• uint256 _queryId: The unique query identifier.

Returns:

• uint256 _gasPrice

readRequestReward

function readRequestReward(uint256 _queryId) external view returns (uint256);

Retrieves the reward currently set for the referred query.

Method Paramaters:

• uint256 _queryId: The unique query identifier.

Returns:

• uint256 reward

Fails if:

• the _queryId is not valid or, if it has already been reported, or deleted.

readResponse

function readResponse(uint256 _queryId) 
    external view returns (Witnet.Response memory);

Retrieves the whole Witnet.Response record referred to a previously posted Witnet Data Request.

Method Paramaters:

• uint256 _queryId: The unique query identifier.

Returns:

• Witnet.Response memory _response

readResponseDrTxHash

function readResponseDrTxHash(uint256 _queryId) external view returns (bytes32);

Retrieves the hash of the Witnet transaction hash that actually solved the referred query.

Method Paramaters:

• uint256 _queryId: The unique query identifier.

Returns:

• bytes32 _witnetTransactionHash

readResponseReporter

function readResponseReporter(uint256 _queryId) external view returns (address);

Retrieves the address that reported the result to a previously-posted request.

Method Paramaters:

• uint256 _queryId: The unique query identifier.

Returns:

• address _reporter

Fails if:

• the _queryId is not in 'Reported' status.

readResponseResult

function readResponseResult(uint256 _queryId)
    external view returns (Witnet.Result memory);

Retrieves the Witnet-provided CBOR-bytes result of a previously posted request.

Method Paramaters:

• uint256 _queryId: The unique query identifier.

Returns:

• Witnet.Result memory _result

Fails if:

• the _queryId is not in 'Reported' status.

readResponseTimestamp

function readResponseTimestamp(uint256 _queryId) external view returns (uint256);

Retrieves the timestamp in which the result to the referred query was solved by the Witnet DON.

Method Paramaters:

• uint256 _queryId: The unique query identifier.

Returns:

• uint256 _timestamp

Fails if:

• the _queryId is not in 'Reported' status.

IWitnetRequestParser

The Witnet interface for decoding Witnet-provided request to Data Requests. This interface exposes functions to check for the success/failure of a Witnet-provided result, as well as to parse and convert result into Solidity types suitable to the application level.

resultFromCborBytes

function resultFromCborBytes(bytes memory _cborBytes)
    external pure returns (Witnet.Result memory);

Decode raw CBOR bytes into a Witnet.Result instance.

Method Paramaters:

• bytes memory _cborBytes: Raw bytes representing a CBOR-encoded value.

Returns:

• Witnet.Result memory: A Witnet.Result instance.

resultFromCborValue

function resultFromCborValue(Witnet.CBOR memory _cborValue) 
    external pure returns (Witnet.Result memory);

Method Paramaters:

• Witnet.CBOR memory _cborValue: An instance of Witnet.CBOR.

Returns:

• Witnet.Result memory: A Witnet.Result instance.

isOk

 function isOk(Witnet.Result memory _result) external pure returns (bool);

Tells if a Witnet.Result is successful.

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• true if successful, false if errored.

isError

 function isError(Witnet.Result memory _result) external pure returns (bool);

Tell if a Witnet.Result is errored.

asBytes

function asBytes(Witnet.Result memory _result)
    external pure returns (bytes memory);

Decode a bytes value from a Witnet.Result as a bytes value.

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• bytes: The bytes decoded from the Witnet.Result.

asBytes32

 function asBytes32(Witnet.Result memory _result) external pure returns (bytes32);

Decode a bytes value from a Witnet.Result as a bytes32 value.

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• bytes32: The bytes32 decoded from the Witnet.Result.

asErrorCode

function asErrorCode(Witnet.Result memory _result) 
    external pure returns (Witnet.ErrorCodes);

Decode an error code from a Witnet.Result as a member of Witnet.ErrorCodes.

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• Witnet.ErrorCodes: The CBORValue.Error memory decoded from the Witnet.Result.

asErrorMessage

function asErrorMessage(Witnet.Result memory _result) 
    external pure returns (Witnet.ErrorCodes, string memory);

Generate a suitable error message for a member of Witnet.ErrorCodes and its corresponding arguments.

Note that client contracts should wrap this function into a try-catch foreseing potential errors generated in this function.

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• uint8 Witnet.ResultErrorCodes: A tuple containing the CBORValue.Error memory decoded from the Witnet.Result,

• string: A loggable error message.

asRawError

function asRawError(Witnet.Result memory _result)
    external pure returns(uint64[] memory);

Decode a raw error from a Witnet.Result as a uint64[].

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• uint64:

asBool

function asBool(Witnet.Result memory _result) external pure returns (bool);

Decode a boolean value from a Witnet.Result as an bool value.

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• uint64:

asFixed16

 function asFixed16(Witnet.Result memory _result) external pure returns (int32);

Decode a fixed16 (half-precision) numeric value from a Witnet.Result as an int32 value.

Due to the lack of support for floating or fixed point arithmetic in the EVM, this method offsets all values. by 5 decimal orders so as to get a fixed precision of 5 decimal positions, which should be OK for most fixed16. use cases. In other words, the output of this method is 10,000 times the actual value, encoded into an int32.

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• uint64:

asFixed16Array

function asFixed16Array(Witnet.Result memory _result)
    external pure returns (int32[] memory);

Decode an array of fixed16 values from a Witnet.Result as an int128[] value.

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• uint64:

asInt128

 function asInt128(Witnet.Result memory _result) external pure returns (int128);

Decode a integer numeric value from a Witnet.Result as an int128 value.

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• uint64:

asInt128Array

function asInt128Array(Witnet.Result memory _result)
    external pure returns (int128[] memory);

Decode an array of integer numeric values from a Witnet.Result as an int128[] value.

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• uint64:

asString

Decode a string value from a Witnet.Result as a string value.

function asString(Witnet.Result memory _result)
    external pure returns (string memory);

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• uint64:

asStringArray

Decode an array of string values from a Witnet.Result as a string[] value.

function asStringArray(Witnet.Result memory _result)
    external pure returns (string[] memory);

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• uint64:

asUint64

Decode a natural numeric value from a Witnet.Result as a uint64 value.

function asUint64(Witnet.Result memory _result)
    external pure returns(uint64);

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• uint64: The uint64 decoded from the Witnet.Result.

asUint64Array

function asUint64Array(Witnet.Result memory _result)
    external pure returns (uint64[] memory);

Decode an array of natural numeric values from a Witnet.Result as a uint64[] value.

Method Paramaters:

• Witnet.Result memory _result: An instance of Witnet.Result.

Returns:

• uint64[]: The uint64[] decoded from the Witnet.Result.