ErgoTool

Introduction

ErgoTool is a command-line interface (CLI) for Ergo blockchain. You can use ErgoTool without running your own Ergo node. However, running a node is the most secure way to communicate with the blockchain. However, the Ergo blockchain network, ErgoTool, aims to provide more foundational tools at your disposal. Surely, you still can use it with your running node.

In this post, we will walk through simple steps to generate a mnemonic phrase, create a local secret storage and use it to send ERGs between addresses, all with the help of ErgoTool commands.

Getting Started

First, we need to install ErgoTool on our system from sources by following the installation instructions. In the directory where we cloned ErgoTool, there is the ergo-tool.sh script we will use to run commands. Run the following command to check that ErgoTool is installed correctly.

$./ergo-tool.sh help the command name is not specified (run ergo-tool without arguments to list commands) Command Name: help Usage Syntax: ergo-tool help <commandName> Description: prints usage help for a command Doc page: https://aslesarenko.github.io/ergo-tool/api/org/ergoplatform/appkit/ergotool/HelpCmd.html  Let's see what we get here. ErgoTool outputs the error message with the information about the help command. This is a typical output of ErgoTool when one of the known commands is specified but used incorrectly. As we can learn from the message, the help. the command requires us to specify an additional <commandName> argument. Also, each command has an API doc page with all the details about command execution, so its URL is shown here. Create a New Mnemonic Phrase A Mnemonic is a random sequence of characters that is used to generate a master key according to Hierarchical Deterministic Wallets specification. For random convenience sequence of English words is used, but this is not required. Run the following command to generate a new mnemonic phrase: $ ./ergo-tool.sh mnemonic
bird harbor wheat innocent business disease busy quick yellow trust time oil enter situate moon


Please write it down on paper and keep it in a safe and secret place. As an additional security measure, you can create a random mnemonic password. In some sense, it can serve as another non-vocabulary word in the mnemonic. A mnemonic password is optional and is used for additional security. If you decide to use a mnemonic password, you should also write it down and keep it a secret, probably different from a mnemonic one.

Important, both mnemonic phrases and mnemonic passwords are required to restore secret keys, if you lose any of them, then you will not be able to regenerate your master key again.

Next, use the generated Mnemonic to create storage with a master secret key.

Create a New Encrypted Storage

For better security, neither a mnemonic phrase nor password is required by ErgoTool to perform the transaction signing. Instead, the secret key from the encrypted storage is required to sign a spending transaction. We can generate a secret key and store it in encrypted storage using the createStorage command.

$./ergo-tool.sh help createStorage Command Name: createStorage Usage Syntax: ergo-tool createStorage [<storageDir>="storage"] [<storageFileName>="secret.json"] Description: Creates an encrypted storage file for the Mnemonic entered by the user Doc page: https://aslesarenko.github.io/ergo-tool/api/org/ergoplatform/appkit/ergotool/CreateStorageCmd.html$ ./ergo-tool.sh createStorage
Enter mnemonic phrase> bird harbor wheat innocent business disease busy quick yellow trust time oil enter situate moon
Storage File: storage/secret.json


A master secret key is generated from the (mnemonic phrase, mnemonic password) pair and saved encrypted in the storage/secret.json file. The Mnemonic itself is not stored in the file, and there is no way to restore it from the file, even if you know the passwords.

Please enter the correct mnemonic password, the one you chose and saved before.

Since a mnemonic password is optional, you can leave it empty by pressing enter.

If you forget the storage password (aka encryption password), you will not be able to use that storage file anymore; however, you can always restore your secret keys from (Mnemonic the phrase, mnemonic password) pair and thus create a new storage file with a new password.

Keep your storage file and storage password in secret; anyone who obtains both your storage file and storage password will be able to decipher it and access secret keys.

Extracting Data From Storage

Secret storage contains a master secret key and can be used to compute both the public key and the pay-to-public-key address corresponding to that secret key. The extractStorage command is doing just that.

$./ergo-tool.sh help extractStorage Command Name: extractStorage Usage Syntax: ergo-tool extractStorage <storage file> address|masterKey|publicKey|secretKey mainnet|testnet Description: Reads the file, unlocks it using a password and extracts the requested property from the given storage file. Doc page: https://aslesarenko.github.io/ergo-tool/api/org/ergoplatform/appkit/ergotool/ExtractStorageCmd.html$ ./ergo-tool.sh extractStorage storage/secret.json address mainnet
9iHiSAg3ko2ZGxR2vhc1Aem3tShqfzEPDAF7XK5cdtbZ3Ut2CCf


