Karaka Tutorial #3: Constants

Karaka is an Automation (clerk) for Hive and Hive Engine blockchains. In this tutorial, we learn 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 two tutorials, so try those out first.

• Karaka Tutorial #1: A Basic Tutorial config.json example
• Karaka Tutorial #2: Hive-Engine Tokens

Why constants?

Karaka rules make use of facts, and a constant is a fact, with name and value, that is hard-coded into the config.json file. There are two main reasons why constants could be helpful: semantics and convenience. Let's talk about these using an example rule without constants and the same rule with two constants named hivereserve and hivemargin.

"if": "eturnerx.hive_balance > 11.0",
"then": "transfer (eturnerx.hive_balance - 10) HIVE from eturnerx to otheraccount"

"if": "eturnerx.hive_balance > (hivereserve + hivemargin)",
"then": "transfer (eturnerx.hive_balance - hivereserve) HIVE from eturnerx to otheraccount"

Semantics

When we read a number in a file, it's hard to remember why that number, in particular, was chosen. In the first example, the number 11.0 doesn't tell us what the number is for, and the relationship between the 11.0 in the if portion of the rule and the 10 in the then clause is also not clear. In the second example, the constants named hivereserve and hivemargin are reminders of what we mean by those numbers. We want to maintain a minimum reserve of a certain amount but only trigger the rule when we have a certain margin above the reserve amount. From this example, you can see that properly named constants can help remind us of the meaning. This is particularly important since Karaka rules, once written, will probably run unattended for many months.

Convenience

How can it be that writing a longer constant name is more convenient than writing shorter numbers? The trick comes when it comes time to update the value. What if, at some future date, we wanted to increase our amount of hive we want to hold in reserve to 100. In the above rules, we'd have to remember to update the value in if to 101.0 and the value in the then to 100. It's easy to make a mistake or to forget to update one value or the other. This problem may increase if you're using the same reserve figures in multiple rules - as you might for hive engine tokens. If you use a constant, you can update the value in the constants section, and the job's done. So, when we call constants convenient, we mean long-term convenient.

How to Karaka constants in config.json

Karaka constants are written within a hive or hiveengine blockchain section as a JSON collection. A constant is written as a name-value pair.
Here's a complete example:

{
    "intervalmins": 43,
    "hive": {
        "apinode": "https://api.hive.blog",
        "accounts": {
            "eturnerx": "***YourPrivateActiveKeyHere***"
        },
        "constants": {
            "hivereserve": 10.0,
            "hivemargin": 1
        }
        "rules": [
            {
                "if": "eturnerx.hive_balance > (hivereserve + hivemargin)",
                "then": "transfer (eturnerx.hive_balance - hivereserve) HIVE from eturnerx to otheraccount"
            }
        ]
    }
}

Summary

Constants are a great way to indicate the meaning of Karaka rules and provide a single point of update for policy changes. There are more keystrokes, but future, you will be thankful that you took the time now to save more time later.

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