13.1. Bitcoin Depolymerizer Setup Manual#

depolymerizer-bitcoin is a bitcoin blockhain Taler adapter.

This manual targets system administrators who want to install and operate a Bictoin GNU Taler Depolymerizer

In this manual, we explain how to setup a depolymerizer.

13.1.1. Installation of the Bitcoin Depolymerizer #

13.1.1.1. Installing on Debian #

To install the depolymerizer, you can now simply run:

# apt install bitcoin-depolymerizer

13.1.1.2. Installing on Ubuntu #

To install the depolymerizer, you can now simply run:

# apt install bitcoin-depolymerizer

13.1.1.3. Building from source #

Bitcoin Depolymerizer belongs to the Depolymerization project, and can be downloaded via Git:

$ git clone git://git.taler.net/depolymerization
$ cd depolymerization

You will need the latest version of the rust stable toolchain and a C toolchain:

$ sudo apt install rustup build-essential
$ rustup toolchain install stable

Then from top-level run:

$ ./bootstrap

13.1.1.3.1. Install deb package #

To install the depolymerizer as a Debian/Ubuntu package with an automated secure setup and systemd services:

$ sudo apt install debhelper
$ make deb
$ sudo dpkg -i ../depolymerizer-bitcoin*.deb

If the previous steps succeeded, the depolymerizer-bitcoin command should be found in the $PATH.

13.1.1.3.2. Install binaries #

To install the depolymerizer binaries and default configuration localy run:

$ ./configure --prefix=$PREFIX
$ make install

If the previous steps succeeded, the depolymerizer-bitcoin command should be found in the $PATH.

13.1.1.4. Services, users, groups and file system hierarchy #

The depolymerizer-bitcoin package will create several system users to compartmentalize different parts of the system:

depolymerizer-bitcoin-httpd: runs the HTTP daemon with the API logic.
depolymerizer-bitcoin-worker: runs the worker daemon with the bitcoind node.
depolymerizer-bitcoin-node: runs the bitcoind node daemon interacting.
postgres: runs the PostgreSQL database (from postgresql package).

The depolymerizer setup uses the following system groups:

depolymerizer-bitcoin-db: group for all users with direct database access, specifically depolymerizer-bitcoin-httpd and depolymerizer-bitcoin-worker.
depolymerizer-bitcoin-cookie: group for all users with access to the bicoind cookie file, specifically depolymerizer-bitcoin-worke and depolymerizer-bitcoin-node.

The package will deploy systemd service files in /usr/lib/systemd/system/ for the various components:

depolymerizer-bitcoin-httpd.service: adapter REST API.
depolymerizer-bitcoin-httpd.socket: systemd socket activation for the HTTP daemon.
depolymerizer-bitcoin-worker.service: worker daemon with the bitcoind node.
depolymerizer-bitcoin-node.service: bitcoin node.
depolymerizer-bitcoin.target: main target for the depolymerizer to be operational.

The deployment creates the following key locations in the system:

/etc/depolymerizer-bitcoin/: configuration files.
/run/depolymerizer-bitcoin/: contains the UNIX domain sockets for inter-process communication (IPC).
/var/lib/bitcoind: serves as the $HOME for depolymerizer-bitcoin-node and contains the bitcoind node data and cookie files.

13.1.2. Installation of the Bitcoin node #

You need to install bitcoind & bitcoin-cli yourself, you can install them from the Bitcoin Core website.

$ curl -L https://bitcoincore.org/bin/bitcoin-core-29.0/bitcoin-29.0-x86_64-linux-gnu.tar.gz | tar xz
$ sudo cp bitcoin-29.0/bin/bitcoin* /usr/bin
$ rm -r bitcoin-29.0

13.1.3. Starting a local Bitcoin node #

13.1.3.1. Using package script #

Start the node service:

$ sudo systemctl start depolymerizer-bitcoin-node

Then check if the node is running:

$ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf getblockchaininfo

13.1.3.2. Simple setup #

You need to edit bitcoind default configuration:

$HOME/.bitcoin/bitcoin.conf#

txindex=1 # Enable full transaction indexes
rpcservertimeout=0 # Disable RPC timeout

Start the node daemon:

$ bitcoind

In another terminal check if the node is running:

$ bitcoin-cli getblockchaininfo

13.1.4. Configuration Fundamentals #

This chapter provides fundamental details about the adapter configuration.

