Getting started
Oracles work by running a client that fetches the price from centralized exchanges (CEX) and pushes those prices on-chain by callingSortedOracles.report(address token, uint256 value, address lesserKey, address greaterKey)
. SortedOracles is a Celo Core Contract.
A reference implementation of such a client is written in TypeScript and would be used for this guide. Releases for this client can be found here.
Requirements
- One VM dedicated for each oracle is recommended, but it is acceptable that they run multiple instances in the case they are for different stables.
- A dedicated full node running in its own VM. Minimal hardware requirements and instructions on how to run a full node can be found here.
- The private key of an address on Celo, which can be stored on a private key file, on a Hardware Security Module (HMS) or hosted in the full nodes itself. More information about each can be found below.
Setting up the environment
Find the latest stable Docker Image for the oracle in the oracle releases here. From the oracle VM, make sure you can access your node. This can be done via the Celo CLI with this command:celocli node:synced --node YOUR_NODE_HOSTNAME:YOUR_NODE_PORT
Also make sure your node is accessible via WS, usually full nodes listen in port 8546
.
Using Forno or other public full node providers to run the oracles in production is strongly discouraged. Oracles doing so wouldnât be eligible for rewards.
.env.prod
in your oracle VM. A template env file in a format accepted by Docker can be found in the Github repository. A list of all the available, as well as required variables, can be found here.
Running with HSM
Using High Security Modules (HSM) is the recommended way to store the keys for the oracles. Currently supported HSM are Azure and AWS. If you have already configured HSM, the relevant variables to add to your.env.prod
are:
AWS:
WALLET_TYPE=AWS_HSM
AWS_KEY_REGION
WALLET_TYPE=AZURE_HSM
AZURE_KEY_VAULT_NAME
Using a private key
This method is not recommended in production as the private key remains unencrypted in the VM.
$ celocli account:new
The output field of privateKey
should be stored in a file and its path should be set in the env variable PRIVATE_KEY_PATH
. Aditionally WALLET_TYPE
should also be set to PRIVATE_KEY
. This private key should have some CELO balance used for gas to sign the report transactions.
Recommended configuration
WARNING: it is encouraged that before running the oracles in production, they should run for at least a week in one of the Celo Public testnets.
PRICE_SOURCES
. This sets what exchanges and prices shall be used to report. It is recommended to store this in a file called price_sources
and export the content to a new env variable with cat
.
export PRICE_SOURCES=$(cat price_sources)
An example of such a file for CELO/USD is:
Note that this example configuration is using three direct pairs, and the last one is an implicit pair calculated using two exchanges. This is useful in the case extra liquidity is required to calculate the price.
Existing exchange connectors
Available connectors are, in alphabetical order:- Binance
- Bitso
- Bittrex
- Coinbase
- Novadax
- OkCoin
Running the node
Once all the environment variables are set in the VM, an oracle can be started with:docker run --name celo-oracle -it --restart unless-stopped --env-file .env.prod -e PRICE_SOURCES=$PRICE_SOURCES us-west1-docker.pkg.dev/celo-testnet-production/celo-oracle/celo-oracle:1.0.0-rc2
If your oracle is not yet enabled by governance, youâll see these messages in the terminal:
Account 0x... is not whitelisted as an oracle for CURRENCY_PAIR
As soon as governance enables it, the node should start reporting automatically.