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
+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