ERG/USD Oracle on top of Ergo

Finally, “Sininen Taivas” finished an oracle (started by lorien) publishing ERG/USD price from CoinMarketCap (CMC) on the Ergo blockchain. Then the price can be used in contracts, e.g. loan or bond contracts.

Scripts for starting a new oracle box, updating a box with CMC price and cleaning the working state can be found at and are described below.

Starting New Oracle

To start new oracle, a new singleton token is to be issued. Contracts then can use identifier of this token to authenticate the oracle box.

To create a new oracle token and an oracle box, run like following:

python3 --api-key 7yaASMijGEGTbttYHg1MrXnWB8EbzjJnFLSWvmNoHrXV --name ERGUSD_1 --description "Ergo to USD Oracle (nanoergs to cent)" --mainnet

In case of success, the script will print nothing, just creating new files in the folder where it resides, namely,, and The files are containing just identifiers.

The oracle box contains token issuance data according to the upcoming standard, see e.g. last output of

Updating The Oracle

To update the price in the oracle box, should be called like:

python3 --api-key 7yaASMijGEGTbttYHg1MrXnWB8EbzjJnFLSWvmNoHrXV --cmc-key 562...... --mainnet

The script prints output like:

2019-10-24 16:44:27,449 [INFO] CMC price: 0.598898592381
2019-10-24 16:44:27,450 [INFO] Address: 9fRusAarL1KkrWQVsxSRVYnvWxaAT2A96cKtNn9tvPh5XUyCisr
2019-10-24 16:44:27,450 [INFO] Box ID: bf85ebdf242a983d5aa11ef19cef1e05cd2d863effb06392c6a38103183abc5a
2019-10-24 16:44:27,451 [INFO] Token ID: c402cee951b3f0f1efcfd6b9328db14b1212845efffbfa8cd1ab48479992d16a
2019-10-24 16:44:27,451 [INFO] Encoded Price: 05f289db05
2019-10-24 16:44:27,515 [INFO] Second Box ID: 550a0090261a94f0f1901b338c5f24a9eb5baa3a37fa937fac0f56b19a5c5082

The script will add identifier of the new box (containing updated price) to the file.

Please note that there’s no guarantee that the updating transaction will get into the blockchain.

Thus there’s another script which is tracking status of both boxes. If new box has enough confirmations (30, this number is hard-coded), the first line of the file (identifier of the old box) is to be removed. With the --stop flag the script stops tracking the new box and removing it. With one line in the script can work again (it works only when has one line).

Scripts can be called from crontab, e.g. with a schedule like:

15 */4 * * * /path/ --api-key <API-KEY> --cmc-key <COINMARKETCAP APIKEY> --mainnet
*/30 * * * * /path/ --api-key <API-KEY> --mainnet
10 */4 * * * /path/ --api-key <API-KEY> --stop --mainnet --stop

How To Use Oracle Data

First, how data is encoded. In our example, CMC price: 0.598898592381, which is about 5988985 nanoErgs per US cent. This value is encoded using VLQ + Zigzag, and also type descriptor (64-bit signed number which type is encoded as 0x05). You can use script to check encoding as python3 5988985 which gives 05f289db05.

Now how to use the oracle. It contains price in the register R4. Then the oracle box should be provided as data (i.e. read-only) input, and to read the price and to check it is provided by a certain party, the following code (from the USD token box contract) could be useful:

  val rateBox = CONTEXT.dataInputs(0)
  val rate = rateBox.R4[Long].get
  val validRateBox = rateBox.tokens(0)._1 == rateTokenID

I’m more interested in an high level view on how this actually works, with after that deep technical explanation possibly, is there any good source to read about this?


Ergo transaction, like in Bitcoin can spend many inputs and create many outputs, but (unlike Bitcoin and all the Bitcoin descendants I know about) it also can have read-only inputs. This creates an efficient mechanism to refer to unspent coins and so create applications like oracles with no much cost.

A coin in Ergo is not just about a nominal and a protecting script, like in Bitcoin, it also can contain additional registers which contain typed data to be used in scripts. Thus we’re talking about “boxes”, not “coins” in Ergo. More information can be found in this topic: Ergo terminology: a Box and a Register .

Thus this Oracle tool is creating boxes with pricing data which can be read by different scripts.

For scripting capabilities of Ergo, really good introduction to ErgoScript (high-level language, kind of Solidity of Ergo) is here , there are some examples on this forum which are using oracles, e.g. interest-free loan contract Interest-Free Loan Contract .


I wonder if it’s worth protecting oracles from accidental destruction (accidental burning of the singleton token). This could be achieved with a simple check to ensure the oracle token cannot be burned.

We should also make sure that any contracts that rely on oracles have some ability to handle the case where the oracle stops updating (e.g. if the oracle owner loses their key).

1 Like

I think this is incorrect: this is the price of ERG in USD (with a multiplier 1e7).

1 Like