What is the Reference Implementation of Bitcoin Core?

Downloading the Reference Client Bitcoin Core

You can download the Reference Client Bitcoin Core, also known as the “Satoshi client,” from bitcoin.org. The reference client implements all aspects of the bitcoin system, including wallets, a transaction verification engine with a full copy of the entire transaction ledger (blockchain), and a full network node in the peer-to-peer bitcoin network. Go to http://bitcoin.org/en/choose-your-wallet and select “Bitcoin Core” to download the reference client. Depending on your operating system, you will download an executable installer. For Windows, this is either a ZIP archive or an EXE executable. For Mac OS it is a DMG disk image. Linux versions include a PPA package for Ubuntu or a TAR.GZ archive.

Running Bitcoin Core for the First Time

If you download an installable package, such as an EXE, DMG, or PPA, you can install it the same way as any application on your operating system. For Windows, run the EXE and follow the step-by-step instructions. For Mac OS, launch the DMG and drag the Bitcoin-QT icon into your Applications folder. For Ubuntu, double-click on the PPA in your File Explorer and it will open the package manager to install the package. Once you have completed the installation, you should have a new application called “Bitcoin-Qt” in your application list. Double-click on the icon to start the bitcoin client.

Synchronizing Bitcoin Core

The first time you run Bitcoin Core, it will start downloading the blockchain, a process that may take several days. Leave it running in the background until it displays “Synchronized” and no longer shows “Out of sync” next to the balance.

Bitcoin Core keeps a full copy of the transaction ledger (blockchain), with every transaction that has ever occurred on the bitcoin network since its inception in 2009. This dataset is several gigabytes in size (approximately 16GB in late 2013) and is downloaded incrementally over several days. The client will not be able to process transactions or update account balances until the full blockchain dataset is downloaded. During that time, the client will display “Out of sync” next to the account balances and show “Synchronizing” in the footer. Make sure you have enough disk space, bandwidth, and time to complete the initial synchronization.

Compiling Bitcoin Core from the Source Code

For developers, there is also the option to download the full source code as a ZIP archive or by cloning the authoritative source repository from Github. Go to https://github.com/bitcoin/bitcoin and select “Download ZIP” from the sidebar. Alternatively, use the git command line to create a local copy of the source code on your system. In the example below, we are cloning the source code from a unix-like command-line in Linux or Mac OS:

$ git clone https://github.com/bitcoin/bitcoin.git
Cloning into 'bitcoin'…
remote: Counting objects: 31864, done.
remote: Compressing objects: 100% (12007/12007), done.
remote: Total 31864 (delta 24480), reused 26530 (delta 19621)
Receiving objects: 100% (31864/31864), 18.47 MiB | 119 KiB/s, done.
Resolving deltas: 100% (24480/24480), done.
$

When the git cloning operation has completed, you will have a complete local copy of the source code repository in the directory bitcoin. Change to this directory by typing:

$ cd bitcoin

Checking Out a Specific Version of Bitcoin

By default, the local copy will be synchronized with the most recent code, which may be an unstable or “beta” version of bitcoin. Before compiling the code, we want to select a specific version by checking out a release tag. This will synchronize the local copy with a specific snapshot of the code repository identified by a keyword tag. Tags are used by the developers to mark specific releases of the code by version number. To find the available tags, we use the git tag command:

$ git tag
v0.1.5
v0.1.6test1
v0.2.0
v0.2.10
v0.2.11
v0.2.12
[… many more tags …]
v0.8.4rc2
v0.8.5
v0.8.6
v0.8.6rc1
v0.9.0rc1

The list of tags shows all the released versions of bitcoin. By convention, release candidates, which are intended for testing, have the suffix “rc”. Stable releases that can be run on production systems have no suffix. From the list above, we select the highest version release, which at this time is v0.9.0rc1. To synchronize the local code with this version, we use the git checkout command:

$ git checkout v0.9.0rc1
Note: checking out 'v0.9.0rc1'.
HEAD is now at 15ec451… Merge pull request #3605
$

Reviewing the Documentation

The source code includes documentation, which can be found in a number of files. Review the main documentation located in README.md in the bitcoin directory by typing:

$ more README.md

In this chapter, we will build the command-line bitcoin client, also known as bitcoind on Linux. Review the instructions for compiling the bitcoind command-line client on your platform by typing:

$ more doc/build-unix.md

Alternative instructions for Mac OSX and Windows can be found in the doc directory, as build-os.md or buildmsw.md respectively.

Building Bitcoin Core

Carefully review the build pre-requisites in the first part of the build documentation. These are libraries that must be present on your system before you can begin to compile bitcoin. If these pre-requisites are missing, the build process will fail with an error. If this happens because you missed a pre-requisite, you can install it and then resume the build process from where you left off. Assuming the pre-requisites are installed, we start the build process by generating a set of build scripts using the autogen.sh script.

The Bitcoin Core build process was changed to use the autogen/configure/make system starting with version 0.9. Older versions use a simple Makefile and work slightly differently. Follow the instructions for the version you want to compile.

$ ./autogen.sh

This script creates a set of automatic configuration scripts that 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. Type:

$ ./configure --help

Next, run the configure script to automatically discover all the necessary libraries and create a customized build script for your system.

$ ./configure
config.status: creating src/bitcoin-config.h
config.status: executing depfiles commands
$

If all goes well, the configure command will end by creating the customized build scripts that will allow us to compile bitcoind.

Compiling the Code

Next, we will compile the source code, which may take up to an hour to complete. Type:

$ make

If all goes well, bitcoind is now compiled. The final step is to install the bitcoind executable into the system path using:

$ sudo make install

Confirming Installation

We can confirm that bitcoin is correctly installed by asking the system for the path of the two executables:

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

Running Bitcoin Core for the First Time

When we first run bitcoind, it will remind us to create a configuration file with a strong password for the JSON-RPC interface. We run it by typing:

$ bitcoind

Edit the configuration file in your preferred editor and set the parameters, replacing the password with a strong password as recommended by bitcoind. Create a file inside the .bitcoin directory and enter a username and password.

Now, run the Bitcoin Core client. The first time you run it, it will rebuild the bitcoin blockchain by downloading all the blocks. This is a multi-gigabyte file and will take, on average, two days to download in full. You can shorten the blockchain initialization time by downloading a partial copy of the blockchain using a bittorrent client.

Blocks in Mining

Run bitcoind in the background with the option:

$ bitcoind -daemon