Karaka Tutorial #4: Import facts between chains

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.

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

Why imports?

Typically, Karaka facts below to a particular chain, but there are situations where you might want to access a fact from a different chain. For example, you might want to check that @hiveswap has sufficient balance before transferring to it for an exchange. This is where imports come in; you can use an import to copy a fact from a different chain.
An argument could be made to mix all facts into a single pool, irrespective of chain, or to introduce syntax that allows one to access facts from outside the chain. Combining the facts into a single pool could cause name clashes, esp. if Karaka moves to support the various alternative Hive-like chains. Having different syntax to access other chain fact collections would make writing rules easier but might cause problems later as rules are changed. Having imported facts explicitly declared has a single place where to check which facts are in use by rules for other chains.

How to use imports

An import must be in the imports section of the config.json.

"hiveengine": {
    "imports": [
        { "chain": "hive", "from": "hiveswap.hive_balance" },
        { "chain": "hive", "from": "hbdreserve" }
    ]
}

The imports section is an [array] of {objects}, and each object must specify the chain and the fact name (from) to import. That fact will then be available with the same fact name within the rules for that engine.
Note that both facts gathered from accounts and constants can be imported. In the above example, the hiveswap.hive_balance is collected by reading the live balance of the @hiveswap account, and hbdreserve is a constant.

The default behaviour is that imported facts have the same name as the source fact, but a fact can be renamed within the importing chain by adding a to parameter to the import object:

{ "chain": "hive", "from": "hiveswap.hive_balance",  "to": "hiveswapbalance" }

Renaming facts should help improve the readability of rules. Curiously useful, a chain can use the from' ->to` ability to rename facts when importing variables from themselves.

Summary

Importing facts offers the helpful ability that enables reasoning over facts from multiple chains. For example, use imported facts to keep a wallet on another account topped up and to check that an exchange has sufficient funds before sending your hive tokens. Importing also allows facts to be renamed.

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