Karaka Tutorial #1: A Basic Tutorial config.json example

Getting started with Karaka automation can be a bit daunting at first, so in this tutorial, we step through a basic config example that shows how to power up some hive, donates some to a worthy cause and sells all HBD for HIVE.

Karaka is an Automation (clerk) for Hive and Hive-engine blockchains.
Karaka is a Maori word meaning variously: an English loanword for 'clerk' or 'clock' and a significant coastal plant 'Corynocarpus laevigatus'.

Get Karaka from https://github.com/Stormrose/karaka

The basic config.json file

{
    "intervalmins": 43,
    "hive": {
        ...
    }
}

Karaka's config file is in the standard JSON file format. You can edit JSON in any standard text editor, but JSON is very picky about punctuation, and so you might want to use a purpose-built editor or an online editor.
Karaka's config has a checking interval, which in the above case is set to 43 minutes. The intervalmins should be long enough that each second invocation triggers a rule but not so short as to overwhelm the shared API nodes. There is a minimum set in code that may change or not.
The following entry is a container for things related to the hive blockchain.

The blockchain section

"hive": {
    "apinode": "https://api.hive.blog",
    "accounts": {
        "eturnerx": "***YourPrivateActiveKeyHere***"
    },
    "rules": [
        ...
    ]
}

Within the hive blockchain section are apinode, a map of accounts and their keys, and a list of rules.
The apinode specifies which of the hive API nodes to communicate with. More advanced users can supply an array with alternative nodes instead. The accounts section holds the user accounts that Karaka will read and at least the private active key. There is a more advanced way to provide additional account information, but we'll save that for future tutorials.
The rules section is Karaka's game zone; this is where you can specify triggers and actions to take.

An example rule

"rules": [
    {
        "comment": "@eturnerx sell HBD for HIVE",
        "if": "eturnerx.hbd_balance > 0.10",
        "then": "sell 0.10 HBD for HIVE from eturnerx at market"
    }
]

A rule is enclosed in curly brackets. The compulsory fields are if and then. The user can supply an optional name and comment to help document the intent of a rule. When a name is not available, then Karaka will use the value of the if clause instead. A comment is for the user to self-document files only.

If clauses

The if part is a string containing something that Karaka can evaluate as true or false. In the above case, eturnerx.hbd_balance > 0.10, the "fact" eturnerx.hbd_balance is tested to see if it is greater than 10 cents. eturnerx.hbd_balance is the name of the fact that holds the balance of @eturnerx's HBD. But what is a fact, and where do they come from?

Where does Karaka get facts Facts from?

Whenever Karaka wakes up (generally every intervalmins minutes), it first gets information about the accounts listed in the "accounts" section from the blockchain API nodes. It pulls out key values as 'facts'. The format of a fact name is accountname.factname. For the hive blockchain, the following facts are created:

• accountname.hive_balance
• accountname.hbd_balance
• accountname.vesting_shares
• accountname.reputation
• accountname.voting_power - actually voting percentage times 100, so 9001 is 90.01% VP

Then clauses

When an if clause evaluates as true, then the rules listed in the then section are executed. A complete list of the commands is available here

Let's walk through an example of the shell command:

sell 0.10 HBD for HIVE from eturnerx at market

Here the command is sell, and the amount is 0.10 of the symbol HBD. For commands dealing with amounts, they must always be prefixed with the command name, then the amount and then the symbol.
The amount can also be a mathematical expression that can use facts. To do this, enclose the expression in round brackets. For example, let's update the command to sell the entire HBD balance instead of just a fixed amount.

sell (eturnerx.hbd_balance) HBD for HIVE from eturnerx at market

The rest of the command provides essential parameters. The for HIVE specifies that the sale should be for HIVE tokens. Karaka does know some default sale pairs, but it's always better to specify. from eturnerx tells Karaka to sell from the account "eturnerx". Finally, at market is a compulsory reminder that sales are on the internal market place at market rate, so slippage may occur.

Karaka's rules are human-readable, if somewhat wordy. I believe that readable rules ease maintenance once you have a lot of rules.

The config.json with the rule in place

So what does the complete config look like so far?

{
    "intervalmins": 43,
    "hive": {
        "apinode": "https://api.hive.blog",
        "accounts": {
            "eturnerx": "***YourPrivateActiveKeyHere***"
        },
        "rules": [
            {
                "comment": "@eturnerx sell HBD for HIVE",
                "if": "eturnerx.hbd_balance > 0.10",
                "then": "sell (eturnerx.hbd_balance) HBD for HIVE from eturnerx at market"
            }
        ]
    }
}

