[taler-docs] branch master updated: regional currency manual, first draft

[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 8b5d2274 regional currency manual, first draft
8b5d2274 is described below

commit 8b5d22743a907a8f10a0289701e33859d4a7d1ba
Author: Christian Grothoff <grothoff@gnunet.org>
AuthorDate: Tue Nov 28 13:21:16 2023 +0900

    regional currency manual, first draft
---
 libeufin/index.rst           |   1 +
 libeufin/nexus-manual.rst    |   7 +-
 libeufin/regional-manual.rst | 228 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 235 insertions(+), 1 deletion(-)

diff --git a/libeufin/index.rst b/libeufin/index.rst
index 985e92b6..042388dc 100644
--- a/libeufin/index.rst
+++ b/libeufin/index.rst
@@ -9,4 +9,5 @@ LibEuFin is a project providing free software tooling for 
European FinTech.
 
   nexus-manual
   bank-manual
+  regional-manual
   setup-ebics-at-postfinance
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
index 63dbb0d5..686bb1ff 100644
--- a/libeufin/nexus-manual.rst
+++ b/libeufin/nexus-manual.rst
@@ -45,7 +45,12 @@ be found in the $PATH.
 Setting up the EBICS subscriber
 ===============================
 
-The following snippet shows the mandatory configuration values.
+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/libeufin-nexus.conf`` configuration file together with the
+name of the *fiat* currency.
+
+The following snippet shows the mandatory configuration values:
 
 .. _core-config:
 
diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst
new file mode 100644
index 00000000..fa6778c0
--- /dev/null
+++ b/libeufin/regional-manual.rst
@@ -0,0 +1,228 @@
+.. target audience: operator
+
+Regional Currency Setup Manual
+##############################
+
+.. contents:: Table of Contents
+
+GNU Taler can be used to operate a regional currency. For this, LibEuFin Bank
+is setup to operate bank accounts in the regional currency that ultimately
+interact with the GNU Taler exchange.  Optionally, LibEuFin Nexus be used to
+integrate with the traditional core banking system, and then the LibEuFin
+Conversion triggers help convert fiat currency to regional currency and vice
+versa.  Conversion rates and limits can be applied when converting between
+the regional currency and the fiat currency.
+
+
+In this manual, we explain how to setup such a regional currency.
+
+
+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.
+Furthermore, you should run the process on a system with one or more globally
+reachable IP address(es) *and* with various DNS names already pointing to
+these IPs.
+
+To further simplify the process, we suggest to use (or at least study) the
+automatic deployment scripts provided in the ``deployment.git`` Git repository
+in the ``netzbon/`` folder.
+
+
+Obtaining the scripts
+---------------------
+
+First, download the deployment scripts via Git:
+
+.. code-block:: console
+
+  $ git clone git://git.taler.net/deployment
+
+Guided Configuration
+--------------------
+
+Navigate into the *netzbon/* directory, and as **root** run:
+
+.. code-block:: console
+
+  # ./main.sh
+
+The script will start by asking you fundamental questions about the
+desired setup, in particular:
+
+  * The name of the regional currency. It must have 3 to 11 letters.
+  * The name of the regional currency bank. It will be shown to business
+    users when they interact with the system.
+  * Whether to use TLS. You should answer ``y`` in most cases.
+  * Whether to run taler-exchange-offline. Unless you need a high-security
+    setup and expect to run an offline key management process, say ``y``.
+    If you say ``n``, you will need to run ``taler-exchange-offline setup``
+    on your offline system and provide the master public key. Furthermore,
+    you should then study the exchange manual on
+    offline key management to finish the exchange setup process later.
+  * The admin password for the bank. Be absolutely sure to enter a very,
+    very long and high-entropy password, preferably generated by a tool
+    like "uuidgen".
+  * The DNS domain name of your setup. Various sub-domains (specifically,
+    ``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN`` must
+    already exist and point to the public IP address of the system on which
+    you are running the installation).
+
+The information you entered will be stored in a file called
+``config/user.conf``. Should you run the script in the future (for
+example, to upgrade the installation), you will not be asked these
+questions a second time.
+
+After answering all of the questions, the actual installation will
+start. The scripts will download and configure various packages,
+which may take some time. Grab a coffee.
+
+Connecting to a Fiat Bank
+=========================
+
+Some regional currencies are backed by assets in a fiat currency
+and allow users to convert fiat currency into the regional
+currency (``cash in``) and to convert regional currency into
+fiat currency (``cash out``). Restrictions, exchange rates and
+fees may apply to these conversions.  This section explains how
+to setup LibEuFin 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
+in that bank account would likely confuse the system, it is highly advised to
+use a fresh account with an empty transaction history.
+
+Today, the LibEuFin implementation supports EBICS 2.5 and 3.0 and has been
+tested with the GLS Bank (EUR) and the Postfinance (CHF). Please note that
+banks tend to have their 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.
+
+Once you have accepted the bank keys, you should
+setup currency conversion before actually starting
+to import transactions.
+
+
+
+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
+"cash out" transactions --- and to setup your system for sending e-mails or
+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 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
+
+  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
+
+
+Web-based Configuration
+-----------------------
+
+Now you should be able to setup conversion rates 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.
+
+Wallet setup
+------------
+
+Next, you need to add your regional currency exchange to the wallet.  This can
+be done by scanning a QR code with a ``taler://add-exchange/exchange.$DOMAIN``
+URL or by manually entering the URL into the respective ``Add exchange``
+dialogue.
+
+With this, you should then be able to ``add`` funds in the regional currency
+to your exchange by starting the withdraw process in the wallet. After
+specifying the desired amount, the wallet should show you the details of the
+fiat wire transfer that must be made for the cash in to be completed. Once the
+money has arrived at the fiat bank account, Nexus will obtain the transaction
+data and the regional currency bank will create the corresponding amount in
+regional currency, crediting the GNU Taler exchange account. In turn, the
+exchange will issue the respective amount to your wallet.
+
+For testing, you should be able to *deposit* regional currency directly
+into a LibEuFin Bank account from the Taler wallet.  Once the exchange
+has credited the reginal currency account, log into the bank account
+using the Web interface. Assuming the cash out rules are satisfied, you
+should then be able to start a cash out operation. This will trigger a
+transfer from your regional currency account to the regional currency
+master ``bank`` account which will effectively destroy the respective
+amount of regional currency. The conversion triggers will inform Nexus
+about the destruction and Nexus will then wire the corresponding amount
+in fiat to the associated fiat bank account.
+
+

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