Bitcoin Core: The Reference Implementation and Developer Guide

Bitcoin is an open-source project, released under the MIT license, meaning its source code is freely available for download and use. Beyond free access, this openness signifies that Bitcoin is developed by a community of open-source volunteers. Initially, this community consisted only of Satoshi Nakamoto. By 2016, the Bitcoin source code had over 400 contributors, with roughly a dozen developers working nearly full-time and dozens more contributing part-time. Anyone can contribute code—including you!

When Satoshi Nakamoto created Bitcoin, the software was actually completed before the publication of the famous whitepaper. Satoshi wanted to ensure it worked before presenting it. That first implementation has been heavily modified and improved, evolving into what is now known as Bitcoin Core, a name that distinguishes it from other compatible implementations. Bitcoin Core is the reference implementation of the Bitcoin system, meaning it serves as the authoritative reference on how every part of the technology should be built. It implements all aspects of Bitcoin, including a wallet, a transaction and block validation engine, and a full network node in the peer-to-peer bitcoin network.

The Bitcoin Development Environment

For developers, setting up a proper development environment is the first step. This environment contains all the necessary tools, libraries, and supporting software for building Bitcoin applications. This section will guide you through the process step-by-step. If you find the technical details overwhelming and don't plan to set up an environment, feel free to skip to the next chapter.

Compiling Bitcoin Core from Source Code

Many examples in this chapter use the operating system's command-line interface (CLI), or "shell," accessed through a terminal application. The shell displays a prompt; you type a command; the shell returns some text and a new prompt. Your prompt may look different, but in our examples, it's represented by a $ symbol. Only type the command that follows the $ symbol, then press Enter to execute it. The lines following each command represent the operating system's response.

We'll use the git command to create a local copy (clone) of the source code repository.

$ git clone https://github.com/bitcoin/bitcoin.git
Cloning into 'bitcoin'...
remote: Counting objects: 102071, done.
remote: Compressing objects: 100% (10/10), done.
Receiving objects: 100% (102071/102071), 86.38 MiB | 730.00 KiB/s, done.
remote: Total 102071 (delta 4), reused 5 (delta 1), pack-reused 102060
Resolving deltas: 100% (76168/76168), done.
Checking connectivity... done.
$

Once the git clone operation completes, you will have a full local copy of the source code repository in a directory called bitcoin. Use the command cd bitcoin to switch into this directory.

Selecting a Bitcoin Core Release

By default, your local copy will be synchronized with the latest code, which might be an unstable or beta version of Bitcoin. Before compiling, select a specific version by checking out a tag. This synchronizes your local copy with a specific snapshot of the code repository identified by a keyword tag. Developers use tags to mark specific releases of code by version number.

First, to find the available tags, use the git tag command:

$ git tag
v0.1.5
v0.1.6test1
v0.10.0
...
v0.11.2
v0.11.2rc1
v0.12.0rc1
v0.12.0rc2
...

The tag list shows all released versions of Bitcoin. By convention, release candidates used for testing have the suffix "rc." Stable releases that can be run on production systems have no suffix. From the list above, select the highest version release; at the time of writing, it was v0.15.0. To synchronize your local code with this version, use the git checkout command:

$ git checkout v0.15.0
HEAD is now at 3751912... Merge #11295: doc: Old fee_estimates.dat are discarded by 0.15.0

You can confirm you have "checked out" the desired version with the git status command:

$ git status
HEAD detached at v0.15.0
nothing to commit, working directory clean

Configuring the Bitcoin Core Build

The source code includes documentation. Type more README.md to view the main README.md file in the bitcoin directory, using the spacebar to scroll. In this chapter, we will build the command-line bitcoin client, also known on Linux as bitcoind.

Type more doc/build-unix.md to view the instructions for compiling bitcoind on your platform. Instructions for macOS and Windows can be found in the doc directory as build-osx.md or build-windows.md, respectively.

Carefully review the prerequisite dependency libraries listed at the beginning of the build documentation, such as boost-devel, libevent-devel, openssl-devel, gcc-c++, libdb4-cxx-devel, autoconf, automake, and libtool. These libraries must be present on your system before you start compiling Bitcoin, or the build process will fail. If the build fails because you missed a dependency, you can install it and then resume the build process from where it stopped.

You can start the build process by using the autogen.sh script to generate a set of build scripts.