The configuration for all adapter components uses a single configuration file as entry point: /etc/depolymerizer-bitcoin/depolymerizer-bitcoin.conf.

System defaults are automatically loaded from files in /usr/share/depolymerizer-bitcoin/config.d. These default files should never be modified.

The default configuration depolymerizer-bitcoin.conf configuration file also includes all configuration files in /etc/depolymerizer-bitcoin/conf.d. The settings from files in conf.d are only relevant to particular components of an adapter, while depolymerizer-bitcoin.conf contains settings that affect all adapter components.

The directory /etc/depolymerizer-bitcoin/secrets contains configuration file snippets with values that should only be readable to certain users. They are included with the @inline-secret@ directive and should end with .secret.conf.

To view the entire configuration annotated with the source of each configuration option, you can use the depolymerizer-bitcoin config helper:

# depolymerizer-bitcoin config dump --diagnostics

13.1.5. Bitcoin Depolymerizer Setup #

13.1.5.1. Using package script #

13.1.5.1.1. Database setup #

The configuration file must include a connection string that tells the depolymerizer how it should connect to the database. The default is:

/etc/depolymerizer-bitcoin/secrets/depolymerizer-bitcoin-db.secret.conf#

[depolymerizer-bitcoindb-postgres]
config = postgres:///depolymerizer-bitcoin

If the database is run on a different host, please follow the instructions from the PostgreSQL manual for configuring remote access.

Assuming the configuration is correct, the following command initializes (or upgrades) the database schema using: You can then use a script to automate a secure database setup:

$ sudo depolymerizer-bitcoin-dbconfig

13.1.5.1.2. Worker setup #

You will need a bitcoin wallet to sync, you can either create:

$ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf createwallet $WALLET false false $PASSWORD

Or use an existing one:

$ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf loadwallet $WALLET

You also need to choose an address from you wallet to use as it’s unique Taler identifier. You can generate a new address using:

$ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf -rpcwallet=$WALLET getnewaddress

Update the configuration files:

/etc/depolymerizer-bitcoin/depolymerizer-bitcoin.conf#

[depolymerizer-bitcoin]
CURRENCY = BTC
WALLET = $ADDRESS
NAME = John Smith S.A.

/etc/depolymerizer-bitcoin/conf.d/depolymerizer-bitcoin-worker.conf#

[depolymerizer-bitcoin-worker]
WALLET_NAME = $WALLET

/etc/depolymerizer-bitcoin/secrets/depolymerizer-bitcoin-worker.secret.conf#

[depolymerizer-bitcoin-worker]
PASSWORD = $PASSWORD

And finaly run the setup process:

$ sudo -u depolymerizer-bitcoin-worker depolymerizer-bitcoin setup

13.1.5.1.3. Server setup #

Update the configuration files:

/etc/depolymerizer-bitcoin/conf.d/depolymerizer-bitcoin-httpd.conf#

[depolymerizer-bitcoin-httpd-wire-gateway-api]
ENABLED = YES

/etc/depolymerizer-bitcoin/secrets/depolymerizer-bitcoin-httpd.secret.conf#

[depolymerizer-bitcoin-httpd-wire-gateway-api]
AUTH_METHOD = bearer
TOKEN = $SECRET_TOKEN

Check the server is correctly configured:

$ sudo -u depolymerizer-bitcoin-httpd depolymerizer-bitcoin serve --check

13.1.5.2. Simple setup #

13.1.5.2.1. Database setup #

The configuration file must include a connection string that tells the depolymerizer how it should connect to the database. The default is:

$CONFIG_FILE#

[depolymerizer-bitcoindb-postgres]
config = postgres:///depolymerizer-bitcoin

You must make sure that this database exists and is accessible to the user running the depolymerizer before continuing. If the database is run on a different host, please follow the instructions from the PostgreSQL manual for configuring remote access.

Assuming that the configuration file exists at $CONFIG_FILE, the following command initializes (or upgrades) the database schema:

$ depolymerizer-bitcoin -c "$CONFIG_FILE" dbinit

You will need a bitcoin wallet to sync, you can either create:

$ bitcoin-cli createwallet $WALLET false false $PASSWORD

Or use an existing one:

$ bitcoin-cli loadwallet $WALLET

You also need to choose an address from you wallet to use as it’s unique Taler identifier. You can generate a new address using:

