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.
|
||||
|
||||
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
|
||||
|
||||
|
||||
@@ -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