- 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>
78 lines
3.6 KiB
Markdown
78 lines
3.6 KiB
Markdown
# nix-bitcoin (satstack fork)
|
|
|
|
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. 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?ref=refs/tags/v0.1.0";
|
|
inputs.nixpkgs.follows = "nixpkgs";
|
|
};
|
|
|
|
# in a nixosSystem's modules
|
|
inputs.nix-bitcoin.nixosModules.default
|
|
```
|
|
|
|
```nix
|
|
{
|
|
nix-bitcoin = {
|
|
generateSecrets = true; # writes /etc/nix-bitcoin-secrets on the host
|
|
operator = { enable = true; name = "alice"; };
|
|
nodeinfo.enable = true;
|
|
onionServices.bitcoind.public = true;
|
|
};
|
|
|
|
services.tor = { enable = true; client.enable = true; };
|
|
|
|
services.bitcoind = { enable = true; tor.proxy = true; };
|
|
services.lnd.enable = true;
|
|
services.electrs.enable = true;
|
|
services.mempool.enable = true; # also enables electrs
|
|
}
|
|
```
|
|
|
|
Packages come from the consumer's nixpkgs (`pkgs.bitcoind`, `pkgs.lnd`,
|
|
`pkgs.electrs`, `pkgs.lndinit`). The only package built here is mempool
|
|
(`pkgs/mempool/`).
|
|
|
|
## What's in the repo
|
|
|
|
| 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, 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 your host's system before switching to a
|
|
new release, and roll back (`nixos-rebuild switch --rollback`) if a
|
|
service fails at runtime.
|
|
|
|
## License
|
|
|
|
MIT, see [LICENSE](LICENSE).
|