10.1. Bitcoin Depolymerizer Setup Manual#
depolymerizer-bitcoin is a bitcoin blockhain Taler adapter.
In this manual, we explain how to setup an adapter.
10.1.1. Installing Bitcoin Depolymerizer#
10.1.1.1. Building from source#
Bitcoin Depolymerizer belongs to the Depolymerization project, and can be downloaded via Git:
$ git clone git://git.taler.net/depolymerization
You will need the latest version of the rust stable toolchain:
$ sudo apt install rustup
$ rustup toolchain install stable
Navigate into the depolymerization local repository, and from top-level run:
$ ./bootstrap
10.1.1.1.1. Install deb package#
To install the depolymerizer as a Debian/Ubuntu package with an automated secure setup and systemd services:
$ cargo install cargo-deb
$ make deb
$ sudo dpkg -i target/debian/*.deb
If the previous steps succeeded, the depolymerizer-bitcoin command should be found in the $PATH.
10.1.1.1.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.
10.1.2. Installing bitcoind#
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
10.1.3. Starting a local Bitcoin node#
10.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
10.1.3.2. Simple setup#
You need to edit bitcoind default configuration:
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
10.1.4. Bitcoin Depolymerizer Setup#
10.1.4.1. Using package script#
10.1.4.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:
[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
10.1.4.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:
[depolymerizer-bitcoin]
CURRENCY = BTC
WALLET = $ADDRESS
NAME = John Smith S.A.
[depolymerizer-bitcoin-worker]
WALLET_NAME = $WALLET
[depolymerizer-bitcoin-worker]
PASSWORD = $PASSWORD
And finaly run the setup process:
$ sudo -u depolymerizer-bitcoin-worker depolymerizer-bitcoin setup
10.1.4.1.3. Server setup#
Update the configuration files:
[depolymerizer-bitcoin-httpd-wire-gateway-api]
ENABLED = YES
[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
10.1.4.2. Simple setup#
10.1.4.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:
[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:
[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
10.1.4.2.2. Server setup#
Update the configuration files:
[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
10.1.5. Configuring bitcoind#
Here are some bitcoind configuration you might want to change:
# bitcoin transactions fees can exceed taler wire fees, putting
your wire in bankruptcy. You must specify an acceptable transaction fee cap.
maxtxfee=?
10.1.6. 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
10.1.6.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
10.1.6.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
10.1.7. Deployment#
$ sudo systemctl start depolymerizer-bitcoin.target