Karaka - automation clerk for Hive and Hive-engine

in #enginelast month (edited)

Karaka

logo_banner_630x226px_c.png

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

Disclaimers

Preview release code. Use with caution. There is minimal error checking, and it's easy to send your tokens someplace irrecoverable. Always test with small amounts. There are likely bugs.
WARNING: If a command errors, it will be retried up to three times and then aborted. Retries make this program unsuitable for use in a splitter contract where all transactions must succeed or fail.

Usage

node dist/index.js

Installing

Requires node js. In the project folder:

npm install -g typescript
npm install
tsc

Then create a config.json file for your specific needs.

config.json file

The program takes its instructions from a file named config.json. Look at the config_example.json file and build your own. The rules are somewhat human-readable.

Concepts

For each supported blockchain, the program gathers facts about listed accounts and then checks these facts against the if clause of supplied rules. Matched rules have the commands in their then clauses executed.

An example rule:
{ "if": "'msp-makeaminnow.hive_balance' > 0.100",
"then": "stake ('msp-makeaminnow.hive_balance') HIVE from 'msp-makeaminnow'" }

The if clauses contains a conditional statement. In this case, the fact 'msp-makeaminnow.hive_balance' is evaluated to see if it is greater than 0.1. The fact is enclosed in single quotes because the fact name contains a hyphen.
The then clause is a single command string in this case but can also be a JSON array of commands strings that Karaka executes in order.

Facts

A fact generally takes the form of accountanme.tokensymbol_type where type is balance or stake. For example, eturnerx.hive_balance is the fact with the value of eturnerx's liquid hive balance.
GOTCHA: account names with a hyphen-in-them must use 'single quotes' around the fact name.
There is a per-blockchain constants section where the user can hardcode facts. Constants simplify the administration of rules that reuse the same values, such as setting the reserve (keep-back) levels of a particular token.

Commands

The available commands are transfer, stake, sell, buy and warn. See the file config_example.json for various examples.

transfer 1.000 HIVE from eturnerx to null - this command transfers 1 HIVE from the account @eturnerx to the account @null. To note:

  • the command comes first.
  • the amount and symbol come next
  • the other parameters are a pair of words parameter_name space parameter_value. In the above command, there are two parameter pairs, from and to.

Amounts can be mathematical expressions if enclosed in brackets. e.g.
transfer (eturnerx.hbd_balance - 50) HIVE from eturnerx to null
Karaka converts the results of mathematical expressions to an appropriate number of decimal places for the token type, rounded down.

Use backslash-double-quote escaping to enclosed memo/message parameters
warn message \"This is a warning message.\"

transfer

transfer 1.000 HIVE from eturnerx to null memo \"Burn baby burn\"
prefix: transfer amount symbol
pairs: to, from, memo

Transfers with memos are a powerful tool because they can initiate token exchanges, keep associated accounts topped up and a whole host of other things.

stake

stake 1.000 HIVE from eturnerx to anotheraccount
prefix: stake amount symbol
pairs: to, from

If only one of to or from is specified, then the missing parameter value is taken from the other to improve the readability of commands, for example:
stake 1.000 HIVE to eturnerx and stake 1.000 HIVE from eturnerx are equivalent commands.

sell

sell ((eturnerx.PAL_balance - palreserve) * 0.5) PAL for SWAP.HIVE from eturnerx at market
prefix: stake amount symbol
pairs: for, from, at

The above sell command example sells PAL tokens for SWAP.HIVE. On the hive blockchain, the sell command can sell HIVE->HBD and HBD->HIVE. On the hiveengine sidechain, the for symbol must currently be SWAP.HIVE. To sell SWAP.HIVE for another token, use the buy command.
The at parameter must be set to market as a wordy reminder that all sales are at market price. Be aware that large sales may incur slippage.

buy

buy ('eturnerx.SWAP.HIVE_balance' * 0.5) SWAP.HIVE of BEE from 'eturnerx' at market

prefix: buy amount symbol
pairs: of, from, at

This command buys a token with SWAP.HIVE on the hiveengine order book market. Not valid for the Hive blockchain; use sell instead.

warn

warn message \"This is a warning message.\"
prefix: warn
pairs: message

This command outputs a message to the log. The message must be enclosed in backslash-double-quotes. Be aware that Karaka suppresses repetition in logs.

License

Copyright © 2021 Emmanuel King Turner - All Rights Reserved.
MIT License. See the LICENSE file

Sort:  

A cool tool indeed. Can be used in many ways. Thank you.

A question - is the order of pairs important?

!BEER

The order of the pairs shouldn't matter after the prefix of command amount symbol so write whatever is most readable for you. But, please test your rules with small amounts and let me know if there are any aberrant behaviours. I've tried different parameter pair ordering myself but my cautious nature falls back to the principle that parsers are notoriously difficult to get right.

Cool project, looking forward to see where this goes.

Thanks for the vote of confidence. I have plans, but suggestions are always welcome.

Cool idea you got here, and a good write up. Also i want to say a big thank you for your upvotes, its really been of great help and I feel encouraged

!PIZZA
!BEER
for you

@eii, sorry!

You can call the PIZZA bot a maximum of 10 times per day.


Hey @eturnerx, here is a little bit of BEER from @ervin-lemark for you. Enjoy it!

Learn how to earn FREE BEER each day by staking your BEER.

Congratulations @eturnerx! You have completed the following achievement on the Hive blockchain and have been rewarded with new badge(s) :

You distributed more than 40000 upvotes.
Your next target is to reach 41000 upvotes.

You can view your badges on your board and compare yourself to others in the Ranking
If you no longer want to receive notifications, reply to this comment with the word STOP

Check out the last post from @hivebuzz:

False-Positive phishing alert reported by antivirus software
Feedback from the May 1st Hive Power Up Day
Support the HiveBuzz project. Vote for our proposal!