What if we want a rule to do more than one thing?

You can specify multiple commands in a then clause by using a JSON array with multiple Karaka commands. Commands are executed in the order specified. Let's set through an example rule that powers up a percentage of any liquid HIVE and donates some to a worthy cause.

{
    "comment": "@eturnerx power up and donate HIVE",
    "if": "eturnerx.hive_balance > 1.0",
    "then": [
        "stake 0.80 HIVE to eturnerx",
        "transfer 0.20 HIVE from eturnerx to hive.fund"
    ]
}

In this case, the stake command powers up 0.75 HIVE to @eturnerx. The transfer command sends 0.25 to @hive.fund (The DHF). There is theoretically no limit to the number of commands you can issue. But, be aware that Karaka does not check you have enough RCs before attempting to issue a command - it just assumes that if you're the type of person who needs Karaka, then you'll have enough RCs.

If we want to send the 80/20 percentage all in one go, then use a mathematical expression:

{
    "comment": "@eturnerx power up and donate HIVE",
    "if": "eturnerx.hive_balance > 1.0",
    "then": [
        "stake (eturnerx.hive_balance * 0.80) HIVE to eturnerx",
        "transfer (eturnerx.hive_balance * 0.20) HIVE from eturnerx to hive.fund"
    ]
}

I like to use this multiply by 0.xx format because it helps me keep track of the percentages because all the 0.xx's must add up to 1.0, which is 100 per cent. But any arithmetical formula works.

What if we want to keep a minimum balance of 20 Hive?

Mathematical expressions in rules can be potent. Let's say we want only to stake and donate HIVE above a certain account balance?

{
    "comment": "@eturnerx power up and donate HIVE, keeping 20",
    "if": "eturnerx.hive_balance > (20.0 + 1.0)",
    "then": [
        "stake ((eturnerx.hive_balance - 20) * 0.80) HIVE to eturnerx",
        "transfer ((eturnerx.hive_balance - 20) * 0.20) HIVE from eturnerx to hive.fund"
    ]
}

Phew! Let's talk through the if clause. First, we check that the HIVE balance is over our reserve of 20 HIVE plus some margin. We could write 21 here, but keeping the reserve amount and margin separate might be more readable. The round brackets are not essential, but I prefer to indicate the order of operations that I expect.
The arithmetic expression in the then clause is a bit more complex. First, we subtract the reserve amount from the HIVE balance and then multiple that by zero point something to get a percentage. If this doesn't make sense, let's talk through a real example by seeing what happens if the HIVE balance is 25 HIVE.

1. 25 HIVE is higher than the reserve of 20 HIVE plus the 1 HIVE margin (21).
2. 25 HIVE minus the 20 HIVE reserve is 5 HIVE. That 5 HIVE is multiplied by 0.8 to yield 4 HIVE. That 4 HIVE is staked.
3. 25 HIVE minus the 20 HIVE reserve is 5 HIVE. That 5 HIVE multiplied by 0.2 gives 1 HIVE. That 1 HIVE is donated (transferred) to @hive.fund
4. As a check, the 4 HIVE power up and 1 HIVE donation is 5 HIVE, which is the HIVE balance minus the 20 HIVE reserve.

The complete example

We have walked through a config.json file that sells all HBD for HIVE, stakes some HIVE and donates some too. Here is the complete file:

{
    "intervalmins": 43,
    "hive": {
        "apinode": "https://api.hive.blog",
        "accounts": {
            "eturnerx": "***YourPrivateActiveKeyHere***"
        },
        "rules": [
            {
                "comment": "@eturnerx sell HBD for HIVE",
                "if": "eturnerx.hbd_balance > 0.10",
                "then": "sell (eturnerx.hbd_balance) HBD for HIVE from eturnerx at market"
            }, {
                "comment": "@eturnerx power up and donate HIVE, keeping 20",
                "if": "eturnerx.hive_balance > (20.0 + 1.0)",
                "then": [
                    "stake ((eturnerx.hive_balance - 20) * 0.80) HIVE to eturnerx",
                    "transfer ((eturnerx.hive_balance - 20) * 0.20) HIVE from eturnerx to hive.fund"
                ]
            }
        ]
    }
}

After reading through the article above, I hope you can understand this config file. Perhaps you have an idea of how to modify the rules to suit you.

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