- Scheme 85.1%
- Shell 6.6%
- Tree-sitter Query 6.3%
- JavaScript 2%
guix-bitcoin
guix-bitcoin
check license: GPL-3.0+ channel: authenticated substitutes: build from source
A GNU Guix channel for the Bitcoin ecosystem: full nodes, wallets, libraries,
Lightning implementations, Electrum-protocol indexers, and block explorers.
Everything is packaged from upstream source and built locally — the channel is
GPG-authenticated and serves no binary substitutes, so you verify rather than
trust. Guile modules live under the (bitcoin packages ...) and
(bitcoin services ...) namespaces, with sources in the bitcoin/ directory.
Build status
All package sets currently build successfully, both VM system tests pass, and
the example operating system builds. The table reflects verified local builds
as of 2026年06月16日. The libs badge tracks the per-push check workflow;
heavier package-set badges track the shared changed-set build-set workflow,
which runs automatically when those files change or on demand (see
Building).
| Set | Packages | CI |
|---|---|---|
libs |
libsecp256k1, libsecp256k1-zkp | libs |
nodes |
bitcoin-core, bitcoin-knots, btcd, floresta | nodes |
wallets |
electrum, hwi, hal, bdk-cli | wallets |
indexers |
fulcrum, electrs | indexers |
lightning |
core-lightning, lnd | lightning |
rust |
rust-bitcoin, rust-bitcoin-hashes, rust-secp256k1, rust-miniscript, rust-bdk-wallet | rust |
explorers |
mempool-backend, mempool-frontend (+ mempool-rust-gbt build dep) | explorers |
VM system tests %test-bitcoin-node and %test-electrs (in
tests/bitcoin.scm) pass in a marionette VM, and examples/system-node.scm builds
with guix system build.
Package versions
| Package | Version | Set |
|---|---|---|
| libsecp256k1 | 0.7.1 | libs |
| libsecp256k1-zkp | commit-pinned | libs |
| bitcoin-core | 31.0 | nodes |
| bitcoin-knots | 29.3.knots20260508 | nodes |
| btcd | 0.25.0 | nodes |
| floresta | 0.9.1 | nodes |
| electrum | 4.7.2 | wallets |
| hwi | 3.2.0 | wallets |
| hal | 0.11.0 | wallets |
| bdk-cli | 3.0.0 | wallets |
| sparrow-wallet † | 2.5.2 | wallets |
| fulcrum | 2.1.1 | indexers |
| electrs | 0.11.1 | indexers |
| core-lightning | 26.06.1 | lightning |
| lnd | 0.20.1-beta | lightning |
| rust-bitcoin | 0.32.100 | rust |
| rust-bitcoin-hashes | 1.0.0 | rust |
| rust-secp256k1 | 0.31.1 | rust |
| rust-miniscript | 13.1.0 | rust |
| rust-bdk-wallet | 3.0.0 | rust |
| mempool-backend | 3.3.1 | explorers |
| mempool-frontend | 3.3.1 | explorers |
† sparrow-wallet repackages upstream's official, reproducible release image
rather than building from source (a from-source build needs JavaFX 26, which
Guix lacks). It is the channel's only binary package, and the reason the channel
depends on nonguix — pulled automatically as a channel dependency. Because it
is a binary repackage, the per-push CI does not build it (build it on demand
with etc/ci-build.sh binary under a pulled guix); its upstream releases are
still tracked by the monthly refresh job.
Installation
Add the channel to ~/.config/guix/channels.scm. The introduction pins the
commit and OpenPGP fingerprint Guix uses to authenticate the channel:
(cons (channel
(name 'bitcoin)
(url "https://codeberg.org/trevarj/guix-bitcoin.git")
(branch "master")
(introduction
(make-channel-introduction
"747b9cb83c0f88da46a14638165253b3b0d4b3bc"
(openpgp-fingerprint
"A6C2 0D0C 2AD8 38F9 4907 0EA3 A52D 6879 4EBE D758"))))
%default-channels)
Then pull:
guix pull
The canonical, authenticated origin is https://codeberg.org/trevarj/guix-bitcoin.git. A GitHub mirror (where CI runs) is at https://github.com/trevarj/guix-bitcoin. Every commit on the channel is GPG-signed and verified against the fingerprint above when you pull.
Usage
Try a package in a temporary shell:
guix shell bitcoin-core -- bitcoind --version
Build a package from this channel:
guix build bitcoin-core
Services
On Guix System, the channel provides service types in (bitcoin services ...):
bitcoin-node-service-type— runsbitcoind(Bitcoin Core or Knots) on any network, with cookie-based RPC authentication.electrs-service-typeandfulcrum-service-type— Electrum-protocol indexers that attach to a local node.clightning-service-typeandlnd-service-type— Lightning daemons that authenticate to the local node via cookie RPC.mempool-service-type— the mempool.space backend, with MariaDB provisioning and an nginx vhost for the frontend.
A minimal node configuration:
(use-modules (bitcoin services bitcoin))
(operating-system
;; ...
(services
(cons* (service bitcoin-node-service-type)
%base-services)))
See examples/system-node.scm for a complete, commented
example (node plus optional indexer, Lightning, and explorer services), and the
module docstrings in bitcoin/services/ for the available configuration fields.
For a container-first walkthrough of the explorer stack, see
examples/README.md.
Building / substitutes
No substitute server is offered for this channel — every package builds from source on your machine. This is intentional (verify, don't trust). Expect node, indexer, and Lightning builds to take a while on first install.
You can build any named set locally the same way CI does:
./etc/ci-build.sh libs # or: nodes indexers wallets lightning rust explorers all
CI (.github/workflows/check.yml) lints and builds the libs set on every
push using a cached Guix. Heavier sets build automatically when their files
change: build-set.yml maps each changed file to its set
(etc/ci-changed-sets.sh) and builds exactly those sets in parallel — e.g. a
commit touching bitcoin/packages/lightning.scm builds only the lightning
set. You can also dispatch a set on demand:
gh workflow run build-set.yml -f package_set=nodes
# sets: libs | nodes | indexers | wallets | lightning | rust | explorers | all
A monthly job (.github/workflows/refresh.yml) runs guix refresh over the
packages — plus a GitHub Releases check for the node and explorer packages
whose custom download URLs guix refresh cannot follow (bitcoin-core,
bitcoin-knots, mempool) — and opens a tracking issue listing what is outdated.
Run it any time with gh workflow run refresh.yml.
Contributing
See CONTRIBUTING.md. Maintainer runbooks for recurring tasks (bumping packages, adding packages/services, releasing, troubleshooting) are in docs/maintenance/.
License
GPL-3.0-or-later. See LICENSE for the full text; the package and service modules each carry the GNU GPL v3-or-later header.