[taler-docs] branch master updated: -misc fixes, add taler-merchant-depositcheck

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 2f78f048 -misc fixes, add taler-merchant-depositcheck
2f78f048 is described below

commit 2f78f048c007ade79421fd921e2cafdab1a2c9ee
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sat Jan 6 14:01:39 2024 +0100

    -misc fixes, add taler-merchant-depositcheck
---
 conf.py                                            |  7 ++
 .../036-currency-conversion-service.rst            | 52 ++++++-------
 design-documents/044-ci-system.rst                 | 13 ++--
 design-documents/054-dynamic-form.rst              | 37 +++++----
 libeufin/regional-manual.rst                       | 88 +++++++++++-----------
 manpages/taler-merchant-depositcheck.1             | 72 ++++++++++++++++++
 taler-auditor-manual.rst                           |  1 +
 7 files changed, 174 insertions(+), 96 deletions(-)

diff --git a/conf.py b/conf.py
index fc747f0a..e1663ff4 100644
--- a/conf.py
+++ b/conf.py
@@ -609,6 +609,13 @@ man_pages = [
         "GNU Taler contributors",
         1,
     ),
+    (
+        "manpages/taler-merchant-depositcheck.1",
+        "taler-merchant-depositcheck",
+        "check status of deposits with exchange",
+        "GNU Taler contributors",
+        1,
+    ),
     (
         "manpages/taler-merchant-setup-reserve.1",
         "taler-merchant-setup-reserve",
diff --git a/design-documents/036-currency-conversion-service.rst 
b/design-documents/036-currency-conversion-service.rst
index be3a01a0..92d88499 100644
--- a/design-documents/036-currency-conversion-service.rst
+++ b/design-documents/036-currency-conversion-service.rst
@@ -44,54 +44,54 @@ Requirements
 * CCS must link every fiat-side of a cash-out to its regional currency
   counterpart.  In particular, because every cash-out starts with a
   payment *P* from regio-user to regio-issuer and ends with another
-  payment *Q* from fiat-issuer to fiat-target, CCS must link P and Q. 
+  payment *Q* from fiat-issuer to fiat-target, CCS must link P and Q.
 
 Proposed Solution
 =================
 
-The following design assumes that CCS is coded in libeufin-bank and that 
-libeufin-bank and libeufin-nexus share the same database with separate 
-schemas. The solution relies on SQL triggers to atomically synchronise 
+The following design assumes that CCS is coded in libeufin-bank and that
+libeufin-bank and libeufin-nexus share the same database with separate
+schemas. The solution relies on SQL triggers to atomically synchronise
 cash-in and cash-out operations between the two schemas.
 
 SQL triggers and conversion operations
 --------------------------------------
 
-Libeufin-bank controls the conversion support and sets up or removes 
-conversion SQL triggers when necessary. In order for the SQL triggers to 
-perform the conversion operations, the configurable rates/fees are stored 
-in the database and the conversion operations are performed using stored 
-SQL procedures. The SQL triggers and conversion procedures are stored in 
+Libeufin-bank controls the conversion support and sets up or removes
+conversion SQL triggers when necessary. In order for the SQL triggers to
+perform the conversion operations, the configurable rates/fees are stored
+in the database and the conversion operations are performed using stored
+SQL procedures. The SQL triggers and conversion procedures are stored in
 the libeufin-bank schema.
 
 Cash-out operation
 ------------------
 
 Libeufin-bank learns instantly about a cash-out operation, because it's
-*the* service offering such feature. Therefore, as soon as a cash-out 
-operation gets TAN-confirmed, libeufin-bank performs a wire transfer from 
-regio-user to regio-issuer by specifying the amount without any rates/fees 
-applied. Along the same database transaction, a SQL trigger store the 
-*instructions* of another payment *P* from fiat-issuer to fiat-target, 
+*the* service offering such feature. Therefore, as soon as a cash-out
+operation gets TAN-confirmed, libeufin-bank performs a wire transfer from
+regio-user to regio-issuer by specifying the amount without any rates/fees
+applied. Along the same database transaction, a SQL trigger store the
+*instructions* of another payment *P* from fiat-issuer to fiat-target,
 but this time **with** the cash-out rates/fees.
 
-Asynchronously, a libeufin-nexus background task picks P and sends it to 
-the fiat bank. Finally, fiat bank conducts P and fiat-target receives the 
-wanted amount. The same libeufin-nexus background task should also retry 
+Asynchronously, a libeufin-nexus background task picks P and sends it to
+the fiat bank. Finally, fiat bank conducts P and fiat-target receives the
+wanted amount. The same libeufin-nexus background task should also retry
 previous payments like P that failed to be submitted to fiat bank.
 
 Cash-in operation
-----------------
+-----------------
 
 A cashin-in operation starts as soon as the customer sends a fiat
-payment from fiat-customer to fiat-issuer. 
+payment from fiat-customer to fiat-issuer.
 
-The libeufin-nexus component is responsible to query the fiat bank 
-via EBICS every X seconds. X should match the tightest interval allowed 
+The libeufin-nexus component is responsible to query the fiat bank
+via EBICS every X seconds. X should match the tightest interval allowed
 by the bank.
 
-When libeufin-nexus registers an incoming payment on fiat-issuer in the 
-database, a SQL trigger applies the **current** cash-in rates/fees and 
-performs a wire transfer from regio-issuer to regio-exchange. Libeufin-bank 
-makes the exchange aware via the Taler Wire Gateway API and from now on, 
-the system proceeds like it always did in Taler.
\ No newline at end of file
+When libeufin-nexus registers an incoming payment on fiat-issuer in the
+database, a SQL trigger applies the **current** cash-in rates/fees and
+performs a wire transfer from regio-issuer to regio-exchange. Libeufin-bank
+makes the exchange aware via the Taler Wire Gateway API and from now on,
+the system proceeds like it always did in Taler.
diff --git a/design-documents/044-ci-system.rst 
b/design-documents/044-ci-system.rst
index cfb733aa..e38632c0 100644
--- a/design-documents/044-ci-system.rst
+++ b/design-documents/044-ci-system.rst
@@ -6,7 +6,7 @@ Summary
 
 This documents describes Taler's CI system based on Buildbot.
 
-This document uses `RFC 2119 <https://tools.ietf.org/html/rfc2119>`_  
+This document uses `RFC 2119 <https://tools.ietf.org/html/rfc2119>`_
 keywords throughout.
 
 Motivation
@@ -58,13 +58,13 @@ Example directory structure:
           └── 2-docs
               ├── docs.sh
               └── job.sh
-  
-Job directories **MUST** follow this pattern: 
+
+Job directories **MUST** follow this pattern:
 ``<repo_root>/contrib/ci/jobs/<n-job_name>/``
 
 ``n`` is an integer used for ordering the build steps.
 
-Job directories **MUST** contain a script named ``job.sh`` which **MAY** 
+Job directories **MUST** contain a script named ``job.sh`` which **MAY**
 execute other scripts.
 
 Config files may optionally be created, and MUST be named ``config.ini`` and
@@ -84,7 +84,7 @@ Available config options:
 
 Unless *all* jobs specify a "CONTAINER_NAME" in their custom config a
 container file **MUST** be present at ``<repo_root>/contrib/ci/Containerfile``.
-The container file will be built and used to run all of a repo's jobs 
+The container file will be built and used to run all of a repo's jobs
 by default.
 
 All projects SHOULD have a ``build`` step and a ``test`` step, at a minimum.
@@ -95,8 +95,7 @@ Running CI Locally
 Running the CI scripts locally can be useful for development and testing.
 
 Included in each CI directory is a script which simplifies running jobs
-in the same way the CI Worker does, in containers, using either `podman`
-or `docker`, detecting if you have either installed.
+in the same way the CI Worker does, in containers, using ``podman``.
 
 ::
 
diff --git a/design-documents/054-dynamic-form.rst 
b/design-documents/054-dynamic-form.rst
index 6a6d96af..6ff84d41 100644
--- a/design-documents/054-dynamic-form.rst
+++ b/design-documents/054-dynamic-form.rst
@@ -9,15 +9,15 @@ This document outlines the approach for implementing a 
dynamic web form feature.
 Motivation
 ==========
 
-Currently, creating a new form for a web app involves coding a new 
-page with HTML, CSS, and JS. Exchange AML requires multiple forms, 
+Currently, creating a new form for a web app involves coding a new
+page with HTML, CSS, and JS. Exchange AML requires multiple forms,
 and different instances may have distinct forms based on jurisdiction.
 
 
 Requirements
 ============
 
-A form consist of a layout and a set of fields. 
+A form consist of a layout and a set of fields.
 
 Layout requirements
 -------------------
@@ -28,8 +28,8 @@ Layout requirements
 * **accesibility**: Forms should meet accessibility level AA.
 
 * **responsive**: Forms should be responsive and function on all devices.
-  
-* **metadata**: Generated form information should contain enough data 
+
+* **metadata**: Generated form information should contain enough data
   to handle multiple form versions.
 
 Fields requirements
@@ -37,17 +37,17 @@ Fields requirements
 
 * **validations**: Each field may require custom validation
 
-* **custom data type**: A field may consist of a list, string, number, or a 
+* **custom data type**: A field may consist of a list, string, number, or a
   complex composite structure.
 
 
 Proposed Solutions
 ==================
 
-Forms are initialized using a flexible structure defined by the 
-TypeScript interface FormType<T>. This interface comprises properties 
-such as value (current form data), initial (initial form data for resetting), 
-readOnly (flag to disable input), onUpdate (callback on form data update), 
+Forms are initialized using a flexible structure defined by the
+TypeScript interface FormType<T>. This interface comprises properties
+such as value (current form data), initial (initial form data for resetting),
+readOnly (flag to disable input), onUpdate (callback on form data update),
 and computeFormState (function to derive the form state based on current data).
 
 
@@ -80,15 +80,15 @@ Fields type can be:
 
 The field type ``AmountJson`` and ``AbsoluteTime`` are opaque since field is 
used as a whole.
 
-The form can be instanciated using 
+The form can be instanciated using
 
 .. code-block:: javascript
 
   import { FormProvider } from "@gnu-taler/web-util/browser";
 
 
-Then the field component can access all the properties by the 
``useField(name)`` hook, 
-which will return 
+Then the field component can access all the properties by the 
``useField(name)`` hook,
+which will return
 
 .. code-block:: javascript
 
@@ -123,7 +123,7 @@ and should be used inside a ``Form`` context.
       <InputAmount name="amount"  />
       <InputText   name="subject" />
       <button type="submit"> Confirm </button>
-    </FormProvier>
+    </FormProvider>
   }
 
 
