Bitcoin Core: The Reference Implementation

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 the PPA in your File Explorer and it will open the package manager to install the package. Once you have completed installation you should have a new application called Bitcoin-Qt in your application list. Double-click the icon to start the bitcoin client.

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

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. On the GitHub bitcoin page, 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 following example, we are cloning the source code from a Unix-like command line, in Linux or Mac OS:

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 at the prompt:

By default, the local copy will be synchronized with the most recent code, which might be an unstable or beta version of bitcoin. Before compiling the code, 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. First, to find the available tags, we use the command:

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 preceding list, select the highest version release, which at this writing was vrc1. To synchronize the local code with this version, use the command:

The source code includes documentation, which can be found in a number of files. Review the main documentation located in conwaytransport.com.au in the bitcoin directory by typing at the prompt and using the space bar to progress to the next page. In this chapter, we will build the command-line bitcoin client, also known as on Linux. Review the instructions for compiling the bitcoind command-line client on your platform by typing . Alternative instructions for Mac OS X and Windows can be found in the doc directory, as conwaytransport.com.au or conwaytransport.com.au, respectively.

Carefully review the build prerequisites, which are 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 prerequisites are missing, the build process will fail with an error. If this happens because you missed a prerequisite, you can install it and then resume the build process from where you left off. Assuming the prerequisites are installed, you start the build process by generating a set of build scripts using the conwaytransport.com.au script.

The conwaytransport.com.au 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 script that offers a number of different options to customize the build process. Type to see the various options:

The script allows you to enable or disable certain features of bitcoind through the use of the and flags, where is replaced by the feature name, as listed in the help output. In this chapter, we will build the bitcoind client with all the default features. We won’t be using the configuration flags, but you should review them to understand what optional features are part of the client. Next, run the script to automatically discover all the necessary libraries and create a customized build script for your system:

If all goes well, the command will end by creating the customized build scripts that will allow us to compile bitcoind. If there are any missing libraries or errors, the command will terminate with an error instead of creating the build scripts. If an error occurs, it is most likely because of a missing or incompatible library. Review the build documentation again and make sure you install the missing prerequisites. Then run again and see if that fixes the error. Next, you will compile the source code, a process that can take up to an hour to complete. During the compilation process you should see output every few seconds or every few minutes, or an error if something goes wrong. The compilation process can be resumed at any time if interrupted. Type to start compiling:

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

You can confirm that bitcoin is correctly installed by asking the system for the path of the two executables, as follows:

The default installation of bitcoind puts it in /usr/local/bin. When you first run bitcoind, it will remind you to create a configuration file with a strong password for the JSON-RPC interface. Run bitcoind by typing into the terminal:

Edit the configuration file in your preferred editor and set the parameters, replacing the password with a strong password as recommended by bitcoind. Do not use the password shown here. Create a file inside the .bitcoin directory so that it is named .bitcoin/conwaytransport.com.au and enter a username and password:

While you’re editing this configuration file, you might want to set a few other options, such as (see Transaction Database Index and txindex Option). For a full listing of the available options, type .

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 multigigabyte file and will take an average of 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 from SourceForge.

Run bitcoind in the background with the option :

Using Bitcoin Core’s JSON-RPC API from the Command Line

Commands:

Bitcoin’s RPC command displays basic information about the status of the bitcoin network node, the wallet, and the blockchain database. Use to run it:

The data is returned in JavaScript Object Notation (JSON), a format that can easily be “consumed” by all programming languages but is also quite human-readable. Among this data we see the version numbers for the bitcoin software client (), protocol (), and wallet (). We see the current balance contained in the wallet, which is zero. We see the current block height, showing us how many blocks are known to this client (). We also see various statistics about the bitcoin network and the settings related to this client. We will explore these settings in more detail in the rest of this chapter.

Commands: ,

Before you proceed with creating keys and other commands, you should first encrypt the wallet with a password. For this example, you will use the command with the password “foo”. Obviously, replace “foo” with a strong and complex password!

You can verify the wallet has been encrypted by running again. This time you will notice a new entry called . This is a counter showing how long the wallet decryption password will be stored in memory, keeping the wallet unlocked. At first this will be set to zero, meaning the wallet is locked:

To unlock the wallet, issue the command, which takes two parameters—the password and a number of seconds until the wallet is locked again automatically (a time counter):

