WitnetRequestBoard
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.
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.
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.
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
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.
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.
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.
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.
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 actualIWitnetRequest
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.
function postRequest(IWitnetRequest _addr)
external payable returns (uint256 _queryId);
Method Paramaters:
Returns:
uint256 _queryId
: The unique query identifier.
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
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.
function getNextQueryId() external view returns (uint256);
Returns next query id to be generated by the Witnet Request Board.
Returns:
uint256 _queryId
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
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
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
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
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
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.
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
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
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.
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.
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.
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.
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
: AWitnet.Result
instance.
function resultFromCborValue(Witnet.CBOR memory _cborValue)
external pure returns (Witnet.Result memory);
Method Paramaters:
Witnet.CBOR memory _cborValue
: An instance ofWitnet.CBOR
.
Returns:
Witnet.Result memory
: AWitnet.Result
instance.
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 ofWitnet.Result
.
Returns:
true
if successful,false
if errored.
function isError(Witnet.Result memory _result) external pure returns (bool);
Tell if a
Witnet.Result
is errored.
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 ofWitnet.Result
.
Returns:
bytes
: Thebytes
decoded from theWitnet.Result
.
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 ofWitnet.Result
.
Returns:
bytes32
: Thebytes32
decoded from theWitnet.Result
.
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 ofWitnet.Result
.
Returns:
Witnet.ErrorCodes
: TheCBORValue.Error memory
decoded from the Witnet.Result.
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 theCBORValue.Error memory
decoded from theWitnet.Result
,string
: A loggable error message.
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 ofWitnet.Result
.
Returns:
uint64
:
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 ofWitnet.Result
.
Returns:
uint64
:
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 ofWitnet.Result
.
Returns:
uint64
:
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 ofWitnet.Result
.
Returns:
uint64
:
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 ofWitnet.Result
.
Returns:
uint64
:
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 ofWitnet.Result
.
Returns:
uint64
:
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 ofWitnet.Result
.
Returns:
uint64
:
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 ofWitnet.Result
.
Returns:
uint64
:
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 ofWitnet.Result
.
Returns:
uint64
: Theuint64
decoded from theWitnet.Result
.
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 ofWitnet.Result
.
Returns:
uint64[]
: Theuint64[]
decoded from theWitnet.Result
.
Last modified 26d ago