Files
nix-bitcoin/docs/maintenance.md
T
plebandClaude Opus 5.5 aedda5bc86 docs: describe the fork vs upstream, add CLAUDE.md
- README: table of differences from upstream (master), pin a release
  tag in the usage example, drop references to personal hosts
- docs/fork-maintenance.md -> docs/maintenance.md: rewritten from a
  tracking note into a record of what was removed and an ongoing
  maintenance guide (mempool signers, per-release checklist)
- CLAUDE.md: branch layout, tag a release after consumer-facing
  changes (v0.MINOR.PATCH), how to check changes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 08:40:23 -08:00

7.0 KiB

Maintaining the fork

Upstream (fort-nix/nix-bitcoin) was archived in August 2026, so this fork is now the only source of fixes. This document records what was removed when the fork was trimmed, and covers the maintenance work that remains.

What was removed

The trim was done in November 2026, in commits 6e13a8b through e1af5b7 on main, and released as v0.1.0. Upstream's tree is still on master. The guiding rule was to keep only what a node running bitcoind, lnd, electrs and mempool actually evaluates, and remove everything else, since each remaining module has to be ported across every NixOS release.

Area Removed Why
Services clightning (with plugins, REST, replication), joinmarket (with ob-watcher), btcpayserver/nbxplorer, rtl, liquid, lightning-loop, lightning-pool, charge-lnd, lndconnect, fulcrum, hardware-wallets Not used. Each one broke independently whenever nixpkgs renamed an option or dropped a dependency
Packages python-packages/ (pyln, joinmarket, hwi and their pinned cython/ecdsa), clightning-plugins/, clightning-rest/, clnrest/, trustedcoin/, rtl/, nbxplorer/, liquid-swap/, joinmarket/, bitcoind_29/, netns-exec/, krops/, nixops/, generate-secrets-deprecated.nix, the local lndinit (0.1.3) Only needed by removed services. lndinit now comes from nixpkgs
Support features netns-isolation.nix, i2p support in bitcoind.nix, backups.nix, versioning.nix, obsolete-options.nix, modules/deployment/ (krops, nixops) netns-isolation reached into every service and caused the NixOS 26.11 i2pd breakage. Versioning and obsolete-options exist to migrate other people's configs across upstream releases
Presets secure-node, enable-tor, hardened, hardened-extended, wireguard, bitcoind-remote Mostly configured removed services. Consumers now set the Tor, onion-service and hardening options directly, which also lets them change values such as bitcoind.dbCache that the preset set without mkDefault
Flake inputs nixpkgs-unstable, nixpkgs-25_05, flake-utils, extra-container, plus pinned.nix, nixpkgs-pinned.nix and the useVersionLockedPkgs option Consumers following only nixpkgs still got packages from the fork's stale pins. Everything now comes from the consumer's nixpkgs
Scaffolding test/ (VM tests and CI), examples/, dev/, upstream's docs/, .github/, SECURITY.md, shell.nix, helper/ except update-fixed-output-derivation.sh (release signing, update-flake) Upstream's user-facing material and release process. Replaced by a short README

All told, about 174 files changed and the code went from about 16,500 lines to about 2,300. Option names in the remaining modules are unchanged from upstream.

What's left, and what it costs to maintain

Ordered from most to least work:

  1. mempool package (pkgs/mempool/). This is the only package built here; nixpkgs doesn't package mempool. It has:

    • five fixed-output hashes: source, frontend and backend node modules, the frontend-assets fetch, and the rust-gbt cargo vendor
    • a local patch, 0001-allow-disabling-mining-pool-fetching.patch
    • a pinned nodejs_26 / nodejs-slim_26
    • an en-US-only frontend build
    • NG_FORCE_TTY=false, without which the Angular CLI's spinner redraws forever under Nix's pty and the frontend build never finishes

    Expect every version bump to need the hashes redone (generate.sh does this). When Node 26 reaches end of life, nixpkgs will drop it and force a Node bump here. If the mempool UI is ever no longer wanted, removing it is the biggest maintenance cut available.

  2. mempool.nix module. It configures mariadb, nginx (including mempool-nginx-conf from the package) and the backend's JSON config, so it follows changes to NixOS's mysql and nginx modules and to mempool's config schema.

  3. bitcoind.nix. It tracks Bitcoin Core config changes across major versions; nixpkgs moves bitcoind on its own schedule. It disables NixOS's own services/networking/bitcoind.nix through disabledModules in modules.nix, so watch for that module being renamed or split.

  4. lnd.nix. It tracks lnd config changes and uses pkgs.lndinit. Check that the gen-seed and init-wallet flags still match after lndinit bumps.

  5. Tor plumbing (onion-services.nix, onion-addresses.nix, nbLib.tor). It's built on services.tor.relay.onionServices and tor.client.socksListenAddress, which NixOS has kept stable for years, so expect low churn.

  6. Secrets (secrets/). setup-secrets generates RPC passwords, the lnd cert and similar on the host. It's mostly shell and openssl, so low churn.

  7. electrs.nix, nodeinfo.nix, operator.nix, security.nix, nix-bitcoin.nix. These are small. The electrs package comes from nixpkgs.

  8. systemd hardening in pkgs/lib.nix (defaultHardening, allowedIPAddresses, allowNetlink). Occasionally a systemd or NixOS change makes a service fail at runtime, not at evaluation. That only shows up after a deploy.

Updating mempool

Edit version in pkgs/mempool/generate.sh and run it. The script clones the release tag and checks its signature against two pinned fingerprints:

  • wiz, 913C5FF1F579B66CA10378DBA394E332255A6173. He signed every release through v3.3.0-alpha2. The key is on keyservers and Keybase.
  • mononaut, 523B596A78BB8495AA2EC45ABFD16BE592A9CD8D. Mononaut has signed releases since v3.3.0. The key is fetched from github.com/mononaut.gpg. It was created on 2026-04-14, nobody has cross-signed it, and it isn't on keyservers or Keybase, so trusting it means trusting mononaut's GitHub account. wiz published the v3.3.1 GitHub release, which mononaut's key signed.

If a release is signed by any other key, find out why before adding its fingerprint. After the script refreshes the hashes, build all four packages.*.mempool-* outputs.

Per-release checklist

On each NixOS release, or each nixpkgs bump in a consuming config:

  1. Run nix flake check here.
  2. Build the consuming host's nixosConfigurations.<host>.config.system.build.toplevel. Evaluation errors will point into this fork's modules.
  3. If mempool or Node changed, build services.mempool.package and services.mempool.frontend.package first, and update the hashes.
  4. Commit, then tag a new release (see CLAUDE.md for the versioning scheme) and point the consumer at the new tag.
  5. Switch the host and check that bitcoind, lnd, electrs, mempool and nginx are running. Hardening regressions don't show at build time. If a service fails, run nixos-rebuild switch --rollback.

Testing

There is no test suite. Problems are handled as they show up on a deployed node, with rollback as the fallback. A regtest VM test was written during the trim and then dropped as not worth maintaining. If runtime breakage becomes frequent, upstream's test/tests.py on master has per-service checks for all four services to start from.