[taler-docs] branch master updated: more work on bank documentation

[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 f4cc36c3 more work on bank documentation
f4cc36c3 is described below

commit f4cc36c3b3ef69900f2c5a3da760364be7010795
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sun Jan 21 20:01:00 2024 +0100

    more work on bank documentation
---
 libeufin/bank-manual.rst     | 134 +++++++++++++++++++++++++++++++------------
 libeufin/nexus-manual.rst    |  40 +++++++------
 libeufin/regional-manual.rst |  78 ++++++++++++++++++-------
 3 files changed, 174 insertions(+), 78 deletions(-)

diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst
index e627ae68..af977492 100644
--- a/libeufin/bank-manual.rst
+++ b/libeufin/bank-manual.rst
@@ -41,9 +41,9 @@ be found in the $PATH.
 Setting up the LibEuFin Bank
 ============================
 
-The following snippet shows the mandatory configuration values :
+The following snippet shows the mandatory configuration values:
 
-.. code-block:: console
+.. code-block:: ini
 
   [libeufin-bank]
   CURRENCY = KUDOS
@@ -64,69 +64,127 @@ command would define the database schema and create an 
admin account.
 
 .. code-block:: console
 
-  libeufin-bank dbinit -c $config_file
+  $ libeufin-bank dbinit -c $config_file
 
 If you wish to authenticate as admin, you must change the account password 
with the following command.
 
 .. code-block:: console
 
-  libeufin-bank passwd -c $config_file admin $PASSWORD
+  $ libeufin-bank passwd -c $config_file admin $PASSWORD
 
 Then you can start the HTTP server.
 
 .. code-block:: console
 
-  libeufin-bank serve -c $config_file
+  $ libeufin-bank serve -c $config_file
 
-Enable regional currency conversion
-===================================
 
-Prerequisites
--------------
+Using custom e-mail / SMS TAN scripts
+-------------------------------------
 
-This step assumes that you already have a working regional currency bank
-and have successfully connected to a backing fiat bank account. 
-Follow the instructions from :ref:`EBICS subscriber setup <ebics-setup>`.
+The guided setup installs the TAN scripts found in ``libeufin/contrib/``:
+``libeufin-tan-email.sh`` and ``libeufin-tan-sms.sh``, but should you want to
+use custom scripts to send the e-mail or SMS TAN, set the configuration like
+follows:
 
-Configuration
--------------
+.. note::
 
-Then you have to enable conversion and at least one TAN channel for cashout in 
the configuration file.
+  The default SMS TAN script is based on the `Telesign 
<https://www.telesign.com>`_ provider.
 
-.. code-block:: console
+.. code-block:: ini
 
   [libeufin-bank]
-  ALLOW_CONVERSION = yes
-  FIAT_CURRENCY = EUR
 
-  TAN_SMS = libeufin-tan-sms.sh
-  # And/Or
-  TAN_EMAIL = libeufin-tan-email.sh
+  TAN_SMS = custom-tan-sms.sh
+  TAN_EMAIL = custom-tan-email.sh
 
+The scripts TAN_SMS/EMAIL must accept the phone number / e-mail address as the
+``$1`` parameter and the message content to be transmitted in their standard
+input.
 
-You must have an exchange account with username ``exchange`` for conversion to 
work. 
-Assuming that the configuration file exists at ``$config_file``, the following
-command would create one: 
 
-.. code-block:: console
-  
-  libeufin-bank create-account 
'{"username":"exchange","password":"password","name":"Cashout 
Exchange","is_taler_exchange":true}' -c $config_file
+Using the Bank Web Interface
+============================
 
-Then the following command would start the server with conversion API enabled :
+Before you can use the Web interface, you must set
+a password for the "admin" account. You can do this
+using:
 
 .. code-block:: console
 
-  libeufin-bank serve -c $config_file
+  $ libeufin-bank passwd -c $config_file admin "$PASSWORD"
+
+Setting up Accounts
+-------------------
+
+Using the above "$PASSWORD", log into the Web interface as "admin". Then
+search for the button "Create account" near the list of all existing bank
+accounts in the Web interface of libeufin-bank.
+
+You will be asked to specify:
+
+Username
+  A unique account name the user will use to access the bank account.
+
+Name
+  Legal name of the user or business owning the account.
+
+Email
+  E-mail address of the account owner. Can be used to send a TAN message for 
2-factor authentication (if enabled).
+
+Phone
+  Mobile phone number of the account owner. Can be used to send a TAN message 
for 2-factor authentication (if enabled).
+
+Max debt
+  Maximum amount the account is allowed to go into debt. Non-zero settings 
**must** be used for the "admin" account where this setting effectively creates 
a limit on the amount of money managed by the bank.
+
+Is this a Taler Exchange?
+  Should be disabled except if you are setting up an account for a GNU Taler 
exchange. If enabled, transactions that are not compatible with a GNU Taler 
exchange will be automatically refused by the bank.
+
+XXX Cashout channel
+  Used in a regional currency setup to specify the external account number of 
a bank account in fiat currency that belongs the merchant. Allows the merchant 
to exchange its regional currency money for wire transfers in fiat currency 
into this account. Optional. Not available unless the bank is configured for 
regional currencies.
+
+Is this account public?
+  Public accounts can be viewed without access control, their balance and 
transaction history becomes public.
+
+After submitting the form, a randomly created password
+for the new account will be shown in a notification.
+The administrator can also change passwords for any
+account in the system using the "change password" link
+in the account list. To change other details about an
+account, select the "Username" in the account list.
+
+
+Account Introspection
+---------------------
+
+Users can see (and possibly change) the settings of
+their bank account and also their IBAN by clicking
+on the "Welcome, $USERNAME" text after logging into
+their bank account using their username and password.
+
+The IBAN field has a convenient "copy to clipboard"
+button next to it.
+
+
+Making Transfers between Accounts
+---------------------------------
+
+First, you need to know the IBAN of the account to credit, and log in as the
+user of the account to be debited. Then select "Using a form", enter the IBAN
+under "Recipient" and specify a wire transfer subject and the total amount to
+be wired. After pressing "Send", you may have to pass a 2-FA check.
+
+
+Integration with the Taler Exchange
+===================================
 
-Web-based Configuration
------------------------
+Exchange 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.
+TODO.
 
-Conversion ON!
---------------
+Withdrawing e-cash to a Taler wallet
+------------------------------------
 
-The last step is to run Nexus to import incoming bank
-transactions (cash in) and to trigger outgoing bank transactions (cash out).
-Refers to ``nexus-manual.conf`` for more details.
\ No newline at end of file
+TODO.
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
index 99a41c54..bc4ca471 100644
--- a/libeufin/nexus-manual.rst
+++ b/libeufin/nexus-manual.rst
@@ -35,7 +35,7 @@ Navigate into the *libeufin* local repository, and from 
top-level run:
 
   $ ./bootstrap
   $ ./configure --prefix=$PREFIX
-  $ make install 
+  $ make install
 
 If the previous steps succeeded, the ``libeufin-nexus`` command should
 be found in the $PATH.
@@ -59,16 +59,16 @@ for submittable payments in the database.
 
 The connection string is specified as
 
-.. code-block:: console
-  
+.. code-block:: ini
+
   [nexus-postgres]
 
   config = postgres:///nexus
 
 The frequency **may** be specified as
 
-.. code-block:: console
-  
+.. code-block:: ini
+
   [nexus-submit]
   frequency = 5m
   # Optional, but useful to check what Nexus sends to the bank
@@ -81,7 +81,7 @@ created, therefore run the following command:
 
 .. code-block:: console
 
-  libeufin-nexus dbinit -c $config_file
+  $ libeufin-nexus dbinit -c $config_file
 
 Where ``$config_file`` is the path to a configuration path that contains at
 least the ``[nexus-postgres]`` section.
@@ -107,7 +107,7 @@ subject.
 
 .. code-block:: console
 
-  ./payment_initiation_debug.sh $config_file CH987654321 "Hello, Nexus!"
+  $ ./payment_initiation_debug.sh $config_file CH987654321 "Hello, Nexus!"
 
 ``$config_file`` is the path to Nexus' configuration file and it does not need
 the FREQUENCY value.  If the previous command worked, now the database should
@@ -120,7 +120,7 @@ send it to the bank.
 
 .. code-block:: console
 
-  libeufin-nexus ebics-submit -c $config_file --transient
+  $ libeufin-nexus ebics-submit -c $config_file --transient
 
 The ``--transient`` flag instructs the software to perform only one pass on
 the database, submit what is submittable, and return.
@@ -142,7 +142,7 @@ payment according to their submission state.
 
 .. code-block:: console
 
-  libeufin-nexus ebics-submit -c $config_fixed_frequency
+  $ libeufin-nexus ebics-submit -c $config_fixed_frequency
 
 
 Transient mode causes ``ebics-submit`` to check the database only once, submit 
any
@@ -150,7 +150,7 @@ initiated payment according to their submission state, and 
return.
 
 .. code-block:: console
 
-  libeufin-nexus ebics-submit -c $config
+  $ libeufin-nexus ebics-submit -c $config
 
 Downloading records
 ===================
@@ -162,8 +162,8 @@ The configuration file must contain all the 
``[ebics-setup]`` sections, plus the
 values to set the database connection and a log directory where any downloaded 
record would
 be stored.
 
-.. code-block:: console
-  
+.. code-block:: ini
+
   [nexus-postgres]
   config = postgres:///nexus
   [nexus-fetch]
@@ -175,7 +175,7 @@ would download any unseen notifications (as camt.054 files).
 
 .. code-block:: console
 
-  libeufin-nexus ebics-fetch -c $config_file --transient
+  $ libeufin-nexus ebics-fetch -c $config_file --transient
 
 The ``--transient`` flag makes the command to download only once and return.  
If the
 bank returned any records, look in ``$LIBEUFIN_DATA_HOME/camt/YYYY-MM-DD`` to 
find them.
@@ -184,8 +184,9 @@ YYYY-MM-DD is the date when the download took place.
 To activate periodic downloads, add the following setting to the 
``nexus-fetch``
 configuration section in ``$config_file``:
 
-.. code-block:: console
+.. code-block:: ini
 
+   [nexus-fetch]
    frequency = 5m
 
 The following invocation would then download records every five minutes, 
asking the bank
@@ -193,7 +194,7 @@ to only return documents that are timestamped *from* 
(inclusive) the last incomi
 
 .. code-block:: console
 
-  libeufin-nexus ebics-fetch -c $config_file
+  $ libeufin-nexus ebics-fetch -c $config_file
 
 Testing
 -------
@@ -205,7 +206,7 @@ in order to have the redownloaded transactions ingested.
 
 .. note::
 
-   double-check the configuration: resetting the wrong database might cause 
DATA LOSS!
+   Double-check the configuration: resetting the wrong database might cause 
DATA LOSS!
 
 For example, say that three back on the 2023-06-01 an handful of incoming 
transactions
 got booked at the bank account watched by Nexus.  After such day, the 
following command
@@ -213,6 +214,9 @@ would redownload them (and ingest them, if the database 
doesn't have them):
 
 .. code-block:: console
 
-  libeufin-nexus ebics-fetch -c $config_file --pinned-start 2023-06-01
+  $ libeufin-nexus ebics-fetch -c $config_file --pinned-start 2023-06-01
+
+
+.. note::
 
-Note: the command redownloads transactions *from* the pinned start until the 
present.
+   The command redownloads transactions *from* the pinned start until the 
present.
diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst
index ec7b4e2d..e497e8c9 100644
--- a/libeufin/regional-manual.rst
+++ b/libeufin/regional-manual.rst
@@ -128,28 +128,6 @@ Grab a coffee.
 
   At this point, the setup is NOT connected to any fiat bank account!
 
-Custom e-mail / SMS TAN scripts
-===============================
-
-The guided setup installs the TAN scripts found in ``libeufin/contrib/``:
-``libeufin-tan-email.sh`` and ``libeufin-tan-sms.sh``, but should you want
-to use custom scripts to send the e-mail or SMS TAN, set the configuration
-like follows:
-
-.. note::
-
-  the default SMS TAN script is based on the `Telesign 
<https://www.telesign.com>`_ provider.
-
-.. code-block:: console
-
-  [libeufin-bank]
-
-  TAN_SMS = custom-tan-sms.sh
-  TAN_EMAIL = custom-tan-email.sh
-
-The scripts TAN_SMS/EMAIL must accept the phone number / e-mail address
-as the ``$1`` parameter and the content in their standard input.
-
 Connecting to a Fiat Bank
 =========================
 
@@ -182,6 +160,62 @@ EBICS setup
   For debug setups where the cash-ins are simulated :ref:`this way 
<withdraw-simulation>`,
   this step can be entirely skipped.
 
+
+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.
+Follow the instructions from :ref:`EBICS subscriber setup <ebics-setup>`.
+
+Configuration
+-------------
+
+Then you have to enable conversion and at least one TAN channel for cashout in 
the configuration file.
+
+.. code-block:: ini
+
+  [libeufin-bank]
+  ALLOW_CONVERSION = YES
+  FIAT_CURRENCY = EUR
+
+  TAN_SMS = libeufin-tan-sms.sh
+  # And/Or
+  TAN_EMAIL = libeufin-tan-email.sh
+
+
+You must have an exchange account with username ``exchange`` for conversion to 
work.
+Assuming that the configuration file exists at ``$config_file``, the following
+command would create one:
+
+.. code-block:: console
+
+  libeufin-bank create-account 
'{"username":"exchange","password":"password","name":"Cashout 
Exchange","is_taler_exchange":true}' -c $config_file
+
+Then the following command would start the server with conversion API enabled :
+
+.. code-block:: console
+
+  libeufin-bank serve -c $config_file
+
+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 run Nexus to import incoming bank
+transactions (cash in) and to trigger outgoing bank transactions (cash out).
+Refers to ``nexus-manual.conf`` for more details.
+
+
+
 Configuring the merchant
 ========================
 

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