You can confirm the wallet is unlocked and see the timeout by running again:

Commands: , ,

Next, we will practice creating a wallet backup file and then restoring the wallet from the backup file. Use the command to back up, providing the filename as the parameter. Here we back up the wallet to the file conwaytransport.com.au:

Now, to restore the backup file, use the command. If your wallet is locked, you will need to unlock it first (see in the preceding section) in order to import the backup file:

The command can be used to dump the wallet into a text file that is human-readable:

Commands: getnewaddress, getreceivedbyaddress, listtransactions, getaddressesbyaccount, getbalance

The bitcoin reference client maintains a pool of addresses, the size of which is displayed by when you use the command . These addresses are generated automatically and can then be used as public receiving addresses or change addresses. To get one of these addresses, use the command:

Now, we can use this address to send a small amount of bitcoin to our bitcoind wallet from an external wallet (assuming you have some bitcoin in an exchange, web wallet, or other bitcoind wallet held elsewhere). For this example, we will send 50 millibits ( bitcoin) to the preceding address.

We can now query the bitcoind client for the amount received by this address, and specify how many confirmations are required before an amount is counted in that balance. For this example, we will specify zero confirmations. A few seconds after sending the bitcoin from another wallet, we will see it reflected in the wallet. We use with the address and the number of confirmations set to zero (0):

If we omit the zero from the end of this command, we will only see the amounts that have at least confirmations, where is the setting for the minimum number of confirmations before a transaction is listed in the balance. The setting is specified in the bitcoind configuration file. Because the transaction sending this bitcoin was only sent in the last few seconds, it has still not confirmed and therefore we will see it list a zero balance:

The transactions received by the entire wallet can also be displayed using the command:

We can list all addresses in the entire wallet using the command:

Finally, the command will show the total balance of the wallet, adding up all transactions confirmed with at least confirmations:

Commands: , ,

We’ll now explore the incoming transaction that was listed previously using the command. We can retrieve a transaction by its transaction hash, shown at earlier, with the command:

The transaction form shown with the command is the simplified form. To retrieve the full transaction code and decode it, we will use two commands: and . First, takes the transaction hash (txid) as a parameter and returns the full transaction as a “raw” hex string, exactly as it exists on the bitcoin network:

To decode this hex string, use the command. Copy and paste the hex as the first parameter of to get the full contents interpreted as a JSON data structure (for formatting reasons the hex string is shortened in the following example):

The transaction decode shows all the components of this transaction, including the transaction inputs and outputs. In this case we see that the transaction that credited our new address with 50 millibits used one input and generated two outputs. The input to this transaction was the output from a previously confirmed transaction (shown as the vin txid starting with ). The two outputs correspond to the 50 millibit credit and an output with change back to the sender.

We can further explore the blockchain by examining the previous transaction referenced by its txid in this transaction using the same commands (e.g., ). Jumping from transaction to transaction we can follow a chain of transactions back as the coins are transmitted from owner address to owner address.

Once the transaction we received has been confirmed by inclusion in a block, the command will return additional information, showing the block hash (identifier) in which the transaction was included:

Here, we see the new information in the entries (the hash of the block in which the transaction was included), and with value 18 (indicating that our transaction was the 18th transaction in that block).

Commands: ,

Now that we know which block our transaction was included in, we can query that block. We use the command with the block hash as the parameter:

The block contains transactions and as you can see, the 18th transaction listed () is the txid of the one crediting 50 millibits to our address. The entry tells us this is the th block in the blockchain.

We can also retrieve a block by its block height using the command, which takes the block height as the parameter and returns the block hash for that block:

Here, we retrieve the block hash of the “genesis block,” the first block mined by Satoshi Nakamoto, at height zero. Retrieving this block shows:

The , , and commands can be used to explore the blockchain database, programmatically.

Commands: , , , , ,

Bitcoin’s transactions are based on the concept of spending “outputs,” which are the result of previous transactions, to create a transaction chain that transfers ownership from address to address. Our wallet has now received a transaction that assigned one such output to our address. Once this is confirmed, we can spend that output.

First, we use the command to show all the unspent confirmed outputs in our wallet:

We see that the transaction created an output (with vout index 0) assigned to the address for the amount of 50 millibits, which at this point has received seven confirmations. Transactions use previously created outputs as their inputs by referring to them by the previous txid and vout index. We will now create a transaction that will spend the 0th vout of the txid as its input and assign it to a new output that sends value to a new address.

First, let’s look at the specific output in more detail. We use to get the details of this unspent output. Transaction outputs are always referenced by txid and vout, and these are the parameters we pass to :

What we see here is the output that assigned 50 millibits to our address . To spend this output we will create a new transaction. First, let’s make an address to which we will send the money:

We will send 25 millibits to the new address we just created in our wallet. In our new transaction, we will spend the 50 millibit output and send 25 millibits to this new address. Because we have to spend the whole output from the previous transaction, we must also generate some change. We will generate change back to the address, sending the change back to the address from which the value originated. Finally, we will also have to pay a fee for this transaction. To pay the fee, we will reduce the change output by millibits, and return millibits in change. The difference between the sum of the new outputs (25 mBTC + mBTC = mBTC) and the input (50 mBTC) will be collected as a transaction fee by the miners.

We use to create this transaction. As parameters to we provide the transaction input (the 50 millibit unspent output from our confirmed transaction) and the two transaction outputs (money sent to the new address and change sent back to the previous address):

The command produces a raw hex string that encodes the transaction details we supplied. Let’s confirm everything is correct by decoding this raw string using the command:

That looks correct! Our new transaction “consumes” the unspent output from our confirmed transaction and then spends it in two outputs, one for 25 millibits to our new address and one for millibits as change back to the original address. The difference of millibits represents the transaction fee and will be credited to the miner who finds the block that includes our transaction.

As you might notice, the transaction contains an empty because we haven’t signed it yet. Without a signature, this transaction is meaningless; we haven’t yet proven that we own the address from which the unspent output is sourced. By signing, we remove the encumbrance on the output and prove that we own this output and can spend it. We use the command to sign the transaction. It takes the raw transaction hex string as the parameter:

The command returns another hex-encoded raw transaction. We decode it to see what changed, with :

Now, the inputs used in the transaction contain a , which is a digital signature proving ownership of address and removing the encumbrance on the output so that it can be spent. The signature makes this transaction verifiable by any node in the bitcoin network.

Now it’s time to submit the newly created transaction to the network. We do that with the command , which takes the raw hex string produced by . This is the same string we just decoded:

The command returns a transaction hash (txid) as it submits the transaction on the network. We can now query that transaction ID with :

As before, we can also examine this in more detail using the and commands. These commands will return the exact same hex string that we produced and decoded previously just before we sent it on the network.

Alternative Clients, Libraries, and Toolkits

The libbitcoin library is a C++ scalable multithreaded and modular implementation that supports a full-node client and a command-line toolset called sx, which offers many of the same capabilities as the bitcoind client commands we illustrated in this chapter. The sx tools also offer some key management and manipulation tools that are not offered by bitcoind, including type-2 deterministic keys and key mnemonics.

The Python library pycoin, originally written and maintained by Richard Kiss, is a Python-based library that supports manipulation of bitcoin keys and transactions, even supporting the scripting language enough to properly deal with nonstandard transactions.

The pycoin library supports both Python 2 (x) and Python 3 (after ), and comes with some handy command-line utilities, ku and tx. To install pycoin under Python 3 in a virtual environment (venv), use the following:

Here’s a sample Python script to fetch and spend some bitcoin using the pycoin library:

For examples using the command-line utilities ku and tx, see Appendix B.

btcd is a full-node bitcoin implementation written in Go. It currently downloads, validates, and serves the blockchain using the exact rules (including bugs) for block acceptance as the reference implementation, bitcoind. It also properly relays newly mined blocks, maintains a transaction pool, and relays individual transactions that have not yet made it into a block. It ensures that all individual transactions admitted to the pool follow the rules required and also includes the vast majority of the more strict checks that filter transactions based on miner requirements (“standard” transactions).

One key difference between btcd and bitcoind is that btcd does not include wallet functionality, and this was a very intentional design decision. This means you can’t actually make or receive payments directly with btcd. That functionality is provided by the btcwallet and btcgui projects, which are both under active development. Other notable differences between btcd and bitcoind include btcd support for both HTTP POST requests (such as bitcoind) and the preferred Websockets, and the fact that btcd’s RPC connections are TLS-enabled by default.