@@ -133,7 +133,7 @@ Example
 Consider a form shape represented by the TypeScript type:
 
 .. code-block:: javascript
-  
+
   type TheFormType = {
     name: string,
     age: number,
@@ -161,9 +161,9 @@ An example instance of this form could be:
   }
 
 
-For such a form, a valid state can be computed using a function like 
-``computeFormStateBasedOnFormValues``, returning an object indicating 
-the state of each field, including properties such as ``hidden``, 
+For such a form, a valid state can be computed using a function like
+``computeFormStateBasedOnFormValues``, returning an object indicating
+the state of each field, including properties such as ``hidden``,
 ``disabled``, and ``required``.
 
 
@@ -199,4 +199,3 @@ the state of each field, including properties such as 
``hidden``,
 
 Q / A
 =====
-
diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst
index 1ece9dda..0d09a150 100644
--- a/libeufin/regional-manual.rst
+++ b/libeufin/regional-manual.rst
@@ -11,7 +11,7 @@ how to set up one using GNU Taler and LibEuFin technology.
 
 How to create/destroy regional currency
 =======================================
-   
+
 In this model, the regional currency is backed by the fiat currency and users 
are
 offered two operations: *cash-in* to create regional currency starting from 
the fiat,
 and *cash-out* to destroy regional currency and obtain fiat currency back.