Here the command transforms the secret key to the corresponding public key and then creates the pay-to-public-key address on the mainnet.

In the same way, we can obtain the public key, private key and other data from the storage.

$./ergo-tool.sh extractStorage storage/secret.json secretKey mainnet Storage password> 55dfde63c9b6b4f47683592e85ee997ba2e93507f38ba3f9c82933bcfbc677ca$ ./ergo-tool.sh extractStorage storage/secret.json publicKey mainnet


Listing Unspent Boxes

ErgoTool has the special command to list all available (aka unspent) boxes for a given address.

$./ergo-tool.sh listAddressBoxes 9f4QF8AD1nQ3nJahQVkMj8hFSVVzVom77b52JU7EW71Zexg6N8v BoxId NanoERGs 4840cb6facc20b765085db0ad24768ed0c5e7afd413e8e58e597c33a993f8119 4987000000  if we specify the --print-json option, then ErgoTool will output all the boxes in JSON format $ ./ergo-tool.sh listAddressBoxes --print-json 9f4QF8AD1nQ3nJahQVkMj8hFSVVzVom77b52JU7EW71Zexg6N8v


Transfer Coins

With a secret key stored securely in the encrypted storage file, we can use ErgoTool to transfer coins from our address to some other recipient address. The command to do that is send.

./ergo-tool.sh help send

Command Name: send
Usage Syntax: ergo-tool send <storageFile> <recipientAddr> <amountToSend>
Description:  send the given <amountToSend> to the given <recipientAddr> using
the given <storageFile> to sign transaction (requests storage password)
Doc page: https://aslesarenko.github.io/ergo-tool/api/org/ergoplatform/appkit/ergotool/SendCmd.html

The storage file is necessary to access the secret key and generate a signature. The ErgoTool will request a storage password to unlock and decipher the file content. The command send supports the --dry-run option, which forces ErgoTool to create the the signed transaction, but instead of sending it to the blockchain, ErgoTool prints the transaction on the console.

