Wednesday, September 10, 2014

Configuring bitcoind for Debugging

This post is a reference for Bitcoin Core version 0.9.3

Configuring Bitcoin-RPC

Prior to 0.9.0 there were a number of commands you could give bitcoind from the command line. Those commands exposed the features required for Bitcoin (sending payments, managing your wallet, etc). These commands were also available through a JSON-RPC api. The JSON-RPC interface better fit the model that most server processes follow.

Starting with bitcoind version 0.9.0, the command line interface was stripped out into a separate process called bitcoin-cli. All bitcoin-cli does is allow you to talk to the bitcoind JSON-RPC api from the command line. When debugging, you'll want to be able to use bitcoin-cli to send commands to the bitcoind running process. Of course it follows that in order for this to work you need to properly setup RPC in bitcoind. This is done through the bitcoin.conf file. Relevant settings from bitcoin.conf:


These commands tell bitcoind to run in server mode with RPC enabled. RPC is how you would interact with bitcoind not only from bitcoin-cli, but also from a slew of other libraries that expose bitcoind in their respective languages. A long list of libraries that add bitcoin RPC support in various languages can be found here:

Regtest Mode

Testnet can be a little laborious to run because it needs to download the Testnet blockchain which is actually kind of large at this point. If you don't need to interact with other clients on the network for your testing, you can actually start your own local fresh blockchain by using regtest mode. This allows you to get up and running faster, and you can generate new coins whenever you want. The following launches bitcoind in regtest mode and generates 2 blocks:

bitcoind -regtest -daemon
bitcoin-cli -regtest setgenerate 2

If you are debugging bitcoind from an IDE you may not want to run it as a daemon since that forks the process and could make attaching the debugger a little more difficult.

With these two items configured, you should be well on your way to debugging bitcoind.


  1. Thanks for taking the time to discuss this, I feel strongly about it and love learning more on this topic. If possible, as you gain expertise, would you mind updating your blog with extra information? It is extremely helpful for me.

  2. While there are some nodes that will relay all valid transactions, your client will only send the transaction out about once every half an hour or so. As a result, it can be a long time before, by sheer luck, your client happens to send the transaction to a node that's willing to relay it (that happens to be able to relay it to other nodes that are similarly willing).