@@ -58,7 +58,7 @@ Guided basic setup
 ==================
 
 Prerequisites
--------------
++++++++++++++
 
 For this manual, we assume that the system is deployed on a contemporary
 Debian GNU/Linux or Ubuntu LTS system using the binary packages provided.
@@ -72,7 +72,7 @@ in the ``regional-currency/`` folder.
 
 
 Obtaining the scripts
----------------------
++++++++++++++++++++++
 
 First, download the deployment scripts via Git:
 
@@ -81,7 +81,7 @@ First, download the deployment scripts via Git:
   $ git clone git://git.taler.net/deployment
 
 Guided Configuration
---------------------
+++++++++++++++++++++
 
 This approach sets up a regional currency with cash-in/-out rates of 1:1.
 
@@ -110,8 +110,8 @@ desired setup, in particular:
     like "uuidgen".
   * The DNS domain name of your setup (i.e: domain.tld). The installer will
     create by itself all the needed subdomains for your domain name,
-    as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). 
-    But, these subdomain names, must have been added beforehand to your 
+    as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``).
+    But, these subdomain names, must have been added beforehand to your
     DNS domain control panel, and they must be pointing to the
     IP address of the system on which you are running the
     installation (before you execute the installer)).
@@ -160,7 +160,7 @@ and fees may apply to these conversions.  This section 
explains how to setup Lib
 Nexus to communicate with the fiat bank account that backs the regional 
