Getting started: bitcoin-cli

This lesson will be valid for both BTC and BCH.

Before reading the rest of it however, you might have to do some work. This lesson assumes that:

  • You know the very basics.
    • (what is a block, what is a hash and how blocks get chained)
  • You have a bitcoin node running.
    • To install a BTC node go to¬†https://bitcoin.org/en/full-node and grab the bitcoin core client. Then start 'bitcoin-qt' to get a bitcoin node with a GUI, or 'bitcoind' for a node running as a deamon.
    • To install a BCH node go to https://www.bitcoincash.org/#nodes and grab the bitcoin abc client. Then start 'bitcoin-qt' to get a bitcoin node with a GUI, or 'bitcoind' for a node running as a deamon.

(Note 1: If you don't have 170 GB of free hard disk space on your PC, you can run the node with the '--prune' option, which tells it to delete the blocks after verifying them. This way a node can take as little space as ~500 MB)

(Note 2: Do not try to run both nodes, unless you know what you are doing. They both use the same port by default.)

 


 

Ok. Let's assume that you already have that node running.

Now let's access the bitcoin-cli. I will be using the BCH version (Bitcoin ABC node).

$ bitcoin-cli
Bitcoin ABC RPC client version v0.17.1.0-e1fa952

Usage:
bitcoin-cli [options] <command> [params] Send command to Bitcoin ABC
bitcoin-cli [options] -named <command> [name=value] ... Send command to Bitcoin ABC (with named arguments)
bitcoin-cli [options] help List commands
bitcoin-cli [options] help <command> Get help for a command

Options:
..........

From the Usage section we can see that we can pass commands, call help to get list of commands and get help for a specific command.
Make sure to always read the help for a command that you are interested in.

Now let's see what the commands are:

$ bitcoin-cli help

And here is the output:

== Blockchain ==
getbestblockhash
getblock "blockhash" ( verbose )
getblockchaininfo
getblockcount
getblockhash height
getblockheader "hash" ( verbose )
getchaintips
getchaintxstats ( nblocks blockhash )
getdifficulty
getmempoolancestors txid (verbose)
getmempooldescendants txid (verbose)
getmempoolentry txid
getmempoolinfo
getrawmempool ( verbose )
gettxout "txid" n ( include_mempool )
gettxoutproof ["txid",...] ( blockhash )
gettxoutsetinfo
preciousblock "blockhash"
pruneblockchain
verifychain ( checklevel nblocks )
verifytxoutproof "proof"

== Control ==
getinfo
getmemoryinfo
help ( "command" )
stop
uptime

== Generating ==
generate nblocks ( maxtries )
generatetoaddress nblocks address (maxtries)

== Mining ==
getblocktemplate ( TemplateRequest )
getmininginfo
getnetworkhashps ( nblocks height )
prioritisetransaction <txid> <priority delta> <fee delta>
submitblock "hexdata" ( "jsonparametersobject" )

== Network ==
addnode "node" "add|remove|onetry"
clearbanned
disconnectnode "[address]" [nodeid]
getaddednodeinfo ( "node" )
getconnectioncount
getexcessiveblock
getnettotals
getnetworkinfo
getpeerinfo
listbanned
ping
setban "subnet" "add|remove" (bantime) (absolute)
setexcessiveblock blockSize
setnetworkactive true|false

== Rawtransactions ==
createrawtransaction [{"txid":"id","vout":n},...] {"address":amount,"data":"hex",...} ( locktime )
decoderawtransaction "hexstring"
decodescript "hexstring"
fundrawtransaction "hexstring" ( options )
getrawtransaction "txid" ( verbose )
sendrawtransaction "hexstring" ( allowhighfees )
signrawtransaction "hexstring" ( [{"txid":"id","vout":n,"scriptPubKey":"hex","redeemScript":"hex"},...] ["privatekey1",...] sighashtype )

== Util ==
createmultisig nrequired ["key",...]
estimatefee nblocks
estimatepriority nblocks
estimatesmartfee nblocks
estimatesmartpriority nblocks
signmessagewithprivkey "privkey" "message"
validateaddress "address"
verifymessage "address" "signature" "message"

== Wallet ==
abandontransaction "txid"
addmultisigaddress nrequired ["key",...] ( "account" )
backupwallet "destination"
dumpprivkey "address"
dumpwallet "filename"
encryptwallet "passphrase"
getaccount "address"
getaccountaddress "account"
getaddressesbyaccount "account"
getbalance ( "account" minconf include_watchonly )
getnewaddress ( "account" )
getrawchangeaddress
getreceivedbyaccount "account" ( minconf )
getreceivedbyaddress "address" ( minconf )
gettransaction "txid" ( include_watchonly )
getunconfirmedbalance
getwalletinfo
importaddress "address" ( "label" rescan p2sh )
importmulti "requests" "options"
importprivkey "bitcoinprivkey" ( "label" ) ( rescan )
importprunedfunds
importpubkey "pubkey" ( "label" rescan )
importwallet "filename"
keypoolrefill ( newsize )
listaccounts ( minconf include_watchonly)
listaddressgroupings
listlockunspent
listreceivedbyaccount ( minconf include_empty include_watchonly)
listreceivedbyaddress ( minconf include_empty include_watchonly)
listsinceblock ( "blockhash" target_confirmations include_watchonly)
listtransactions ( "account" count skip include_watchonly)
listunspent ( minconf maxconf ["addresses",...] [include_unsafe] )
listwallets
lockunspent unlock ([{"txid":"txid","vout":n},...])
move "fromaccount" "toaccount" amount ( minconf "comment" )
removeprunedfunds "txid"
sendfrom "fromaccount" "toaddress" amount ( minconf "comment" "comment_to" )
sendmany "fromaccount" {"address":amount,...} ( minconf "comment" ["address",...] )
sendtoaddress "address" amount ( "comment" "comment_to" subtractfeefromamount )
setaccount "address" "account"
settxfee amount
signmessage "address" "message"

There are quite a few things you can do with this client.
You can read blocks and transaction, send money, handle a wallet, or even publish raw transactions, which give you the ability to write custom scripts. Explaining these scripts is outside of the scope of this article, so let's leave it for another time...

For now, let's see how the command help looks like. Let's get more info on the 'submitblock' from the mining category:

$ bitcoin-cli help submitblock

...and the output is:

submitblock "hexdata" ( "jsonparametersobject" )

Attempts to submit new block to network.
The 'jsonparametersobject' parameter is currently ignored.
See https://en.bitcoin.it/wiki/BIP_0022 for full specification.

Arguments
1. "hexdata" (string, required) the hex-encoded block data to submit
2. "parameters" (string, optional) object of optional parameters
{
"workid" : "id" (string, optional) if the server provided a workid, it MUST be included with submissions
}

Result:

Examples:
> bitcoin-cli submitblock "mydata"
> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "submitblock", "params": ["mydata"] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/

As you see, the 'bitcoin-cli' program covers pretty much anything you might need to do when integrating Bitcoin in your programs. There are other tools that do the same, of course. There are libraries in almost any language. The bitcoin-cli however comes bundled with the most popular nodes. It can be considered the default client.

Take some time to read about all it can do.

Now try running these commands and analyze each row of the outputs (consider this your homework):

$ bitcoin-cli getinfo
$ bitcoin-cli getblockchaininfo
$ bitcoin-cli getblock 000000001aeae195809d120b5d66a39c83eb48792e068f8ea1fea19d84a4278a

(getblock only works if your node is not --pruned)

$ bitcoin-cli getnetworkinfo
$ bitcoin-cli getchaintips

(You might need to read the help for getchaintips very carefully. It is a bit harder to understand.)

$ bitcoin-cli getmempoolinfo

 


 

Remember that many of the settings you see in the outputs of these commands can change. Some of them can be changed by the owner of the node (like which network you use to connect to the other nodes), while others are decided by the network (like the mining difficulty).
Think about these changes. Make sure to understand what they would mean.

Study hard. Bye!

Leave a Reply

Your email address will not be published. Required fields are marked *