---

name: bitcoin-core-release-engineering disable-model-invocation: true description: | Bitcoin Core release engineering: Guix reproducible builds, signed release tarballs, deterministic outputs, code-signing keys, the release process, security disclosure. USE WHEN: building Bitcoin Core from source for verification, understanding release security, contributing to consensus-critical code. allowed-tools: Read, Grep, Glob

Bitcoin Core Release Engineering

Bitcoin Core ships reproducible builds: anyone with the source

• Guix can produce byte-identical binaries to the official release. This protects against supply-chain attacks targeting the build server.

Guix reproducible builds

GNU Guix is the deterministic build environment.

# In bitcoin/ source directory
./contrib/guix/guix-build

Outputs:

• guix-build-<version>/output/x86_64-linux-gnu/bitcoin-<version>-x86_64-linux-gnu.tar.gz
• (and per other platforms via cross-compile)

The hash of these tarballs is what gets signed by maintainers.

guix.sigs

Repository: github.com/bitcoin-core/guix.sigs. The Guix build runs in two stages and each stage gets its own attestation, so after each release trusted builders publish two signed hash files:

<version>/<builder-name>/noncodesigned.SHA256SUMS      # stage 1: built from source
<version>/<builder-name>/noncodesigned.SHA256SUMS.asc
<version>/<builder-name>/all.SHA256SUMS                # stage 2: + code signatures
<version>/<builder-name>/all.SHA256SUMS.asc

Stage 2 attaches the Windows/macOS detached code signatures distributed from bitcoin-core/bitcoin-detached-sigs. all.SHA256SUMS covers every binary uploaded to the website and is what release downloads should be checked against (guix.sigs README, as of September 2026).

Verifying a release: download official binaries, compute SHA256, compare to entries from N independent builders. If they all match, no single builder could have introduced malware.

Release signing keys

As of Bitcoin Core v22.0 releases are signed by a set of builder keys published in the guix.sigs repository, one file per signer:

github.com/bitcoin-core/guix.sigs → builder-keys/<signer>.gpg

The old contrib/builder-keys/keys.txt in bitcoin/bitcoin is gone — it shipped through v24.0 and was removed in November 2022 (commit e6864fa1, "contrib: remove builder keys"). The path 404s on master and on every tag from v25.0 onward (checked September 2026).

Publication does have thresholds. doc/release-process.md (as of September 2026) gates the upload step on "6 or more people [having] guix-built and their results match", and the Windows/macOS detached code signatures are only produced "once the Windows and macOS builds each have 3 matching signatures". Those numbers bind the release managers. They are not a verification rule for you — downstream you still pick which builder keys to trust and how many matching signatures to demand.

Core ships the supported one-command path, contrib/verify-binaries/verify.py:

# download SHA256SUMS(.asc) + binaries, check sigs then hashes
./contrib/verify-binaries/verify.py pub 31.1

# fetch unrecognised builder keys automatically
./contrib/verify-binaries/verify.py --import-keys pub 31.1

# demand more attestations than the default of 3
./contrib/verify-binaries/verify.py --min-good-sigs 10 pub 31.1

Builders rotate keys and the signer set changes between releases; read builder-keys/ as of the version you are verifying, not an old copy.

Release process (high level)

