Bitcoin Depolymerizer Setup Manual

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

9.1.1. Installation of the Bitcoin Depolymerizer#

9.1.1.1. Installing on Debian#

To install the GNU Taler Debian packages, first ensure that you have the right Debian distribution. At this time, the packages are built for Debian trixie.

You need to add a file to import the GNU Taler packages. Typically, this is done by adding a file /etc/apt/sources.list.d/taler.list that looks like this:

deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/debian trixie main

Next, you must import the Taler Systems SA public package signing key into your keyring and update the package lists:

# wget -O /etc/apt/keyrings/taler-systems.gpg \
    https://taler.net/taler-systems.gpg
# apt update

Note

You may want to verify the correctness of the Taler Systems SA key out-of-band.

Now your system is ready to install the official GNU Taler binary packages using apt.

To install the depolymerizer, you can now simply run:

# apt install bitcoin-depolymerizer

9.1.1.2. Installing on Ubuntu#

To install the GNU Taler Ubuntu packages, first ensure that you have the right Ubuntu distribution. At this time, the packages are built for Ubuntu Lunar and Ubuntu Jammy. Make sure to have universe in your /etc/apt/sources.list.d/ubuntu.sources (after main) as we depend on some packages from Ubuntu universe.

A typical /etc/apt/sources.list.d/taler.list file for this setup would look like this for Ubuntu Noble:

deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ noble main

Next, you must import the Taler Systems SA public package signing key into your keyring and update the package lists:

# wget -O /etc/apt/keyrings/taler-systems.gpg \
    https://taler.net/taler-systems.gpg
# apt update

Note

You may want to verify the correctness of the Taler Systems key out-of-band.

Now your system is ready to install the official GNU Taler binary packages using apt.

To install the depolymerizer, you can now simply run:

# apt install bitcoin-depolymerizer

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

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

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

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

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

9.1.3. Starting a local Bitcoin node#

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

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

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

9.1.4.1. Configuration format#

All GNU Taler components are designed to possibly share the same configuration files. When installing a GNU Taler component, the installation deploys default values in configuration files located at ${prefix}/share/taler/config.d/ where ${prefix} is the installation prefix. Different components must be installed to the same prefix.

In order to override these defaults, the user can write a custom configuration file and either pass it to the component at execution time using the -c option, or name it taler.conf and place it under $HOME/.config/ which is where components will look by default. Note that the systemd service files pass -c /etc/taler/taler.conf, thus making /etc/taler/taler.conf the primary location for the configuration.

A config file is a text file containing sections, and each section contains maps options to their values. Configuration files follow basically the INI syntax:

[section1]
value1 = string
value2 = 23

[section2]
value21 = string
value22 = /path22

Comments start with a hash (#). Throughout the configuration, it is possible to use $-substitution for options relating to names of files or directories. It is also possible to provide defaults values for those variables that are unset, by using the following syntax: ${VAR:-default}. There are two ways a user can set the value of $-prefixable variables:

  1. by defining them under a [paths] section:

    [paths]
TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data
..
[section-x]
path-x = ${TALER_DEPLOYMENT_SHARED}/x

  2. or by setting them in the environment:

    $ export VAR=/x

The configuration loader will give precedence to variables set under [path] over environment variables.

The utility taler-config, which gets installed along with the exchange, can be used get and set configuration values without directly editing the configuration file. The option -f is particularly useful to resolve pathnames, when they use several levels of $-expanded variables. See taler-config --help.

The repository git://git.taler.net/deployment contains example code for generating configuration files under deployment/netzbon/.

9.1.5. Bitcoin Depolymerizer Setup#

9.1.5.1. Using package script#

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

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

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

9.1.5.2. Simple setup#

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

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

9.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=?

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

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

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

9.1.8. Deployment#

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

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

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

9.1.8.3. Launching the depolymerizer#

$ sudo systemctl start depolymerizer-bitcoin.target