| coverY | layout | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0 |
|
Relying on the WitnetOracle, this contract acts as a third-party oracle solution for the provisioning of regularly updated price feeds, where price feeds get identified by a descriptive string tag (see ERC-2362). Unlike most other price feed oracles, price updates on a WitnetPriceFeeds contract can be pulled at anytime by any consuming contract. Moreover, all provided price updates (both values and timestamps) can be proven to be 100% truthful to the public sources being used, with no human-driven workflows involved at all, while providing a 15-minute finalization period in worst-case scenarios.
{% 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 |
|---|---|
:: footprint(): bytes4 | Returns a unique hash determined by the combination of data sources being used by supported non-routed price feeds, and dependencies of all supported routed price feeds. The footprint changes if any price feed is modified, added, removed or if the dependency tree of any routed price feed is altered. |
^ hash(string): bytes4 | This pure function determines the ERC-2362 identifier of the given data feed caption string, truncated to bytes4. |
:: lookupCaption(bytes4): string | Returns the ERC-2362 caption of the given feed identifier, if known. |
:: supportedFeeds():(b4[],str[],b32[]) | Returns the list of feed ids, captions and RAD hashes of all currently supported data feeds. The RAD hash of a data feed determines in a verifiable way the actual data sources and off-chain computations solved by the Witnet oracle blockchain upon every data update. The RAD hash value for a routed feed actually contains the address of the IWitnetPriceSolver logic contract that solves it. |
:: supportsCaption(string): bool | Tells whether the given ERC-2362 feed caption is currently supported. |
:: totalFeeds(): uint256 | Total number of data feeds, routed or not, that are currently supported. |
| Methods | Description |
|---|---|
= dataType(): Witnet.RadonDataTypes | Primitive data type produced by successful data updates of all supported feeds (e.g. Witnet.RadonDataTypes.Integer in WitnetPriceFeeds). |
=prefix(): string | ERC-2362 caption prefix shared by all supported feeds (e.g. "Price-" in WitnetPriceFeeds). |
:: defaultRadonSLA() | Default SLA data security parameters that will be fulfilled on Witnet upon every feed update, if no others are specified by the requester. |
::estimateUpdateRequestFee(uint256) | Estimates the minimum EVM fee required to be paid upon requesting a data update with the given the _evmGasPrice value. |
:: lastValidQueryId(bytes4) | Returns the query id (in the context of the WitnetOracle addressed by witnet()) that solved the most recently updated value for the given feed. |
:: lastValidResponse(bytes4) | Returns the actual response from the Witnet oracle blockchain to the last successful update for the given data feed. |
:: latestUpdateQueryId(bytes4) | Returns the Witnet query id of the latest update attempt for the given data feed. |
:: latestUpdateResponse(bytes4) | Returns the response from the Witnet oracle blockchain to the latest update attempt for the given data feed. |
:: latestUpdateResponseStatus(bytes4) | Tells the current response status of the latest update attempt for the given data feed. |
:: latestUpdateResultError(bytes4) | Describes the error returned from the Witnet oracle blockchain in response to the latest update attempt for the given data feed, if any. |
:! lookupWitnetBytecode(bytes4) | Returns the Witnet-compliant bytecode of the data retrieving script to be solved by the Witnet oracle blockchain upon every update of the given data feed. |
:: lookupWitnetRadHash(bytes4) | Returns the RAD hash that uniquely identifies the data retrieving script that gets solved by the Witnet oracle blockchain upon every update of the given data feed. |
:: lookupWitnetRetrievals(bytes4) | Returns the list of actual data sources and offchain computations for the given data feed. |
$! requestUpdate(bytes4): uint256 | Triggers a fresh update on the Witnet oracle blockchain for the given data feed, using the defaultRadonSLA() security parameters. |
$! requestUpdate(bytes4,RadonSLA):u256 | Triggers a fresh update for the given data feed, requiring also the SLA data security parameters that will have to be fulfilled on Witnet. |
| Methods | Description |
|---|---|
= class(): string | Returns the name of the contract that's actually implementing the ABI's specs() logic. |
= specs(): bytes4 | Returns the immutable ERC-165 id that represents the expected functionality as for the WitnetPriceFeeds ABI. |
= witnet(): WitnetOracle | Address of the underlying singleton WitnetOracle contract used for posting data feed update requests to be solved on the Witnet blockchain. |
| Methods | Description |
|---|---|
:: lookupDecimals(bytes4) | Returns the number of decimals to be added to the the integer values provided for the given price, in order to determine its actual market denomination. |
:: lookupPriceSolver(bytes4) | Returns the address of the logic contract that solves a given routed price feed, and the list of the ids upon which this routed price feed relies. Routed price feeds are not directly solved by the Witnet oracle blockchain (i.e. live price feeds), but as an on-chain combination of other live price feeds and/or routed price feeds. If the given id corresponds to no routed price feed, a zero address will be returned. |
:! latestPrice(bytes4) | Returns the most recently updated IWitnetPriceSolver.Price data point for the given price feed id. |
:! latestPrices(bytes4[]) | Returns the most recently updated data points for the list of given price feeds. |
| Methods | Description |
|---|---|
:: valueFor(b32):(int,uint,uint) | Returns last valid price and timestamp values received so far, as well as the current update status code for the given data feed id: - 200: no new update has been requested since the last successful report.- 400: last update request failed but still no new update is currently in course. - 404: an update is currently in course, but has not yet been reported. |
| Events | Arguments | Description |
|---|---|---|
PullingUpdate |
| A fresh update on the data feed identified as erc2364Id4 has just been requested and paid for by some evmSender, under command of the evmOrigin externally owned account. |
| Events | Arguments | Description |
|---|---|---|
WitnetQuery |
| Emitted every time a new data update is requested and paid for on the WitnetPriceFeeds contract. |
WitnetQueryUpgrade |
| Emitted if the EVM reward for solving an update request in course is increased in any amount. |
Most recently updated data about some price feed, as returned by either latestPrice(bytes4) and latestPrices(bytes4).
| Field | Type | Description |
|---|---|---|
value | uint256 | Most recently updated price value. |
timestamp | uint256 | Timestamp at which the most recently updated price was produced. |
tallyHash | bytes32 | Hash of the transaction in the Witnet oracle blockchain that produced the most recently updated price. |
status | WitnetV2.ResponseStatus | Current status of the underlying price update attempt, if any. |
Required on requestUpdate(bytes4,WitnetV2.RadonSLA). Returned by defaultRadonSLA().
| Field | Type | Description |
|---|---|---|
committeeSize | uint8 | Number of randomly 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. Randomly selected nodes in Witnet will have to stake a collateral 100x this amount in order to participate as witnesses. |
Actual data reported from the Witnet oracle blockchain in response to some update attempt.
| 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 oracle blockchain produced the reported result. |
resultTallyHash | bytes32 | Hash of the transaction on the Witnet oracle 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, as returned by latestUpdateResultError(bytes4).
| 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. |
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 | A key/value map of CBOR values. |
0x07 | String | A CBOR-encoded string value. |
Possible response status of some given data feed update attempt.
| Hex | Caption | Description |
|---|---|---|
0x01 | Awaiting | The underlying query is being solved on the Witnet oracle 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 oracle 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. |