The Oracle
contract provides price data to the Kolibri ecosystem. It is implemented using a Harbinger Price Feed.
The Oracle
contract calls to a Harbinger Normalizer
contract. It sanity checks the return values, normalizes them for the Kolibri system, and returns them to the client.
The current implementation uses a Coinbase Data Feed normalized by volume weighted average price (VWAP) with n=6
.
The Oracle
performs the following checks on data returned from Harbinger:
Oracle
has a single callback function that returns the price to the caller. The caller includes a callback contract/entrypoint in the request and data is called back to that location.
The callback is a single nat
which is the XTZ-USD price, specified with 10^-18 precision.
Anyone may request a price via the getXtzUsdPrice
entrypoint.
However, only the Harbinger
contract can return price data via the getXtzUsdPrice_callback
entrypoint.
Any contract that points to the Oracle
should have a governable address
for the Oracle
. In case of upgrades, a new Oracle could be deployed, and governance could upgrade contracts to point to the new contract.
Oracle
maintains a simple state machine with two states: (1) IDLE
and (2) WAITING_FOR_HARBINGER
.
From the IDLE
state, the Oracle
can only transition to the WAITING_FOR_HARBINGER
state. The getXtzUsdPrice
can only be invoked when in the IDLE
state. Invoking the entrypoint transitions the Oracle
to the WAITING_FOR_HARBINGER
state. In the IDLE
state, clientCallback
is always none
.
From the WAITING_FOR_HARBINGER
state, the Oracle
can only transition to the IDLE
state. The getXtzUsdPrice_callback
can only be invoked when in the WAITING_FOR_HARBINGER
state. Invoking the entrypoint transitions the Oracle
to the IDLE
state. In the WAITING_FOR_HARBINGER
state, clientCallback
is always some
.
The Oracle
stores the following:
harbingerContractAddress
(address
): The address of the Harbinger Price feed
contract. Used to request data and for ACL checking.state
(nat
): The current state of the contract; see 'State Machine' above.clientCallback
(option(contract(nat))
): A register that stores state when the Oracle
is waiting for Harbinger data.governorContractAddress
(address
): The address of the Governor
contract. Used for ACL checking.maxDataDelaySec
(nat
): The maximum acceptable age of data received from Harbinger, in seconds.governorContractAddress
and maxDataDelaySec
are governable.
The Oracle
has the following entrypoints:
getXtzUsdPrice
: Retrieve, sanity check, and normalize Harbinger data.getXtzUsdPrice_callback
: Callback to receive data from Harbinger. This entrypoint may only be called by the harbingerContractAddress.
default
: No-op. Always fails to prevent transfer of XTZ into contract.setMaxDataDelaySec
: Set the maximum acceptable age of data recieved from Harbinger. May only be called by the Governor
.setGovernorContract
: Set the Governor
address. May only be called by the Governor
.A future version of Oracle
may choose to use a custom view on the Harbinger
data, or another oracle solution.
If a new version of the Oracle
is required to be deployed to accomodate updates to Harbinger
, then harbingerContractAddress
could become governable.