1. Feature freeze — typically ~1 month before scheduled release.
2. Release branch — NN.x branched off master (e.g. 31.x).
3. Release candidates (rc1, rc2, ...).
4. Backports — bug fixes flow from master to release branches.
5. Final tag — signed git tag.
6. Guix builds — multiple builders produce binaries.
7. guix.sigs PR — builders publish signed hashes.
8. Release announcement — per doc/release-process.md (as of September 2026): the bitcoin-dev and bitcoin-core-dev mailing lists, the Bitcoin Core announcements list (https://bitcoincore.org/en/list/announcements/join/) and the project's social account. A bitcoincore.org blog post and the maintained-versions table are updated in the same pass.

Source verification

To verify a downloaded tarball before building:

# Get GPG keys
gpg --keyserver hkps://keys.openpgp.org --recv-keys <maintainer-fingerprint>

# Verify
gpg --verify SHA256SUMS.asc SHA256SUMS
sha256sum -c SHA256SUMS

Code-signing for binaries

• macOS: signed via Apple's developer cert (so Gatekeeper accepts it).
• Windows: code-signed with EV certificate.
• These signatures are separate from the GPG signatures and protect against OS-level "untrusted publisher" warnings, not against tampering of the source tarball itself.

For Linux: no platform-level signing (rely on Guix + GPG).

Hash verification on first run

bitcoind does NOT self-verify on each run. The integrity check is done at install time:

sha256sum bitcoin-31.1-x86_64-linux-gnu.tar.gz
# compare to entries in SHA256SUMS

Security disclosure

security@bitcoincore.org for security issues. Embargoed disclosures: maintainers coordinate fixes across exchanges, miners, services before public release.

Process documented in SECURITY.md of the repo.

Medium- and High-severity advisories are published about two weeks after the last affected version goes EOL, so the public CVE list lags the fix by a long way (Low severity is disclosed two weeks after the fixed major ships; Critical is handled ad hoc). Policy as of September 2026 — see https://bitcoincore.org/en/security-advisories/. CVE-2024-52911 (High; use-after-free — a background script-check thread could read the precomputed transaction data after it was destroyed; affects 0.14.0 through 28.x) was reported 2024-11-02, fixed in 29.0 (April 2025) and disclosed 2026-05-05, just over two weeks after 28.x went EOL on 2026-04-19. So "no advisory against this major" is not evidence it is safe. For the resulting version floor see operations/SKILL.md, "Security advisories and minimum safe version".

Vulnerability scoring

Bitcoin uses ad-hoc severity classification:

• Critical: consensus split, theft, DoS that crashes nodes.
• High: privacy leak, low-cost DoS.
• Medium / Low: bugs without immediate fund impact.

Past vulnerabilities like CVE-2018-17144 (inflation bug) → fixed silently before public disclosure.

Branch policy

• master — current development.
• NN.x — one maintenance branch per major version.
• Backport criteria: bugfix only, no features. Documented exception: consensus rule changes ship first in a maintenance release (22.2, 23.1, …) so the changeset stays small and reviewable.
• Maintenance window: the latest three major versions. When a new major is released the oldest falls out and becomes End of Life; EOL lines do not generally receive security fixes. Majors are targeted every 6 months, so a line is maintained for roughly 18 months — not a fixed calendar period.
• As of September 2026: latest release 31.1 (2026-07-08), with maintenance releases 30.3 and 29.4 (both 2026-07-10). Maintained lines are 29.x, 30.x and 31.x; 28.x (EOL 2026-04-19) and older are not. 32.x is branched for the in-flight v32.0 (v32.0rc1 tagged 2026-09-14); when v32.0 ships, 29.x goes EOL.
• The schedule moves every ~6 months — read it from https://bitcoincore.org/en/lifecycle/ rather than trusting the list above.

Common confusions

• "Bitcoin Core" vs "Bitcoin" — Bitcoin Core is one implementation. Others (Bitcoin Knots, btcd) exist but Bitcoin Core is the reference and runs on ~81–83% of public nodes (Coin Dance 82.9%, 21,361 of 25,766; Bitnodes ~81%, 21,497 of 26,556; both 2026-09-16) — a large majority, not the whole network. See knots/SKILL.md for the split.
• Pre-release builds from PRs are NOT trusted; only tagged releases.
• Guix builds for non-reproducible components (system libraries like libc) require Guix to be set up correctly; cross-platform reproducibility is maintained via Guix's bootstrap chain.

See also

• rpc/SKILL.md
• knots/SKILL.md
• operations/SKILL.md