- 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>
117 lines
7.0 KiB
Markdown
117 lines
7.0 KiB
Markdown
# 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.
|