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>
This commit is contained in:
pleb
2026-11-16 08:40:23 -08:00
co-authored by Claude Opus 5.5
parent 230e5c539b
commit aedda5bc86
4 changed files with 184 additions and 265 deletions
+43
View File
@@ -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 "<summary>"`. 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.
+25 -8
View File
@@ -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
-257
View File
@@ -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.
+116
View File
@@ -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.<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.