At time of writing, bitcoind is available on Github at https://github.com/bitcoin/bitcoin. If you'd like, you can clone the repository and build the project from source.
The easier and faster way to get bitcoind
working is to download a pre-built binary. Bitcoincore.org has an update list of them: https://bitcoincore.org/en/download/. If you download a pre-built version it is strongly recommended that you verify the binary. There are instructions on how to do so currently on the download page.
If you skip this part, it's not a problem for this class. We won't be putting any real bitcoin on your installation.
There are currently three different 'networks'* you can run bitcoind against: mainnet, testnet, and regtest.
* A fourth, called 'signet' also exists, but we're going to pretend it doesn't for now.
mainnet
is the global network that 'real' bitcoins are mined and transacted on. This network requires an 'initial block sync' in order for bitcoind to be fully operational. This means that the computer running bitcoind will download the entire Bitcoin blockchain from other peers on the mainnet network. Depending on your network connection, hardware speed, and year that you are attempting this, it can take up to two weeks to fully download and verify the current blockchain. Additionally, it will require somewhere from 200 to 500GB of space.*testnet
is the global test network. The bitcoins that are mined and transacted on this network have no value; typically they're denoted as tBTC. This network is meant to be used to test software on. As it is a global network with a blockchain, it also requires an initial block sync in order to be operational. Typically, testnet is smaller than the mainnet blockchain, but it can still take several hours for the sync to complete.regtest
is a local testing environment for bitcoind. The blockchain is entirely local to the machine runningbitcoind
. No initial block sync is required in order to set up. ('reg' in 'regtest' stands for 'regression' as in 'regression testing'). Every time you start up a new regtest version of bitcoind is identical. This is the mode that we'll be running bitcoind in for the examples in this book.
* Note that it's possible to use less memory, but operating your node in a 'pruned' state. Running a pruned bitcoin client is out of the scope of this document.
Bitcoind stores all of the data required for it to operate in a directory, called the datadir. By default, it's .bitcoin
and located in your home directory. On my Ubuntu machine this is ~/.bitcoin
. (MacOS and Windows machines will have a different filepath). This is where the blockchain data is stored, logs, mempool data, wallets, fee estimates, peers, etc. It's all here.
Bitcoind* should come with two programs, the bitcoin node software (bitcoind) and an RPC client that allows you to interact with the node (bitcoin-cli).
* The 'd' part of Bitcoind stands for 'daemon'. Traditionally, daemons are programs that run in background processes of your machine.
Both of these programs have options that you can configure. For bitcoind, place configuration options in the datadir in a file called bitcoin.conf
. To see a list of all of the options that are possible, run bitcoind --help
. bitcoin-cli
also has a list of options available. Similarly, you can list them with bitcoin-cli --help
.
There are two ways to pass options to bitcoind. You can either places them in a configuration file (the default location for this is in a file called bitcoin.conf
in the .bitcoin
directory) or pass them via the command line when you start the program.
Note: bitcoin-cli by default uses the same config file as bitcoind. If you set up the config file as listed below, you won't need to use the -regtest flag when making bitcoin-cli calls.
For the exercises in this book, we're going to configure bitcoind to run as a daemon (which means in the background) and in regtest mode. Here's a ~/.bitcoin/bitcoin.conf
file with 'daemon' and 'regtest' options:
daemon=1
regtest=1
fallbackfee=0.00001
The place to put your bitcoin.conf file on a MacOSX is /Users/<username>/Library/Application Support/Bitcoin/bitcoin.conf
. It's very likely this file won't exist yet. You should create it.
If you're running this on Windows, you'd want to leave the daemon
option off. Your bitcoin.conf will look like:
regtest=1
fallbackfee=0.00001
Your data directory will probably be C:\Users\<username>\AppData\Roaming\Bitcoin
. Create a file called bitcoin.conf
in this directory. (So C:\Users\<username>\AppData\Roaming\Bitcoin\bitcoin.conf
). Then you can start the bitcoind daemon and any configurations in this file should be applied.
Note that it's very likely the bitcoin.conf
file doesn't exist yet. You should create it.
The easiest way to find the data directory is to run bitcoind -regtest
, then
$ bitcoin-cli -regtest getrpcinfo
You can start bitcoind then, like so:
$ bitcoind
> Bitcoin server starting
Alternatively, here's how to start bitcoind with these options turned on, without setting up a config file.
$ bitcoind -daemon -regtest -fallbackfee=0.00001
> Bitcoin server starting
Once bitcoind
is running, we can use bitcoin-cli
to interact with it. We can verify that bitcoind is up and working and that bitcoin-cli
is talking to it correctly by the following command (again, if you've set up the config file, like above, you can omit the -regtest
). For the rest of the examples in this book, we assume that you've configured bitcoind and bitcoin-cli using the config file shown previously.
$ bitcoin-cli -regtest help
> ... lists all of the commands
If you get the following error, make sure that bitcoind is running and is configured to run in regtest mode.
$ bitcoin-cli -regtest help
> error: Could not connect to the server 127.0.0.1:18443
>
> Make sure the bitcoind server is running and that you are connecting to the correct RPC port.
For Mac setup, I also found this resource really valuable (step-by-step video walkthrough of setting up a pruned node from the pre-built version): https://bitcoin.org/en/full-node#setup-a-full-node