$./ergo-tool.sh send --dry-run storage/E1.json 9hHDQb26AjnJUXxcqriqY1mnhpLuUeC81C4pggtK7tupr92Ea1K 5000000 Storage password> Creating prover... Ok Loading unspent boxes from at address 9f4QF8AD1nQ3nJahQVkMj8hFSVVzVom77b52JU7EW71Zexg6N8v... Ok Signing the transaction... Ok Tx: { "id": "2633733a1d81b8fc747d984bdc36fac42cb52118b5057375b081b4c543c62b0e", "inputs": [ { "boxId": "4840cb6facc20b765085db0ad24768ed0c5e7afd413e8e58e597c33a993f8119", "spendingProof": { "proofBytes": "060e7c99c9c9cecf89ec5c3e7b692075e0b3415318f8064c64f7f01401ac29c6637b44535151e51d43d4cd25e05ad459dbe33718a99a22dd", "extension": {} } } ], "dataInputs": [], "outputs": [ { "boxId": "4eaed414ae763158126859bbf912fa9ffb9ea67ac13d81d473b1c81ec65b06fd", "value": 5000000, "ergoTree": "ErgoTree(0,WrappedArray(),Right(ConstantNode(SigmaProp(ProveDlog(ECPoint(6ba5cf,8ae5ac,...))),SSigmaProp)),80,[[email protected])", "creationHeight": 130508, "assets": [], "additionalRegisters": {}, "transactionId": "2633733a1d81b8fc747d984bdc36fac42cb52118b5057375b081b4c543c62b0e", "index": 0 }, { "boxId": "059b426fe2aaef10b6a9a618f0c5b4e97d4dd9931328bf4f52bcf92b0943a42c", "value": 1000000, "ergoTree": "ErgoTree(16,WrappedArray(IntConstant(0), IntConstant(0), ConstantNode(Coll(16,2,4,-96,11,8,-51,2,121,-66,102,126,-7,-36,-69,-84,85,-96,98,-107,-50,-121,11,7,2,-101,-4,-37,45,-50,40,-39,89,-14,-127,91,22,-8,23,-104,-22,2,-47,-110,-93,-102,-116,-57,-89,1,115,0,115,1),Coll[SByte$]), ConstantNode(Coll(1),Coll[SInt$]), IntConstant(1)),Right(BoolToSigmaProp(AND(ConcreteCollection(WrappedArray(EQ(Height$(163),SelectField(ExtractCreationInfo(ByIndex(Outputs$(165),ConstantPlaceholder(0,SInt$),None)),1)), EQ(ExtractScriptBytes(ByIndex(Outputs$(165),ConstantPlaceholder(1,SInt$),None)),SubstConstants(ConstantPlaceholder(2,Coll[SByte$]),ConstantPlaceholder(3,Coll[SInt$]),ConcreteCollection(WrappedArray(CreateProveDlog(DecodePoint(MinerPubkey$(172)))),SSigmaProp))), EQ(SizeOf(Outputs$(165)),ConstantPlaceholder(4,SInt$))),SBoolean)))),4836,[[email protected])", "creationHeight": 130508, "assets": [], "additionalRegisters": {}, "transactionId": "2633733a1d81b8fc747d984bdc36fac42cb52118b5057375b081b4c543c62b0e", "index": 1 }, { "boxId": "0638ddb0fe6a8cc6ca4f981f71777f4a6e8aad72d57fdf945b24e0ef4ca714e1", "value": 4981000000, "ergoTree": "ErgoTree(0,WrappedArray(),Right(ConstantNode(SigmaProp(ProveDlog(ECPoint(472963,7c85fd,...))),SSigmaProp)),80,[[email protected])", "creationHeight": 130508, "assets": [], "additionalRegisters": {}, "transactionId": "2633733a1d81b8fc747d984bdc36fac42cb52118b5057375b081b4c543c62b0e", "index": 2 } ] }  Note the "ergoTree" scripts are deserialized and printed as abstract syntax trees. This printing format can be regulated by additional options so that the scripts can be printed as human-readable ErgoScript. (Not yet implemented, but somewhere on the roadmap.) If we exclude the --dry-run option, the transaction will be sent and included in the blockchain. $ ./ergo-tool.sh send storage/E1.json 9hHDQb26AjnJUXxcqriqY1mnhpLuUeC81C4pggtK7tupr92Ea1K 5000000
Creating prover... Ok
Signing the transaction... Ok
Sending the transaction... Ok
Server returned tx id: "c5710af17f5124a232a5ef731fdf94a493025334c2a7d5a79e9923210972b962"

The newly created transaction will be broadcast all over the blockchain, and miners will start to include it in a new block. Once the new block with our transaction is mined and accepted by the network, our transfer is confirmed, and we can see it in Explorer.

We can also list boxes of the recipient address and see the coin we created, among others. (until it is spent by the recipient)

\$ ./ergo-tool.sh listAddressBoxes 9hHDQb26AjnJUXxcqriqY1mnhpLuUeC81C4pggtK7tupr92Ea1K
BoxId                                                             NanoERGs
252c5ce38fc367001ea48fa6813e6252ebc169288d9b5392c572edb55380b3cd  5000000
6df9dbf08b4859b7e280afbd0822dcf20dba5bf8e3e33b78fe278df6597276f1  2000000
d47f958b201dc7162f641f7eb055e9fa7a9cb65cc24d4447a10f86675fc58328  1000000
e050a3af38241ce444c34eb25c0ab880674fc23a0e63632633ae14f547141c37  1000000
b50ed8c2953fd33b52af816c4caa63ec5b6d236a262a5a192534695c3478da78  1000000


Security Notes

ErgoTool is created with security in mind and tries its best to safeguard the usage of sensitive information like mnemonic phrases (which are never stored persistently), passwords (which are never shown on the screen) etc. In addition, secret keys are never stored on a local disk unencrypted and surely never sent anywhere.

Conclusion

ErgoTool is designed to look and feel like a typical CLI utility:

• which is easy to use and fast to run from the command line
• can be scriptable via shell scripts
• has built-in usage help

At the same time, ErgoTool is designed to be easily extensible:

• implemented in high-level language Scala
• reuses the core libraries which are used in the Ergo network client
• open-sourced and fully documented

This last point is especially important as many new commands can be easily added to ErgoTool, thanks to its architecture. If you need a specific feature or a command, please file an issue or maybe even a PR.