📃WitnetOracle

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

⛓️Supported chains

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.

IWitnetAppliance

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.

IWitnetOracle

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.
$! postRequest( bytes32 witnetRadHash, WitnetV2.RadonSLA witnetSLA )	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: - witnetRadHash corresponds to no previously verified data request in the registry(); - invalid witnetSLA data security parameters were provided; - insufficient msg.value is lesser than the required base fee; - msg.value is greater than 10x times greater than the minimum base fee.
$! postRequestWithCallback( bytes32 witnetRadHash, WitnetV2.RadonSLA witnetSLA, uint24 callbackGasLimit )	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: - the caller is not a contract implementing the IWitnetConsumer interface; - witnetRadHash corresponds to no previously verified data request in the registry(); - insufficient msg.value is lesser than the required base fee; - msg.value is greater than 10x times greater than the minimum base fee.
$! postRequestWithCallback( bytes witnetBytecode, WitnetV2.RadonSLA witnetSLA, uint256 callbackGasLimit )	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. Reasons to fail: - the caller is not a contract implementing the IWitnetConsumer interface; - witnetBytecode is empty; - insufficient msg.value is lesser than the required base fee; - msg.value is greater than 10x times greater than the minimum base fee.
= 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

IWitnetOracleEvents

Events	Arguments	Description
WitnetQuery	address evmRequester uint256 evmGasPrice uint256 evmReward uint256 queryId bytes32 queryRadHash RadonSLA querySLA	Emitted every time a verified data request gets queried.
WitnetQuery	address evmRequester uint256 evmGasPrice uint256 evmReward uint256 queryId bytes queryBytecode RadonSLA querySLA	Emitted every time a non-verified data request bytecode gets queried.
WitnetQueryUpgrade	uint256 queryId address evmSender uint256 evmGasPrice uint256 evmReward	Emitted if the EVM reward for solving some query in course gets increased in any amount.
WitnetQueryResponse	uint256 queryId uint256 evmGasPrice	Emitted when a response to a query with no callback gets reported into WitnetOracle.
..ResponseDelivered	uint256 queryId uint256 evmGasPrice uint256 evmCallbackGas	Emitted when a response to a query gets directly reported to its requesting contract.
..ResponseDeliveryFailed	uint256 queryId uint256 evmGasPrice uint256 evmCallbackGas string evmRevertReason bytes resultCborBytes	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.

Structs

Witnet.Query

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.

Witnet.RadonSLA

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.

Witnet.Request

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.

Witnet.Response

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.

Witnet.ResultError

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.

Enums

Witnet.QueryStatus

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.

Witnet.RadonDataTypes

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.

Witnet.ResponseStatus

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.