Go to file
Jonas Nick 06cba7b519
Merge #249: Add regtest support
9951f10e74 test: add scenario 'regtest' (Erik Arvstedt)
1f96ca67c5 electrs test: make service shutdown optional (Erik Arvstedt)
eb42fc8e06 test: extract test 'joinmarket-yieldgenerator' (Erik Arvstedt)
06b2ec5b02 joinmarket: add regtest support (Erik Arvstedt)
975b30c90e joinmarket: don't hardcode bitcoind rpc port (Erik Arvstedt)
031df4231f joinmarket: move comment out of config file (Erik Arvstedt)
848c4c6eda joinmarket: add variable 'bitcoind' (Erik Arvstedt)
96b08f5d60 btcpayserver: add regtest support (Erik Arvstedt)
bd2145dc77 btcpayserver: add 'port' option (Erik Arvstedt)
001f8fe8d3 btcpayserver: use option bitcoind.rpc.port (Erik Arvstedt)
6f4715ac2a electrs: add regtest support (Erik Arvstedt)
46efd141a1 lightning-loop: add regtest support (Erik Arvstedt)
75ec85bea2 lnd: add regtest support (Erik Arvstedt)
1935c252ec lnd: remove redundant option 'bitcoind-host' (Erik Arvstedt)
b1a8629223 lnd: add variable 'bitcoind' (Erik Arvstedt)
937aee0062 spark-wallet: add regtest support (Erik Arvstedt)
47d611b5ef spark-wallet: use tor rate provider only when enforceTor (Erik Arvstedt)
127b186c3c spark-wallet: simplify start script (Erik Arvstedt)
0f32f3c99e clightning: add regtest support (Erik Arvstedt)
c24ac5d363 clightning: remove redundant option 'bitcoin-rpcconnect' (Erik Arvstedt)
abd32cde30 clightning: enable config file read access for group (Erik Arvstedt)
ddadaed3da clightning: always use bind-addr in config (Erik Arvstedt)
9e928e2097 bitcoind: add regtest support (Erik Arvstedt)

Pull request description:

ACKs for top commit:
  jonasnick:
    ACK 9951f10e74

Tree-SHA512: 42e2d95755a16b59044e400bc4c9d891bfc22eb73b920fdcf29e607f7df88de599bec99677cf49be7c275c0113a2224a45b1f47f40c029878421eae1a44f3254
2020-10-17 13:04:27 +00:00
docs docs: fix joinmarket usage instructions 2020-09-22 17:32:08 +00:00
examples add module 'versioning' 2020-10-16 23:23:00 +02:00
helper push-release: fix bug where assets are not pushed 2020-09-24 16:10:23 +00:00
modules Merge #249: Add regtest support 2020-10-17 13:04:27 +00:00
pkgs extra-container: pre-release -> 0.5-pre 2020-10-16 15:53:32 +02:00
test test: add scenario 'regtest' 2020-10-16 23:55:13 +02:00
.gitignore Change the nix-bitcoin deployment from forking this repo to importing the module 2020-03-24 21:43:17 +00:00
.travis.yml test: add non-secure-node eval test 2020-10-16 15:53:34 +02:00
default.nix simplify overlay.nix 2020-01-09 10:43:29 +01:00
LICENSE Add license 2019-01-02 14:03:52 +00:00
overlay.nix simplify overlay.nix 2020-01-09 10:43:29 +01:00
README.md examples/deploy-container: use new extra-container features 2020-10-16 15:53:34 +02:00
shell.nix Clean up development shell.nix 2020-03-30 10:49:15 +02:00

nix-bitcoin

Build Status

Nix packages and nixos modules for easily installing Bitcoin nodes and higher layer protocols with an emphasis on security. This is a work in progress - don't expect it to be bug-free, secure or stable.

The default configuration sets up a Bitcoin Core node and c-lightning. The user can enable spark-wallet in configuration.nix to make c-lightning accessible with a smartphone using spark-wallet. A simple webpage shows the lightning nodeid and links to nanopos letting the user receive donations. It also includes elements-daemon. Outbound peer-to-peer traffic is forced through Tor, and listening services are bound to onion addresses.

