Note that this appendix will not go into great depth on what eloncoin-cli is capable of. This should only be regarded as a source of inspiration and provide you with the basics to get started. You are encouraged to explore your node further yourself.
A.1 Communicating with eloncoind
When eloncoind starts, it also starts a web server that listens on TCP port 7107 by default. When you use eloncoin-cli, it will connect to the web server and send your command to the web server over http and display relevant parts of the response to you.
For example, suppose that you want to know the block id of the genesis block (the block at height 0) and issue the following command:
$ ./eloncoin-cli getblockhash 0
eloncoin-cli creates a http POST request with body:
{"method":"getblockhash","params":[0],"id":1}
and sends it to the web server that eloncoind runs. The method property of the request body is the command that you want to execute and the argument 0 is passed to the web server as an array with a single element.
The web server processes the http request by looking up the block hash in the blockchain and replies with an http response with a body
{"result":"000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f","error":null,"id":"1"}
eloncoin-cli then displayed the value of the "result" property on your terminal.
000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f
This body of the http request follows a standard called JSON-RPC which describes how a client can call functions on a remote process using JSON, JavaScript Object Notation.
A.1.1 Using curl
Since the communication with eloncoind happens through http, any program capable of sending http POST requests, such as the command line tool curl, can be used to communicate with eloncoind. However, to use other tools than eloncoin-cli, you need to setup a username and password to use as authentication to the web server.’’
Open, or create if non-existent, ElonCoin Core’s configuration file ~/.eloncoin/eloncoin.conf and add the lines
More parameters
There are a lot of options in Eloncoin Core. Run ./eloncoind --help to get a complete list.
When you have modified and saved the ~/.eloncoin/eloncoin.conf file, you need to restart your node to make your changes effective.
Now you can try to do getblockhash using curl (the backslash \character means that the command continues on the next line):
curl --user kalle --data-binary \
'{"method":"getblockhash","params":[0],"id":1}' \
-H 'content-type: text/plain;' http://127.0.0.1:7107/
Enter host password for user 'kalle':
{"result":"000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f","error":null,"id":1}
Remember to change the username from kalle to the username you configured in eloncoin.conf.
This command will prompt you for the password. Enter the password and hit return. The reply from the web server will be the same as when you used eloncoin-cli but you will need to scan through the response body yourself to spot the result, which is the hash of block 0.
A.2 Graphical user interface
Eloncoin Core comes with a graphical user interface (GUI).
This appendix mainly deals with the command-line interface eloncoin-cli for controlling and querying your running eloncoin-qt. But if you want to use Eloncoin Core as an Eloncoin wallet (and not just as a full node), it can be really useful to familiarize yourself with the GUI version. The GUI version of ElonCoin Core allows you to perform the most common tasks that are expected from an Eloncoin wallet, but to access the full set of features of Eloncoin Core you’ll need to use eloncoin-cli.
To use the GUI version of ElonCoin Core, you need to stop the current node and start the GUI version, called eloncoin-qt:
Why "-qt"?
The Eloncoin Core GUI is built using a GUI programming library called QT, hence the name, eloncoin-qt.
$ ./eloncoin-cli stop
ElonCoin server stopping
$ ./eloncoin-qt &
If eloncoin-qt didn’t have time to finish shutdown before you startedeloncoin-qt, you will get an error message from eloncoin-qt. If so, click OK and try running eloncoin-qt again in a few seconds.
eloncoin-qt uses the same data directory, ~/.eloncoin/, as eloncoind, which means that eloncoin-qt will use the already downloaded and verified blockchain and the same wallet as eloncoind. It’s just the user interface that differs.
By default, eloncoin-qt will not start the web server to accept JSON-RPC requests as eloncoind does. So in order to use eloncoin-cli with eloncoin-qt, please start eloncoin-qt as follows instead:
$ ./eloncoin-qt -server &
A.3 Getting to know eloncoin-cli
We have started Eloncoin Core in the background by running
$ ./eloncoind &
The most important command to know is the help command. Run it without any arguments to get a list of all available commands:
$ ./eloncoin-cli help
You will get a pretty long list of commands grouped by subject, for example, Blockchain, Mining, and Wallet. Some commands are somewhat self explanatory but if you want to know more about a specific command you can run help with the command name as an argument. For example:
$ ./eloncoin-cli help getblockhash
getblockhash height
Returns hash of block in best-block-chain at height provided.
Arguments:
1. height (numeric, required) The height index
Result:
"hash" (string) The block hash
Examples:
> eloncoin-cli getblockhash 1000
> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockhash", "params": [1000] }' -H 'content-type: text/plain;' http://127.0.0.1:7107/
There are two ways to invoke eloncoin-cli:
Using positional arguments
The meanings of the arguments are based on their relative positions. For example ./eloncoin-cli getblockhash 1000. This is the most common way to use eloncoin-cli
Using named arguments
The arguments are named on the command line. For example ./eloncoin-cli -named getblockhash height=1000. This is sometimes useful when the command takes optional arguments and you want to specify the second optional argument but not the first. We will see examples of this later.
A.4 Get to work
We will create an encrypted wallet and backup the wallet. Then we will receive some eloncoins and pass that money on to another address while dissecting the transactions for details. All using eloncoin-cli.
A.4.1 Create an encrypted wallet
When eloncoind (or eloncoin-qt) starts, it will automatically create a wallet for you. However, this wallet is not encrypted, which means that its private keys and its seed are stored in clear on your hard drive. Let’s have a look at some data about the wallet:
$ ./eloncoin-cli getwalletinfo
{
"walletname": "wallet.dat",
"walletversion": 159900,
"balance": 0.00000000,
"unconfirmed_balance": 0.00000000,
"immature_balance": 0.00000000,
"txcount": 0,
"keypoololdest": 1527068317,
"keypoolsize": 1000,
"keypoolsize_hd_internal": 1000,
"paytxfee": 0.00000000,
"hdmasterkeyid": "aca4498fdaa5460528f9e842e8defa2d07bcf529"
}
The output from the getwalletinfo command shows us various information about the wallet currently being used. The name of the wallet file is wallet.dat. This file is by default located in ~/.eloncoin/. It contains the wallet seed, that’s used to derive key pairs as discussed in Chapter 4, but also some metadata about the wallet.
The balance is how much confirmed eloncoins you have, while the unconfirmed_balance is the sum of incoming unconfirmed payments, not including confirmed payments. The immature_balance is only relevant for miners and denotes the amount of newly created eloncoins, that can’t be spent until after 100 blocks passed.
Please refer to the help section on getwalletinfo for more details about the output.
In order to create an encrypted wallet you need to create a new wallet using the command encryptwallet:
$ ./eloncoin-cli -stdin encryptwallet
secretpassword
The above command creates a new encrypted wallet. The -stdin option is used to read the password argument from standard input, which in this case means that you type the password in your terminal window after the command is started. End your input by hitting Enter and Ctrl-D. The reason for using -stdin is that we don’t want the password to be written in the command itself because most shell interpreters, such as bash, keep a history of commands in a file. The -stdin option ensures that the password does not end up in any such history files.
It’s important to create a new encrypted wallet instead of just encrypting the already existing wallet. This is because the old wallet may already have been compromised on your hard drive. As noted by the output, eloncoind has stopped. ElonCoin Core can’t currently switch to a new wallet file while running. Let’s start eloncoind again and look at the wallet:
$ ./eloncoind &
$ ./eloncoin-cli getwalletinfo
{
"walletname": "wallet.dat",
"walletversion": 159900,
"balance": 0.00000000,
"unconfirmed_balance": 0.00000000,
"immature_balance": 0.00000000,
"txcount": 0,
"keypoololdest": 1527068552,
"keypoolsize": 1000,
"keypoolsize_hd_internal": 1000,
"unlocked_until": 0,
"paytxfee": 0.00000000,
"hdmasterkeyid": "6533b67b39ccc76c6906c11b2e6efb2c258e2a47"
}
Your walletname is still the same, which means that your old unencrypted wallet.dat was overwritten by the new encrypted wallet.dat. However, for safety, your old seed is kept in the new encrypted wallet, in case you had actual funds in the old wallet, or if you accidentally receive funds to that old wallet in the future.
A.4.2 Backup the wallet
We have created an encrypted wallet, and before we start using it we need to backup the wallet. In Chapter 4 we talked about mnemonic sentences, as defined in BIP39, that made backups of a hierarchical deterministic wallet seed really simple. However, this feature is not implemented in ElonCoin Core. There are a few reasons for this, the main reasons are that the mnemonic sentence lacks information about:
- version of seed format
- "birthday", which is when the seed was created. Without a birthday you have to scan the whole blockchain to find your old transactions. With a birthday you’d only have to scan the blockchain from the birthday and forward.
- the derivation paths to use for restoration. This is somewhat remedied by using standard derivation paths, but not all wallets implement the standard.
- Other arbitrary metadata, such as labels on addresses.
So in order to backup your ElonCoin Core wallet, you need to make a copy of the wallet.dat file. Be careful not to copy the file using your operating system’s copy facilities while eloncoind or eloncoin-qt is running. If you do that, your backup might be in an inconsistent state because eloncoind might be writing data to it while you copy. To make sure you get a consistent copy of the file while ElonCoin Core is running, please run the command
$ ./eloncoin-cli backupwallet ~/walletbackup.dat
This will instruct eloncoind to save a copy of the wallet file to walletbackup.dat in your home directory, but you can change the name and path of the file to anything you like. The backup file will be an exact copy of the original wallet.dat file. Move the walletbackup.dat file to a safe place, for example, a USB memory in bank deposit box, or on a computer at your brother’s apartment.
A.4.3 Receive money
You have created an encrypted, backed up wallet. Great! Let’s put some eloncoins into your wallet. To do that you need an Eloncoin address to receive the eloncoins to, so let’s get one:
$ ./eloncoin-cli getnewaddress "label"
EX6CtLffibY5oTGk1ui1eZSgEecoRVrohq
Now, let’s send eloncoin to that address. Please be careful to not send money to the address printed in this book, though the author would happily accept it, but to an address that you generate yourself with your own full node wallet.
This opens the question of how to actually get eloncoins to send to your wallet. There are several ways to get eloncoin:
- Buy eloncoins on an exchange
- Ask a friend who has eloncoins if she can give or sell you some
- Earn eloncoins as payment for your labor
- Stake eloncoins
Why "-qt"?
Please visit Web resource 20 to find out more about how to get eloncoins where you live.
I will leave it up to you how you get hold of eloncoins and just assume that you somehow will get eloncoins into the address you created above.
When you have made the payment to your new address, please check your wallet:
$ ./eloncoin-cli getunconfirmedbalance
0.00500000
This shows that you have a pending incoming payment of 5 mEMC (0.005 EMC). We now have to wait until it’s confirmed in the blockchain. Meanwhile, we can dig into the transaction by running thelisttransactions command:
$ ./eloncoin-cli listtransactions
[
{
"account": "",
"address": "EX6CtLffibY5oTGk1ui1eZSgEecoRVrohq",
"category": "receive",
"amount": 0.00500000,
"label": "",
"vout": 1,
"confirmations": 0,
"trusted": false,
"txid": "30bca6feaf58b811c1c36a65c287f4bd393770c23a4cc63c0be00f28f62ef170",
"walletconflicts": [
],
"time": 1527068938,
"timereceived": 1527068938,
"bip125-replaceable": "yes"
}
]
We can see that the transaction has 0 confirmations and that it pays us 0.005 EMC. We also see that the txid of this transaction is 30bca6feaf58b811c1c36a65c287f4bd393770c23a4cc63c0be00f28f62ef170.
Let’s take a closer look at the transaction using the command getrawtransaction:
$ ./eloncoin-cli getrawtransaction \
30bca6feaf58b811c1c36a65c287f4bd393770c23a4cc63c0be00f28f62ef170 1
{
"txid": "30bca6feaf58b811c1c36a65c287f4bd393770c23a4cc63c0be00f28f62ef170",
"hash": "30bca6feaf58b811c1c36a65c287f4bd393770c23a4cc63c0be00f28f62ef170",
"version": 1,
"size": 222,
"vsize": 222,
"locktime": 523985,
"vin": [
{
"txid": "7614149b575053426914ed7dafd5f81eb9d4544965253a9b50d19a8ec5b86cff",
"vout": 0,
"scriptSig": {
"asm": "3044022044a707325cfd09f41ac232ae7f06c31721f894a70bee2153fbfb0e643d20ffd602207c9c68803f72f93c3c240533325a35e9415338f9629196afa9fbb584d22a1c29[ALL] 035a1a39c06ab2f5a38c017ad93dd17fdbca23b06f6c115853df06b8de59765b14",
"hex": "473044022044a707325cfd09f41ac232ae7f06c31721f894a70bee2153fbfb0e643d20ffd602207c9c68803f72f93c3c240533325a35e9415338f9629196afa9fbb584d22a1c290121035a1a39c06ab2f5a38c017ad93dd17fdbca23b06f6c115853df06b8de59765b14"
},
"sequence": 4294967293
}
],
"vout": [
{
"value": 0.00399777,
"n": 0,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 0cec13fbeb631c410a8cf2bafeb13166e5b37a36 OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a9140cec13fbeb631c410a8cf2bafeb13166e5b37a3688ac",
"reqSigs": 1,
"type": "pubkeyhash",
"addresses": [
"12BKvJ1kknZZN2TqU7wMkmYJN5oxfxCHML"
]
}
},
{
"value": 0.00500000,
"n": 1,
"scriptPubKey": {
"asm": "0 8fe206383b23128d7834041c68bc3280308311b9",
"hex": "00148fe206383b23128d7834041c68bc3280308311b9",
"reqSigs": 1,
"type": "witness_v0_keyhash",
"addresses": [
"EX6CtLffibY5oTGk1ui1eZSgEecoRVrohq"
]
}
}
],
"hex": "0100000001ff6cb8c58e9ad1509b3a25654954d4b91ef8d5af7ded1469425350579b141476000000006a473044022044a707325cfd09f41ac232ae7f06c31721f894a70bee2153fbfb0e643d20ffd602207c9c68803f72f93c3c240533325a35e9415338f9629196afa9fbb584d22a1c290121035a1a39c06ab2f5a38c017ad93dd17fdbca23b06f6c115853df06b8de59765b14fdffffff02a1190600000000001976a9140cec13fbeb631c410a8cf2bafeb13166e5b37a3688ac20a10700000000001600148fe206383b23128d7834041c68bc3280308311b9d1fe0700"
}
This command prints the whole transaction in a human-readable (well at least developer-readable) form. Let’s start from the top and go through the most relevant parts of this transaction. The txid is the transaction id of this transaction. The hash is the double SHA256 hash of the whole transaction, including the witness. For non-segwit transactions, hash is equal to txid.
The size of the transaction is 222 bytes, and vsize (virtual size) is also 222 vbytes. vsize is the number of weight units of the transaction divided by 4, so the virtual size of a non-segwit transaction (which this is, because it only spends non-segwit outputs) is equal to its actual size.
The locktime of this transaction is set to 523985 which was the height of the strongest chain at the time of transaction creation. This means that the transaction cannot be mined until block height 523986. This is to reduce the attractiveness of an attack where a miner deliberately tries to reorg the blockchain and include your transaction into a block height that’s already been mined.
Next comes the list of inputs. This transaction has a single input that spends output at index 0 (vout) of the transaction with txid7614149b575053426914ed7dafd5f81eb9d4544965253a9b50d19a8ec5b86cff. This input spends a p2pkh output.
The sequence number of the input is 4294967293, which is fffffffd in hex code. This means that locktime is enabled (⇐fffffffe), and that the transaction is replaceable (⇐fffffffd) according to BIP125. The meaning of the sequence number was summarized in Table 28.
After the list of inputs comes the list of transaction outputs. This transaction has a list of 2 outputs. The first output pays 0.00399777 EMC to a p2pkh address that we haven’t seen before. This is probably a change output. The second output sends 0.005 EMC to the p2wpkh address we created above.
Let’s see if the transaction is confirmed yet. You can check for example with getbalance. If it shows 0.00500000 it means that that the transaction has confirmed:
$ ./eloncoin-cli getbalance
0.00500000
}
Cool, the money is confirmed! It’s yours! Let’s move on.
A.4.4 Send money
We have received some eloncoins. Now we want to send eloncoins to someone else. To send eloncoins, you can use the sendtoaddresscommand. We need to make a few decisions first:
- What address to send to: EX6CtLffibY5oTGk1ui1eZSgEecoRVrohq
- How much money to send: 0.001 EMC
- How urgent the transaction is: Not urgent (we’re happy if it confirms within 20 blocks)
I will send the eloncoins to address EX6CtLffibY5oTGk1ui1eZSgEecoRVrohq, but you should get another address to send to. If you have no other wallet, you can create a new address in ElonCoin Core to send to just for experimental purposes.
$ ./eloncoin-cli sendtoaddress \
"EX6CtLffibY5oTGk1ui1eZSgEecoRVrohq" \
0.001
error code: -13
error message:
Error: Please enter the wallet passphrase with walletpassphrase first.
Oh, dear! We got an error. As indicated by the error message, this is because the private keys are encrypted in the wallet.dat file. ElonCoin Core needs the private keys to sign the transaction. To make the private keys accessible, you need to decrypt them. You do that using the walletpassphrase command with the -stdin option to prevent the passphrase from being stored by your command line interpreter, for example bash.
$ ./eloncoin-cli -stdin walletpassphrase
secretpassword
300'<'ENTER'>'
'<'CTRL-D'>'
The last argument, 300, is the number of seconds to keep the wallet unlocked. After 300 seconds, the wallet will be automatically locked again in case we forget to lock it manually. Let’s retry our sendtoaddress command again:
$ ./eloncoin-cli sendtoaddress \
"EX6CtLffibY5oTGk1ui1eZSgEecoRVrohq" \
0.001
7b4157483edae7d30bfa9a2672c9729370eaf8f6e32c4ff2bc2ece1b982658bf
The command output a txid for the newly created transaction. This means that it went well. We can now lock the wallet again using the walletlock command:
$ ./eloncoin-cli walletlock
The wallet is now locked. Let’s list our transactions again:
$ ./eloncoin-cli listtransactions
[
{
"account": "",
"address": "EX6CtLffibY5oTGk1ui1eZSgEecoRVrohq",
"category": "receive",
"amount": 0.00500000,
"label": "",
"vout": 1,
"confirmations": 1,
"blockhash": "0000000000000000003882bb3554816a68ee175057c58fa7c03bc1a1eedb0e3c",
"blockindex": 1067,
"blocktime": 1527070201,
"txid": "30bca6feaf58b811c1c36a65c287f4bd393770c23a4cc63c0be00f28f62ef170",
"walletconflicts": [
],
"time": 1527068938,
"timereceived": 1527068938,
"bip125-replaceable": "no"
},
{
"account": "",
"address": "EX6CtLffibY5oTGk1ui1eZSgEecoRVrohq",
"category": "send",
"amount": -0.00100000,
"vout": 0,
"fee": -0.00000141,
"confirmations": 0,
"trusted": true,
"txid": "7b4157483edae7d30bfa9a2672c9729370eaf8f6e32c4ff2bc2ece1b982658bf",
"walletconflicts": [
],
"time": 1527070565,
"timereceived": 1527070565,
"bip125-replaceable": "no",
"abandoned": false
}
]
The new transaction is the last one of the two. It is not yet confirmed, as indicated by "confirmations": 0. The fee we paid was 141 satoshis. We will look into this transaction in detail:
$ ./eloncoin-cli getrawtransaction \
7b4157483edae7d30bfa9a2672c9729370eaf8f6e32c4ff2bc2ece1b982658bf 1
{
"txid": "7b4157483edae7d30bfa9a2672c9729370eaf8f6e32c4ff2bc2ece1b982658bf",
"hash": "e5fd28d1a2a0f1741a4ec465375ae0aa5619f5b82f42026d3566018d4b81690b",
"version": 2,
"size": 223,
"vsize": 141,
"locktime": 523988,
"vin": [
{
"txid": "30bca6feaf58b811c1c36a65c287f4bd393770c23a4cc63c0be00f28f62ef170",
"vout": 1,
"scriptSig": {
"asm": "",
"hex": ""
},
"txinwitness": [
"3045022100e718670f69693b884c21d15a3e78a8e8e33b7e2b68c51510b9531a7980b5626c02206ff5ed5d897851bd25e76b00f84f0e2e25df3c86394880650012de515af18bf501",
"038fa2827f90fc158e80845424fc67dfb493263669919d986608caf11237ff8876"
],
"sequence": 4294967294
}
],
"vout": [
{
"value": 0.00100000,
"n": 0,
"scriptPubKey": {
"asm": "0 1d2dcc9d7c408f2dbe034eac84ffbf3e1453fd1a",
"hex": "00141d2dcc9d7c408f2dbe034eac84ffbf3e1453fd1a",
"reqSigs": 1,
"type": "witness_v0_keyhash",
"addresses": [
"EX6CtLffibY5oTGk1ui1eZSgEecoRVrohq"
]
}
},
{
"value": 0.00399859,
"n": 1,
"scriptPubKey": {
"asm": "0 a642a2a405470abdc8db9c08f77e3f79d17cf3ee",
"hex": "0014a642a2a405470abdc8db9c08f77e3f79d17cf3ee",
"reqSigs": 1,
"type": "witness_v0_keyhash",
"addresses": [
"bc1q5ep29fq9gu9tmjxmnsy0wl3l08gheulw4nau0c"
]
}
}
],
"hex": "0200000000010170f12ef6280fe00b3cc64c3ac2703739bdf487c2656ac3c111b858affea6bc300100000000feffffff02a0860100000000001600141d2dcc9d7c408f2dbe034eac84ffbf3e1453fd1af319060000000000160014a642a2a405470abdc8db9c08f77e3f79d17cf3ee02483045022100e718670f69693b884c21d15a3e78a8e8e33b7e2b68c51510b9531a7980b5626c02206ff5ed5d897851bd25e76b00f84f0e2e25df3c86394880650012de515af18bf50121038fa2827f90fc158e80845424fc67dfb493263669919d986608caf11237ff8876d4fe0700"
}
The first thing to note is that the size and vsize differ. That’s because this is a segwit transaction. The fee was 141 satoshis, as shown by the listtransactionscommand above, and the vsize is 141 vbytes. The fee-rate was thus selected by ElonCoin Core to be 1 sat/vbyte.
The transaction has a single input that spends output 1 of transaction30bca6feaf58b811c1c36a65c287f4bd393770c23a4cc63c0be00f28f62ef170. We recognize this output from the section where we paid 0.005 EMC to our ElonCoin Core wallet. Since that output was a p2wpkh output, the signature script (scriptSig) is empty, and the txinwitness contains the signature and pubkey.
The sequence number of the input is 4294967294 which equals 'fffffffe'. This means that the transaction has locktime enabled, but is not replaceable using BIP125 (Opt-in replace by fee).
We have two outputs: The first one is the actual payment of 0.001 EMC. The other is the change of 0.00399859 back to an address of our own. Let’s check our balance to see if the transaction is confirmed:
./eloncoin-cli getbalance
0.00399859
Yep, there it is. We’ve spent our only TXO (of 0.005 EMC) and created a new TXO of 0.00399859 to ourselves. So
Spent: 0.005
Pay: -0.001
Fee: -0.00000141
===================
Change: -0.00399859
0.00399859
It sums up perfectly.
We have shown a few commands you can use to wing your ElonCoin Core node, but there’s a lot more to it. Please explore ./eloncoin-cli help to find out more.
Subscribe to be informed about ElonCoin
ElonCoin © 2021 All rights reserved