Igor Bubelov About Blog Notes Photos

Bitcoin Release Unpacked

June 17, 2022

Every Bitcoin release is distributed as a single archive containing a lot of cryptic files. In fact, you rarely need all of them, but it's pretty important to understand the purpose of each and every file in this archive in order to pick the ones you might actually need.

Photo by Pavel Neznanov

Table of Contents

Where to Find the Latest Release

Bitcoin’s source code is currently hosted on GitHub. When Bitcoin devs feel that their code is stable enough to be deployed in production, they tag it as a release and increment its version number. GitHub has a nice interface which allows us to see the latest release tags.

The most recent release is tagged as v23.0, so that’s the latest Bitcoin version and it’s the most sensible thing for us to download.

Building From Source vs Getting Binaries

Since Bitcoin is an open source project, you can fetch its source code and compile it yourself. However, this practice is discouraged because it’s far more complicated compared with getting a pre-compiled package. Some might think that building from source is safer, but it couldn’t be further from the truth. The archive with pre-built binaries is no less secure than the source code itself because it’s protected by a bunch of cryptographic signatures which you can verify if you suspect that your archive might have been tampered with.

Extracting Files From the Archive

Every Bitcoin release has a link to the page where you can download an archive with pre-built binaries. You’ll see a lot of archives there, but you only need the one which is built for your operating system and instruction set architecture. I’m running Linux and I have an AMD CPU, so I need an x86_64-linux-gnu version:

curl --output bitcoin-23.0.tar.gz https://bitcoincore.org/bin/bitcoin-core-23.0/bitcoin-23.0-x86_64-linux-gnu.tar.gz

The name of the archive we just downloaded ends with .tar.gz which is supposed to give as a hint on how to deal with this file. It’s common to assume that archives are always compressed, but you can create an uncompressed archive with a tool like tar. Since the compression is optional, it’s a good practice to append the information about the compression method to the name of your archive. Bitcoin releases are always compressed with gzip, so that’s the reason behind this weird file extension.

Okay, now it’s time to extract all the files from the archive we just downloaded:

tar --extract --file bitcoin-23.0.tar.gz --verbose

You should see the following output:

bitcoin-23.0/
bitcoin-23.0/README.md
bitcoin-23.0/bin/
bitcoin-23.0/bin/bitcoin-cli
bitcoin-23.0/bin/bitcoin-qt
bitcoin-23.0/bin/bitcoin-tx
bitcoin-23.0/bin/bitcoin-util
bitcoin-23.0/bin/bitcoin-wallet
bitcoin-23.0/bin/bitcoind
bitcoin-23.0/bin/test_bitcoin
bitcoin-23.0/include/
bitcoin-23.0/include/bitcoinconsensus.h
bitcoin-23.0/lib/
bitcoin-23.0/lib/libbitcoinconsensus.so
bitcoin-23.0/lib/libbitcoinconsensus.so.0
bitcoin-23.0/lib/libbitcoinconsensus.so.0.0.0
bitcoin-23.0/share/
bitcoin-23.0/share/man/
bitcoin-23.0/share/man/man1/
bitcoin-23.0/share/man/man1/bitcoin-cli.1
bitcoin-23.0/share/man/man1/bitcoin-qt.1
bitcoin-23.0/share/man/man1/bitcoin-tx.1
bitcoin-23.0/share/man/man1/bitcoin-util.1
bitcoin-23.0/share/man/man1/bitcoin-wallet.1
bitcoin-23.0/share/man/man1/bitcoind.1

Wow, that’s a lot of files and dirs. Let’s go through them one by one:

Inspecting /bin Directory

First, let’s check that the /bin directory also exists on our target machine. That’s the path where we’re expected to place our Bitcoin executables.

ls -l /bin
lrwxrwxrwx 1 root root 7 Dec 7 2021 /bin -> usr/bin

In many modern Linux distributions, both /bin and /usr/bin point to the same directory, so /bin is just an alias for /usr/bin. This sounds like the best place to keep your Bitcoin binaries. If you have any doubts, you can always check Filesystem Hierarchy Standard.

