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:
@@ -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.
|
||||||
@@ -4,16 +4,32 @@ NixOS modules for a Bitcoin node running **bitcoind, lnd, electrs and
|
|||||||
mempool**, with Tor onion services and host-generated secrets.
|
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),
|
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
|
which was archived in August 2026. Upstream's tree is preserved on the
|
||||||
been removed. See [docs/fork-maintenance.md](docs/fork-maintenance.md) for
|
`master` branch. Development happens on `main`, and releases are tagged
|
||||||
what was cut, what's left, and the per-release checklist.
|
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
|
## Usage
|
||||||
|
|
||||||
|
Pin a release tag. The repo's default branch is still upstream's `master`.
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
# flake.nix
|
# flake.nix
|
||||||
inputs.nix-bitcoin = {
|
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";
|
inputs.nixpkgs.follows = "nixpkgs";
|
||||||
};
|
};
|
||||||
|
|
||||||
@@ -48,12 +64,13 @@ Packages come from the consumer's nixpkgs (`pkgs.bitcoind`, `pkgs.lnd`,
|
|||||||
| Path | Contents |
|
| Path | Contents |
|
||||||
|---|---|
|
|---|---|
|
||||||
| `modules/` | `bitcoind`, `lnd`, `electrs`, `mempool`, plus `secrets/`, `operator`, `security`, `onion-services`, `onion-addresses`, `nodeinfo` |
|
| `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 |
|
| `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,
|
There is no test suite. Build your host's system before switching to a
|
||||||
and roll back (`nixos-rebuild switch --rollback`) if a service fails at
|
new release, and roll back (`nixos-rebuild switch --rollback`) if a
|
||||||
runtime.
|
service fails at runtime.
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
|
|||||||
@@ -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.
|
|
||||||
@@ -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.
|
||||||
Reference in New Issue
Block a user