taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

commit 399483707af4911397c26c0622b38ff22e617aa5
parent ff48b9daafd1a6fc27756d6db06a2915ea95c950
Author: Antoine A <>
Date:   Fri,  6 Nov 2026 12:30:49 +0100

libeufin & depolymerization: config and documentation fixes

Diffstat:
Mdepolymerization/bitcoin-manual.rst | 41++++++++++++++++++++---------------------
Mlibeufin/bank-manual.rst | 16++++++++--------
Mlibeufin/ebisync-manual.rst | 13++++++-------
Mlibeufin/nexus-manual.rst | 2+-
Mmanpages/depolymerizer-bitcoin.1.rst | 2+-
Mmanpages/depolymerizer-bitcoin.conf.5.rst | 5++++-
Mmanpages/libeufin-bank.conf.5.rst | 9+++++----
Mmanpages/libeufin-ebisync.1.rst | 2++
Mmanpages/libeufin-ebisync.conf.5.rst | 6++++--
Mmanpages/libeufin-nexus.conf.5.rst | 21+++++----------------
10 files changed, 56 insertions(+), 61 deletions(-)

diff --git a/depolymerization/bitcoin-manual.rst b/depolymerization/bitcoin-manual.rst @@ -38,7 +38,7 @@ To install the depolymerizer, you can now simply run: .. code-block:: shell-session - # apt install bitcoin-depolymerizer + # apt install depolymerizer-bitcoin Installing on Ubuntu -------------------- @@ -49,7 +49,7 @@ To install the depolymerizer, you can now simply run: .. code-block:: shell-session - # apt install bitcoin-depolymerizer + # apt install depolymerizer-bitcoin Building from source -------------------- @@ -61,12 +61,16 @@ Bitcoin Depolymerizer belongs to the Depolymerization project, and can be downlo $ git clone git://git.taler.net/depolymerization $ cd depolymerization -You will need the latest version of the rust stable toolchain and a C toolchain: +Building Debian/Ubuntu packages requires the distribution packages ``cargo`` +and ``rustc`` (version 1.95 or newer), as well as a C toolchain, Python and Git: .. code-block:: console - $ sudo apt install rustup build-essential - $ rustup toolchain install stable + $ sudo apt install cargo rustc build-essential python3 git debhelper + +If your distribution provides an older ``rustc``, install newer distribution +packages before continuing. A toolchain installed only through ``rustup`` does +not satisfy the Debian package build dependencies. Then from top-level run: @@ -81,7 +85,6 @@ To install the depolymerizer as a Debian/Ubuntu package with an automated secure .. code-block:: console - $ sudo apt install debhelper $ make deb $ sudo dpkg -i ../depolymerizer-bitcoin*.deb @@ -211,7 +214,7 @@ can use the ``depolymerizer-bitcoin config`` helper: .. code-block:: shell-session - # depolymerizer-bitcoin config dump --diagnostics + # depolymerizer-bitcoin -c /etc/depolymerizer-bitcoin/depolymerizer-bitcoin.conf config dump --diagnostics .. include:: ../frags/configuration-format.rst @@ -233,12 +236,8 @@ 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: +For a local PostgreSQL installation, the following helper creates the database +and roles, initializes (or upgrades) the schema, and grants service access: .. code-block:: console @@ -291,7 +290,7 @@ And finally run the setup process: .. code-block:: console - $ sudo -u depolymerizer-bitcoin-worker depolymerizer-bitcoin setup + $ sudo -u depolymerizer-bitcoin-worker depolymerizer-bitcoin -c /etc/depolymerizer-bitcoin/depolymerizer-bitcoin.conf setup Server setup ~~~~~~~~~~~~ @@ -315,7 +314,7 @@ Check the server is correctly configured: .. code-block:: console - $ sudo -u depolymerizer-bitcoin-httpd depolymerizer-bitcoin serve --check + $ sudo -u depolymerizer-bitcoin-httpd depolymerizer-bitcoin -c /etc/depolymerizer-bitcoin/depolymerizer-bitcoin.conf serve --check Simple setup ------------ @@ -386,7 +385,7 @@ Server setup Update the configuration files: .. code-block:: ini - :caption: $CONF_FILE + :caption: $CONFIG_FILE [depolymerizer-bitcoin-httpd-wire-gateway-api] ENABLED = YES @@ -397,7 +396,7 @@ Check the server is correctly configured: .. code-block:: console - $ depolymerizer-bitcoin -c "$CONF_FILE" serve --check + $ depolymerizer-bitcoin -c "$CONFIG_FILE" serve --check Configuring bitcoind ==================== @@ -418,7 +417,7 @@ Here are some bitcoind configuration you might want to change: .. code-block:: ini - [depolymerizer-bitcoin] + [depolymerizer-bitcoin-worker] # Number of blocks to consider a transactions durable # The default is the recommended value # Lowering it make the confirmation process faster (more user friendly) @@ -427,7 +426,7 @@ Here are some bitcoind configuration you might want to change: # Amount to keep when bouncing malformed credit # Default is 0 as the mining fee is always paid by the creditor - BOUNCE_FEE = 0.00001 + BOUNCE_FEE = BTC:0.00001 Process lifetime ---------------- @@ -496,7 +495,7 @@ 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 +The ``depolymerizer-bitcoin`` package ships with a sample configuration that can be enabled in nginx: .. code-block:: shell-session @@ -514,4 +513,4 @@ Launching the depolymerizer .. code-block:: console - $ sudo systemctl start depolymerizer-bitcoin.target + $ sudo systemctl enable --now depolymerizer-bitcoin.target diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst @@ -86,16 +86,16 @@ The following snippet shows the mandatory configuration values: [libeufin-bank] CURRENCY = KUDOS - # THe public URL that the bank will be served under + # The public URL that the bank will be served under BASE_URL = https://bank.taler.net # Supported payment target type - WIRE_TYPE = iban or x-taler-bank + WIRE_TYPE = iban # If WIRE_TYPE = iban IBAN_PAYTO_BIC = SANDBOXX .. note:: - Refer to the manpage ``libeufin-man.conf(5)`` + Refer to the manpage ``libeufin-bank.conf(5)`` for the full array of configuration values. Configuring password storage @@ -155,7 +155,7 @@ To test your setup run: .. code-block:: console - $ TELESIGN_AUTH_TOKEN=$TELESIGN_TOKEN + $ export TELESIGN_AUTH_TOKEN=$TELESIGN_TOKEN $ echo "Test 1234" | libeufin-tan-sms.sh $PHONE If you received an SMS containing "Test 1234" you can enable this channel in the config: @@ -164,7 +164,7 @@ If you received an SMS containing "Test 1234" you can enable this channel in the [libeufin-bank] TAN_SMS = libeufin-tan-sms.sh - TAN_SMS_ENV = "TELESIGN_AUTH_TOKEN=$TELESIGN_TOKEN" + TAN_SMS_ENV = { "TELESIGN_AUTH_TOKEN": "$TELESIGN_TOKEN" } Mail TAN channel ++++++++++++++++ @@ -197,9 +197,9 @@ options in the configuration file: [libeufin-bank] TAN_SMS = custom-tan-sms.sh - TAN_SMS_ENV = + TAN_SMS_ENV = {} TAN_EMAIL = custom-tan-email.sh - TAN_EMAIL_ENV = + TAN_EMAIL_ENV = {} Launching libeufin-bank ======================= @@ -209,7 +209,7 @@ command initializes (or upgrades) the database schema: .. code-block:: console - $ libeufin-bank-dbinit -c "$CONFIG_FILE" + $ libeufin-bank dbinit -c "$CONFIG_FILE" Once this is done, you can start the libeufin-bank HTTP server: diff --git a/libeufin/ebisync-manual.rst b/libeufin/ebisync-manual.rst @@ -139,9 +139,8 @@ is: [ebisyncdb-postgres] config = postgres:///libeufin-ebisync -You must make sure that this database exists and is accessible to the user -running EbiSync before continuing. Then, the EbiSync database schema must be -created (or updated) to the current EbiSync version using the following command: +For a local PostgreSQL installation, the following helper creates the database +and role, initializes (or upgrades) the schema, and grants service access: .. code-block:: console @@ -152,7 +151,7 @@ EBICS setup When you sign up for an EBICS-enabled bank account, the bank will provide you with various credentials. Those must be provided in the -``/etc/libeufin-ebisync/ebisync.conf`` configuration file. +``/etc/libeufin-ebisync/libeufin-ebisync.conf`` configuration file. The following snippet shows the mandatory configuration values: @@ -273,11 +272,11 @@ Some configuration values are sensitive and must be written to a secret configur USERNAME = admin PASSWORD = password -The following command will finish the fetcher setup process: +Check the server configuration: .. code-block:: console - $ sudo -u libeufin-ebisync libeufin-ebisync setup -c /etc/libeufin-ebisync/libeufin-ebisync.conf + $ sudo -u libeufin-ebisync libeufin-ebisync serve --check -c /etc/libeufin-ebisync/libeufin-ebisync.conf Fetching files ============== @@ -365,4 +364,4 @@ Launching .. code-block:: console - $ sudo systemctl start taler-ebisync.target + $ sudo systemctl enable --now libeufin-ebisync.target diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst @@ -101,7 +101,7 @@ created (or updated) to the current Nexus version using the following command: .. code-block:: console - $ libeufin-nexus-dbinit -c "$CONFIG_FILE" + $ libeufin-nexus dbinit -c "$CONFIG_FILE" where ``$CONFIG_FILE`` is again the path to a configuration that contains at least the above ``[libeufin-nexusdb-postgres]`` section. diff --git a/manpages/depolymerizer-bitcoin.1.rst b/manpages/depolymerizer-bitcoin.1.rst @@ -77,7 +77,7 @@ Its options are as follows: **-L** \| **--log** *LOGLEVEL* Configure logging to use LOGLEVEL. **-r** \| **--reset** - Reset sync state to the blockhain genesis. + Reset sync state to the blockchain genesis. **-h** \| **--help** Print short help on options. diff --git a/manpages/depolymerizer-bitcoin.conf.5.rst b/manpages/depolymerizer-bitcoin.conf.5.rst @@ -29,6 +29,9 @@ DEPOLYMERIZER OPTIONS The following options are from the “[depolymerizer-bitcoin]” section. +CURRENCY + Adapter currency + WALLET Bitcoin wallet address to advertise @@ -92,7 +95,7 @@ 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. + Whether to serve the Wire Gateway API and the Prepared Transfer API. .. include:: frags/common-api-options.rst diff --git a/manpages/libeufin-bank.conf.5.rst b/manpages/libeufin-bank.conf.5.rst @@ -36,10 +36,10 @@ WIRE_TYPE Supported payment target type, this can either be ``iban`` or ``x-taler-bank`` IBAN_PAYTO_BIC - Bank BIC used in generated iban payto URI. Required if ``WIRE_TYPE``is ``iban`` + Bank BIC used in generated iban payto URI. X_TALER_BANK_PAYTO_HOSTNAME - Bank hostname used in generated x-taler-bank payto URI. Required if ``WIRE_TYPE``is ``x-taler-bank`` + Deprecated. The hostname from ``BASE_URL`` is used instead. NAME Bank display name, used in webui and TAN messages. Defaults to ``Taler Bank`` if not specified. @@ -83,11 +83,9 @@ FIAT_CURRENCY TAN_SMS Path to TAN challenge transmission script via sms. If not specified, this TAN channel will not be supported. - Only used if ``ALLOW_CONVERSION`` is ``YES``. TAN_EMAIL Path to TAN challenge transmission script via email. If not specified, this TAN channel will not be supported. - Only used if ``ALLOW_CONVERSION`` is ``YES``. TAN_SMS_ENV Environment variables for the sms TAN script as a single-line JSON object @@ -112,6 +110,9 @@ UNIXPATH Which unix domain path should we bind to? Only used if ``SERVE`` is ``unix``. +SPA + Path to the separately installed WebUI files. + SUGGESTED_WITHDRAWAL_EXCHANGE Exchange that is suggested to wallets when withdrawing diff --git a/manpages/libeufin-ebisync.1.rst b/manpages/libeufin-ebisync.1.rst @@ -94,6 +94,8 @@ Fetches of new documents are executed at 'FREQUENCY' or any time a real-time EBI Specifies the configuration file. **-L** \| **--log** *LOGLEVEL* Configure logging to use LOGLEVEL. +**--check** + Check whether a fetch destination is configured. Exit with 0 if configured, otherwise 1. **--transient** Execute once and return, ignoring the 'FREQUENCY' configuration value. **--pinned-start** *YYYY-MM-DD* diff --git a/manpages/libeufin-ebisync.conf.5.rst b/manpages/libeufin-ebisync.conf.5.rst @@ -66,8 +66,7 @@ FETCH OPTIONS The following configuration value(s) belong to the “[ebisync-fetch]” section. FREQUENCY - Duration value to instruct the ``fetch`` subcommand how often it should - download from the bank. + How often should fetch run when the bank does not support real time notification CHECKPOINT_TIME_OF_DAY At what time HH:MM of day should ``fetch`` perform a checkpoint. @@ -127,6 +126,9 @@ UNIXPATH Which unix domain path should we bind to? Only used if ``SERVE`` is ``unix``. +SPA + Path to spa files + DATABASE OPTIONS ---------------- diff --git a/manpages/libeufin-nexus.conf.5.rst b/manpages/libeufin-nexus.conf.5.rst @@ -89,11 +89,10 @@ EBICS SUBMIT OPTIONS The following configuration value(s) belong to the “[nexus-submit]” section. FREQUENCY - Duration value to instruct the ``ebics-submit`` subcommand how much to wait - before checking the database again to find new unsubmitted payments. + How often should ebics-submit submit pending transactions MANUAL_ACK - Wether to wait for manual acknowledgement before submiting transactions. + Whether to wait for manual acknowledgement before submitting transactions. EBICS FETCH OPTIONS ------------------- @@ -101,17 +100,16 @@ EBICS FETCH OPTIONS The following configuration value(s) belong to the “[nexus-fetch]” section. FREQUENCY - Duration value to instruct the ``ebics-fetch`` subcommand how often it should - download from the bank. + How often should ebics-fetch run when the bank does not support real time notification CHECKPOINT_TIME_OF_DAY At what time HH:MM of day should ``ebics-fetch`` perform a checkpoint. IGNORE_TRANSACTIONS_BEFORE - Ignore all transactions before a certain YYYY-MM-DD date, useful when you want to use an existing account with old transactions that should not be bounced. + Ignore incoming transactions before this date (``YYYY-MM-DD``). IGNORE_BOUNCES_BEFORE - Ignore all malformed transactions prior to a certain YYYY-MM-DD date, useful when you want to import old transactions without bouncing the malformed ones a second time. + Do not bounce malformed incoming transactions before this date (``YYYY-MM-DD``). BOUNCE_DEDUCE_FEE Whether to deduce the fee paid by the exchange account from the bounced amount. @@ -172,15 +170,6 @@ ENABLED .. include:: frags/common-api-options.rst -HTTP OBSERVABILITY API OPTIONS ------------------------------- - -The following configuration value(s) belong to the “[nexus-httpd-observability-api]” section. - -ENABLED - Whether to serve the Observability API. - -.. include:: frags/common-api-options.rst DATABASE OPTIONS