But wait, what about this entry?

Locally installed software must be placed within /usr/local rather than /usr unless it is being installed to replace or upgrade software in /usr.

It turns out, the best place to install Bitcoin binaries is /usr/local/bin. Now that we know where to install those binaries, let’s check what they actually do:

File Purpose
bitcoin-cli Command line tool which can talk to a running bitcoind or bitcoin-qt instance.
bitcoin-qt Qt-based GUI with a built-in Bitcoin Core server.
bitcoin-tx A standalone tool which can help you manage raw transactions.
bitcoin-util It can provide functionality that does not rely on the ability to access a running Bitcoin Server. The only available command so far is grind which takes a hex-encoded header and grinds its nonce until its nBits is satisfied.
bitcoin-wallet A standalone tool which is used to manage Bitcoin Core wallet.dat files. Note that Bitcoin Core server (bitcoin-qt or bitcoind) can manage wallets by itself so this tool is completely optional.
bitcoind Bitcoin Core server, without GUI included.
test_bitcoin The binary that implements all of Bitcoin Core’s unit tests. It has been verified to pass all tests when this build of Bitcoin Core was created, but you can always repeat those tests if you feel like it.

Inspecting /include Directory

As usual, it’s always a good idea to check the latest Filesystem Hierarchy Standard.

/usr/include - This is where all of the system’s general-use include files for the C programming language should be placed.

Again, it’s safer to use /usr/local/include instead of /usr/include in order to avoid conflicts with your package manager. We have only a single file to include and here is what it does:

File Purpose
bitcoinconsensus.h C header file for those who want to build software using the libbitcoinconsensus.so library.

Inspecting /lib Directory

/usr/lib includes object files and libraries. On some systems, it may also include internal binaries that are not intended to be executed directly by users or shell scripts.

It looks like /lib follows the same pattern as /bin, and /lib is just an alias for /usr/lib. As usual, it’s better to use /usr/local/lib in order to avoid collisions.

File Purpose
libbitcoinconsensus.so Symlink to libbitcoinconsensus.so.0.0.0
libbitcoinconsensus.so.0 Symlink to libbitcoinconsensus.so.0.0.0
libbitcoinconsensus.so.0.0.0 Shared library that you can link your own software against. It implements the exact same script validation rules as Bitcoin Core does, thus avoiding the need to reimplement consensus logic yourself.

So, this directory contains a single shared library and two symlinks which simply point to its location. This is a standard versioning convention, so it’s better to copy all of those files if you’re planning to use libbitcoinconsensus.

Inspecting /share Directory

The last directory included in our release is /share, so let’s first figure out its purpose.

Any program or package which contains or requires data that doesn’t need to be modified should store that data in /usr/share (or /usr/local/share, if installed locally)

Well, man pages aren’t supposed to be edited, so it would make perfect sense to place them in /usr/local/share directory.

File Purpose
bitcoin-cli.1 man page for bitcoin-cli binary
bitcoin-qt.1 man page for bitcoin-qt binary
bitcoin-tx.1 man page for bitcoin-tx binary
bitcoin-util.1 man page for bitcoin-util binary
bitcoin-wallet.1 man page for bitcoin-wallet binary
bitcoind.1 man page for bitcoind binary

It’s generally a good idea to install manuals for all the tools you’re planning to use because they tend to be quite informative and they don’t need an Internet connection to be accessed.

Conclusion

Bitcoin releases tend to contain a lot of files so it might be hard to understand what’s going on and which files are necessary for your particular use. For a casual desktop user, I’d recommend installing only the following files:

  • /bin/bitcoin-cli
  • /bin/bitcoin-qt
  • /share/man/man1/bitcoin-cli.1
  • /share/man/man1/bitcoin-qt.1

If you don’t have or don’t need a GUI and you want to run a headless node, this set of files might better fit your particular case:

  • /bin/bitcoin-cli
  • /bin/bitcoind
  • /share/man/man1/bitcoin-cli.1
  • /share/man/man1/bitcoind.1