Replace upstream's README with a short one for this fork, and add docs/fork-maintenance.md describing what was removed and how to maintain the rest. Keeps helper/update-fixed-output-derivation.sh for pkgs/mempool/generate.sh. There is no test suite. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
12 KiB
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.2.1, 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 dropspkgs/netns-exec/and the netns-only helpers inpkgs/lib.nix.- i2p support in
bitcoind.nix.i2pis false on squirtle. Dropping thei2poption,i2pSAMand theservices.i2pdblock makes the 26.11 compatibility patch on branchnixos-26.11unnecessary. Prefer this over that patch. backups.nix. It's off on squirtle; the secure-node preset only sets itsfrequency. 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) andobsolete-options.nix(145 lines). Both exist for migrating other people's configs across upstream releases. Squirtle has noconfigVersionset 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 withnixos-rebuildfrom 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.enabletor.proxy/tor.enforcedefaults for bitcoind, lnd, electrs, mempool (squirtle then overridesenforce = falseon bitcoind, lnd, electrs)- onion services for bitcoind, electrs and sshd, plus
onionAddresses.access.pleb nodeinfo.enable,operator.enable,dbusHideProcessInformationbitcoind.listen = true,bitcoind.dbCache = 1000- doas instead of sudo (
squirtle/configuration.nixalready 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 ofdocs/(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.shandkey-jonasnick.binare upstream's release signing.update-flake.{nix,sh}regeneratespkgs/pinned.nixand becomes unnecessary once pins are gone (below). Keepupdate-fixed-output-derivation.shonly 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:
pkgsUnstablesupplieslnd(squirtle overrides it), plusbitcoind-knots,clboss,fulcrumandlightning-loop(all unused).pkgs-25_05is 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:
- 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 pinnednodejs_22. It's at 3.2.1 against upstream's 3.3.2. Expect every version bump to need the hashes redone. Node 22 also has an end-of-life date, after which nixpkgs will dropnodejs_22and 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. mempool.nixmodule: configures mariadb, nginx (includesmempool-nginx-conffrom the package) and the backend's JSON config. It follows NixOS changes to the mysql and nginx modules and mempool's config schema. Drop itsfulcrumoption along with fulcrum.bitcoind.nix: tracks Bitcoin Core config changes across major versions (nixpkgs moves bitcoind on its own schedule; 32.1 today). It disables NixOS's ownservices/networking/bitcoind.nix, so watch for that module being renamed or split. ThatdisabledModulespath is inmodules.nix.lnd.nix: tracks lnd config changes. It useslndinitfrompkgs/lndinit/, which is 0.1.3 while nixpkgs and upstream are at 0.1.38. Switch topkgs.lndinitand deletepkgs/lndinit/; check thatgen-seedandinit-walletflags still match. Also drop its clightning port-conflict assertion.- Tor plumbing (
onion-services.nix,onion-addresses.nix,nbLib.tor): built onservices.tor.relay.onionServicesandtor.client.socksListenAddress, which NixOS has kept stable for years. Low churn. - Secrets (
secrets/): generates RPC passwords, the lnd cert and similar on the host viasetup-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. electrs.nix,nodeinfo.nix,operator.nix,security.nix,nix-bitcoin.nix: small. The package comes from nixpkgs. Remove the dead service entries fromnodeinfo.nix(clightning, liquidd, joinmarket-ob-watcher…) along with those services.- 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:
nix build .#nixosConfigurations.squirtle.config.system.build.toplevelin nix-pleb. Evaluation errors land in this fork's modules.- If mempool or Node changed, build
services.mempool.packageandservices.mempool.frontend.packagefirst, and update the hashes. - 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.
- Remove unused services, their packages, python-packages and
bitcoind_29. Editmodules.nix,nodeinfo.nix,onion-services.nix,enable-tor.nix,backups.nix,versioning.nix,obsolete-options.nixandnetns-isolation.nixonly enough to drop references. Expect the drvPath to change slightly here, because nodeinfo's script and the module set shrink. - Remove netns-isolation, i2p support, backups, versioning,
obsolete-options and deployment, and abandon branch
nixos-26.11's compatibility patch. - Move what squirtle uses from the presets into nix-pleb's
squirtle/services.nix, stop importingsecure-node.nix, and deletepresets/. - Drop
pinned.nixand the extra flake inputs; switch to nixpkgslndinit. - Remove
test/,examples/,dev/,docs/andhelper/(exceptupdate-fixed-output-derivation.sh, used bypkgs/mempool/generate.sh) and replace upstream's README with a short one (keep this file). - Rebuild squirtle on 26.11 in nix-pleb.