currency.
 
 Prerequisites
--------------
++++++++++++++
 
 You must have a bank account at a bank dealing in fiat currency that offers an
 online banking protocol supported by LibEuFin Nexus. As legacy transactions
@@ -173,7 +173,7 @@ own dialects of finance messages and thus other retail 
banks may or may not work
 Contact us if you need support for another bank or core banking protocol.
 
 EBICS setup
------------
++++++++++++
 
 Follow the instructions from :ref:`EBICS subscriber setup <ebics-setup>` to
 configure the LibEuFin Nexus for access to your fiat bank account, but do edit
@@ -224,7 +224,7 @@ After providing the details and confirming, the shop is 
ready to generate orders
 and accept payments.
 
 Make an order
--------------
++++++++++++++
 
 Click on ``Orders`` at the top left corner of the merchant backoffice page; the
 following page should appear
@@ -243,7 +243,7 @@ to withdraw Taler coins and spend them to buy the order we 
just created.
 .. _withdraw-simulation:
 
 Pay for the order
------------------
++++++++++++++++++
 
 This section explains how to pay for the order in a scenario where the fiat 
bank
 is simulated.  The simulation takes place by crafting ad-hoc XML files as if 
the
@@ -338,18 +338,18 @@ should then be able to start a cash out operation.
 
   Enable regional currency conversion
   ===================================
-  
+
   Prerequisites
-  -------------
-  
+  +++++++++++++
+
   This step assumes that you already have a working regional currency bank
   and have successfully connected to a backing fiat bank account.
-  
+
   Additionally, for each account that is allowed to convert regional currency
   into fiat, you must configure the (fiat) bank account number of the fiat
   currency with the respective account profile.  Only the bank ``admin`` is
   allowed to set fiat bank account numbers.
-  
+
   Furthermore, to achieve a reasonable security level, you must enable two
   factor authentication for "cash out" transactions. This requires you to
   configure an e-mail address or phone number for every account that supports
@@ -357,85 +357,85 @@ should then be able to start a cash out operation.
   SMS. This manual does not cover setting up e-mail.  For SMS delivery, you 
will
   need to obtain credentials from an SMS provider and provide a script to send
   messages via such a provider.
-  
+
   Configuration
-  -------------
-  
+  +++++++++++++
+
   You have to enable conversion and at least one TAN channel for cashout in the
   ``/etc/libeufin/libeufin-bank.conf`` configuration file:
-  
+
   .. code-block:: console
-  
+
     [libeufin-bank]
     ALLOW_CONVERSION = yes
     FIAT_CURRENCY = EUR
-  
+
     TAN_SMS = libeufin-tan-sms.sh
     # And/Or
     TAN_EMAIL = libeufin-tan-email.sh
-  
+
   Afterwards, restart the bank:
-  
+
   .. code-block:: console
-  
+
     # systemctl restart libeufin-bank
-  
-  
+
+
   The scripts TAN_SMS/EMAIL must accept the phone number / e-mail address
   as the ``$1`` parameter and the content in their standard input.  The 
LibEuFin
   repository offers them in ``contrib/``: adjust to your setup!
 
   .. note::
-    
+
     the TAN_SMS script relies on a Telesign account.  For this reason,
     it needs a telesign-secret file found in the PATH, that defines the
     environment variables API_KEY and CUSTOMER_ID
-  
+
   Web-based Configuration
-  -----------------------
-  
+  +++++++++++++++++++++++
+
   Now you should be able to setup conversion rates and ``admin`` debt limit 
though the Web
   interface of the bank as the ``admin`` user.
-  
-  
+
+
   Conversion ON!
-  --------------
-  
+  ++++++++++++++
+
   The last step is to enable the Nexus services to import incoming bank
   transactions (cash in) and to trigger outgoing bank transactions (cash out):
-  
+
   .. code-block:: console
