qusal/salt/sys-bitcoin/README.md

# sys-bitcoin

Bitcoin Core in Qubes OS.

## Table of Contents

* [Description](#description)
* [Installation](#installation)
* [Usage](#usage)
  * [Custom daemon parameters](#custom-daemon-parameters)
  * [Bitcoin Core GUI](#bitcoin-core-gui)
  * [Connect to a remote Bitcoin RPC](#connect-to-a-remote-bitcoin-rpc)
    * [Evaluation of remote Bitcoin RPC](#evaluation-of-remote-bitcoin-rpc)
    * [Configure the remote node](#configure-the-remote-node)
    * [Connect the qube to the remote node](#connect-the-qube-to-the-remote-node)
  * [Database on external drive](#database-on-external-drive)
* [Credits](#credits)

## Description

Setup a Bitcoin Daemon full-node qube named "sys-bitcoin", where you will
index the Bitcoin blockchain. A second non-networked qube named "bitcoin" can
manage a wallet and sign transactions.

By default, installation from upstream binaries will be used, but you can
choose to build from source if you prefer. Compiling from source will not have
the default configuration flags, but will be optimized to our use case.

The download of the Bitcoin source code or binaries as well as the connections
to the Bitcoin P2P network will happen over the Tor network.

If you already have a node on your network that has indexed the blockchain
already and has RPC enabled for remote clients, you can also connect to it,
preferably if it has transport encryption when connecting to the Bitcoin node
with an encrypted tunnel.

A disposable qube "disp-bitcoin-builder" will be created, based on
Whonix-Workstation, it will server to install and verify Bitcoin Core. After
the verification succeeds, files are copied to the template "tpl-sys-bitcoin".
This method was chosen so the client can be always offline and the build
artifacts are built on a machine that is not running the daemon and thus can
be copied to the template with a higher degree of trust.

At least `1TB` of disk space is required. At block `829054` (2024-02-05),
`642G` are used.

## Installation

- Top
```sh
qubesctl top.enable sys-bitcoin
qubesctl --targets=sys-bitcoin-gateway,tpl-sys-bitcoin,disp-sys-bitcoin-builder,sys-bitcoin,bitcoin state.apply
qubesctl top.disable sys-bitcoin
qubesctl state.apply sys-bitcoin.appmenus
```

- State
<!-- pkg:begin:post-install -->
```sh
qubesctl state.apply sys-bitcoin.create
qubesctl --skip-dom0 --targets=sys-bitcoin-gateway state.apply sys-bitcoin.configure-gateway
qubesctl --skip-dom0 --targets=tpl-sys-bitcoin state.apply sys-bitcoin.install
qubesctl --skip-dom0 --targets=disp-bitcoin-builder state.apply sys-bitcoin.configure-builder
qubesctl --skip-dom0 --targets=sys-bitcoin state.apply sys-bitcoin.configure
qubesctl --skip-dom0 --targets=bitcoin state.apply sys-bitcoin.configure-client
qubesctl state.apply sys-bitcoin.appmenus
```
<!-- pkg:end:post-install -->

If you prefer to build from source (will take approximately 1 hour to build):
```sh
qubesctl --skip-dom0 --targets=tpl-sys-bitcoin state.apply sys-bitcoin.install-source
qubesctl --skip-dom0 --targets=disp-bitcoin-builder state.apply sys-bitcoin.configure-builder-source
```

If you want to relay blocks (listening node):
```sh
qubesctl --skip-dom0 --targets=sys-bitcoin-gateway state.apply sys-bitcoin.configure-gateway-listen
qubesctl --skip-dom0 --targets=sys-bitcoin state.apply sys-bitcoin.configure-listen
```

Add the tag `bitcoin-client` to the client and install in the client template:
```sh
qubesctl --skip-dom0 --targets=tpl-QUBE state.apply sys-bitcoin.install-client
```


## Usage

The qube `sys-bitcoin` can:

- Index the Bitcoin blockchain connecting to peers over Tor;
- Connect to a remote Bitcoin RPC reachable over Tor; and
- Broadcast transactions over Tor.

The qube `bitcoin` can:

- Create wallet addresses; and
- Sign transactions.

### Custom daemon parameters

You can set extra parameters for the daemon in
`~/.bitcoin/conf.d/bitcoin.conf.local`, this file will never be changed
externally.

One of these parameters is `prune`, which reduces storage requirements by
deleting old blocks. The downside is that it can't serve old blocks, can't be
used to rescan old wallet and is incompatible to serve any Electrum Server.

You can enable pruning in `/home/user/.bitcoin/conf.d/bitcoin.conf.local` by
specifying how many `MiB` of block files to retain:
```cfg
prune=550
```

### Bitcoin Core GUI

Do not use the GUI in the `sys-bitcoin` qube to edit configuration, it won't
persist and `bitcoin-qt` cannot be run at the same time as `bitcoind`.

You can use the GUI in the `bitcoin` qube, specially useful for an easy-to-use
interface for the Bitcoin Core Wallet.

### Connect to a remote Bitcoin RPC

#### Evaluation of remote Bitcoin RPC

You may wish to connect to a remote Bitcoin node with RPC available to:

- Lower disk space usage and to lower resource consumption by not having
  multiple Bitcoin blockchains;
- Avoid changing  scripts and configurations that expect the connection to be
  working on `127.0.0.1:8332`, such as the Qrexec policy for connecting
  Bitcoind RPC to the Electrum Servers.

But there are huge disadvantages to this method:

- [Bitcoin Core RPC does not have transport encryption](https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.12.0.md#rpc-ssl-support-dropped).
  Therefore, this method is advised against unless you know how to enable
  transport encryption to connect to your Bitcoin RPC. If you run bitcoind on
  `sys-bitcoin`, you do not have to worry about transport encryption as
  communication is done securely via Qrexec.
- Bitcoin configuration cannot be changed remotely, therefore adding RPC
  Authentication for clients such as Electrum Servers have to be done
  manually.

The remote bitcoind setup is difficult to fit all user needs and requires you
to change a remote node we have no control over the configuration, therefore,
it is intended for advanced users only.

#### Configure the remote node

On the remote node:

- You must set in the node's `bitcoin.conf`, the following options to bind to
  the external interface: `rpcbind`, `bind` (Electrs),
  `whitelist=download@<ADDR>` (ElectRS), `zmqpubhashblock` (Fulcrum) and allow
  connections of the external IP of your upstream netvm via `rpcallowip`.
- Open the configured ports of the previous settings in the firewall to be
  reachable by the Qubes system.
- Generate RPC credentials (see `bitcoin/share/rpcauth/rpcauth.py`), add
  `rpcauth=` option to `bitcoin.conf` and save the `user` and `password` for
  later.
- Restart bitcoind to apply the configuration changes.

#### Connect the qube to the remote node

**Warning**: use of `sys-bitcoin` for the remote node connection is
discouraged as you either need to expose the node RPC port to an onion service
(preferably with Onion Authentication) or punch a hole in the Whonix firewall
so it can reach your LAN.

The following example uses the qube `sys-net` as a netvm that can connect
to your remote node running on the address `192.168.2.10`, RPC port `8332`,
P2P port `8333`, ZMQPUBHASHBLOCK port `8433`.

In `dom0`, create the user Qrexec policy to target the qube `sys-net` in
`/etc/qubes/policy.d/30-user.policy`:
```qrexecpolicy
## Getting Auth doesn't work with remote node.
qusal.BitcoinAuthGet * @anyvm @anyvm   deny

qubes.ConnectTCP +8332 @tag:bitcoin-client @default allow target=sys-net
qubes.ConnectTCP +8333 @tag:bitcoin-client @default allow target=sys-net
qubes.ConnectTCP +8433 @tag:bitcoin-client @default allow target=sys-net
qubes.ConnectTCP *     @tag:bitcoin-client @anyvm   deny
```

In the qube `sys-net`, add the `socat` command (only the ones you need) to the
file `/rw/config/rc.local`:
```sh
## RPC
socat TCP-LISTEN:8332,reuseaddr,fork,bind=127.0.0.1 TCP:192.168.2.10:8332 &
## P2P (ElectRS)
socat TCP-LISTEN:8333,reuseaddr,fork,bind=127.0.0.1 TCP:192.168.2.10:8333 &
## ZMQPubHashBlock (Fulcrum)
socat TCP-LISTEN:8433,reuseaddr,fork,bind=127.0.0.1 TCP:192.168.2.10:8433 &
```

In the Electrum Server qubes or any Bitcoin Client, `sys-electrumx`,
`sys-electrs`, `sys-fulcrum`, add the `qvm-connect-tcp` command to the file
`/rw/config/rc.local`:
```sh
## RPC
qvm-connnect-tcp ::8332
## P2P (ElectRS)
qvm-connnect-tcp ::8333
## ZMQPubHashBlock (Fulcrum)
qvm-connnect-tcp ::8433
```

Still in the Electrum Server qube, you will have to add the RPC authentication
you got from the remote node to `~/.bitcoin/.cookie`.

Restart the qubes you modified the configuration to check if the service is
starting automatically on boot.

### Database on external drive

Your machine might not have enough disk space to store the database and you
don't want to configure a remote client. Unfortunately, this method is
unsupported. It may be possible, but as mounting the drive requires user
intervention, you are on your own to adjust the database path.

If you have done this, please share a guide.

## Credits

- [qubenix](https://github.com/qubenix/qubes-whonix-bitcoin)