A demo installation is running at http://6tr4dg3f2oa7slotdjp4syvnzzcry2lqqlcvqkfxdavxo6jsuxwqpxad.onion. The following screen cast shows a fresh deployment of a nix-bitcoin node.

The goal is to make it easy to deploy a reasonably secure Bitcoin node with a usable wallet. It should allow managing bitcoin (the currency) effectively and providing public infrastructure. It should be a reproducible and extensible platform for applications building on Bitcoin.

Examples

The easiest way to try out nix-bitcoin is to use one of the provided examples.

git clone https://github.com/fort-nix/nix-bitcoin
cd nix-bitcoin/examples/
nix-shell

The following example scripts set up a nix-bitcoin node according to examples/configuration.nix and then shut down immediately. They leave no traces (outside of /nix/store) on the host system.

Tests

The internal test suite is also useful for exploring features.
The following run-tests.sh commands leave no traces (outside of /nix/store) on the host system.

git clone https://github.com/fort-nix/nix-bitcoin
cd nix-bitcoin/test

# Run a Python test shell inside a VM node
./run-tests.sh debug
print(succeed("systemctl status bitcoind"))

# Run a node in a container. Requires systemd and root privileges.
./run-tests.sh container
c systemctl status bitcoind

# Explore a single feature
./run-tests.sh --scenario electrs container

See run-tests.sh for a complete documentation.

Available modules

By default the configuration.nix provides:

  • bitcoind with outbound connections through Tor and inbound connections through a hidden service. By default loaded with banlist of spy nodes.
  • clightning with outbound connections through Tor, not listening
  • includes "nodeinfo" script which prints basic info about the node
  • adds non-root user "operator" which has access to bitcoin-cli and lightning-cli

In configuration.nix the user can enable:

  • a clightning hidden service
  • liquid
  • lightning charge
  • nanopos
  • an index page using nginx to display node information and link to nanopos
  • spark-wallet
  • electrs
  • recurring-donations, a module to repeatedly send lightning payments to recipients specified in the configuration.
  • bitcoin-core-hwi.
    • You no longer need extra software to connect your hardware wallet to Bitcoin Core. Use Bitcoin Core's own Hardware Wallet Interface with one configuration.nix setting.

The data directories of the services can be found in /var/lib on the deployed machines.

Installation

See install.md for a detailed tutorial.

Security

  • Simplicity: Only services you select in configuration.nix and their dependencies are installed, packages and dependencies are pinned, most packages are built from the nixos stable channel, with a few exceptions that are built from the nixpkgs unstable channel, builds happen in a sandboxed environment, code is continuously reviewed and refined.
  • Integrity: Nix package manager, NixOS and 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 options, there's a non-root user operator to interact with the various services.
  • Defense-in-depth: nix-bitcoin is built with a hardened kernel by default, services are confined through discretionary access control, Linux namespaces, and seccomp-bpf with continuous improvements.

Note that nix-bitcoin is still experimental. Also, by design if the machine you're deploying from is insecure, there is nothing nix-bitcoin can do to protect itself.

Hardware requirements

  • Disk space: 300 GB (235GB for Bitcoin blockchain + some room)
    • Bitcoin Core pruning is not supported at the moment because it's not supported by c-lightning. It's possible to use pruning but you need to know what you're doing.
  • RAM: 2GB of memory. ECC memory is better. Additionally, it's recommended to use DDR4 memory with targeted row refresh (TRR) enabled (https://rambleed.com/).

Tested hardware includes pcengine's apu2c4, GB-BACE-3150, GB-BACE-3160. Some hardware (including Intel NUCs) may not be compatible with the hardened kernel turned on by default (see https://github.com/fort-nix/nix-bitcoin/issues/39#issuecomment-517366093 for a workaround).

Usage

For usage instructions, such as how to connect to spark-wallet, electrs and the ssh Tor Hidden Service, see usage.md.

Troubleshooting

If you are having problems with nix-bitcoin check the FAQ or submit an issue. There's also a #nix-bitcoin IRC channel on freenode. We are always happy to help.

Docs