Learn how Bitcoin works by building miniature replica of it.

Digital Cash

An introductory coding class for Bitcoin enthusiasts. Zero experience required.


1. Sign up for Discord to ask questions (TODO)
2. Sign up for [GitHub](https://github.com), the collaboration platform for programmers
3. Sign up for [GitPod](http://gitpod.io), the platform we will use to write and run our programs
4. [Create GitPod Workspace](https://gitpod.io/#https://github.com/justinmoon/exercises)


Learn To Code


In the [last article](https://mooniversity.io/posts/gitian-1) we explored the problem of reproducibility and the Gitian build environment Bitcoin Core uses to achieve it. We encoutered the [gitian.sigs](https://github.com/bitcoin-core/gitian.sigs) git repository, where anyone can upload signed claims about the correct hashs for different releases of the Bitcoin software. In this post you'll learn to verify your own Bitcoin software downloads against `gitian.sigs` and learn to submit your own claims. This is a nice way to get involved in Bitcoin Core development. You help increase overall confidence that the software is being built correctly, and familiarity with the command line is the only prerequisite knowledge.

# Verify Bitcoin Software

As was the case in the [SHA256SUMS.asc post](/posts/verify-core), let's focus on a specific build of Bitcoin Core: `bitcoin-0.20.1-aarch64-linux-gnu.tar.gz`. Instead of comparing the hash of this file against `SHA256SUMS.asc`, let's instead compare against the `.assert` files submitted by [everyone](https://github.com/bitcoin-core/gitian.sigs/tree/master/0.20.1-linux) who executed the `0.20.1` Gitian build targeting Linux. Instead of trusting a website, we trust an army of paranoid independent volunteers. This is the way!

The Gitian build project requires a certain folder structure, let's make a new folder to contain everything. If you follow along to the end, you'll make a pull request to [gitian.sigs](https://github.com/bitcoin-core/gitian.sigs). For this reason, you'll also want to fork [gitian.sigs](https://github.com/bitcoin-core/gitian.sigs).

[Click here](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo) for instructions on how to fork a GitHub repo if you've never done it before.

```bash
$ mkdir gitian-building
$ cd gitian-building
$ git clone <your gitian.sigs fork>
```

Now let's download `bitcoin-0.20.1-aarch64-linux-gnu.tar.gz` from [bitcoincore.org](https://bitcoincore.org) and hash it:

```bash
$ curl -O https://bitcoincore.org/bin/bitcoin-core-0.20.1/bitcoin-0.20.1-aarch64-linux-gnu.tar.gz
$ sha256sum bitcoin-0.20.1-aarch64-linux-gnu.tar.gz
60c93e3462c303eb080be7cf623f1a7684b37fd47a018ad3848bc23e13c84e1c  bitcoin-0.20.1-aarch64-linux-gnu.tar.gz
```

Next we need to choose [one of the Gitian signers for the 0.20.1 release](https://github.com/bitcoin-core/gitian.sigs/tree/master/0.20.1-linux). I'll choose `luke-jr` because his GPG key is [all](http://luke.dashjr.org/myself/luke-jr.asc) [over](http://bitcoinknots.org/luke-jr.asc) the [place](https://bitcoin.org/luke-jr.asc).

[Here's his .assert file for the 0.20.1 release](https://github.com/bitcoin-core/gitian.sigs/blob/master/0.20.1-linux/luke-jr/bitcoin-core-linux-0.20-build.assert). Note that line 4 contains exactly the same hash we produced above. To convince ourselves Luke authored this proof, we need to PGP-verify this `.assert` file:

```bash
# Download Luke's PGP pubkey
$ curl -O https://bitcoin.org/luke-jr.asc

# Import into gpg
$ gpg --import luke-jr.asc

# Signature verification
$ gpg --verify  gitian.sigs/0.20.1-linux/luke-jr/bitcoin-core-linux-0.20-build.assert.sig
gpg: assuming signed data in 'gitian.sigs/0.20.1-linux/luke-jr/bitcoin-core-linux-0.20-build.assert'
gpg: Signature made Sun 02 Aug 2020 11:02:03 AM CDT
gpg:                using RSA key E463A93F5F3117EEDE6C7316BD02942421F4889F
gpg: Good signature from "Luke Dashjr <luke@dashjr.org>" [unknown]
gpg:                 aka "Luke Dashjr <luke-jr@dashjr.org>" [unknown]
gpg:                 aka "Luke Dashjr <luke-jr+git@utopios.org>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: E463 A93F 5F31 17EE DE6C  7316 BD02 9424 21F4 889F
```

The signature is good, but once again we see a warning that Luke's key isn't "trusted" because we haven't marked this pubkey with a high degree of trust.

Before we try to verify the signatures of other Gitian builders, let's compare Luke's `.assert` with [Jon Atack's](https://github.com/bitcoin-core/gitian.sigs/blob/master/0.20.1-linux/jonatack/bitcoin-core-linux-0.20-build.assert). We'll use the Unix `diff` tool, which generates a report of differences between text files:

```bash
$ diff gitian.sigs/0.20.1-linux/luke-jr/bitcoin-core-linux-0.20-build.assert \
       gitian.sigs/0.20.1-linux/jonatack/bitcoin-core-linux-0.20-build.assert
```

[Here's what I get](https://gist.github.com/justinmoon/ad8fd96bc91ec60a381b1fd55945bea0). Lines starting with `<` lines mean `luke-jr` has that line but `jonatack` doesn't, and `>` means the opposite. The string `bitcoin` doesn't appear in the diff, but it is present in all filenames in `out_manifest` and `in_manifest` sections of each `.assert` file. This means there is no disagreement about inputs to the build -- source code or build instructions contained in Gitian descriptor -- or releases output by the build. All differences are in the `base_system` section which contains hashes of dependencies. Apparently this isn't a problem, but it is strange Gitian fails to exactly pin dependencies ...

At this point we could continue doing everything by hand and go searching for Jon Atack's PGP key. But doing so for every builder would be tedious. Luckily, regular Gitian builders add their PGP key fingerprints directly to the Bitcoin Core git repo [here](https://github.com/bitcoin/bitcoin/tree/master/contrib/gitian-keys). Let's follow those instructions to import the PGP public keys for regular Gitian builders:

```bash
$ git clone git@github.com:bitcoin/bitcoin.git
$ pushd bitcoin/contrib/gitian-keys
$ while read fingerprint keyholder_name; do gpg --keyserver hkp://subset.pool.sks-keyservers.net --recv-keys ${fingerprint}; done < ./keys.txt
$ popd
```

`pushd` / `popd` are commands to enter and exit a directory back to where you were before. After this we should have PGP keys for many of the Gitian builders. For instance, we can now verify Jon Atack's `.assert.sig` files from earlier:

```bash
$ gpg --verify gitian.sigs/0.20.1-linux/jonatack/bitcoin-core-linux-0.20-build.assert.sig
...
gpg: Good signature from "Jon Atack <jon@atack.com>" [unknown]
...
```

Gitian's [gverify](/posts/gitian-1#gverify) script we encountered last time can automate this signature verification for us. Recall that `gverify` requires a path to a "Gitian descriptor" file. This is located in the `bitcoin` repo at the git tag `v0.20.1`:

```bash
$ git clone https://github.com/devrandom/gitian-builder.git
$ cd bitcoin
$ git checkout v0.20.1
$ cd ../gitian-builder
$ bin/gverify --destination ../gitian.sigs/ --release 0.20.1-linux ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml
$ cd ..
```

For all signers contained in the `keys.txt` file from earlier you should see `<username>: OK`. For signers who weren't in that file, you should see:

```text
gpg: Can't check signature: No public key
<username>: BAD SIGNATURE
```

Let's look at the [gverify script](https://github.com/devrandom/gitian-builder/blob/47f615778059f1e0e52cf46cc0aba201d0da7899/bin/gverify) to get a better idea what it's doing:

- [Iterates](https://github.com/devrandom/gitian-builder/blob/47f615778059f1e0e52cf46cc0aba201d0da7899/bin/gverify#L98) over folder in ["signer directory"](https://github.com/bitcoin-core/gitian.sigs/tree/master/0.20.1-linux)
- [PGP-verifies each .assert.sig file](https://github.com/devrandom/gitian-builder/blob/47f615778059f1e0e52cf46cc0aba201d0da7899/bin/gverify#L117)
- [Checks if there are any differences](https://github.com/devrandom/gitian-builder/blob/47f615778059f1e0e52cf46cc0aba201d0da7899/bin/gverify#L129) in the `out_manifest`, `release` or `name` fields of the `.assert` file and prints [MISMATCH](https://github.com/devrandom/gitian-builder/blob/47f615778059f1e0e52cf46cc0aba201d0da7899/bin/gverify#L141) if there are and [OK](https://github.com/devrandom/gitian-builder/blob/47f615778059f1e0e52cf46cc0aba201d0da7899/bin/gverify#L166) if there aren't.
- In summary, it checks that important parts of `.assert` files are identical and verifies signature in `.assert.sig`.

# Become A Gitian Builder

You, too, can become a Gitian builder. There are a few quality guides available so I won't write a new one here:

- The official [bitcoin-core/docs](https://github.com/bitcoin-core/docs/blob/master/gitian-building.md) repo has a guide using VirtualBox. It's [labor intensive](https://github.com/bitcoin-core/docs/blob/master/gitian-building/gitian-building-create-vm-debian.md). I tried the Debian guide and it didn't work for me until I switched from Debian 8 to Debian 10.
- [fanquake has a bare-bones guide using Docker](https://github.com/fanquake/core-review/blob/master/gitian-building/README.md), which is less work.
- [Jon Atack maintains an expanded version of fanquake's guide](https://github.com/jonatack/bitcoin-development/blob/master/gitian-building.md) which I found easiest to follow.

I encourage you to try Jon's guide, now!

## Commentary on Jon's Guide

So far with Gitian we've just been building and verifying for Linux to keep things simple. But Bitcoin Core also has MacOS and Windows releases. Both of these platforms have "code signing" systems that require developers to complete a non-PGP proprietary code signing process so that these operating systems will trust their apps. You've likely seen what happens when developers screw this up:

![image](code-signing-warnings.png)

Individual Bitcoin Core developers control the keys for MacOS and Windows code signing. When a new release is tagged in git, they wait for a few people to upload matching builds to `gitian.sigs`. Then they create "detached signatures" [like so](https://github.com/bitcoin-core/bitcoin-detached-sigs/tree/0.21) which Gitian builders can utilize to produce final MacOS and Windows "code signed" releases. For each platform you end up with 5 builds: Linux, unsigned MacOS, code-signed MacOS, unsigned Windows, code-signed Windows. I believe the "unsigned MacOS/Windows" builds are inputs into the "detached signatures" process. Jon Attack's guide builds the unsigned releases [here](https://github.com/jonatack/bitcoin-development/blob/master/gitian-building.md#now-on-to-building-the-unsigned-sigs) and the code-signed releases [here](https://github.com/jonatack/bitcoin-development/blob/master/gitian-building.md#build-signed-sigs)

The MacOS Gitian build requires you extract files from SDKs published by Apple. Jon's guide downloads these extracted files (4th snippet [here](https://github.com/jonatack/bitcoin-development/blob/master/gitian-building.md#initial-setup)). The official guide [shows you how to extract these yourself](https://github.com/bitcoin-core/docs/blob/master/gitian-building.md#macos-code-signing), which is tedious but increases the independence of your Gitian build.

Bitcoin Core has a [gitian-build.py](https://github.com/bitcoin/bitcoin/blob/master/contrib/gitian-build.py) script which can build, sign and make commits to `gitian.sigs` for each of the 5 release targets. You need to copy it to your base folder containing the other repositories and run it so:

```bash
$ cp bitcoin/contrib/gitian-build.py .
$ ./gitian-build.py -b <username> <version, e.g. 0.20.1>
```

This script reduces the typing / copypasta required by Jon's guide, but when it fails you need to run the whole thing over again. Not sure if it helps or hurts.

Lastly, only make PRs to `gitian.sigs` if you have a PGP key you plan to take care of. Provide a way for other developers to download your PGP public key in your PR. For example, [upload it to a key server](https://phar.io/howto/uploading-public-keys.html) and provide the 40-character fingerprint in your PR.

# Conclusion

Now you have the tools to achieve a much higher degree of confidence in the Bitcoin software you use, and help others increase their confidence by contributing to `gitian.sigs`.

One last question: What are you trusting now? Where might the NSA hide their precious chain split bug? Stop and think about this for a moment.

...

Gitian uses Ubuntu to run the actual builds and downloads all dependencies from Ubuntu's package manager. We are trusting Ubuntu and its package ecosystem.

Due to concerns like this, Bitcoin Core is transitioning to a system called [Guix](https://guix.gnu.org) which promises to deterministically build not just Bitcoin Core but the entire toolchain and environment used to build Bitcoin Core.

We'll discuss Guix next time.



In the [last post](https://mooniversity.io/posts/verify-core) we explored the `SHA256SUMS.asc` file that Bitcoin Core distributes alongside each release to help users verify their downloads. But we had a lingering question: Are we sure the hashes contained in that `SHA256SUMS.asc` correspond to the [Bitcoin Core source code](github.com/bitcoin/bitcoin/)?

To facilitate this independent verification Bitcoin Core uses a tool called [Gitian](https://gitian.org/) which allows anyone to build releases of Bitcoin Core and verify the same output. Before exploring how Bitcoin Core uses Gitian to achieve these "reproducible builds", I want to show you a quick example of a trivial C++ project that has reproducibility problems, and then create a reproducible build environment for it using Gitian.

# Example Project

Here's a simple C++ program which prints "Hello, \<time program was built\>!" If you build this project at different times, different timestamps will be embedded in the executable, producing different executables. As we'll see later when we inspect Bitcoin Core's reproducible build system, much of the challenge involves preventing stuff like timestamps from sneaking into the build. Save it as `hello.cpp`:

```cpp
#include <iostream>

int main()
{
    std::cout << "Hello, " << __TIME__ << "!" << std::endl;
    return 0;
}
```

Let's build and run it twice to demonstrate a non-reproducible build (you may need to install GCC):

```bash
$ g++ hello.cpp -o hello
$ ./hello
Hello, 21:20:39!
$ sha256sum hello
481b7cf190e4b3bcf20af857c48f3fb33da7a199d17fd6560f34608a96c1a425  hello

$ g++ hello.cpp -o hello
$ ./hello
Hello, 21:20:47!
$ sha256sum hello
6d978a670cf26a39634b0f284a3ad05266d1ad8a5ee8b83d9469f79985fe77eb  hello
```

Voila! Build this code at different times and you get different outputs.

For the purposes of this extremely convoluted example, let's pretend this timestamp doesn't have any meaning for our program, but that we can't just remove `__TIME__` from the code. How, then, could we make the build reproducible? Well, GCC allows you to override the `__TIME__` macro by setting a `SOURCE_DATE_EPOCH` environment variable. Let's set it to Unix time 0 (midnight 1/1/1970):

```bash
$ SOURCE_DATE_EPOCH=0 g++ hello.cpp -o hello
$ ./hello
Hello, 00:00:00!
```

Now you can build this as many times as you like and you'll get exactly the same output.

One problem here is that different toolchains have different ways of overriding `__TIME__`. GCC uses `SOURCE_DATE_EPOCH`, Clang has `ZERO_AR_DATE` and MSVC has a `/Brepro` linker flag. Things are already getting complicated in our stupid example. Now imagine how it looks for Bitcoin Core, a big project with a handful of dependencies like QT, Boost, BerkeleyDB, LevelDB and SQLite where this kind of stuff might sneak in.

And even if we figured that out, different compilers produce different outputs. When I compile [hello.cpp without \_\_TIME\_\_](https://gist.github.com/justinmoon/87971c191f8d940285eb256dc6de9160) using GCC and Clang (`clang++ simple_hello.cpp -o simple_hello`), I get different files hashes. And the same compiler on a different operating system might give a different output. So it seems best to just use one compiler, one operating system and eliminate the reproducability leaks for it (learn more [here](https://blog.conan.io/2019/09/02/Deterministic-builds-with-C-C++.html)). This is what Gitian does.

# Gitian

Quoting from the [Gitian](https://gitian.org/) website,

> Gitian is a secure source-control oriented software distribution method. This means you can download trusted binaries that are verified by multiple builders.
>
> Gitian uses a deterministic build process to allow multiple builders to create identical binaries. This allows multiple parties to sign the resulting binaries, guaranteeing that the binaries and tool chain were not tampered with and that the same source was used. It removes the build and distribution process as a single point of failure.

You'll notice that almost all the [top committers for Gitian](https://github.com/devrandom/gitian-builder/graphs/contributors) are Bitcoin Core devs. For a few years it was also [used by Tor](https://blog.torproject.org/deterministic-builds-part-one-cyberwar-and-global-compromise).

The first step with Gitian to run the [bin/make-base-vm](https://github.com/devrandom/gitian-builder/blob/master/bin/make-base-vm) Ruby script which builds a Ubuntu VM / container (honestly I still don't understand the difference!) using either LXC, KVM, Vagrant or Docker. This VM is independent of the project you're building.

Once you build a VM, you run [bin/gbuild <path>](https://github.com/devrandom/gitian-builder/blob/master/bin/gbuild) to initiate a build inside the VM. `<path>` is a path to a YAML "gitian descriptor" which specifies what to build and how to build it. For example, [here is Bitcoin Core's Gitian descriptor for Linux builds](https://github.com/bitcoin/bitcoin/blob/master/contrib/gitian-descriptors/gitian-linux.yml). This command should output final builds that are distributed to users.

Once the build completes, you can run [bin/gsign](https://github.com/devrandom/gitian-builder/blob/master/bin/gsign) script which creates a `.assert` file describing the hashes of all dependencies and outputs from the build as well as a `.assert.sig` containing your PGP signature of that `.assert` file. For example, here are Luke Jr's [.assert](https://github.com/bitcoin-core/gitian.sigs/blob/master/0.10.0-linux/luke-jr/bitcoin-linux-0.10-build.assert) and [.assert.sig](https://github.com/bitcoin-core/gitian.sigs/blob/master/0.10.0-linux/luke-jr/bitcoin-linux-0.10-build.assert.sig) files for the 0.10 Linux release. Together these two files are a cryptographic proof that a certain output is produced when building a release of your project. He's claiming "The hash of `bitcoin-0.10.0-linux64.tar.gz` is `4be12ac4e1a2e1a27135009eb3dc003529f9e56c11df97e59c5b0415f79ed4ec`".

Lastly, there is a [bin/gverify](https://github.com/devrandom/gitian-builder/blob/master/bin/gverify) command which can PGP-verify pairs of `.assert` and `.assert.sig` files. Using this tool you are able to verify that a group of independent developers all agree what the build should output.

In Bitcoin's case this process unfolds in the [bitcoin-core/gitian.sigs](https://github.com/bitcoin-core/gitian.sigs) Git reposotory. When it's time for a new release, developers upload `.assert` and `.assert.sig` files for it. Once a handful of developers assert the same hashes, `SHA256SUMS.asc` is created. In fact, you can skip `SHA256SUMS.asc` altogether when installing Bitcoin Core and directly verify the `.assert` and `.assert.sig` files in found in this repository. [Luke Jr published detailed instructions](https://medium.com/@lukedashjr/how-to-securely-install-bitcoin-9bfeca7d3b2a).

# Building Example Project Inside Gitian

Now that we've covered the concepts, let's build our example project inside Gitian. In order to get started make sure you have [Docker](https://docs.docker.com/get-docker/), Ruby and Git installed.

For simplicity sake, let's clone `gitian-builder` alongside our `hello.cpp` file:

```bash
$ git clone https://github.com/devrandom/gitian-builder.git
```

## `make-base-vm`

Now let's construct a build environment inside Docker:

```bash
# no docker images exist
$ docker image ls
REPOSITORY    TAG       IMAGE ID       CREATED         SIZE

$ gitian-builder/bin/make-base-vm --suite bionic --arch amd64 --docker
...

# docker image created
$ docker image ls
REPOSITORY          TAG       IMAGE ID       CREATED         SIZE
base-bionic-amd64   latest    45d3b1e23d01   9 seconds ago   1.01GB
```

## `gbuild`

In order to run `bin/gbuild` we need a "gitian descriptor". Save the following as `gitian-linux.yml`:

```bash
---
name: "hello-linux"
enable_cache: true
distro: "ubuntu"
suites:
- "bionic"
architectures:
- "amd64"
packages:
- "gcc"
remotes:
- "url": "https://github.com/mooniversity/gitian-example.git"
  "dir": "gitian-example"
  "commit": "1875b8dcdeae3f755ae9d9bf779142c42e792589"
files: []
script: |
  cd gitian-example
  export SOURCE_DATE_EPOCH=0
  g++ hello.cpp -o hello
  mv hello $OUTDIR
```

Notes:
- `enable_cache` will save some state to our filesystem to speed up builds.
- `architecture` and `suites` say we only build on the `amd64` architecture using Ubuntu 18 *Bionic* Beaver OS.
- `packages` will be `apt-get install`ed inside the container.
- `remotes` will checkout and build [this Git repo](https://github.com/mooniversity/gitian-example) at [this commit](https://github.com/mooniversity/gitian-example/commit/1875b8dcdeae3f755ae9d9bf779142c42e792589). Cloning a Git repo at a specific commit is how you know exactly what code we're building.
- `script` contains commands to build the code. This is where we drop our `SOURCE_DATE_EPOCH` hack. `mv hello $OUTDIR` will fish the final build out from Docker and onto our filesystem.

Let's run it. From the `gitian-builder` directory we set a `USE_DOCKER=1` environment variable to tell Gitian we want to use Docker and run `bin/gbuild` with a path to our descriptor file:

```bash
$ cd gitian-builder
$ USE_DOCKER=1 bin/gbuild ../gitian-linux.yml
$ ./build/out/hello
Hello, 00:00:00!
```

Notes:
- Our output shows up at `build/out/hello`.
- A build cache is saved to `cache/` because of the `enable_cache` setting in the descriptor. It's actually empty for our tiny project!
- Installation and build logs can be found in `var/install.log` and `var/build.log`. Helpful for debugging!

## `gsign`

Now PGP sign them (this requires a PGP key, instructions to create one [here](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-gpg-key)):

```bash
$ bin/gsign --signer <your-github-username> --release 0.1-linux --destination ../sigs ../gitian-linux.yml
$ ls ../sigs/0.1-linux/<your-github-username>/
hello-linux-build.assert  hello-linux-build.assert.sig
```

Notes:
- `gsign` requires a username (`gitian.sigs` uses GitHub handles), a release name, a destination to save `.assert` and `.assert.sig` files plus a path to our Gitian descriptor.
- The assert files are saved in `<destination>/<release>/<your-github-username>`. This is the file structure of the [gitian.sigs](https://github.com/bitcoin-core/gitian.sigs) Bitcoin Core repo mentioned earlier. This is why you need to specify a username -- your assert files are saved to their own directory.

[Here is my .assert file](https://github.com/mooniversity/gitian-example/blob/master/sigs/0.1-linux/justinmoon/hello-linux-build.assert). `out_manifest` contains hashes for each output file -- just `hello` in our case. `in_manifest` contains a hash of our descriptor and commit hash for our Git repository. `base_manifests` contains hashes for all dependencies on the OS / architecture pair our example is built on: Ubuntu 18 *Bionic* Beaver and `amd64`.

## `gverify`

Now use `gverify` to your signature.

```bash
$ bin/gverify -v --release 0.1-linux --destination ../sigs ../gitian-linux.yml
gpg: Signature made Sun 27 Dec 2020 07:46:20 PM CST
gpg:                using RSA key 2066733A74BD6A6C0489E2BE5E35A85919DD0D22
gpg:                issuer "mail@justinmoon.com"
gpg: Good signature from "Justin Moon <mail@justinmoon.com>" [ultimate]
justinmoon: OK
```

I admit this is a little anticlimactic. If you can't PGP verify your own signature you have big problems! But it will get more exciting in the next post when we run it in `gitian.sigs` to verify that an army of independent developers reproducibly build Bitcoin Core.




When you visit [bitcoincore.org](https://bitcoincore.org/en/download) to download the Bitcoin software, you're greeted with a page like this.

<img src="/download-bitcoin-core.jpeg" width="50%"></img>

If you're like me, you smash the blue "Download" button, say a prayer to the Virgin Mary, and hope your bitcoins don't disappear!

But there's a better way. That "Verify release signature" link is front-and-center for a reason. It helps you prove to yourself that you downloaded the real Bitcoin software. Let's go over how this works so you can more confidently use Bitcoin in the future.

## SHA256SUMS.asc

When you click that "Verify release signature" link it will download a SHA256SUMS.asc file like the one below. (Note: In future this exact file will remain available [here](https://bitcoincore.org/bin/bitcoin-core-0.20.1/). You can also try this tutorial with future releases of Bitcoin Core, but the hashes and filenames will be different.).


```bash
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

60c93e3462c303eb080be7cf623f1a7684b37fd47a018ad3848bc23e13c84e1c  bitcoin-0.20.1-aarch64-linux-gnu.tar.gz
55b577e0fb306fb429d4be6c9316607753e8543e5946b542d75d876a2f08654c  bitcoin-0.20.1-arm-linux-gnueabihf.tar.gz
b9024dde373ea7dad707363e07ec7e265383204127539ae0c234bff3a61da0d1  bitcoin-0.20.1-osx64.tar.gz
c378d4e21109f09e8829f3591e015c66632dff2925a60b64d259be05a334c30b  bitcoin-0.20.1-osx.dmg
fa71cb52ee5e0459cbf5248cdec72df27995840c796f58b304607a1ed4c165af  bitcoin-0.20.1-riscv64-linux-gnu.tar.gz
4bbd62fd6acfa5e9864ebf37a24a04bc2dcfe3e3222f056056288d854c53b978  bitcoin-0.20.1.tar.gz
930b96e774f5fe4795b9a3c0d4fd1da278d2b0777c9401dea3ba7453f8bbe14c  bitcoin-0.20.1-win64-setup.exe
e59fba67afce011d32b5d723a3a0be12da1b8a34f5d7966e504520c48d64716d  bitcoin-0.20.1-win64.zip
376194f06596ecfa40331167c39bc70c355f960280bd2a645fdbf18f66527397  bitcoin-0.20.1-x86_64-linux-gnu.tar.gz
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)gg

iQIcBAEBCAAGBQJfJU5lAAoJEJDIAZ42wulkAbAP/1pyFrxMrUFlNJdA8yCr0Dj5
5FBBGzFhVrAU+ouiJrPOf/X1HSM8haZ2TSsdI7Mg+S9wbMfFPBmeTIZNtdPkrEfB
YWEWqkhYZZoSGxaOwQVyQmBTLyvlZcLM0Tuz5cVTcJ4ttFnrZBAcr251MVYRbJWx
RxVb67GBgO7OOmxTfRIrgKLHAZo7zTdpPrSMhHEfcarf0A1r4xwUJCtNFRtBUQXi
uacUessZCeZ3x+qoqRHdoeVJDXzshFzqVx7jLMMTKUgQ7HBiH+sWOwZi8VFeCI8u
XgzPW6lv5Y1F5gOjfbHq+N+PggOBBukIKTHx9m6y60RSRXB08DwDnAldK900L+LD
8QUBNxzbCIKx65W80Nhb1GZxIWm89byvb1BR8LCk/P+8MBppp8x9zWfAdtOmnFXG
pl34Q0en8dZvd+0tpNmEKcNHNVzVCF1hFmf9PPS6DW/AzFzYjVggsB1LKLbThjts
XtdB5wcCEbFWSFsH3th/j7+gA1UkE6gnxq2lZdNQMV99KDZf6oP+XykKeq7xFIWG
y2omYiRiFw9UkiUDNIhrE2wHA+VDCsOUwo2HM0dGJ/ZegdqLO5YjNP0nOi3Q9JP5
TeQF/DvkVTnU/ex0URkbkYY6SDod0f1KasFm1Ft3ygL9FXDncgYycYvAn7T7M3Wv
QSEtaREvgcH90iLyHl90
=szhI
-----END PGP SIGNATURE-----
```

This is a [PGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy)-signed message. There are two parts:
- The text between `-----BEGIN PGP SIGNED MESSAGE-----` and `-----BEGIN PGP SIGNATURE-----` is the message.
- The text between `-----BEGIN PGP SIGNATURE-----` and `-----END PGP SIGNATURE-----` is a PGP signature of that message. 

The message declares the correct SHA-256 hashes for different releases of the Bitcoin Core software. In order to use this file to verify our Bitcoin Core download, we must check 2 things: that we get the same value when we hash our download of the Bitcoin software, and that the PGP signature is valid. Let's start with the PGP signature.

## Verify PGP Signature

Let's verify the signature inside SHA256SUM.asc:

```bash
$ gpg --verify SHA256SUMS.asc 
gpg: Signature made Sat 01 Aug 2020 06:13:41 AM CDT
gpg:                using RSA key 90C8019E36C2E964
gpg: Can't check signature: No public key
```

Interesting. PGP can't verify this signature because it doesn't have the public key. But it knows which PGP key it doesn't have: `90C8019E36C2E964`. This is a PGP "key ID" which is one way PGP public keys are identified. One of these key ID's is embedded in the signature we're dealing with.  

The downloads page on [bitcoincore.org](https://bitcoincore.org/en/downloads) tells us which key is used for this signature and how to obtain it: `01EA5486DE18A882D4C2684590C8019E36C2E964`. Notice anything about it?

It ends with `90C8019E36C2E964`, our PGP key ID! Let's download the full public key using the fingerprint from bitcoincore.org:

```bash
$ gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys 01EA5486DE18A882D4C2684590C8019E36C2E964
gpg: key 90C8019E36C2E964: public key "Wladimir J. van der Laan (Bitcoin Core binary release signing key) <laanwj@gmail.com>" imported
gpg: Total number processed: 1
gpg:               imported: 1
```

Looking good. We once again see our key id, and the description of the key "Wladimir J. van der Laan (Bitcoin Core binary release signing key) <laanwj@gmail.com>" sounds like what we're looking for.

Now that we have the public key, let's try to verify the signature again:

```bash
$ gpg --verify SHA256SUMS.asc 
gpg: Signature made Sat 01 Aug 2020 06:13:41 AM CDT
gpg:                using RSA key 90C8019E36C2E964
gpg: Good signature from "Wladimir J. van der Laan (Bitcoin Core binary release signing key) <laanwj@gmail.com>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 01EA 5486 DE18 A882 D4C2  6845 90C8 019E 36C2 E964
```

A few notes:
- "Good signature" means the signature was cryptographically valid
- "WARNING: This key is not certified with a trusted signature!" means that PGP doesn't place a high degree of trust in the public key we just downloaded from the internet. If you really wanted to trust this key, it would be ideal to meet Wladimir at a bitcoin conference and ask for it in person. Or maybe ask a few friends for it and make sure everyone gives you the same key. PGP has commands to mark such public keys with greater trust. We can ignore this message for now.

## Verify File Hash

Now that we're reasonably convinced the Bitcoin Core release signing key signed that list of hashes, let's download a release of the Bitcoin software, hash it, and see if we get a match.

The first line in the PGP message asserts that when you SHA-256 hash `bitcoin-0.20.1-aarch64-linux-gnu.tar.gz` you will get `60c93e3462c303eb080be7cf623f1a7684b37fd47a018ad3848bc23e13c84e1c`. Let's verify this. You can download the file [here](https://bitcoincore.org/bin/bitcoin-core-0.20.1/). These instructions should work on Linux and MacOS:

```bash
# download the file
$ curl -O https://bitcoincore.org/bin/bitcoin-core-0.20.1/bitcoin-0.20.1-aarch64-linux-gnu.tar.gz

# the file is present
$ ls 
bitcoin-0.20.1-aarch64-linux-gnu.tar.gz

# hash the file, and the hash looks similar
# on MacOS use `shasum -a 256` instead of `sha256sum`
$ sha256sum bitcoin-0.20.1-aarch64-linux-gnu.tar.gz
60c93e3462c303eb080be7cf623f1a7684b37fd47a018ad3848bc23e13c84e1c  bitcoin-0.20.1-aarch64-linux-gnu.tar.gz

# better than visual inspections, sha256sum has a --check flag that 
# will look for every file in the list, hash it and compare.
# --ignore-missing only checks files that are present in current directory 
$ sha256sum --ignore-missing --check SHA256SUMS.asc
bitcoin-0.20.1-aarch64-linux-gnu.tar.gz: OK
sha256sum: WARNING: 20 lines are improperly formatted
```

We're now convinced that Wladimir signed the PGP message and that the copy of the Bitcoin software we downloaded is *exactly* the same as the one he released -- because they hash to the same value. You should be able to use this and future releases with greater confidence.

But one question remains. Why does Wladimir get to choose the hashes? Are we placing an unreasonable amount of trust in one person? In the next post I'll explain how Bitcoin Core developers use a system called Gitian to enable anyone to independently build these releases and arrive at consensus on the correct hashes before the software is ever released. Wladimir's signature reflects this consensus, not his personal opinion.



To build Bitcoin Core on Unix systems (Linux or MacOS) [the docs tell you to do the following](https://github.com/bitcoin/bitcoin/blob/f1dbf92ff0475a01d20170ea422c1d086acbbc57/doc/build-unix.md#to-build). Let's try to figure out what these actually do:

```bash
./autogen.sh
./configure
make
make install # optional
```

In order the steps seems to do the following:

- Execute a shell script
- Execute a shell script
- Build executables using [Make](<https://en.wikipedia.org/wiki/Make_(software)>)
- Optionally, install executables using [Make](<https://en.wikipedia.org/wiki/Make_(software)>)

So far so good. After visiting the Bitcoin Core GitHub repository, we find [autogen.sh](https://github.com/bitcoin/bitcoin/blob/master/autogen.sh). It seems to do some setup and then executes `autoreconf --install --force --warnings=all`. Before investigating this command further, let's check out the next script script we execute, `configure`.

Hmmmm ... this script isn't in the [Bitcoin Core source code](https://github.com/bitcoin/bitcoin). In fact, it's in the [.gitignore](https://github.com/bitcoin/bitcoin/blob/f1dbf92ff0475a01d20170ea422c1d086acbbc57/.gitignore#L37) file. This usually means it's a file the user is responsible for generating and different users on different systems might generate different files -- so it can't be checked into the source code. Where does this file come from? Note there is a similarly-named [configure.ac](https://github.com/bitcoin/bitcoin/blob/f1dbf92ff0475a01d20170ea422c1d086acbbc57/configure.ac) script. Perhaps it has something to do with the `autoreconf` we saw above? This is mystery #1.

The third step is `make`. If you've never used `make` before, [check out this 2 minute tutorial](https://www.youtube.com/watch?v=a8mPKBxQ9No). Briefly, `make` is a system for building code. You write a `Makefile` containing shell commands necessary and configuration variables to builds your code. It locates all the dependencies on your system, compile your code, and output a final executable. For example, [here's the Makefile for the Linux project](https://github.com/torvalds/linux/blob/master/Makefile). Once again, the Bitcoin Core git repository doesn't have a `Makefile`, but there is a similarly-named [Makefile.am](https://github.com/bitcoin/bitcoin/blob/f1dbf92ff0475a01d20170ea422c1d086acbbc57/Makefile.am) file. This is mystery #2.

### 🕵️ Mystery #1: Case of the Missing `configure`

Let's run the first command:

```bash
$ ./autogen.sh
libtoolize: putting auxiliary files in AC_CONFIG_AUX_DIR, 'build-aux'.
libtoolize: copying file 'build-aux/ltmain.sh'
libtoolize: putting macros in AC_CONFIG_MACRO_DIRS, 'build-aux/m4'.
libtoolize: copying file 'build-aux/m4/libtool.m4'
libtoolize: copying file 'build-aux/m4/ltoptions.m4'
libtoolize: copying file 'build-aux/m4/ltsugar.m4'
libtoolize: copying file 'build-aux/m4/ltversion.m4'
libtoolize: copying file 'build-aux/m4/lt~obsolete.m4'
configure.ac:45: installing 'build-aux/compile'
configure.ac:28: installing 'build-aux/missing'
Makefile.am: installing 'build-aux/depcomp'
libtoolize: putting auxiliary files in AC_CONFIG_AUX_DIR, 'build-aux'.
libtoolize: copying file 'build-aux/ltmain.sh'
libtoolize: putting macros in AC_CONFIG_MACRO_DIRS, 'build-aux/m4'.
libtoolize: copying file 'build-aux/m4/libtool.m4'
libtoolize: copying file 'build-aux/m4/ltoptions.m4'
libtoolize: copying file 'build-aux/m4/ltsugar.m4'
libtoolize: copying file 'build-aux/m4/ltversion.m4'
libtoolize: copying file 'build-aux/m4/lt~obsolete.m4'
configure.ac:15: installing 'build-aux/compile'
configure.ac:9: installing 'build-aux/missing'
Makefile.am: installing 'build-aux/depcomp'
libtoolize: putting auxiliary files in AC_CONFIG_AUX_DIR, 'build-aux'.
libtoolize: copying file 'build-aux/ltmain.sh'
libtoolize: putting macros in AC_CONFIG_MACRO_DIRS, 'build-aux/m4'.
libtoolize: copying file 'build-aux/m4/libtool.m4'
libtoolize: copying file 'build-aux/m4/ltoptions.m4'
libtoolize: copying file 'build-aux/m4/ltsugar.m4'
libtoolize: copying file 'build-aux/m4/ltversion.m4'
libtoolize: copying file 'build-aux/m4/lt~obsolete.m4'
configure.ac:93: installing 'build-aux/compile'
configure.ac:47: installing 'build-aux/missing'
Makefile.am:335: warning: .INTERMEDIATE was already defined in condition !BUILD_DARWIN, which is included in condition TRUE ...
Makefile.am:139: ... '.INTERMEDIATE' previously defined here
src/Makefile.am: installing 'build-aux/depcomp'
```

If this output looks foreign to you, that makes two of us! But we might recognize a few things: `configure.ac` and `Makefile.am`. As a comment to our blameless beloved Core developers, it would be nice if this script told us what it did! Let's inspect our filesystem to find out for ourselves (`ls -1` shows one listing per line):

```bash
$ ls -1
CONTRIBUTING.md
COPYING
INSTALL.md
Makefile
Makefile.am
Makefile.in               <- Hey, you weren't here before ...
README.md
REVIEWERS
SECURITY.md
aclocal.m4
autogen.sh
autom4te.cache
build-aux
build_msvc
ci
config.log
config.status
configure                 <- FOUND YOU!
configure.ac
contrib
depends
doc
libbitcoinconsensus.pc
libbitcoinconsensus.pc.in
libtool
share
src
test
```

Two observations: `configure` is generated by `autoreconf` and so is `Makefile.in`. Onwards!

### 🕵️ Mystery #2: Case of the Missing `Makefile`

Let's run the second command:

```bash
$ ./configure
checking for pkg-config... /usr/bin/pkg-config
checking pkg-config is at least version 0.9.0... yes
checking ...
...
```

The script is inspecting our to make sure all dependencies needed to build Bitcoin Core are available. Some dependencies are optional. If [QT](https://www.qt.io/) is missing then it will won't build the GUI, but it will print a warning and proceed building everything else.

```text
configure: WARNING: Qt5Core >= 5.5.1 not found; bitcoin-qt frontend will not be built
```

Other dependencies are required. One my Ubuntu system I got this error:

```text
configure: error: Found Berkeley DB other than 4.8, required for portable BDB wallets (--with-incompatible-bdb to ignore or --without-bdb to disable BDB wallet support)
```

I'm missing development library for the ancient Berkeley DB version used by the Bitcoin Core wallet. I can pass a `--without-bdb` to disable wallet support, `--with-incompatible-bdb` to use the wallet in a way where the `wallet.dat` file might not work on other systems, or run [./contrib/install_db4.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/install_db4.sh) to install the proper version of BDB.

Consult the `build-x.md` files in [Bitcoin Core's documentation folder](https://github.com/bitcoin/bitcoin/tree/master/doc) for more information about installing dependencies for your system.

### Autotools

Meet GNU Autotools, the suite of build system tools behind all this madness. The [Wikipedia page](https://en.wikipedia.org/wiki/GNU_Autotools) explains what's happening here. Some highlights:

> It can be difficult to make a software program portable: the C compiler differs from system to system; certain library functions are missing on some systems; header files may have different names. One way to handle this is to write conditional code, with code blocks selected by means of preprocessor directives (#ifdef); but because of the wide variety of build environments this approach quickly becomes unmanageable. Autotools is designed to address this problem more manageably.

> The GNU Build System makes it possible to build many programs using a two-step process: `configure` followed by `make`.

> Autoconf generates a configure script based on the contents of a `configure.ac` file which characterizes a particular body of source code. The configure script, when run, scans the build environment and generates a subordinate config.status script which, in turn, converts other input files and most commonly `Makefile.in` into output files (Makefile) which are appropriate for that build environment. Finally the `make` program uses Makefile to generate executable programs from source code.

It's all clear now. Bitcoin Core prioritizes portability -- ensuring code runs on many computer architectures and oeprating systems. Ability to run Bitcoin Core on a Raspberry Pi keeps the cost of running a fully validating Bitcoin node far below [that of gold](https://www.thermofisher.com/us/en/home/industrial/spectroscopy-elemental-isotope-analysis/oes-xrd-xrf-analysis/x-ray-fluorescence-xrf.html). Running Bitcoin Core on computers made pre-2009 offers some assurances against state-level backdoors. Bitcoin Core uses Autotools to help enable these and other usecases.

There's only one thing left to explain. The wiki mentions `autoconf`, but `autogen.sh` uses a similarly-named `autoreconf`. Check out [this StackOverflow answer](https://stackoverflow.com/a/27334612) to understand the difference:

> `autoconf` generates the `configure` script from various input files, some of which are created using other tools like `aclocal`, `automake`, etc.
>
> `autoreconf` is a helper that knows how to call all these tools in the right order
>
> You'll usually just call `autoreconf` yourself and let it deal with all the lower level tools ....

I was curious what differences there would actually be if I ran `autogen.sh` on two different computer. [Here's a diff](https://www.diffchecker.com/vSDCLlbI/) with Mac `configure` script on the left and a Ubuntu one on the right. They're slightly different, but mysteriously much of the difference seems to be whitespace related. Odd! If you have multiple computers you might try generating and comparing `configure` or `Makefile` scripts.

We can also see what changes when we pass different flags to `configure`.

```bash
$ ./configure --without-bdb
...
$ cp Makefile without.txt
$ ./configure
...
$ diff without Makefile
305c305
< BDB_LIBS =
---
> BDB_LIBS = -ldb_cxx
```

`-ldb_cxx` stands for `libdb-cxx`, which is the C++ library for [Berkeley DB](https://stackoverflow.com/a/12314645/2542016) we discussed earlier. This makes sense -- if we remove `bdb` wallet support then the BDB library code is removed as a dependency. If we disable the wallet entirely with the `--disable-wallet` flag, it also removes the dependencies for SQLite, which is the successor to BDB.

```bash
$ ./configure --disable-wallet
...
$ cp Makefile without.txt
$ ./configure
...
$ cp Makefile with.txt
$ diff without with
305c305
< BDB_LIBS =
---
> BDB_LIBS = -ldb_cxx
505c505
< SQLITE_LIBS =
---
> SQLITE_LIBS = -lsqlite3
```

### Make

Now that we have a `Makefile` generated, let's use it to build Bitcoin core:

```bash
$ make
...
```

This will take a while. After it's done you should be able to execute the generated `bitcoind` executable:

```bash
$ ./src/bitcoind
2020-12-18T19:18:58Z Bitcoin Core version v21.99.0-1811e488d (release build)
...
```

Talk to it with the generated `bitcoin-cli` executable:

```bash
$ ./src/bitcoin-cli getblockchaininfo
{
    "chain": "main",
    "blocks": 0,
    ...
}
```

Don't want to type out relative paths to these files every time you check your wallet balance? That's what `make install` is for. All this does is copies `bitcoind`, `bitcoin-cli` and other files to standard locations where your shell should look for programs. First, kill the `./src/bitcoind` process above with control-c (only one `bitcoind` can run at-a-time). Then:

```bash
// note that bitcoind and bitcoin-cli not installed
$ bitcoind
bitcoind: command not found
$ bitconi-cli
bitcoin-cli: command not found

$ make install
...

$ bitcoind
...

// in another terminal
$ bitcoin-cli
{
  ...
}
```

And now let's return the git repo to it's original state, deleting the `configure` script, the `Makefile`, and everything else that was generated along the way:

```bash
$ make clean
```


Mooniversity
Learn how bitcoin works

Digital Cash

Learn To Code

Reproducible Builds With Gitian (2/2)

Reproducible Builds With Gitian (1/2)

Verify Your Bitcoin Core Download

Building Bitcoin Core