Core bridging contract that enables your smart contract to pull all sorts of data from the real world, estimate required EVM fees and check for data results as reported from the underlying Witnet blockchain.
(hint sobre extra fee ...)
{% content-ref url="../../../supported-chains.md" %} supported-chains.md {% endcontent-ref %}
{% 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 actual contract implementing the underlying logic. |
= specs():bytes4 | Returns the immutable ERC-165 id that represents the expected functionality as for the WitnetOracle ABI. |
| Methods | Description |
|---|---|
^ channel() | Uniquely identifies this WitnetOracle contract and the chain on which it's deployed. |
:: estimateBaseFee(uint256,uint16) | Estimates the minimum reward required for requesting the Witnet blockchain to retrieve data up to the specified number of bytes passed as second parameter. The required reward depends also on the gas price of the transaction that calls upon any of the postRequest(..) methods., passed as first parameter. |
:: estimateBaseFee(uint256,bytes32) | Estimates the minimum reward required for making the Witnet blockchain solve the given data request specs (i.e. the RAD hash) passed as second parameter. The required reward depends also on the gas price of the transaction that calls upon any of the postRequest(bytes32,..) methods, passed as first parameter. Reverts if the given RAD hash value was not previously verified into the registry(). |
:: estimateBaseFeeWithCallback(u,u24) | Estimates the minimum reward required for requesting the Witnet blockchain to solve some data request which result is to be reported as a callback to some requesting contract. The reward ultimately depends on the given gas price and the maximum gas expected to be consumed by the requester's callback method, passed as first and second parameters, respectively. |
= factory() | Returns the address of the WitnetRequestFactory appliance capable of building compliant data requests and templates, verified into the sameWitnetRadonRegistry instance as returned by registry(). |
+! fetchQueryResponse(uint256) | Retrieves a copy of all Witnet-provable data related to a previously posted request, removing such data from the WitnetOracle storage right away. Reverts if the referred query was not in Reported status, or if the caller is not the actual query's requester. |
:: getQuery(uint256) | Return all metadata currently stored in the EVM storage about the given query, no matter its current. |
:: getQueryEvmReward(uint256) | Returns the current EVM reward an eventual reporter (i.e. bridge) can potentially claim for the given query, if not done yet. |
:: getQueryRequest(uint256) | Retrieves the RAD hash and data SLA security parameters that were specified for the given query, if any. |
:: getQueryResponse(uint256) | Retrieves metadata related to the actual response reported from the Witnet blockchain, if any yet, about the given query. |
:: getQueryResponseStatus(uint256) | Returns the current response status to the given query from its requester's point of view. See WitnetV2.ResponseStatus below. |
:: getQueryResultCborBytes(uint256) | Retrieves the CBOR-encoded buffer containing the Witnet-provided result to the given query, if any. |
:: getQueryResultError(uint256) | Returns an error code identifying some possible failure on the resolution of the given query, and a human-readable description of such error, if any. See Witnet.ResultError below. |
:: getQueryStatus(uint256) | Returns the current general status of the given query. See Witnet.QueryStatus below. |
:: getQueryStatusBatch(uint256[]) | Returns the current general status of the given queries. |
:: getNextQueryId() | Return the query sequential identifier to be assigned to the next query posted to the WitnetOracle contract. |
$!
| Requests the resolution of the given Witnet-compliant data request, in expectation that it will be relayed and solved on the Witnet oracle blockchain. A reward is kept in escrow until some reporter (i.e. bridge) successfully relays back a Witnet-provable result to this query. Reverts if: |
$!
| Requests the resolution of the given Witnet-compliant data request, in expectation that it will be relayed and solved on the Witnet oracle blockchain. A reward is kept in escrow to be transferred to the reporter who relays back a Witnet-provable result to this query, directly to a callback method on the requesting contract. If the report callback fails for any reason an event will be triggered (see IWitnetOracleEvents below), some Witnet traceability data will be saved in the WitnetOracle storage as proof, but not so the actual result data. Reasons to fail: |
$! | Requests the resolution of the given unverified but yet Witnet-compliant data request, in expectation that it will be relayed and solved on the Witnet oracle blockchain. A reward is kept in escrow to be transferred to the reporter who relays back a Witnet-provable result to this query, directly to a callback method on the requesting contract. If the report callback fails for any reason an event will be triggered (see IWitnetOracleEvents below), some Witnet traceability data will be saved in the WitnetOracle storage as proof, but not so the actual result data. |
= registry() | Returns the singleton WitnetRadonRegistry in which all Witnet-compliant data requests and templates must be previously verified so they can be passed as reference when calling postRequest(bytes32,..) methods. |
$! upgradeQueryEvmReward(uint256) | Increments the reward of the given query by adding the transaction value to it. Reverts if the query is not in Posted status. |
| Events | Arguments | Description |
|---|---|---|
WitnetQuery |
| Emitted every time a verified data request gets queried. |
WitnetQuery |
| Emitted every time a non-verified data request bytecode gets queried. |
WitnetQueryUpgrade |
| Emitted if the EVM reward for solving some query in course gets increased in any amount. |
WitnetQueryResponse |
| Emitted when a response to a query with no callback gets reported into WitnetOracle. |
..ResponseDelivered |
| Emitted when a response to a query gets directly reported to its requesting contract. |
..ResponseDeliveryFailed |
| Emitted when a query with a response to a query is expected to be reported directly to its requesting contract, but it's not possible for some reason. |
Contains both request and response metadata bound to every query posted to the WitnetOracle.
| Field | Type | Description |
|---|---|---|
request | WitnetV2.Request | Witnet request metadata. |
response | WitnetV2.Response | Witnet response metadata. |
SLA security parameters to be fulfilled by the Witnet blockchain when solving some Witnet query posted into the WitnetOracle.
| Field | Type | Description |
|---|---|---|
committeeSize | uint8 | Number of randomnly selected nodes in the Witnet oracle blockchain that will take part in solving some price update. |
witnessingFeeNanoWit | uint256 | Reward in nanowits that will be paid to every node in the Witnet oracle blockchain involved in solving some price update. Randomnly selected nodes in Witnet will have to stake a collateral 100x this amount in order to participate as witnesses. |
Request metadata that's kept in EVM-storage for every query posted to the WitnetOracle.
| Field | Type | Description |
|---|---|---|
reporter | address | Bridge EVM address from which the query result was reported. |
finality | uint64 | Block number at which the query result can be considered to be final. |
resultTimestamp | uint32 | Timestamp at which the Witnet blockchain produced the reported result. |
resultTallyHash | bytes32 | Hash of the transaction on the Witnet blockchain that produced the actual query result. |
resultCborBytes | bytes | CBOR-encoded buffer containing the query result: either a primitive value (see Witnet.RadonDataTypes below), or an error. |
Actual data bridged from the Witnet blockchain in response to some query posted to the WitnetOracle.
| Field | Type | Description |
|---|---|---|
reporter | address | Bridge EVM address from which the query result was reported. |
finality | uint64 | Block number at which the query result can be considered to be final. |
resultTimestamp | uint32 | Timestamp at which the Witnet blockchain produced the reported result. |
resultTallyHash | bytes32 | Hash of the transaction on the Witnet blockchain that produced the actual query result. |
resultCborBytes | bytes | CBOR-encoded buffer containing the query result: either a primitive value (see Witnet.RadonDataTypes below), or an error. |
Struct describing an error reported from the Witnet blockchain.
| Field | Type | Description |
|---|---|---|
code | Witnet.ResultErrorCodes | Unique code identifying the actual error as reported from the Witnet blockchain. |
reason | string | Human-readable description of the reported error from the Witnet blockchain. |
Possible status of a Witnet query posted to the WitnetOracle.
| Hex | Caption | Description |
|---|---|---|
0x00 | Unknown | The given query does not exist, either because it has not been posted yet, or it was deleted by its requester. |
0x01 | Posted | The query is being solved on the Witnet blockchain but its result has not yet been reported to the EVM storage. |
0x02 | Reported | Some result to the query has been allegedly bridged from the Wit/oracle blockchain into the EVM storage, but cannot yet be considered final. |
0x03 | Finalized | The result to the query has been successfully reported into the EVM storage, and it can be considered to be finalized. |
Primitive data types that can be contained in successful results to Witnet data requests.
| Hex | Caption | Description |
|---|---|---|
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 | Arrayed key/value map of CBOR values. |
0x07 | String | A CBOR-encoded string value. |
Possible response status of some query posted to the WitnetOracle.
| Hex | Caption | Description |
|---|---|---|
0x01 | Awaiting | The underlying query is being solved on the Witnet blockchain and its result has not yet been reported to the EVM storage. |
0x02 | Ready | The underlying query was successfully solved on Witnet, and the reported result can be considered to be final. |
0x03 | Error | The underlying query was solved with errors on the Witnet blockchain, and the reported error can be considered to be final. |
0x04 | Finalizing | The result to the underlying query is being bridged from the Witnet blockchain but it cannot yet be considered to be final. |
0x05 | Delivered | The result to the underlying query, either successful or with errors, was already delivered to the requesting contract that paid for it. |