Files
plebandClaude Opus 5.5 aedda5bc86 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>
2026-11-16 08:40:23 -08:00

3.6 KiB

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

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