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_balanceaccountname.hbd_balanceaccountname.vesting_sharesaccountname.reputationaccountname.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.
- 25 HIVE is higher than the reserve of 20 HIVE plus the 1 HIVE margin (21).
- 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.
- 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
- 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.
Hello is it possible to stake Tokens?
I would like to stake all tokens i have. But i habe to donit for every token on hive-engine manuelly.
Yes. Hive engine tokens are supported in their own "hiveengine" section. See the example config.json on the GitHub site. I'll write a tutorial on this soon.
I have a "sell half, stake half" policy for many tokens and have written Karaka rules to do this for me. The staking command format is basically the same e.g.
stake 10 LEO from eturnerxbut it has to be in a hiveengine section.Ok, i will try it.
I may also. Not all In but a portion
I will also look which i will use an which non. Bilpcoin is not working for me so this wouöd be oneni will exchange
DM me on discord (eturnerx). Please send your config.json with the private key obscured. I'll check your
hiveenginesection is correct and look over yourrules.Thanks but i think i need some time, a lot to do. Maybe next weekend.
hello @eturnerx, i had some time and died first steps but i get this error:
Its win 7, can this be the problem? I will try it on other device with win 10 if this is the problem.
I have created a tutorial for hive engine tokens. The staking command is the same as for Hive. Let me know how it goes: Karaka Tutorial #2
Thank you
@mein-senf-dazu , sorry da bin ich relativ schnell ausgestiegen. Bin mehr der Anwender der nur einen Click macht😂.
I might have something for you in future.
Schade, vielleicjt findet sich ja wer anderes hier. Gibt ja einige die sich mit sowas auskennen.
Your content has been voted as a part of Encouragement program. Keep up the good work!
Use Ecency daily to boost your growth on platform!
Support Ecency
Vote for Proposal
Delegate HP and earn more
Bookmarked
This is quite simple in fact to start with for people already used to shell programming.
Great! I hope that Karaka can be a time saver, even for people smart enough to write their own code. LMK if there's any features you'd like added.
I will. Nice also to use Māori names :) I love the bird names for example.
Thank you very much!
I just wanted to learn a bit like this...thanks for the help!
!ENGAGE 100 !PIZZA !LUV !BEER
@eturnerx! I sent you a slice of $PIZZA on behalf of @ximlouiii.
Learn more about $PIZZA Token at hive.pizza
ENGAGEtokens.Hi @eturnerx, you were just shared some LUV thanks to @ximlouiii. Holding 10 LUV in your wallet enables you to give up to 3 LUV per day, for free. See the LUV in your wallet at https://hive-engine.com or learn about LUV at https://peakd.com/@luvshares https://ipfs.io/ipfs/QmUptF5k64xBvsQ9B6MjZo1dc2JwvXTWjWJAnyMCtWZxqM
View or trade
BEER.Hey @eturnerx, here is a little bit of
BEERfrom @ximlouiii for you. Enjoy it!Learn how to earn FREE BEER each day by staking your
BEER.Doing well, getting things done. Heh. A lot of automation stuff sits in that "complex to setup, but just runs once done". I like to have these.things setup so I can forget about them.