Karaka Tutorial #5: Oracles

Karaka is an Automation (clerk) for Hive and Hive Engine blockchains. This tutorial teaches how to use constants to automate Hive and Hive Engine. Get Karaka from https://github.com/Stormrose/karaka

Karaka is a Maori word meaning variously: an English loanword for 'clerk' or 'clock' and a significant coastal plant 'Corynocarpus laevigatus'.

This tutorial builds on the first three tutorials, so try those out first.

1. Karaka Tutorial #1: A Basic Tutorial config.json example
2. Karaka Tutorial #2: Hive-Engine Tokens
3. Karaka Tutorial #3: Constants
4. Karaka Tutorial #4: Import facts between chains

Why oracles?

In history and myth, an oracle has the power to see into worlds beyond, which is what oracles also do for blockchains. An oracle allows Karaka to assert facts based on information outside the blockchain. For now, Karaka has price oracles for the Hive internal market and prices from Coingecko. Karaka configs can use pricing information to decide how to act. For example, you might wait until HBD exceeds $1 USD before sending some to @blocktrades for exchange.

How to use oracles

"oracles": [
    { "type": "coingecko", "params": { "vs_currency": "usd", "ids": [ "hive", "hive_dollar" ]}},
    { "type": "hiveinternal" }
]

The oracle section is an [array] of {oracle objects} that lives in the top level of the config.json file. The only compulsory part for an oracle is its type, though coingecko oracles will want some useful parameters. To control the naming of variables, you can also specify a prefix for each oracle — otherwise, coingecko and hiveinternal default to a prefix of cg and hv, respectively.

{ "type": "hiveinternal", "prefix": "hive" }

Karaka copies facts from oracles into the scope of each chain, so oracle facts don't need to be imported.

Hive Internal Market Oracle

The hiveinternal oracle grabs pricing information from the hive internal market's ticker. This is the market used for the hive blockchain when a command instructs Karaka to buy or sell. The fact names are:

• hvHIVEHBD - The current hive price in hbd
• hvHBDHIVE - The current hbd price in hive
• hvHIVEHBD_bid - Bid price for Hive to HBD
• hvHIVEHBD_ask - Ask price for Hive to HBD

Coingecko Oracle

A Coingecko price oracle needs a base currency, which is the basis for the prices requested and this is called the vs_currency. Typically you'll specify usd or your local currency. Then, you provide a list of coingecko ids for the cryptos you'd like pricing. You can find coingecko ids by browsing prices on their site and seeing how the URI changes for the cryptocurrencies that interest you.
There can be multiple coingecko oracles, though you should be aware that coingecko will rate limit your requests if you ask for information too often. The most common use of multiple coingecko oracles is to fetch tickers with a different vs_currency.

The pricing oracle then asserts facts with names in the format of:

prefix + uppercase(symbol + vs_currency)

For the above example, Karaka asserts the following facts with these names:

• cgHIVEUSD
• cgHBDUSD

Example rule

"if": "hvHIVEHBD > 1.01 and cgHBDUSD > 1.01"

Summary

Oracles can obtain information vital to good decision-making. For now, Karaka supports fetching pricing information from Coingecko and the Hive Internal market. However, there are plans for more oracles, driven mainly by demand, so do ask for what you need.

If you have any questions about Karaka, then please get in touch.