Remove upstream tests, docs, examples, dev env and release tooling
Replace upstream's README with a short one for this fork, and add docs/fork-maintenance.md describing what was removed and how to maintain the rest. Keeps helper/update-fixed-output-derivation.sh for pkgs/mempool/generate.sh. There is no test suite. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,135 +1,60 @@
|
||||
> [!WARNING]
|
||||
> **Archived and unmaintained as of August 13, 2026.**
|
||||
> v0.0.139 is the final release; there will be no further updates or security fixes.
|
||||
# nix-bitcoin (satstack fork)
|
||||
|
||||
<p align="center">
|
||||
<img
|
||||
width="320"
|
||||
src="docs/img/nix-bitcoin-logo.png"
|
||||
alt="nix-bitcoin logo">
|
||||
</p>
|
||||
<br/>
|
||||
<p align="center">
|
||||
<a href="https://github.com/fort-nix/nix-bitcoin/actions" target="_blank">
|
||||
<img src="https://github.com/fort-nix/nix-bitcoin/actions/workflows/test.yml/badge.svg?branch=master"
|
||||
alt="Github Actions status">
|
||||
</a>
|
||||
<a href="https://github.com/fort-nix/nix-bitcoin/releases/latest" target="_blank">
|
||||
<img src="https://img.shields.io/github/v/release/fort-nix/nix-bitcoin" alt="GitHub tag (latest SemVer)">
|
||||
</a>
|
||||
<a href="https://github.com/fort-nix/nix-bitcoin/commits/master" target="_blank">
|
||||
<img src="https://img.shields.io/github/commit-activity/y/fort-nix/nix-bitcoin" alt="GitHub commit activity">
|
||||
</a>
|
||||
<a href="https://github.com/fort-nix/nix-bitcoin/graphs/contributors" target="_blank">
|
||||
<img src="https://img.shields.io/github/contributors-anon/fort-nix/nix-bitcoin" alt="GitHub contributors">
|
||||
</a>
|
||||
<a href="https://github.com/fort-nix/nix-bitcoin/releases" target="_blank">
|
||||
<img src="https://img.shields.io/github/downloads/fort-nix/nix-bitcoin/total" alt="GitHub downloads">
|
||||
</a>
|
||||
</p>
|
||||
<br/>
|
||||
NixOS modules for a Bitcoin node running **bitcoind, lnd, electrs and
|
||||
mempool**, with Tor onion services and host-generated secrets.
|
||||
|
||||
nix-bitcoin is a collection of Nix packages and NixOS modules for easily installing **full-featured Bitcoin nodes** with an emphasis on **security**.
|
||||
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.
|
||||
|
||||
Overview
|
||||
---
|
||||
nix-bitcoin can be used for personal or merchant wallets, public infrastructure or
|
||||
for Bitcoin application backends. In all cases, the aim is to provide security and
|
||||
privacy by default. However, while nix-bitcoin is used in production today, it is
|
||||
still considered experimental.
|
||||
## Usage
|
||||
|
||||
nix-bitcoin nodes can be deployed on dedicated hardware, virtual machines or containers.
|
||||
The Nix packages and NixOS modules can be used independently and combined freely.
|
||||
```nix
|
||||
# flake.nix
|
||||
inputs.nix-bitcoin = {
|
||||
url = "git+ssh://gitea@gitea.satstack.dev/pleb/nix-bitcoin.git";
|
||||
inputs.nixpkgs.follows = "nixpkgs";
|
||||
};
|
||||
|
||||
nix-bitcoin is built on top of Nix and [NixOS](https://nixos.org/) which provide powerful abstractions to keep it highly customizable and
|
||||
maintainable. Testament to this are nix-bitcoin's robust security features and its potent test framework. However,
|
||||
running nix-bitcoin does not require any previous experience with the Nix ecosystem.
|
||||
# in a nixosSystem's modules
|
||||
inputs.nix-bitcoin.nixosModules.default
|
||||
```
|
||||
|
||||
Get started
|
||||
---
|
||||
- See the [examples](examples/README.md) for an overview of all features.
|
||||
- To setup a new node from scratch, see the [installation instructions](docs/install.md).
|
||||
- To add nix-bitcoin to an existing NixOS configuration, see [importable-configuration.nix](examples/importable-configuration.nix)
|
||||
and the [Flake example](examples/flakes/flake.nix).
|
||||
```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;
|
||||
};
|
||||
|
||||
Docs
|
||||
---
|
||||
Hint: To show a table of contents, click the button () in the
|
||||
top left corner of the documents.
|
||||
services.tor = { enable = true; client.enable = true; };
|
||||
|
||||
<!-- TODO-EXTERNAL: -->
|
||||
<!-- Change query to `nix-bitcoin` when upstream search has been fixed -->
|
||||
* [NixOS options search](https://search.nixos.org/flakes?channel=unstable&sort=relevance&type=options&query=bitcoin)
|
||||
* [Hardware requirements](docs/hardware.md)
|
||||
* [Installation](docs/install.md)
|
||||
* [Configuration and maintenance](docs/configuration.md)
|
||||
* [Using services](docs/services.md)
|
||||
* [FAQ](docs/faq.md)
|
||||
services.bitcoind = { enable = true; tor.proxy = true; };
|
||||
services.lnd.enable = true;
|
||||
services.electrs.enable = true;
|
||||
services.mempool.enable = true; # also enables electrs
|
||||
}
|
||||
```
|
||||
|
||||
Features
|
||||
---
|
||||
A [configuration preset](modules/presets/secure-node.nix) for setting up a secure node
|
||||
* All applications use Tor for outbound connections and support accepting inbound connections via onion services.
|
||||
Packages come from the consumer's nixpkgs (`pkgs.bitcoind`, `pkgs.lnd`,
|
||||
`pkgs.electrs`, `pkgs.lndinit`). The only package built here is mempool
|
||||
(`pkgs/mempool/`).
|
||||
|
||||
NixOS modules ([src](modules/modules.nix))
|
||||
* Application services
|
||||
* [bitcoind](https://github.com/bitcoin/bitcoin)
|
||||
* [clightning](https://github.com/ElementsProject/lightning) with support for announcing an onion service
|
||||
and [database replication](docs/services.md#setup-clightning-database-replication).\
|
||||
Available plugins:
|
||||
* [clboss](https://github.com/ZmnSCPxj/clboss): automated C-Lightning Node Manager
|
||||
* [currencyrate](https://github.com/lightningd/plugins/tree/master/currencyrate): currency converter
|
||||
* [monitor](https://github.com/lightningd/plugins/tree/master/monitor): helps you analyze the health of your peers and channels
|
||||
* [rebalance](https://github.com/lightningd/plugins/tree/master/rebalance): keeps your channels balanced
|
||||
* [trustedcoin](https://github.com/nbd-wtf/trustedcoin) ([experimental](docs/services.md#trustedcoin)): replaces bitcoind with trusted public explorers
|
||||
* [zmq](https://github.com/lightningd/plugins/tree/master/zmq): publishes notifications via ZeroMQ to configured endpoints
|
||||
* [lnd](https://github.com/lightningnetwork/lnd) with support for announcing an onion service and [static channel backups](https://github.com/lightningnetwork/lnd/blob/master/docs/recovery.md)
|
||||
* [Lightning Loop](https://github.com/lightninglabs/loop)
|
||||
* [Lightning Pool](https://github.com/lightninglabs/pool)
|
||||
* [charge-lnd](https://github.com/accumulator/charge-lnd): policy-based channel fee manager
|
||||
* [lndconnect](https://github.com/LN-Zap/lndconnect): connect your wallet to lnd or
|
||||
clightning [via WireGuard](./docs/services.md#use-zeus-mobile-lightning-wallet-via-wireguard) or
|
||||
[Tor](./docs/services.md#use-zeus-mobile-lightning-wallet-via-tor)
|
||||
* [Ride The Lightning](https://github.com/Ride-The-Lightning/RTL): web interface for `lnd` and `clightning`
|
||||
* [mempool](https://github.com/mempool/mempool): Bitcoin visualizer, explorer, and API service
|
||||
* [electrs](https://github.com/romanz/electrs): Electrum server
|
||||
* [fulcrum](https://github.com/cculianu/Fulcrum): Electrum server (see [the module](modules/fulcrum.nix) for a comparison with electrs)
|
||||
* [btcpayserver](https://github.com/btcpayserver/btcpayserver)
|
||||
* [liquid](https://github.com/elementsproject/elements): federated sidechain
|
||||
* [JoinMarket](https://github.com/joinmarket-org/joinmarket-clientserver)
|
||||
* [JoinMarket Orderbook Watcher](https://github.com/JoinMarket-Org/joinmarket-clientserver/blob/master/docs/orderbook.md)
|
||||
* [bitcoin-core-hwi](https://github.com/bitcoin-core/HWI)
|
||||
* Helper
|
||||
* [netns-isolation](modules/netns-isolation.nix): isolates applications on the network-level via network namespaces
|
||||
* [nodeinfo](modules/nodeinfo.nix): script which prints info about the node's services
|
||||
* [backups](modules/backups.nix): duplicity backups of all your node's important files
|
||||
* [operator](modules/operator.nix): configures a non-root user who has access to client tools (e.g. `bitcoin-cli`, `lightning-cli`)
|
||||
## What's in the repo
|
||||
|
||||
Security
|
||||
---
|
||||
See [SECURITY.md](SECURITY.md) for the security policy and how to report a vulnerability.
|
||||
| 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/lib.nix` | systemd hardening and Tor helpers shared by the modules |
|
||||
|
||||
nix-bitcoin aims to achieve a high degree of security by building on the following principles:
|
||||
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.
|
||||
|
||||
* **Simplicity:** Only services enabled in `configuration.nix` and their dependencies are installed, support for [doas](https://github.com/Duncaen/OpenDoas) ([sudo alternative](https://lobste.rs/s/efsvqu/heap_based_buffer_overflow_sudo_cve_2021#c_c6fcfa)), code is continuously reviewed and refined.
|
||||
* **Integrity:** The Nix package manager guarantees that all dependencies are exactly specified, packages can be built from source to reduce reliance on binary caches, nix-bitcoin merge commits are signed, all commits are approved by multiple nix-bitcoin developers, upstream packages are cryptographically verified where possible, we use this software ourselves.
|
||||
* **Principle of Least Privilege:** Services operate with least privileges; they each have their own user and are restricted further with [systemd features](pkgs/lib.nix), [RPC whitelisting](modules/bitcoind-rpc-public-whitelist.nix) and [netns-isolation](modules/netns-isolation.nix). There's a non-root user *operator* to interact with the various services.
|
||||
* **Defense-in-depth:** nix-bitcoin supports a [hardened kernel](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/profiles/hardened.nix), services are confined through discretionary access control, Linux namespaces, [dbus firewall](modules/security.nix) and seccomp-bpf with continuous improvements.
|
||||
## License
|
||||
|
||||
Note that if the machine you're deploying *from* is insecure, there is nothing nix-bitcoin can do to protect itself.
|
||||
|
||||
Security fund
|
||||
---
|
||||
The nix-bitcoin security fund is a 2 of 3 bitcoin multisig address open for donations, used to reward
|
||||
security researchers who discover vulnerabilities in nix-bitcoin or its upstream dependencies.\
|
||||
See [Security Fund](./SECURITY.md#nix-bitcoin-security-fund) for details.
|
||||
|
||||
Developing
|
||||
---
|
||||
See [dev/README](./dev/README.md).
|
||||
|
||||
Troubleshooting
|
||||
---
|
||||
If you are having problems with nix-bitcoin check the [FAQ](docs/faq.md) or submit an issue.\
|
||||
There's also a Matrix room at [#general:nixbitcoin.org](https://matrix.to/#/#general:nixbitcoin.org).\
|
||||
We are always happy to help.
|
||||
MIT, see [LICENSE](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user