Bootstrappable Bitcoin Core Builds
This directory contains the files necessary to perform bootstrappable Bitcoin Core builds.
Bootstrappability furthers our binary security guarantees by allowing us to audit and reproduce our toolchain instead of blindly trusting binary downloads.
We achieve bootstrappability by using Guix as a functional package manager.
Conservatively, a x86_64 machine with:
- 2 or more logical cores
- 4GB of free disk space on the partition that /gnu/store will reside in
- 24GB of free disk space on the partition that the Bitcoin Core git repository resides in
Note: these requirements are slightly less onerous than those of Gitian builds
Otherwise, follow the Guix installation guide.
Note: For those who like to keep their filesystems clean, Guix is designed to be very standalone and will not conflict with your system's package manager/existing setup. It only touches
Choosing your security model
Guix allows us to achieve better binary security by using our CPU time to build everything from scratch. However, it doesn't sacrifice user choice in pursuit of this: users can decide whether or not to bootstrap and to use substitutes.
After installation, you may want to consider adding substitute servers to speed up your build if that fits your security model (say, if you're just testing that this works). This is skippable if you're using the Dockerfile.
If you prefer not to use any substitutes, make sure to set
ADDITIONAL_GUIX_ENVIRONMENT_FLAGS like the following snippet. The first build
will take a while, but the resulting packages will be cached for future builds.
Likewise, to perform a bootstrapped build (takes even longer):
export ADDITIONAL_GUIX_ENVIRONMENT_FLAGS='--bootstrap --no-substitutes'
Using the right Guix
Once Guix is installed, deploy our patched version into your current Guix profile. The changes there are slowly being upstreamed.
guix pull --url=https://github.com/dongcarl/guix.git \ --commit=82c77e52b8b46e0a3aad2cb12307c2e30547deec \ --max-jobs=4 # change accordingly
Make sure that you are using your current profile. (You are prompted to do this
at the end of the
As a Development Environment
For a Bitcoin Core depends development environment, simply invoke
guix environment --manifest=contrib/guix/manifest.scm
And you'll land back in your shell with all the build dependencies required for
depends build injected into your environment.
As a Tool for Deterministic Builds
From the top of a clean Bitcoin Core repository:
After the build finishes successfully (check the status code please), compare hashes:
find output/ -type f -print0 | sort -z | xargs -r0 sha256sum
Recognized environment variables
Override the space-separated list of platform triples for which to perform a bootstrappable build. (defaults to "i686-linux-gnu x86_64-linux-gnu arm-linux-gnueabihf aarch64-linux-gnu riscv64-linux-gnu")
Windows and OS X platform triplet support are WIP.
Set the depends tree download cache for sources. This is passed through to the depends tree. Setting this to the same directory across multiple builds of the depends tree can eliminate unnecessary redownloading of package sources.
Override the maximum number of jobs to run simultaneously, you might want to do so on a memory-limited machine. This may be passed to
xargs -P"$MAX_JOBS". (defaults to the value of
nprocoutside the container)
Override the reference UNIX timestamp used for bit-for-bit reproducibility, the variable name conforms to standard. (defaults to the output of
$(git log --format=%at -1))
If non-empty, will pass
Additional flags to be passed to
guix environment. For a fully-bootstrapped build, set this to
--bootstrap --no-substitutes(refer to the security model section for more details). Note that a fully-bootstrapped build will take quite a long time on the first run.
Tips and Tricks
Speeding up builds with substitute servers
This whole section is automatically done in the convenience Dockerfiles
For those who are used to life in the fast (and trustful) lane, you can use substitute servers to enable binary downloads of packages.
For those who only want to use substitutes from the official Guix build farm and have authorized the build farm's signing key during Guix's installation, you don't need to do anything.
Authorize the signing keys
For the official Guix build farm at https://ci.guix.gnu.org, run as root:
guix archive --authorize < ~root/.config/guix/current/share/guix/ci.guix.gnu.org.pub
For dongcarl's substitute server at https://guix.carldong.io, run as root:
wget -qO- 'https://guix.carldong.io/signing-key.pub' | guix archive --authorize
Use the substitute servers
The official Guix build farm at https://ci.guix.gnu.org is automatically used
--no-substitutes flag is supplied.
This can be overridden for all
guix invocations by passing the
--substitute-urls option to your invocation of
guix-daemon. This can also be
overridden on a call-by-call basis by passing the same
option to client tools such at
To use dongcarl's substitute server for Bitcoin Core builds after having authorized his signing key:
export ADDITIONAL_GUIX_ENVIRONMENT_FLAGS='--substitute-urls="https://guix.carldong.io https://ci.guix.gnu.org"'
How can I trust the binary installation?
As mentioned at the bottom of this manual page:
The binary installation tarballs can be (re)produced and verified simply by running the following command in the Guix source tree:
When will Guix be packaged in debian?
Vagrant Cascadian has been making good progress on this here. We have all the pieces needed to put up an APT repository and will likely put one up soon.