Minor improvement and typo correction

2 files changed, 253 insertions, 4 deletions

diff --git a/libeufin/#regional-manual.rst# b/libeufin/#regional-manual.rst#
new file mode 100644
index 00000000..345c4403
--- /dev/null
+++ b/libeufin/#regional-manual.rst#
@@ -0,0 +1,246 @@
+.. 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 (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 before to your DNS domain control panel , and furthermore, they must be pointing to the IP address of your server of the system on which you are running the installation (before you execute the installer)).
+
+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 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
+
+  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.
+
+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 notify wallets about
+the possibility of currency conversion (cash in):
+
+.. 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.
+
+
+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.
+
+
diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst
index d072b30a..548ce24a 100644
--- a/libeufin/regional-manual.rst
+++ b/libeufin/regional-manual.rst
@@ -68,10 +68,13 @@ desired setup, in particular:
   * 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 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 
+    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)).
 
 The information you entered will be stored in a file called
 ``config/user.conf``. Should you run the script in the future (for