$ bitcoin-cli -rpcwallet=$WALLET getnewaddress

Update the configuration files:

$CONFIG_FILE#

[depolymerizer-bitcoin]
CURRENCY = BTC
WALLET = $ADDRESS
NAME = John Smith S.A.

[depolymerizer-bitcoin-worker]
WALLET_NAME = $WALLET
PASSWORD = $PASSWORD

And finaly run the setup process:

$ depolymerizer-bitcoin -c "$CONFIG_FILE" setup

13.1.5.2.2. Server setup #

Update the configuration files:

$CONF_FILE#

[depolymerizer-bitcoin-httpd-wire-gateway-api]
ENABLED = YES
AUTH_METHOD = bearer
TOKEN = $SECRET_TOKEN

Check the server is correctly configured:

$ depolymerizer-bitcoin -c "$CONF_FILE" serve --check

13.1.6. Configuring bitcoind #

Here are some bitcoind configuration you might want to change:

bitcoin.conf#

# bitcoin transactions fees can exceed taler wire fees, putting
your wire in bankruptcy. You must specify an acceptable transaction fee cap.
maxtxfee=?

13.1.7. Configuring Bitcoin Depolymerizer #

Here are some bitcoind configuration you might want to change:

[depolymerizer-bitcoin]
# Number of blocks to consider a transactions durable
# The default is the recommended value
# Lowering it make the confirmation process faster (more user friendly)
# But it make the depolymerizer more sensible to adversarial reorg
CONFIRMATION = 6

# Amount to keep when bouncing malformed credit
# Default is 0 as the mining fee is always paid by the creditor
BOUNCE_FEE   = 0.00001

13.1.7.1. Process lifetime #

You may want to restart depolymerization processes regularly to improve stability (ex. fix memory fragmentation). It is possible to configure a lifetime that triggers a graceful shutdown every time a specific amount of work has been done.

[depolymerizer-bitcoin-worker]
# Number of worker's loops before worker shutdown (0 means never)
LIFETIME = 0

[depolymerizer-bitcoin-httpd]
# Number of requests to serve before server shutdown (0 means never)
LIFETIME = 0

13.1.7.2. Stuck transaction #

When we send a transaction with a fee too small, it may not be confirmed in a timely fashion. To unstuck those transactions, it is possible to replace them with other transactions with more fees. Depolymerizer can be configured to do this automatically:

[depolymerizer-bitcoin-worker]
# Delay in seconds before bumping an unconfirmed transaction fee (0 means never)
BUMP_DELAY = 0

13.1.8. Deployment #

This chapter describes how to deploy the depolymerizer once the basic installation and configuration are completed.

13.1.8.1. Serving #

The depolymerizer can serve HTTP over both TCP and UNIX domain socket.

The following options are to be configured in the section [depolymerizer-bitcoin-httpd]:

SERVE: Must be set to tcp to serve HTTP over TCP, or unix to serve HTTP over a UNIX domain socket.
PORT: Set to the TCP port to listen on if SERVE is tcp.
UNIXPATH: Set to the UNIX domain socket path to listen on if SERVE is unix.
UNIXPATH_MODE: Number giving the mode with the access permission mask
for the UNIXPATH (i.e. 660 = rw-rw---). Make sure to set it in such a way that your depolymerizer has permissions to access the UNIX domain socket. The default (660) assumes that the reverse proxy is a member of the group under which the depolymerizer HTTP server is running.

13.1.8.2. Reverse Proxy Setup #

By default, the depolymerizer-bitcoin-httpd service listens for HTTP connections on a UNIX domain socket. To make the service publicly available, a reverse proxy such as nginx should be used. We strongly recommend to configure nginx to use TLS.

The depolymerizer-bitcoin-bank package ships with a sample configuration that can be enabled in nginx:

# vim /etc/nginx/sites-available/depolymerizer-bitcoin
< ... customize configuration ... >
# ln -s /etc/nginx/sites-available/depolymerizer-bitcoin /etc/nginx/sites-enabled/depolymerizer-bitcoin
# systemctl reload nginx

With this last step, we are finally ready to launch the main depolymerizer process.

13.1.8.3. Launching the depolymerizer #

$ sudo systemctl start depolymerizer-bitcoin.target

Bitcoin Depolymerizer Setup Manual

Contents

13.1. Bitcoin Depolymerizer Setup Manual#