diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..bce4e70 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,43 @@ +# CLAUDE.md + +This is a trimmed fork of fort-nix/nix-bitcoin, which is archived. It has NixOS modules for bitcoind, lnd, electrs and mempool only. Read README.md for an overview and docs/maintenance.md for what was removed and what needs upkeep. + +## Branches + +- `main` is where development happens, and releases are tagged from it. Commit here. +- `master` holds upstream's archived tree for reference. Don't commit to it or move it. +- On gitea, the default branch is `master`, so consumers must pin a tag. + +## Tag a release after every change + +Consumers pin `?ref=refs/tags/vX.Y.Z`, so a change on `main` doesn't reach anyone until it's tagged. After committing a change that affects what consumers evaluate or build (modules, `pkgs/`, `flake.nix`, `flake.lock`), propose a new tag. Changes that only touch docs don't need one. + +Versioning is `v0.MINOR.PATCH`. Ignore upstream's `v0.0.x` tags, which exist only in older local clones. + +| Bump | When | Examples | +|---|---|---| +| MINOR | Package version bumps, new options, anything a consumer may have to change config for (removed or renamed options, changed defaults) | `v0.1.0` → `v0.2.0` | +| PATCH | Fixes and hash refreshes with no config impact | `v0.1.0` → `v0.1.1` | + +Steps: + +1. Find the latest fork tag with `git tag --list 'v0.[1-9]*' --sort=-v:refname | head -1`. +2. Create an annotated, unsigned tag: `git tag -a vX.Y.Z -m ""`. In the message, summarize the changes since the last tag and say whether the release has been deployed yet. +3. Push the branch and the tag with `git push origin main` and `git push origin vX.Y.Z`. Pushing is outward-facing, so confirm with the user first. +4. Remind the user to bump the tag in the consuming flake. + +## Checking changes + +There is no test suite. + +- Run `nix flake check` for evaluation. +- After touching `pkgs/mempool/`, run `nix build .#mempool-backend .#mempool-frontend .#mempool-rust-gbt .#mempool-nginx-conf`. +- Runtime behaviour is only verified by deploying to a node. Say so when something hasn't been deployed. + +## mempool updates + +Use `pkgs/mempool/generate.sh`. It checks the release tag's signature against pinned fingerprints for wiz and mononaut. Never add a new signer fingerprint without the user's sign-off. See the "Updating mempool" section of docs/maintenance.md. + +## Writing style + +The README and docs describe a generic node. Don't name personal hosts or private configs. diff --git a/README.md b/README.md index 58b3a22..299c7ff 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,32 @@ NixOS modules for a Bitcoin node running **bitcoind, lnd, electrs and mempool**, with Tor onion services and host-generated secrets. This is a trimmed fork of [fort-nix/nix-bitcoin](https://github.com/fort-nix/nix-bitcoin), -which was archived in August 2026. Everything squirtle doesn't use has -been removed. See [docs/fork-maintenance.md](docs/fork-maintenance.md) for -what was cut, what's left, and the per-release checklist. +which was archived in August 2026. Upstream's tree is preserved on the +`master` branch. Development happens on `main`, and releases are tagged +from `main`, starting at `v0.1.0`. + +## How it differs from upstream + +| | Upstream (`master`) | This fork (`main`) | +|---|---|---| +| Services | ~20: bitcoind, lnd, clightning (+ plugins, REST, replication), electrs, fulcrum, mempool, btcpayserver, rtl, joinmarket, liquid, loop, pool, charge-lnd, lndconnect, hardware wallets… | bitcoind, lnd, electrs, mempool | +| Support features | netns-isolation, i2p, backups, config versioning and obsolete-option migrations, krops/nixops deployment | Tor onion services, generated secrets, operator user, systemd hardening, nodeinfo | +| Presets | `secure-node`, `enable-tor`, `hardened`, `wireguard`, … | None: set the options you want in your own config | +| Flake inputs | nixpkgs, nixpkgs-unstable, nixpkgs-25_05, flake-utils, extra-container | nixpkgs only | +| Packages | Pinned set: lnd and others from unstable, clightning plugins, python packages, an old bitcoind, its own lndinit… | Everything from your nixpkgs, except mempool, which is built here | +| Flake outputs | `nixosModules`, `overlays`, `packages`, `legacyPackages`, `lib`, `templates`, tests | `nixosModules.default`, `overlays.default`, `packages.mempool-*` | +| Tests, docs, examples, dev shell, release signing | Yes | Removed | + +The code that's left is about 2,300 lines, down from about 16,500. The modules that remain keep upstream's option names, so a config that only uses those four services should carry over once it stops importing presets and stops setting removed options. See [docs/maintenance.md](docs/maintenance.md) for the full list of what was removed and how the fork is maintained. ## Usage +Pin a release tag. The repo's default branch is still upstream's `master`. + ```nix # flake.nix inputs.nix-bitcoin = { - url = "git+ssh://gitea@gitea.satstack.dev/pleb/nix-bitcoin.git"; + url = "git+ssh://gitea@gitea.satstack.dev/pleb/nix-bitcoin.git?ref=refs/tags/v0.1.0"; inputs.nixpkgs.follows = "nixpkgs"; }; @@ -48,12 +64,13 @@ Packages come from the consumer's nixpkgs (`pkgs.bitcoind`, `pkgs.lnd`, | Path | Contents | |---|---| | `modules/` | `bitcoind`, `lnd`, `electrs`, `mempool`, plus `secrets/`, `operator`, `security`, `onion-services`, `onion-addresses`, `nodeinfo` | -| `pkgs/mempool/` | mempool backend, frontend, rust-gbt and nginx config. `generate.sh` bumps the version and refreshes hashes | +| `pkgs/mempool/` | mempool backend, frontend, rust-gbt and nginx config. `generate.sh` bumps the version, verifies the release signature and refreshes hashes | | `pkgs/lib.nix` | systemd hardening and Tor helpers shared by the modules | +| `helper/update-fixed-output-derivation.sh` | Used by `generate.sh` to recompute hashes | -There is no test suite. Build squirtle in nix-pleb before switching, -and roll back (`nixos-rebuild switch --rollback`) if a service fails at -runtime. +There is no test suite. Build your host's system before switching to a +new release, and roll back (`nixos-rebuild switch --rollback`) if a +service fails at runtime. ## License diff --git a/docs/fork-maintenance.md b/docs/fork-maintenance.md deleted file mode 100644 index 7f9c640..0000000 --- a/docs/fork-maintenance.md +++ /dev/null @@ -1,257 +0,0 @@ -# Maintaining this fork - -Upstream (fort-nix/nix-bitcoin) is archived. This fork is now the only -source of fixes, so every module and package left in it is something we -port across each NixOS release. This note lists what squirtle actually -uses, what can be removed, and what still needs maintenance after that. - -Assessed 2026-11-15, against fork `master` at `da27f27` (upstream's tree -minus its last two SECURITY.md commits; no fork-only commits yet) and -nix-pleb's squirtle config on NixOS 26.05 and 26.11pre. - -**Status (2026-11-15):** steps 1–5 of *Suggested order* are done on -branch `slim`. Step 3's nix-pleb half (squirtle's `services.nix`, -`configuration.nix`, `nixosConfigurations.nix`) is uncommitted in -nix-pleb. Step 6 is still to do. Upstream's tests were dropped, not -replaced (see *Testing*). - -## Who consumes the fork - -Only one host does: squirtle, in nix-pleb -(`systems/brenise.dev/nixosConfigurations.nix`). It imports -`nixosModules.default` and `modules/presets/secure-node.nix`. No other -flake in `~/ops` uses the fork. - -These are squirtle's evaluated settings, not just what the config file -declares: - -| Feature | State on squirtle | -|---|---| -| `services.bitcoind` | on, `bitcoind-32.1` from system nixpkgs, `i2p = false` | -| `services.lnd` | on, package overridden to nix-pleb's `unstablePkgs.lnd` | -| `services.electrs` | on, from system nixpkgs | -| `services.mempool` | on, fork-packaged `mempool-*-3.3.2`, `electrumServer = "electrs"` | -| `nix-bitcoin.operator` | on (`pleb`) | -| `nix-bitcoin.nodeinfo` | on (from secure-node preset) | -| `nix-bitcoin.generateSecrets` | on, `secretsSetupMethod = "setup-secrets"` | -| onion services | bitcoind (public), electrs, sshd | -| `nix-bitcoin.security.dbusHideProcessInformation` | on (preset) | -| `services.tor` | on (preset) | -| `nix-bitcoin.netns-isolation` | **off** | -| `services.i2pd` | **off** | -| `services.backups` | **off** | -| `nix-bitcoin.configVersion` | unset | -| clightning, rtl, fulcrum, btcpayserver, nbxplorer, joinmarket, liquidd, loop, pool, charge-lnd, clightning-rest, hardware-wallets, lndconnect | all **off** | - -Squirtle runs four services: **bitcoind, lnd, electrs and mempool**. The -rest of the fork is unused. - -## What can go - -### Unused services: remove - -These modules and their packages have no consumer. Each one breaks -independently whenever nixpkgs renames an option or drops a dependency. - -| Module | Package(s) in `pkgs/` | Lines (module + pkg) | -|---|---|---| -| `clightning.nix`, `clightning-plugins/`, `clightning-rest.nix`, `clightning-replication.nix` | `clightning-plugins/`, `clightning-rest/`, `clnrest/`, `trustedcoin/`, most of `python-packages/` (pyln-*, pylightning) | ~1,500 | -| `joinmarket.nix`, `joinmarket-ob-watcher.nix` | `joinmarket/`, `python-packages/` (joinmarket, bencoderpyx, chromalog, txzmq, python-bitcointx…) | ~1,000 | -| `btcpayserver.nix` | `nbxplorer/` | ~410 | -| `rtl.nix` | `rtl/` | ~345 | -| `liquid.nix` | `liquid-swap/` | ~320 | -| `lndconnect.nix` | — | ~280 | -| `lightning-loop.nix`, `lightning-pool.nix`, `charge-lnd.nix` | — | ~400 | -| `fulcrum.nix` | — | ~140 | -| `hardware-wallets.nix` | `hwi` (python-packages) | ~85 + | -| — | `bitcoind_29/` (old bitcoind pin) | ~215 | - -`python-packages/` (~520 lines) disappears completely once clightning, -joinmarket and hwi are gone. Its own comments note that it pins older -cython, ecdsa and similar, and that kind of pin breaks on each nixpkgs -bump. - -### Unused support features: remove - -- **`netns-isolation.nix`** (366 lines). It's off on squirtle, but it is - the module that reaches into every other service (btcpayserver, - clightning, joinmarket, rtl, i2pd, …). The 26.11 i2pd breakage came from - here. Removing it also drops `pkgs/netns-exec/` and the - netns-only helpers in `pkgs/lib.nix`. -- **i2p support in `bitcoind.nix`.** `i2p` is false on squirtle. Dropping - the `i2p` option, `i2pSAM` and the `services.i2pd` block makes the - 26.11 compatibility patch on branch `nixos-26.11` unnecessary. **Prefer - this over that patch.** -- **`backups.nix`.** It's off on squirtle; the secure-node preset only - sets its `frequency`. Squirtle isn't in raichu's restic jobs either, so - if you want its lnd channel backup or config backed up, add it there - rather than reviving this module. -- **`versioning.nix`** (292 lines) and **`obsolete-options.nix`** (145 - lines). Both exist for migrating *other people's* configs across - upstream releases. Squirtle has no `configVersion` set and has never - needed either. Most of their entries reference removed services - (joinmarket, liquidd, clightning-rest…). -- **`modules/deployment/`** (krops, nixops), **`pkgs/krops/`, - `pkgs/nixops/`, `pkgs/generate-secrets-deprecated.nix`.** Squirtle - deploys with `nixos-rebuild` from nix-pleb. - -### Presets: fold into squirtle, then remove - -`presets/secure-node.nix` and `presets/enable-tor.nix` mostly configure -services squirtle doesn't run. What squirtle actually gets from them: - -- `services.tor.enable`, `tor.client.enable` -- `tor.proxy`/`tor.enforce` defaults for bitcoind, lnd, electrs, mempool - (squirtle then overrides `enforce = false` on bitcoind, lnd, electrs) -- onion services for bitcoind, electrs and sshd, plus `onionAddresses.access.pleb` -- `nodeinfo.enable`, `operator.enable`, `dbusHideProcessInformation` -- `bitcoind.listen = true`, `bitcoind.dbCache = 1000` -- doas instead of sudo (`squirtle/configuration.nix` already sets this), - `networking.firewall.enable = true` - -Those lines belong in `squirtle/services.nix`. That also fixes the -existing annoyance noted there: `dbCache` "cannot be changed here", -because the preset sets it without `mkDefault`. `hardened.nix`, -`hardened-extended.nix`, `wireguard.nix` and `bitcoind-remote.nix` have no -users. - -### Repo scaffolding: remove or shrink - -- `test/` (2,700 lines). The VM scenarios exercise every service. Removed - entirely; see *Testing*. -- `examples/` (1,250), `dev/` (900), most of `docs/` (1,700). These are - upstream's user-facing docs and dev environment. Replace them with a - short README covering what's left. -- `helper/`: `fetch-release`, `push-release.sh` and `key-jonasnick.bin` - are upstream's release signing. `update-flake.{nix,sh}` regenerates - `pkgs/pinned.nix` and becomes unnecessary once pins are gone (below). - Keep `update-fixed-output-derivation.sh` only if it's still handy for - mempool hashes. - -### Extra nixpkgs pins: remove - -The fork's flake has three nixpkgs inputs plus `extra-container` and -`flake-utils`. nix-pleb overrides only `nixpkgs` (`inputs.nixpkgs.follows`). -`nixpkgs-unstable` and `nixpkgs-25_05` stay pinned at whatever the fork's -`flake.lock` says, and they feed `pinned.nix`: - -- `pkgsUnstable` supplies `lnd` (squirtle overrides it), plus - `bitcoind-knots`, `clboss`, `fulcrum` and `lightning-loop` (all unused). -- `pkgs-25_05` is only plumbed through to python-packages. - -Once the unused packages are gone, take everything from the consumer's -`pkgs`. Make `lnd` default to `pkgs.lnd`; squirtle sets the package -explicitly anyway. Then delete `pinned.nix`, `nixpkgs-pinned.nix`, the -two extra inputs, `extra-container` (used only for container tests and -examples), and the `useVersionLockedPkgs` option. The fork then has one -input, `nixpkgs`, which nix-pleb already follows. - -## What's left, and what it costs to maintain - -After the removals the fork is roughly these modules: `nix-bitcoin.nix`, -`secrets/`, `operator.nix`, `security.nix`, `bitcoind.nix` (with -`bitcoind-rpc-public-whitelist.nix`, which it imports), `lnd.nix`, -`electrs.nix`, `mempool.nix`, `onion-services.nix`, `onion-addresses.nix`, -`nodeinfo.nix`. Plus `pkgs/lib.nix`, `pkgs/mempool/` and -`pkgs/build-support/fetch-node-modules.nix`. That's about 2,300 lines, -down from about 16,500. - -Ordered from most to least work: - -1. **mempool package (`pkgs/mempool/`)**: the only real package we - maintain. 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`), and a pinned - `nodejs_26` / `nodejs-slim_26`. It's at 3.3.2, level with upstream, - and builds the frontend in en-US only. Expect every version bump to - need the hashes redone. Node 26 also has an end-of-life date, after - which nixpkgs will drop `nodejs_26` and force a Node bump here. - nixpkgs doesn't package mempool, so there's no upstream to lean on. If - you ever stop wanting the mempool UI, removing it is the biggest - maintenance cut available. - - `generate.sh` accepts a release tag only if it's signed by one of two - pinned fingerprints: wiz (`913C…6173`, on keyservers and Keybase) or - mononaut (`523B…CD8D`, who has signed releases since v3.3.0). Mononaut's - key is fetched from `github.com/mononaut.gpg`. It is a new key (created - 2026-04-14), not cross-signed by anyone and not on keyservers or Keybase, - so trust in it rests on mononaut's GitHub account. If a release is - signed by any other key, find out why before adding its fingerprint. -2. **`mempool.nix` module**: configures mariadb, nginx (includes - `mempool-nginx-conf` from the package) and the backend's JSON config. - It follows NixOS changes to the mysql and nginx modules and mempool's - config schema. Drop its `fulcrum` option along with fulcrum. -3. **`bitcoind.nix`**: tracks Bitcoin Core config changes across major - versions (nixpkgs moves bitcoind on its own schedule; 32.1 today). It - disables NixOS's own `services/networking/bitcoind.nix`, so watch for - that module being renamed or split. That `disabledModules` path is - in `modules.nix`. -4. **`lnd.nix`**: tracks lnd config changes. It uses `lndinit` from - `pkgs/lndinit/`, which is **0.1.3** while nixpkgs and upstream are at - **0.1.38**. Switch to `pkgs.lndinit` and delete `pkgs/lndinit/`; check - that `gen-seed` and `init-wallet` flags still match. Also drop its - clightning port-conflict assertion. -5. **Tor plumbing** (`onion-services.nix`, `onion-addresses.nix`, - `nbLib.tor`): built on `services.tor.relay.onionServices` and - `tor.client.socksListenAddress`, which NixOS has kept stable for years. - Low churn. -6. **Secrets (`secrets/`)**: generates RPC passwords, the lnd cert and - similar on the host via `setup-secrets`. It's mostly shell and openssl, - so low churn. Note that nix-pleb uses sops for everything else; moving - these to sops would remove this too, at the cost of a migration on a - live node. -7. **`electrs.nix`, `nodeinfo.nix`, `operator.nix`, `security.nix`, - `nix-bitcoin.nix`**: small. The package comes from nixpkgs. Remove the - dead service entries from `nodeinfo.nix` (clightning, liquidd, - joinmarket-ob-watcher…) along with those services. -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 or in a VM test. - -### Per-release checklist - -On each NixOS release, or each nixpkgs bump in nix-pleb: - -1. `nix build .#nixosConfigurations.squirtle.config.system.build.toplevel` - in nix-pleb. Evaluation errors land in this fork's modules. -2. If mempool or Node changed, build `services.mempool.package` and - `services.mempool.frontend.package` first, and update the hashes. -3. Switch squirtle and check that bitcoind, lnd, electrs, mempool and - nginx are running. Hardening regressions don't show at build time. - If one fails, `nixos-rebuild switch --rollback`. - -## Testing - -There is no test suite. The fork isn't distributed and only squirtle -consumes it, so problems are handled as they show up on squirtle, with -rollback as the fallback. A regtest VM test mirroring squirtle was -written and then dropped as not worth maintaining; if runtime breakage -becomes frequent, upstream's `test/tests.py` (in git history before -branch `slim`) has per-service checks for all four services to start -from. - -## Suggested order - -Each step should leave squirtle's evaluated system unchanged on 26.05. -Compare `toplevel.drvPath` before and after, as was done for the i2pd -patch. - -1. Remove unused services, their packages, python-packages and - `bitcoind_29`. Edit `modules.nix`, `nodeinfo.nix`, `onion-services.nix`, - `enable-tor.nix`, `backups.nix`, `versioning.nix`, `obsolete-options.nix` - and `netns-isolation.nix` only enough to drop references. Expect the - drvPath to change slightly here, because nodeinfo's script and the - module set shrink. -2. Remove netns-isolation, i2p support, backups, versioning, - obsolete-options and deployment, and abandon branch `nixos-26.11`'s - compatibility patch. -3. Move what squirtle uses from the presets into nix-pleb's - `squirtle/services.nix`, stop importing `secure-node.nix`, and delete - `presets/`. -4. Drop `pinned.nix` and the extra flake inputs; switch to nixpkgs `lndinit`. -5. Remove `test/`, `examples/`, `dev/`, `docs/` and `helper/` (except - `update-fixed-output-derivation.sh`, used by `pkgs/mempool/generate.sh`) - and replace upstream's README with a short one (keep this file). -6. Rebuild squirtle on 26.11 in nix-pleb. diff --git a/docs/maintenance.md b/docs/maintenance.md new file mode 100644 index 0000000..f29bc5c --- /dev/null +++ b/docs/maintenance.md @@ -0,0 +1,116 @@ +# 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..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.