commit 0a0a3fcc9a0828c483143dfbe8c597a2e5d62d12
parent d9cb83110b44a4f23cdb697a37137a46bf311335
Author: Antoine A <>
Date: Wed, 30 Jul 2025 00:36:52 +0200
depolymerizer-bitcoin: improve manual and doc
Diffstat:
3 files changed, 165 insertions(+), 109 deletions(-)
diff --git a/depolymerization/bitcoin-manual.rst b/depolymerization/bitcoin-manual.rst
@@ -60,7 +60,7 @@ To install the depolymerizer as a Debian/Ubuntu package with an automated secure
$ cargo install cargo-deb
$ make deb
- $ sudo dpkg -i target/debian/depolymerizer-bitcoin/*.deb
+ $ sudo dpkg -i target/debian/*.deb
If the previous steps succeeded, the ``depolymerizer-bitcoin`` command should be found in the $PATH.
@@ -76,95 +76,107 @@ To install the depolymerizer binaries and default configuration localy run:
If the previous steps succeeded, the ``depolymerizer-bitcoin`` command should be found in the $PATH.
-Database setup
-==============
+Installing bitcoind
+===================
+
+You need to install bitcoind & bitcoin-cli yourself, you can install them from the `Bitcoin Core website <https://bitcoincore.org/en/download/>`_.
+
+.. code-block:: console
+
+ $ 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
+
+Starting a local Bitcoin node
+=============================
Using package script
--------------------
-The configuration file must include a connection string that tells the depolymerizer how it should connect to the database. The default
-is:
-
-.. code-block:: ini
- :caption: /etc/depolymerizer-bitcoin/secrets/depolymerizer-bitcoin-db.secret.conf
+Start the node service:
- [depolymerizer-bitcoindb-postgres]
- config = postgres:///depolymerizer-bitcoin
+.. code-block:: console
-If the database is run on a different host, please follow the instructions
-from the PostgreSQL manual for configuring remote access.
+ $ sudo systemctl start depolymerizer-bitcoin-node
-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:
+Then check if the node is running:
.. code-block:: console
- $ sudo depolymerizer-bitcoin-dbconfig
+ $ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf getblockchaininfo
-Minimal setup
--------------
+Simple setup
+------------
-The configuration file must include a connection string that tells the depolymerizer how it should connect to the database. The default
-is:
+You need to edit bitcoind default configuration:
.. code-block:: ini
- :caption: $CONFIG_FILE
-
- [depolymerizer-bitcoindb-postgres]
- config = postgres:///depolymerizer-bitcoin
+ :caption: $HOME/.bitcoin/bitcoin.conf
-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.
+ txindex=1 # Enable full transaction indexes
+ rpcservertimeout=0 # Disable RPC timeout
-Assuming that the configuration file exists at ``$CONFIG_FILE``, the following
-command initializes (or upgrades) the database schema:
+Start the node daemon:
.. code-block:: console
- $ depolymerizer-bitcoin -c "$CONFIG_FILE" dbinit
-
-Worker setup
-============
+ $ bitcoind
-Note that bitcoind & bitcoin-cli should already be in $PATH, you can install them from the `Bitcoin Core website <https://bitcoincore.org/en/download/>`_.
+In another terminal check if the node is running:
.. code-block:: console
- $ curl -L https://bitcoincore.org/bin/bitcoin-core-29.0/bitcoin-29.0-x86_64-linux-gnu.tar.gz | tar xz
+ $ bitcoin-cli getblockchaininfo
-Using systemd services
-----------------------
+Bitcoin Depolymerizer Setup
+===========================
-Start the node service:
+Using package script
+--------------------
-.. code-block:: console
+Database setup
+~~~~~~~~~~~~~~
- $ sudo systemctl start depolymerizer-bitcoin-node
+The configuration file must include a connection string that tells the depolymerizer how it should connect to the database. The default
+is:
-Then check if the node is running:
+.. code-block:: ini
+ :caption: /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:
.. code-block:: console
- $ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf -datadir=/var/lib/bitcoind getblockchaininfo
+ $ sudo depolymerizer-bitcoin-dbconfig
+
+Worker setup
+~~~~~~~~~~~~
You will need a bitcoin wallet to sync, you can either create:
.. code-block:: console
- $ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf -datadir=/var/lib/bitcoind createwallet $WALLET false false $PASSWORD
+ $ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf createwallet $WALLET false false $PASSWORD
Or use an existing one:
.. code-block:: console
- $ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf -datadir=/var/lib/bitcoind loadwallet $WALLET
+ $ 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:
.. code-block:: console
- $ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf -datadir=/var/lib/bitcoind -rpcwallet=$WALLET getnewaddress
+ $ sudo -u depolymerizer-bitcoin-node bitcoin-cli -conf=/etc/bitcoind/bitcoin.conf -rpcwallet=$WALLET getnewaddress
Update the configuration files:
@@ -194,34 +206,54 @@ And finaly run the setup process:
$ sudo -u depolymerizer-bitcoin-worker depolymerizer-bitcoin setup
-You can then start the worker service:
+Server setup
+~~~~~~~~~~~~
-.. code-block:: console
-
- $ sudo systemctl start depolymerizer-bitcoin-worker
+Update the configuration files:
-Minimal setup
--------------
+.. code-block:: ini
+ :caption: /etc/depolymerizer-bitcoin/conf.d/depolymerizer-bitcoin-httpd.conf
-You need to edit bitcoind default configuration:
+ [depolymerizer-bitcoin-httpd-wire-gateway-api]
+ ENABLED = YES
.. code-block:: ini
- :caption: $HOME/.bitcoin/bitcoin.conf
+ :caption: /etc/depolymerizer-bitcoin/secrets/depolymerizer-bitcoin-httpd.secret.conf
- txindex=1 # Enable full transaction indexes
- rpcservertimeout=0 # Disable RPC timeout
+ [depolymerizer-bitcoin-httpd-wire-gateway-api]
+ AUTH_METHOD = bearer
+ TOKEN = $SECRET_TOKEN
-Start the node daemon:
+Check the server is correctly configured:
.. code-block:: console
- $ bitcoind
+ $ sudo -u depolymerizer-bitcoin-httpd depolymerizer-bitcoin serve --check
+
+Simple setup
+------------
-In another terminal check if the node is running:
+Database setup
+~~~~~~~~~~~~~~
+
+The configuration file must include a connection string that tells the depolymerizer how it should connect to the database. The default
+is:
+
+.. code-block:: ini
+ :caption: $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:
.. code-block:: console
- $ bitcoin-cli getblockchaininfo
+ $ depolymerizer-bitcoin -c "$CONFIG_FILE" dbinit
You will need a bitcoin wallet to sync, you can either create:
@@ -255,56 +287,95 @@ Update the configuration files:
WALLET_NAME = $WALLET
PASSWORD = $PASSWORD
-And finaly run the setup process and the worker:
+And finaly run the setup process:
.. code-block:: console
$ depolymerizer-bitcoin -c "$CONFIG_FILE" setup
- $ depolymerizer-bitcoin -c "$CONFIG_FILE" worker
-
-The worker will start working, you can enter another terminal.
-
-API setup
-=========
-Using systemd services
-----------------------
+Server setup
+~~~~~~~~~~~~
Update the configuration files:
.. code-block:: ini
- :caption: /etc/depolymerizer-bitcoin/conf.d/depolymerizer-bitcoin-httpd.conf
+ :caption: $CONF_FILE
[depolymerizer-bitcoin-httpd-wire-gateway-api]
ENABLED = YES
-
-.. code-block:: ini
- :caption: /etc/depolymerizer-bitcoin/secrets/depolymerizer-bitcoin-httpd.secret.conf
-
- [depolymerizer-bitcoin-httpd-wire-gateway-api]
AUTH_METHOD = bearer
TOKEN = $SECRET_TOKEN
-Then start the service:
+Check the server is correctly configured:
.. code-block:: console
- $ sudo systemctl start depolymerizer-bitcoin-httpd
+ $ depolymerizer-bitcoin -c "$CONF_FILE" serve --check
-Minimal setup
--------------
+Configuring bitcoind
+====================
-Update the configuration files:
+Here are some bitcoind configuration you might want to change:
.. code-block:: ini
- :caption: $CONF_FILE
+ :caption: bitcoin.conf
+ # bitcoin transactions fees can exceed taler wire fees, putting
+ your wire in bankruptcy. You must specify an acceptable transaction fee cap.
+ maxtxfee=?
- [depolymerizer-bitcoin-httpd-wire-gateway-api]
- AUTH_METHOD = bearer
- TOKEN = $SECRET_TOKEN
+Configuring Bitcoin Depolymerizer
+=================================
+
+Here are some bitcoind configuration you might want to change:
+
+.. code-block:: ini
+
+ [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
+
+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.
+
+.. code-block:: ini
+
+ [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
+
+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:
+
+.. code-block:: ini
+
+ [depolymerizer-bitcoin-worker]
+ # Delay in seconds before bumping an unconfirmed transaction fee (0 means never)
+ BUMP_DELAY = 0
-Then start the server:
+Deployment
+==========
.. code-block:: console
- $ depolymerizer-bitcoin -c "$CONF_FILE" serve
-\ No newline at end of file
+ $ sudo systemctl start depolymerizer-bitcoin.target
+\ No newline at end of file
diff --git a/manpages/depolymerizer-bitcoin.1.rst b/manpages/depolymerizer-bitcoin.1.rst
@@ -1,5 +1,5 @@
depolymerizer-bitcoin(1)
-####################
+########################
.. only:: html
@@ -77,16 +77,14 @@ Its options are as follows:
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
**-r** \| **--reset**
- Reset connection info and overwrite keys file
+ Reset sync state to the blockhain genesis.
**-h** \| **--help**
Print short help on options.
worker
------
-This subcommand sync the wallet history, submit transaction and bump stuck transactions.
-
-If ACCOUNT_TYPE is ``exchange``, incoming payments with an invalid Taler subject are bounced.
+This subcommand sync the wallet history, submit transaction and bump stuck transactions. Incoming payments with an invalid Taler subject are bounced.
Its options are as follows:
diff --git a/manpages/depolymerizer-bitcoin.conf.5.rst b/manpages/depolymerizer-bitcoin.conf.5.rst
@@ -1,5 +1,5 @@
depolymerizer-bitcoin.conf(5)
-#########################
+#############################
.. only:: html
@@ -47,19 +47,16 @@ PASSWORD
Password of the encrypted wallet.
CONFIRMATION
- Number of blocks to consider a transaction confirmed.
+ Number of blocks to consider a transactions durable.
BOUNCE_FEE
An additional fee to deduce from the bounced amount.
-ACCOUNT_TYPE
- Specify the account type and therefore the indexing behavior. This can either can be ``normal`` or ``exchange``. Exchange accounts bounce invalid incoming Taler transactions.
-
LIFETIME
- Number of worker's loops before worker shutdown.
+ Number of worker's loops before worker shutdown (0 means never).
BUMP_DELAY
- Delay in seconds before bumping an unconfirmed transaction fee (0 mean never).
+ Delay in seconds before bumping an unconfirmed transaction fee (0 means never).
RPC_BIND
RPC server address.
@@ -87,7 +84,7 @@ The following configuration value(s) belong to the “[depolymerizer-bitcoin-htt
.. include:: frags/common-serve-options.rst
LIFETIME
- Number of requests to serve before server shutdown (0 mean never)
+ Number of requests to serve before server shutdown (0 means never).
HTTP WIRE GATEWAY API OPTIONS
-----------------------------
@@ -99,20 +96,10 @@ ENABLED
.. include:: frags/common-api-options.rst
-HTTP REVENUE API OPTIONS
-------------------------
-
-The following configuration value(s) belong to the “[depolymerizer-bitcoin-httpd-revenue-api]” section.
-
-ENABLED
- Whether to serve the Revenue API.
-
-.. include:: frags/common-api-options.rst
-
DATABASE OPTIONS
----------------
-Setting the database belongs to the “[magnet-bankddb-postgres]” section and the following value.
+Setting the database belongs to the “[depolymerizer-bitcoindb-postgres]” section and the following value.
.. include:: frags/common-db-options.rst