-  
+
     # systemd enable --now libeufin-nexus-ebics-fetch
     # systemd enable --now libeufin-nexus-ebics-submit
-  
+
   Going live!
   ===========
-  
+
   Exchange setup
-  --------------
-  
+  ++++++++++++++
+
   First, you need to use the ``taler-exchange-offline`` tool to inform the
   exchange about the fiat bank account that can be used for cash in operations
   and also specify the URL for currency conversion. Additionally, you may also
   configure restrictions on the bank accounts that may originate the funds, for
   example to prevent international wire transfers that may expose you to
   additional compliance risks.
-  
+
   Given the ``$IBAN`` of the fiat currency bank account and ``$NAME`` as
   the (URL-encoded) name of the exchange-account owner, the following
   ``taler-exchange-offline`` invocation can be used to inform wallets about
   the possibility of currency conversion (cash in) when wallets download
   ``/keys`` with bank account data from the exchange:
-  
+
   .. code-block:: console
-  
+
     # taler-exchange-offline \
         enable-account \
           payto://iban/$IBAN?receiver-name=$NAME \
           conversion-url "$CONVERSION_URL" \
         upload
-  
+
   Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion
   endpoint of the bank, which should be 
``https://bank.$DOMAIN/conversion-info/``
   in our setup.
diff --git a/manpages/taler-merchant-depositcheck.1 
b/manpages/taler-merchant-depositcheck.1
new file mode 100644
index 00000000..d0af4cda
--- /dev/null
+++ b/manpages/taler-merchant-depositcheck.1
@@ -0,0 +1,72 @@
+taler-merchant-depositcheck(1)
+##############################
+
+.. only:: html
+
+   Name
+   ====
+
+   **taler-merchant-depositcheck** - check if deposits are associated with 
wire transfers
+
+
+Synopsis
+========
+
+**taler-merchant-depositcheck**
+[**-c** *FILENAME* | **--config=**\ ‌\ *FILENAME*]
+[**-e** *BASE_URL* | **--exchange=**\ \ *BASE_URL*]
+[**-h** | **--help**]
+[**-L** *LOGLEVEL* | **--loglevel=**\ ‌\ *LOGLEVEL*]
+[**-l** *FILENAME* | **--logfile=**\ ‌\ *FILENAME*]
+[**-t** | **--test**]
+[**-v** | **--version**]
+
+Description
+===========
+
+**taler-merchant-depositcheck** is a command-line tool to inquire with 
exchanges about whether they completed
+bank transfers in response to deposits made by the
+merchant backend.  This will allow the merchant backend to detect deposit 
issues, for example if a KYC is blocking
+a wire transfer.
+
+Its options are as follows:
+
+**-c** *FILENAME* \| **--config=**\ ‌\ *FILENAME*
+   Use the configuration and other resources for the merchant to operate
+   from *FILENAME*.
+
+**-e** *BASE_URL* \| **--exchange=**\ ‌\ *BASE_URL*
+   Base URL of the exchange to monitor. If not given, a worker process will be 
spawned for each exchange in the configuration ("merchant-exchange-" sections).
+
+**-h** \| **--help**
+   Print short help on options.
+
+**-L** *LOGLEVEL* \| **--loglevel=**\ ‌\ *LOGLEVEL*
+   Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``,
+   ``WARNING``, ``ERROR``.
+
+**-l** *FILENAME* \| **--logfile=**\ ‌\ *FILENAME*
+   Send logging output to *FILENAME*.
+
+**-s** *SECTION* \| **--section=**\ \ *SECTION*
+   Configuration section to use. Default is taler-merchant-depositcheck. Needed
+   if different processes are used to watch multiple bank accounts (for the
+   same instance or different instances).
+
+**-t** \| **--test**
+   Run in test mode. Only runs until the current list of bank
+   transactions are all imported.
+
+**-v** \| **–version**
+   Print version information.
+
+See Also
+========
+
+taler-merchant-httpd(1), taler.conf(5).
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst
index 680dd02c..9f9bf1f7 100644
--- a/taler-auditor-manual.rst
+++ b/taler-auditor-manual.rst
@@ -667,6 +667,7 @@ local tables:
    CONFIG = "postgres:///taler-ingress"
 
 .. code-block:: console
+
    # As the 'ingress' user of the exchange:
    $ taler-exchange-dbinit
 

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.