commit 740b2fffd1066db88ca7c016f4691f9caff0c4f4
parent 847bd00b76a035153c840a95aa2ad56704db4114
Author: Antoine A <>
Date: Mon, 21 Jul 2025 12:13:04 +0200
depolymerization: add bitcoin man pages
Diffstat:
6 files changed, 298 insertions(+), 44 deletions(-)
diff --git a/manpages/depolymerizer-bitcoin.1.rst b/manpages/depolymerizer-bitcoin.1.rst
@@ -0,0 +1,128 @@
+depolymerizer-bitcoin(1)
+####################
+
+.. only:: html
+
+ Name
+ ====
+
+ **depolymerizer-bitcoin** - Bitcoin depolymerizer.
+
+
+Synopsis
+========
+
+**depolymerizer-bitcoin**
+[**-h** | **--help**]
+[**--version**]
+COMMAND [ARGS...]
+
+Subcommands: **dbinit**, **setup**,
+**serve**, **worker**, **config**
+
+
+Description
+===========
+
+**depolymerizer-bitcoin** is a Taler depolymerizer for the Bitcoin blockhain.
+
+Its options are as follows:
+
+**-h** \| **--help**
+ Print short help on options.
+
+**--version**
+ Print version information.
+
+The interaction model is as follows:
+
+- Configure the database with commands ``dbinit``.
+
+- Setup node access with commands ``setup``. Setting the access means checking node RPC access and validating worker config.
+
+- After a successful setup, the subcommands ``worker`` can be run to both send payments and sync the wallet transactionhistory.
+
+- Start the HTTP server with command ``serve``.
+ Let this run in a shell, writing logs to stderr.
+
+The following sections describe each command in detail.
+
+dbinit
+------
+
+This command defines the database schema for depolymerizer-bitcoin. It is mandatory to run this command before invoking the ``setup`` or ``serve`` commands.
+
+Its options are as follows:
+
+**-c** \| **--config** *config_file*
+ Specifies the configuration file.
+**-L** \| **--log** *LOGLEVEL*
+ Configure logging to use LOGLEVEL.
+**-r** \| **--reset**
+ Reset database (DANGEROUS: All existing data is lost)
+**-h** \| **--help**
+ Print short help on options.
+
+setup
+-----
+
+This command setup a working node connection. This command check RPC access and validate worker config.
+
+It is mandatory to run this command before invoking the ``worker`` command.
+
+Its options are as follows:
+
+**-c** \| **--config** *config_file*
+ Specifies the configuration file.
+**-L** \| **--log** *LOGLEVEL*
+ Configure logging to use LOGLEVEL.
+**-r** \| **--reset**
+ Reset connection info and overwrite keys file
+**-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.
+
+Its options are as follows:
+
+**-c** \| **--config** *config_file*
+ Specifies the configuration file.
+**-L** \| **--log** *LOGLEVEL*
+ Configure logging to use LOGLEVEL.
+**--transient**
+ Execute once and return.
+**-h** \| **--help**
+ Print short help on options.
+
+serve
+-----
+
+This command starts the HTTP server.
+
+Its options are as follows:
+
+**-c** \| **--config** *config_file*
+ Specifies the configuration file.
+**-L** \| **--log** *LOGLEVEL*
+ Configure logging to use LOGLEVEL.
+**--check**
+ Check whether an API is in use (if it's useful to start the HTTP server). Exit with 0 if at least one API is enabled, otherwise 1.
+**-h** \| **--help**
+ Print short help on options.
+
+.. include:: ../frags/libeufin-config-cli.rst
+
+SEE ALSO
+========
+
+depolymerizer-bitcoin.conf(5)
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic mail to <taler@gnu.org>.
diff --git a/manpages/depolymerizer-bitcoin.conf.5.rst b/manpages/depolymerizer-bitcoin.conf.5.rst
@@ -0,0 +1,128 @@
+depolymerizer-bitcoin.conf(5)
+#########################
+
+.. only:: html
+
+ Name
+ ====
+
+ **depolymerizer-bitcoin.conf** - Bitcoin depolymerizer configuration file
+
+
+Description
+===========
+
+.. include:: ../frags/common-conf-syntax.rst
+
+Files containing default values for many of the options described below
+are installed under ``$DEPOLYMERIZER-BITCOIN/share/depolymerizer-bitcoin/config.d/``.
+The configuration file given with **-c** to Taler binaries
+overrides these defaults.
+
+A configuration file may include another, by using the ``@INLINE@`` directive,
+for example, in ``main.conf``, you could write ``@INLINE@ sub.conf`` to
+include the entirety of ``sub.conf`` at that point in ``main.conf``.
+
+
+DEPOLYMERIZER OPTIONS
+---------------------
+
+The following options are from the “[depolymerizer-bitcoin]” section.
+
+WALLET
+ Bitcoin wallet address to advertise
+
+NAME
+ Legal entity that is associated with the Bitcoin wallet.
+
+WORKER OPTIONS
+--------------
+
+The following options are from the “[depolymerizer-bitcoin-worker]” section.
+
+WALLET_NAME
+ Name of the wallet to sync.
+
+PASSWORD
+ Password of the encrypted wallet.
+
+CONFIRMATION
+ Number of blocks to consider a transaction confirmed.
+
+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.
+
+BUMP_DELAY
+ Delay in seconds before bumping an unconfirmed transaction fee (0 mean never).
+
+RPC_BIND
+ RPC server address.
+
+RPC_AUTH_METHOD
+ RPC authentication scheme, this can either can be ``basic`` or ``cookie``.
+
+RPC_COOKIE_FILE
+ Path to the bitcoind cookie file.
+ Only used if ``RPC_AUTH_METHOD`` is ``cookie``.
+
+RPC_USERNAME
+ User name for basic authentication scheme.
+ Only used if ``RPC_AUTH_METHOD`` is ``basic``.
+
+RPC_PASSWORD
+ Password for basic authentication scheme.
+ Only used if ``RPC_AUTH_METHOD`` is ``basic``.
+
+HTTP SERVER OPTIONS
+-------------------
+
+The following configuration value(s) belong to the “[depolymerizer-bitcoin-httpd]” section.
+
+.. include:: frags/common-serve-options.rst
+
+LIFETIME
+ Number of requests to serve before server shutdown (0 mean never)
+
+HTTP WIRE GATEWAY API OPTIONS
+-----------------------------
+
+The following configuration value(s) belong to the “[depolymerizer-bitcoin-httpd-wire-gateway-api]” section.
+
+ENABLED
+ Whether to serve the Wire Gateway API.
+
+.. 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.
+
+.. include:: frags/common-db-options.rst
+
+SEE ALSO
+========
+
+depolymerizer-bitcoin(1)
+
+BUGS
+====
+
+Report bugs by using https://bugs.taler.net/ or by sending electronic
+mail to <taler@gnu.org>.
+\ No newline at end of file
diff --git a/manpages/frags/common-api-options.rst b/manpages/frags/common-api-options.rst
@@ -0,0 +1,11 @@
+AUTH_METHOD
+ Authentication scheme, this can either be ``basic``, ``bearer`` or ``none``.
+
+USERNAME
+ User name for ``basic`` authentication scheme.
+
+PASSWORD
+ Password for ``basic`` authentication scheme.
+
+TOKEN
+ Token for ``bearer`` authentication scheme.
+\ No newline at end of file
diff --git a/manpages/frags/common-db-options.rst b/manpages/frags/common-db-options.rst
@@ -0,0 +1,5 @@
+CONFIG
+ PostgreSQL connection string.
+
+SQL_DIR
+ Where are the SQL files to setup our tables?
+\ No newline at end of file
diff --git a/manpages/frags/common-serve-options.rst b/manpages/frags/common-serve-options.rst
@@ -0,0 +1,18 @@
+SERVE
+ This can either be ``tcp`` or ``unix``.
+
+PORT
+ Port on which the HTTP server listens, e.g. 9967.
+ Only used if ``SERVE`` is ``tcp``.
+
+BIND_TO
+ Which IP address should we bind to? E.g. ``127.0.0.1`` or ``::1``for loopback. Can also be given as a hostname.
+ Only used if ``SERVE`` is ``tcp``.
+
+UNIXPATH
+ Which unix domain path should we bind to?
+ Only used if ``SERVE`` is ``unix``.
+
+UNIXPATH_MODE
+ What should be the file access permissions for ``UNIXPATH``?
+ Only used if ``SERVE`` is ``unix``.
+\ No newline at end of file
diff --git a/manpages/taler-magnet-bank.conf.5.rst b/manpages/taler-magnet-bank.conf.5.rst
@@ -60,24 +60,7 @@ HTTP SERVER OPTIONS
The following configuration value(s) belong to the “[magnet-bank-httpd]” section.
-SERVE
- This can either be ``tcp`` or ``unix``.
-
-PORT
- Port on which the HTTP server listens, e.g. 9967.
- Only used if ``SERVE`` is ``tcp``.
-
-BIND_TO
- Which IP address should we bind to? E.g. ``127.0.0.1`` or ``::1``for loopback. Can also be given as a hostname.
- Only used if ``SERVE`` is ``tcp``.
-
-UNIXPATH
- Which unix domain path should we bind to?
- Only used if ``SERVE`` is ``unix``.
-
-UNIXPATH_MODE
- What should be the file access permissions for ``UNIXPATH``?
- Only used if ``SERVE`` is ``unix``.
+.. include:: frags/common-serve-options.rst
HTTP WIRE GATEWAY API OPTIONS
-----------------------------
@@ -87,17 +70,7 @@ The following configuration value(s) belong to the “[magnet-bank-httpd-wire-ga
ENABLED
Whether to serve the Wire Gateway API.
-AUTH_METHOD
- Authentication scheme, this can either be ``basic``, ``bearer`` or ``none``.
-
-USERNAME
- User name for ``basic`` authentication scheme.
-
-PASSWORD
- Password for ``basic`` authentication scheme.
-
-TOKEN
- Token for ``bearer`` authentication scheme.
+.. include:: frags/common-api-optio
HTTP REVENUE API OPTIONS
------------------------
@@ -107,28 +80,15 @@ The following configuration value(s) belong to the “[magnet-bank-httpd-revenue
ENABLED
Whether to serve the Revenue API.
-AUTH_METHOD
- Authentication scheme, this can either be ``basic``, ``bearer`` or ``none``.
-
-USERNAME
- User name for ``basic`` authentication scheme.
-
-PASSWORD
- Password for ``basic`` authentication scheme.
-
-TOKEN
- Token for ``bearer`` authentication scheme.
+.. include:: frags/common-api-optio
DATABASE OPTIONS
----------------
Setting the database belongs to the “[magnet-bankddb-postgres]” section and the following value.
-CONFIG
- PostgreSQL connection string.
+.. include:: frags/common-db-options.rst
-SQL_DIR
- Where are the SQL files to setup our tables?
SEE ALSO
========