$ ./autogen.sh
...
glibtoolize: copying file 'build-aux/m4/libtool.m4'
glibtoolize: copying file 'build-aux/m4/ltoptions.m4'
glibtoolize: copying file 'build-aux/m4/ltsugar.m4'
glibtoolize: copying file 'build-aux/m4/ltversion.m4'
...
configure.ac:10: installing 'build-aux/compile'
configure.ac:5: installing 'build-aux/config.guess'
configure.ac:5: installing 'build-aux/config.sub'
configure.ac:9: installing 'build-aux/install-sh'
configure.ac:9: installing 'build-aux/missing'
Makefile.am: installing 'build-aux/depcomp'
...

The autogen.sh script creates a set of automatic configuration scripts. These will interrogate your system to discover the correct settings and ensure you have all the necessary libraries to compile the code. The most important of these is the configure script, which offers many different options to customize the build process. Type ./configure --help to see the various options.

$ ./configure --help
`configure' configures Bitcoin Core 0.15.0 to adapt to many kinds of systems.
Usage: ./configure [OPTION]... [VAR=VALUE]...
...
Optional Features:
 --disable-option-checking ignore unrecognized --enable/--with options
 --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no)
 --enable-FEATURE[=ARG] include FEATURE [ARG=yes]
 --enable-wallet enable wallet (default is yes)
 --with-gui[=no|qt4|qt5|auto]
...

The configure script allows you to enable or disable certain features of bitcoind using the --enable-FEATURE and --disable-FEATURE flags, where FEATURE is replaced by the feature name listed in the help output.

In this chapter, we will build the bitcoind client with all its default features. We won't use configuration flags, but you should review them to understand what optional features are part of the client. If you are in an academic environment, your lab might require you to install applications into your home directory (e.g., using --prefix=$HOME).

Here are some useful options that override the configure script's default behavior:

• --prefix=$HOME: Overrides the default installation location (/usr/local/) for the generated executables. Use $HOME to put everything in your home directory, or another path.
• --disable-wallet: Disables the reference implementation of the wallet.
• --with-incompatible-bdb: If you are building the wallet, this allows the use of an incompatible version of the Berkeley DB library.
• --with-gui=no: Do not build the graphical user interface, which requires the Qt library. This builds only the server and command-line client.

Next, run the configure script. It will automatically discover all necessary libraries and create a custom build script for your system:

$ ./configure
checking build system type... x86_64-unknown-linux-gnu
checking host system type... x86_64-unknown-linux-gnu
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... /bin/mkdir -p
checking for gawk... gawk
checking whether make sets $(MAKE)... yes
...
[many pages of configuration tests follow]
...
$

If all goes well, the configure command will end by creating the customized build scripts that allow us to compile bitcoind. If there are any missing libraries or errors, the configure command will terminate with an error. If an error occurs, it is most likely due to a missing or incompatible library. Review the build documentation again and ensure you install the missing prerequisites. Then run configure again to see if the error is fixed.

Building the Bitcoin Core Executables

Next, you will compile the source code. This process can take up to an hour to complete, depending on the speed of your CPU and available memory. During the compilation, you should see output every few seconds or minutes. If an error occurs, or the compilation is interrupted, you can resume by typing make again.

Type make to start compiling the executable application:

$ make
Making all in src
 CXX crypto/libbitcoinconsensus_la-hmac_sha512.lo
 CXX crypto/libbitcoinconsensus_la-ripemd160.lo
 CXX crypto/libbitcoinconsensus_la-sha1.lo
 CXX crypto/libbitcoinconsensus_la-sha256.lo
 CXX crypto/libbitcoinconsensus_la-sha512.lo
 CXX libbitcoinconsensus_la-hash.lo
 CXX primitives/libbitcoinconsensus_la-transaction.lo
 CXX libbitcoinconsensus_la-pubkey.lo
 CXX script/libbitcoinconsensus_la-bitcoinconsensus.lo
 CXX script/libbitcoinconsensus_la-interpreter.lo
[... many more compilation messages follow ...]
$

On systems with multiple CPUs, you can set the number of parallel compilation jobs. For example, make -j 2 will use two CPU cores.

If all goes well, Bitcoin Core is now compiled. You should run the unit test suite with make check to ensure the linked libraries don't break anything. The final step is to install the executable on your system using the make install command. You may be prompted for your user password because this step requires administrative privileges:

$ make check && sudo make install
Password:
Making install in src
 ../build-aux/install-sh -c -d '/usr/local/lib'
libtool: install: /usr/bin/install -c bitcoind /usr/local/bin/bitcoind
libtool: install: /usr/bin/install -c bitcoin-cli /usr/local/bin/bitcoin-cli
libtool: install: /usr/bin/install -c bitcoin-tx /usr/local/bin/bitcoin-tx
...
$

By default, bitcoind is installed in /usr/local/bin. You can verify this:

$ which bitcoind
/usr/local/bin/bitcoind
$ which bitcoin-cli
/usr/local/bin/bitcoin-cli

Running a Bitcoin Core Node

Bitcoin's peer-to-peer network consists of network "nodes," run mostly by volunteers and some businesses building Bitcoin applications. Those running Bitcoin nodes have a direct and authoritative view of the Bitcoin blockchain, with a local copy of all transactions, independently verified by their own system. By running a node, you do not have to rely on any third party to validate transactions.

👉 Explore more node configuration strategies

Running a node, however, requires a system with sufficient resources to process all Bitcoin transactions—a permanent, always-connected machine. Depending on whether you choose to index all transactions and keep a full copy of the blockchain, you may also need significant hard disk space and memory. As of early 2018, a fully indexed node required at least 2 GB of RAM and 160 GB of hard drive space. Bitcoin nodes also need network bandwidth to transmit and receive Bitcoin transactions and blocks.

Despite the resource requirements, thousands of volunteers run Bitcoin nodes. Some are on systems as simple as a Raspberry Pi. Many volunteers also run Bitcoin nodes on rented servers, often some variant of Linux. A Virtual Private Server (VPS) or Cloud Computing Server instance can be used to run a Bitcoin node.

Why run a Bitcoin node? Here are a few reasons:

• You are developing Bitcoin software and need to rely on a Bitcoin node for API access to the network and blockchain.
• You are building applications that must validate transactions according to Bitcoin's consensus rules. Bitcoin software companies often run multiple nodes.
• You want to support Bitcoin. Running a node makes the network more robust.
• You do not want to rely on any third party to process or validate your transactions.

If you are interested in developing Bitcoin software, you should run your own node.

Configuring the Bitcoin Core Node

Bitcoin Core looks for a configuration file in its data directory every time it starts. In this section, we will examine the various configuration options. To find the configuration file, run bitcoind -printtoconsole in your terminal and look at the first few lines.

$ bitcoind -printtoconsole
Bitcoin version v0.15.0
Using the 'standard' SHA256 implementation
Using data directory /home/ubuntu/.bitcoin/
Using config file /home/ubuntu/.bitcoin/bitcoin.conf
...
[a lot more debug output]
...

Once you've identified the config file location, you can press Ctrl-C to stop the node. Typically, the configuration file is located in the .bitcoin data directory under your user's home directory. Open the configuration file in an editor.

Bitcoin Core offers more than 100 configuration options that modify the network node's behavior, blockchain storage, and many other aspects. To see a list of these options, run bitcoind --help.

Some of the most important options you can set in the configuration file, or as command-line arguments to bitcoind, include:

• alertnotify: Run a specified command or script to send emergency alerts to the node's owner.
• conf: An alternative location for the configuration file. This only works as a command-line argument for bitcoind.
• datadir: The directory to put all blockchain data.
• prune: Reduce the disk space requirements to this many MB by deleting old blocks. Use this on resource-constrained nodes.
• txindex: Maintain an index of all transactions.
• dbcache: The size of the UTXO cache. The default is 300 MB.
• maxconnections: Set the maximum number of nodes from which connections can be accepted.
• maxmempool: Set the transaction memory pool size to this many MB.
• maxreceivebuffer / maxsendbuffer: Limit per-connection memory buffers to this many thousand bytes (KB).
• minrelaytxfee: Set the minimum fee rate for transactions you are willing to relay.

After editing the configuration file to your needs, you can test it by running bitcoind -printtoconsole. If the configuration is loaded correctly, you can stop the process with Ctrl-C.

To run Bitcoin Core as a background process, use bitcoind -daemon.

To monitor the node's progress and runtime status, use bitcoin-cli getblockchaininfo.

Once you have configured your options, you should add Bitcoin to your operating system's startup scripts so it runs continuously and restarts when the operating system reboots. You can find examples of startup scripts for various operating systems in the contrib/init directory of the Bitcoin source directory.

The Bitcoin Core API

The Bitcoin Core client implements a JSON-RPC interface that can also be accessed using the command-line helper bitcoin-cli. The command line allows us to interactively experiment with the functionality offered through the API. First, invoke the help command to see a list of available Bitcoin RPC commands.

Each command may take a number of arguments. For more detailed help, add the command name after help. For example, to see help for the getblockhash RPC command.

The help message ends with two example RPC calls using bitcoin-cli and the HTTP client curl. These examples demonstrate how to invoke the command. Copy the first example and see the result.

The result is a block hash. This command should return the same result on your system, indicating that your Bitcoin Core node is running, accepting commands, and returning information about block 1000 to you.

In the following sections, we will demonstrate some very useful RPC commands and their expected output.

Getting Status Information on the Bitcoin Core Client

Bitcoin Core provides status reports for different modules through its JSON-RPC interface. The most important commands include getblockchaininfo, getmempoolinfo, getnetworkinfo, and getwalletinfo.

The getblockchaininfo RPC command was introduced earlier. The getnetworkinfo command is used to display basic status information about the Bitcoin network node. Invoke it with bitcoin-cli.

The data is returned in JSON format, which is human-readable and can be processed by any programming language. In this data, we can see the Bitcoin software client version (150000), the Bitcoin protocol version (70015), the current number of connections (8), and various information and settings related to the Bitcoin network and this client.

Examining and Decoding Transactions

Commands: getrawtransaction, decoderawtransaction

The getrawtransaction command returns a serialized transaction in hexadecimal. We can decode it by using it as an argument to the decoderawtransaction command.

The decoded transaction shows all components of this transaction, including its inputs and outputs. We see that the transaction used one input and produced two outputs. The input of this transaction is an output from a previously confirmed transaction. The two outputs correspond to the 15 mBTC payment and the change returned to the sender.

Examining Blocks

Commands: getblock, getblockhash

Examining blocks is similar to examining transactions. We can find a block by its height. Let's use the block height as an argument to the getblockhash command to return the block's hash.

Now that we know which block contains Alice's transaction, we can query the block using the getblock command and passing the block hash.

This block contains 419 transactions. The 64th transaction is Alice's coffee payment. The height field tells us this is the 277,316th block in the blockchain.

Using Bitcoin Core's Programmatic Interface

The bitcoin-cli helper is great for exploring the Bitcoin Core API and testing functions. But the API's important function is programmatic access. In this section, we will demonstrate accessing Bitcoin Core from another program.

Bitcoin Core's API is a JSON-RPC interface. JSON stands for JavaScript Object Notation, and it's a very convenient data format, readable by both humans and programs. RPC stands for Remote Procedure Call, meaning we call a function (a procedure) that is remote (on the Bitcoin Core node) over a network protocol. In this case, the network protocol is HTTP or HTTPS (for encrypted connections).

You can use an HTTP library in your own program to make JSON-RPC calls, similar to the curl example.

However, most programming languages have libraries that "wrap" the Bitcoin Core API, making it much simpler. We'll use the python-bitcoinlib library to simplify API access. You need to have a running Bitcoin Core instance to make JSON-RPC calls.

Alternative Clients, Libraries, and Toolkits

There are many alternative clients, libraries, and toolkits in the Bitcoin ecosystem, including full-node implementations. They are implemented in various programming languages, providing developers with a native interface in their language of choice.

Libraries exist for various languages, and more are being developed all the time. 👉 Get advanced development methods

Frequently Asked Questions

What is Bitcoin Core?
Bitcoin Core is the reference implementation of the Bitcoin protocol. It is open-source software that provides a full node for the Bitcoin network, including a wallet, transaction validation, and blockchain storage. It serves as the authoritative standard for how the Bitcoin system should operate.

Why is running a full node important?
Running a full node provides you with a trustless way to verify transactions and blocks according to Bitcoin's consensus rules. It enhances your privacy and security by eliminating reliance on third-party servers. Furthermore, it strengthens the overall Bitcoin network by increasing its decentralization and resilience.

What are the hardware requirements for running a Bitcoin Core node?
The requirements vary over time as the blockchain grows. You will need a permanent internet connection, sufficient bandwidth, and adequate storage (hundreds of gigabytes). You also need enough RAM (at least 2GB, but more is recommended) and a reasonably modern CPU to handle verification processes efficiently.

What is the difference between bitcoind and bitcoin-cli?
bitcoind is the Bitcoin Core daemon, the core program that runs the node in the background. bitcoin-cli is the command-line interface helper tool used to issue RPC commands to a running bitcoind instance, allowing you to interact with and control the node.

What is JSON-RPC?
JSON-RPC is a lightweight remote procedure call protocol that uses JSON for data formatting. Bitcoin Core's API is a JSON-RPC interface, allowing external programs to send commands over HTTP to query blockchain data, get network information, create transactions, and manage the wallet.

Can I use Bitcoin Core as my everyday wallet?
While Bitcoin Core includes a wallet, it is primarily designed as a full node and its wallet functionality may not be as user-friendly as dedicated wallet applications. For daily use, most users prefer wallets that are designed for simplicity, mobility, and support modern standards like HD wallets and seed phrases. The Bitcoin Core wallet is best suited for developers and advanced users who need direct interaction with a full node.