commit 32b087689c7205875e3edf2e806b1eb6e6ccd8da
parent 738347d169e4f5fe2a57d21b439efb82b0971821
Author: Antoine A <>
Date: Tue, 20 Feb 2024 15:54:28 +0100
Split regional manual in two
Diffstat:
9 files changed, 492 insertions(+), 475 deletions(-)
diff --git a/frags/nexus-ebics-setup.rst b/frags/nexus-ebics-setup.rst
@@ -0,0 +1,65 @@
+
+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.
+
+.. note::
+ As legacy transactions in that bank account would likely confuse the system, it is advisable to use a fresh bank account with an empty transaction history.
+
+The following snippet shows the mandatory configuration values:
+
+.. _core-config:
+
+.. code-block:: ini
+
+ [nexus-ebics]
+ CURRENCY = CHF
+
+ # Bank
+ HOST_BASE_URL = https://ebics.postfinance.ch/ebics/ebics.aspx
+ BANK_DIALECT = postfinance
+
+ # EBICS IDs
+ HOST_ID = PFEBICS
+ USER_ID = PFC00563
+ PARTNER_ID = PFC00563
+
+ # Account information
+ IBAN = CH7789144474425692816
+ BIC = POFICHBEXXX
+ NAME = John Smith S.A.
+
+.. note::
+ Refer to the manpage ``libeufin-nexus.conf(5)``
+ for the full array of configuration values.
+
+.. warning::
+ This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost.
+
+.. note::
+ If you want to use existing client keys, copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` with the default config) before running the following commands.
+
+Assuming that the configuration file exists at ``$CONFIG_FILE``, the following
+command should start the EBICS setup process:
+
+.. code-block:: console
+
+ $ libeufin-nexus ebics-setup -c "$CONFIG_FILE"
+
+If the previous command failed when running EBICS INI with an error code of
+``EBICS_INVALID_USER_STATE``, you need to confirm your keys to your bank to
+activate your account.
+
+To that end, the previous run should have left a PDF document that you can
+print, sign and send to the bank. Look for the message that looks like ``PDF
+file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``.
+
+Once the bank has received and processed this document, run the same
+command again to download and verify the bank's keys:
+
+.. code-block:: console
+
+ $ libeufin-nexus ebics-setup -c "$CONFIG_FILE"
+
+The EBICS setup is finished once the bank keys have been accepted.
+\ No newline at end of file
diff --git a/frags/regional-manual-architecture.rst b/frags/regional-manual-architecture.rst
@@ -0,0 +1,48 @@
+Architecture
+============
+
+There are several key components needed to operate a regional currency based
+on GNU Taler and LibEuFin technology:
+
+- LibEuFin Nexus: is responsible to drive the master (fiat) bank account both to learn
+ about incoming payments and to send fiat cash-out payments
+- LibEuFin Bank: offers basic banking operations, e.g. wire transfers, Taler withdrawals,
+ account management, cash-out's
+- Taler exchange: server side of Taler operations.
+- Taler wallet: client side of Taler operations.
+- Taler merchant backend: abstracts Taler details to the shops.
+
+.. image:: ../images/regional-arch.png
+
+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 fiat money, and *cash-out* to convert regional currency into fiat
+currency.
+
+The design assumes that one single unit of regional currency is always backed
+by one single unit of fiat currency.
+
+
+Cash-in
++++++++
+
+One fundamental entity to create the regional currency is the *master bank account*.
+The master bank account is hosted at one fiat bank and whenever it receives a *valid*
+fiat payment of N units, it triggers the creation of N units of regional currency.
+Such trigger causes the *admin bank account* at the regional bank to wire the N units of
+regional currency to the Taler exchange (regional) bank account. At this point, the
+Taler exchange is ready to issue the regional coins to the Taler wallet that proves
+to own them.
+
+.. note::
+
+ *Valid* fiat payments are those with a Taler-relevant subject that should be generated by a Taler wallet.
+
+
+Cash-out
+++++++++
+
+Once a regional bank user confirms a cash-out operation of N units, the system sends
+a regional payment of N units to the *admin bank account*. This latter triggers then
+a fiat payment of N units to the fiat bank account owned by the user who initiated the
+cash-out.
+\ No newline at end of file
diff --git a/frags/regional-manual-use.rst b/frags/regional-manual-use.rst
@@ -0,0 +1,70 @@
+Using the Regional Currency
+===========================
+
+Wallet Setup
+++++++++++++
+
+This section describes the interaction between the Taler graphical wallet (Android,
+iOS, WebExtensions) and the regional currency system.
+
+You need to add your regional currency exchange to the wallet. This can
+be done by scanning a QR code with a ``taler://withdraw-exchange/exchange.$DOMAIN``
+URL or by manually entering the URL into the respective ``Add exchange``
+dialogue.
+
+
+Cash-In
++++++++
+
+Next, start the withdraw process in the Taler wallet for the respective
+currency and specify the desired amount. The wallet will then 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.
+
+.. note::
+
+ Cash-in operations may be subject to conversion rates, conversion fees and
+ minimum amounts to be transferred.
+
+
+Making payments
++++++++++++++++
+
+For testing, you should be able to *deposit* regional currency directly into
+your regional currency libeufin-bank account directly from the Taler wallet.
+For this, you primarily need to know your bank account details (which should
+be accessible by clicking on your name in the bank Web site after logging in).
+
+.. note::
+
+ There may be a short delay between the wallet making the deposit and
+ the exchange crediting your bank account. This is because the wallet
+ uses a small wire transfer delay by default when initiating a deposit
+ into a bank account.
+
+For production, it is more common for a shop to configure a :ref:`Taler
+merchant backend <taler-merchant-backend-operator-manual>` or at least use an
+instance within such a setup. To configure an instance, you primarily need
+again the bank account details to :ref:`setup instance bank accounts
+<instance-bank-account>`.
+
+
+Cash-Out
+++++++++
+
+Regional currency accounts that have a positive balance could be eligible for
+cash-out. Cash-out operations may again be restricted by the regional
+currency operator and will *only* be made to the respective pre-configured
+fiat currency bank account. To cash-out, simply log into your regional
+currency account, select cash-out, specify the desired amount and pass the
+second-factor authorization challenge by entering the TAN you receive at the
+registered e-mail address or mobile phone number.
+
+.. note::
+
+ Cash-out operations may be subject to conversion rates, conversion fees and
+ minimum amounts to be transferred.
diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst
@@ -258,7 +258,7 @@ Integration with the Taler Exchange
.. note::
- This step is fully automated if you use the :ref:`guided automated setup <automated-regional-currency-setup>`.
+ This step is fully automated if you use the :doc:`automated setup manual<regional-automated-manual>`.
You must have an exchange account with username ``exchange`` for conversion to work.
Assuming that the configuration file exists at ``$CONFIG_FILE``, the following
@@ -284,7 +284,7 @@ Withdrawing e-cash to a Taler wallet
.. note::
- This step is fully automated if you use the :ref:`guided automated setup <automated-regional-currency-setup>`.
+ This step is fully automated if you use the :doc:`automated setup manual<regional-automated-manual>`.
Users can withdraw digital cash from their bank account starting from their
online banking as implemented by the libeufin-bank. However, in this scenario,
diff --git a/libeufin/index.rst b/libeufin/index.rst
@@ -29,5 +29,6 @@ LibEuFin is a project providing free software tooling for European FinTech.
nexus-manual
bank-manual
- regional-manual
+ regional-automated-manual
+ regional-custom-manual
setup-ebics-at-postfinance
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
@@ -90,71 +90,7 @@ be found in the $PATH.
Setting up the EBICS subscriber
===============================
-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.
-
-.. note::
- As legacy transactions in that bank account would likely confuse the system, it is advisable to use a fresh bank account with an empty transaction history.
-
-The following snippet shows the mandatory configuration values:
-
-.. _core-config:
-
-.. code-block:: ini
-
- [nexus-ebics]
- CURRENCY = CHF
-
- # Bank
- HOST_BASE_URL = https://ebics.postfinance.ch/ebics/ebics.aspx
- BANK_DIALECT = postfinance
-
- # EBICS IDs
- HOST_ID = PFEBICS
- USER_ID = PFC00563
- PARTNER_ID = PFC00563
-
- # Account information
- IBAN = CH7789144474425692816
- BIC = POFICHBEXXX
- NAME = John Smith S.A.
-
-.. note::
- Refer to the manpage ``libeufin-nexus.conf(5)``
- for the full array of configuration values.
-
-.. warning::
- This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost.
-
-.. note::
- If you want to use existing client keys, copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` with the default config) before running the following commands.
-
-Assuming that the configuration file exists at ``$CONFIG_FILE``, the following
-command should start the EBICS setup process:
-
-.. code-block:: console
-
- $ libeufin-nexus ebics-setup -c "$CONFIG_FILE"
-
-If the previous command failed when running EBICS INI with an error code of
-``EBICS_INVALID_USER_STATE``, you need to confirm your keys to your bank to
-activate your account.
-
-To that end, the previous run should have left a PDF document that you can
-print, sign and send to the bank. Look for the message that looks like ``PDF
-file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``.
-
-Once the bank has received and processed this document, run the same
-command again to download and verify the bank's keys:
-
-.. code-block:: console
-
- $ libeufin-nexus ebics-setup -c "$CONFIG_FILE"
-
-The EBICS setup is finished once the bank keys have been accepted.
-
+.. include:: ../frags/nexus-ebics-setup.rst
Database setup
==============
diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst
@@ -0,0 +1,177 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014-2024 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+ @author Marcello Stanisci
+ @author Christian Grothoff
+
+
+.. target audience: operator
+
+Regional Currency Automated Setup Manual
+########################################
+
+This manual describes how to setup a regional currency backed by a fiat currency using a script that largely automates the process. If you want to do a custom setup you can follow the :doc:`custom setup manual<regional-custom-manual>`.
+
+
+.. contents:: Table of Contents
+ :local:
+
+.. include:: ../frags/regional-manual-architecture.rst
+
+Guided Automated 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.
+
+Preparing the required subdomain names
+++++++++++++++++++++++++++++++++++++++
+
+The GNU Taler program needs to have three subdomains pointing to your server IP address, in order to let NGINX to accommodate each component.
+These are "bank", "exchange" and "backend", this said, you need to have a registered top level domain name,
+where you can create type (A) entries, as subdomains pointing to your own server public IP address.
+A very good advice when creating these subdomains, and if your domain panel lets you specify the TTL (time to live) figure, is
+to specify a very low value (such as 300), so in case of future changes, its value (the IP address), will be propagated quickly.
+
+Once you have added the three required subdomains in your domain control panel, you have to make sure as well, these subdomains have
+propagated over the Internet correctly, and they are currently publicly available.
+
+You can check this from your terminal very easily with the "ping" command, as this:
+
+.. code-block:: console
+
+ $ ping -c1 bank.domainname.ltd
+ $ ping -c1 exchange.domainname.ltd
+ $ ping -c1 backend.domainname.ltd
+
+You can also use `this tool <https://toolbox.googleapps.com/apps/dig/>`_ for the same purpose, and to check the propagation status.
+
+Now you are ready to go with the next step.
+
+Obtaining the Scripts
++++++++++++++++++++++
+
+First, download the deployment scripts via Git:
+
+.. code-block:: console
+
+ # apt update && apt install git
+ $ git clone git://git.taler.net/deployment
+
+Running the Guided Configuration
+++++++++++++++++++++++++++++++++
+
+Navigate into the *regional-currency/* directory and run *main.sh* as **root**:
+
+.. code-block:: console
+
+ $ cd deployment/regional-currency/
+ # ./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 ISO code of the fiat currency. Use 'CHF' or 'EUR'.
+* The name of the regional currency bank. It will be shown to business
+ users when they interact with the system.
+* 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 as explained before, must have been added beforehand to your
+ DNS domain control panel, and they must be pointing to the
+ IP address of the server on which you are running the
+ installation (before you execute the installer).
+* Whether to use TLS or not. 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 use the autogenerated one.
+
+The information you entered as well as the generated bank admin password will
+be stored in a file called ``config/user.conf``. If you run the script in
+the future again (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.
+
+.. note::
+
+ At this point, the setup is NOT connected to any fiat bank account! The next
+ steps must always be done manually!
+
+Running the script again from scratch
++++++++++++++++++++++++++++++++++++++
+
+If for some reason your installation doesn't work because you have answered erroneously
+some of the interactive questions, or you just want to reset the current installation and to re-deploy
+the script again for having its latest changes, you will have to proceed as follows:
+
+In brief you need to wipe completely the "content" of the file config/user.conf, this doesn't mean
+to remove the file itself, but only its content. Even though you can do this manually by editing the file manually
+with you preferred text editor, you can also do this in one single command.
+
+.. code-block:: console
+
+ $ cat /dev/null > config/user.conf
+
+.. note::
+
+ In future versions of the program when executed for the second time, the program itself will
+ show an option to offer wiping the content of this config/user.conf file, automatically.
+
+Multi-factor authentication
++++++++++++++++++++++++++++
+
+By default, multi-factor authentication via SMS and email is enabled. You have to manually configure both channels as described in :ref:`multi-factor authentication <libeufin-mfa>`.
+
+Web-based Configuration
++++++++++++++++++++++++
+
+By default, the regional currency conversion rates are 1:1. You can change the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user.
+
+Connecting to a Fiat Bank: the EBICS setup
+++++++++++++++++++++++++++++++++++++++++++
+
+To complete the conversion setup, you have to set up an EBICS subscriber using a bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus.
+
+.. include:: ../frags/nexus-ebics-setup.rst
+
+System ON!
+++++++++++
+
+The last step is to enable libeufin-nexus to :ref:`import incoming bank
+transactions <receive-transaction-data>` (cash in) and to :ref:`trigger
+outgoing bank transactions <sending-payments>` (cash out).
+
+.. code-block:: console
+
+ # systemctl enable --now libeufin-nexus-ebics-fetch
+ # systemctl enable --now libeufin-nexus-ebics-submit
+
+.. include:: ../frags/regional-manual-use.rst
+\ No newline at end of file
diff --git a/libeufin/regional-custom-manual.rst b/libeufin/regional-custom-manual.rst
@@ -0,0 +1,123 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014-2024 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+ @author Marcello Stanisci
+ @author Christian Grothoff
+
+
+.. target audience: operator
+
+Regional Currency Custom Setup Manual
+#####################################
+
+This manual describes how to setup a regional currency manually. If you want a guided setup you can follow the :doc:`automated setup manual<regional-automated-manual>`.
+
+.. contents:: Table of Contents
+ :local:
+
+.. include:: ../frags/regional-manual-architecture.rst
+
+Custom Manual Setup
+===================
+
+You first need to setup the :ref:`libeufin-bank<libeufin-bank>` and integrate it with a Taler exchange.
+
+If you don't want your regional currency to be backed by a fiat currency, you can stop here.
+
+Enabling Currency Conversion
+++++++++++++++++++++++++++++
+
+You need to setup the :ref:`libeufin-nexus<libeufin-nexus>` using a bank account at a bank dealing in fiat currency that
+offers an online banking protocol supported by LibEuFin Nexus.
+
+Next, you have to enable conversion and should ensure that at least one TAN
+channel for :ref:`multi-factor authentication <libeufin-mfa>` is configured:
+
+.. 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
+
+Make sure to (re)start the libeufin-bank after changing
+these configuration options:
+
+.. code-block:: console
+
+ # systemctl restart libeufin-bank
+
+
+Web-based Configuration
++++++++++++++++++++++++
+
+Now you have to set the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user.
+
+.. _regional-conversion-setup:
+
+Configuring the Exchange for Conversion
++++++++++++++++++++++++++++++++++++++++
+
+This section explains how to enable currency conversion at the exchange,
+which is critical for wallets to know how to wire fiat currency to an
+exchange to obtain regional currency.
+
+You will 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.
+
+.. note::
+
+ The above command adds a **second** bank account to the exchange.
+ You (or the guided setup script) should have already enabled the
+ regional currency bank account (without any "conversion-url").
+
+System ON!
+++++++++++
+
+The last step is to enable libeufin-nexus to :ref:`import incoming bank
+transactions <receive-transaction-data>` (cash in) and to :ref:`trigger
+outgoing bank transactions <sending-payments>` (cash out).
+
+.. code-block:: console
+
+ # systemctl enable --now libeufin-nexus-ebics-fetch
+ # systemctl enable --now libeufin-nexus-ebics-submit
+
+.. include:: ../frags/regional-manual-use.rst
+\ No newline at end of file
diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst
@@ -1,407 +0,0 @@
-..
- This file is part of GNU TALER.
- Copyright (C) 2014-2024 Taler Systems SA
-
- TALER is free software; you can redistribute it and/or modify it under the
- terms of the GNU Affero General Public License as published by the Free Software
- Foundation; either version 2.1, or (at your option) any later version.
-
- TALER is distributed in the hope that it will be useful, but WITHOUT ANY
- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
- A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
-
- You should have received a copy of the GNU Affero General Public License along with
- TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-
- @author Florian Dold
- @author Marcello Stanisci
- @author Christian Grothoff
-
-
-.. target audience: operator
-
-Regional Currency Setup Manual
-##############################
-
-This manual explains how to set up a regional currency that may be backed by a fiat currency. Most of the manual is concerned with setting up the currency conversion logic with a fiat bank that offers an EBICS interface.
-
-To understand how the regional currency works and how it is backed by a fiat currency, you can read about its :ref:`architecture<regional-currency-setup-architecture>`.
-
-If you want to setup a regional currency backed by a fiat currency, you can use the :ref:`guided automated setup<automated-regional-currency-setup>`, which largely automates the process. You can also follow the :ref:`manual setup<manual-regional-currency-setup>` if you want a customized one.
-
-.. contents:: Table of Contents
- :local:
-
-.. _regional-currency-setup-architecture:
-
-Architecture
-============
-
-There are several key components needed to operate a regional currency based
-on GNU Taler and LibEuFin technology:
-
-- LibEuFin Nexus: is responsible to drive the master (fiat) bank account both to learn
- about incoming payments and to send fiat cash-out payments
-- LibEuFin Bank: offers basic banking operations, e.g. wire transfers, Taler withdrawals,
- account management, cash-out's
-- Taler exchange: server side of Taler operations.
-- Taler wallet: client side of Taler operations.
-- Taler merchant backend: abstracts Taler details to the shops.
-
-.. image:: ../images/regional-arch.png
-
-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 fiat money, and *cash-out* to convert regional currency into fiat
-currency.
-
-The design assumes that one single unit of regional currency is always backed
-by one single unit of fiat currency.
-
-
-Cash-in
-+++++++
-
-One fundamental entity to create the regional currency is the *master bank account*.
-The master bank account is hosted at one fiat bank and whenever it receives a *valid*
-fiat payment of N units, it triggers the creation of N units of regional currency.
-Such trigger causes the *admin bank account* at the regional bank to wire the N units of
-regional currency to the Taler exchange (regional) bank account. At this point, the
-Taler exchange is ready to issue the regional coins to the Taler wallet that proves
-to own them.
-
-.. note::
-
- *Valid* fiat payments are those with a Taler-relevant subject that should be generated by a Taler wallet.
-
-
-Cash-out
-++++++++
-
-Once a regional bank user confirms a cash-out operation of N units, the system sends
-a regional payment of N units to the *admin bank account*. This latter triggers then
-a fiat payment of N units to the fiat bank account owned by the user who initiated the
-cash-out.
-
-
-.. _automated-regional-currency-setup:
-
-Guided Automated Setup
-======================
-
-This section describes how to setup a regional currency backed by a fiat currency using a script that largely automates the process. You can also follow the :ref:`manual setup<manual-regional-currency-setup>` if you want a customized one.
-
-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.
-
-Preparing the required subdomain names
-++++++++++++++++++++++++++++++++++++++
-
-The GNU Taler program needs to have three subdomains pointing to your server IP address, in order to let NGINX to accommodate each component.
-These are "bank", "exchange" and "backend", this said, you need to have a registered top level domain name,
-where you can create type (A) entries, as subdomains pointing to your own server public IP address.
-A very good advice when creating these subdomains, and if your domain panel lets you specify the TTL (time to live) figure, is
-to specify a very low value (such as 300), so in case of future changes, its value (the IP address), will be propagated quickly.
-
-Once you have added the three required subdomains in your domain control panel, you have to make sure as well, these subdomains have
-propagated over the Internet correctly, and they are currently publicly available.
-
-You can check this from your terminal very easily with the "dig" command, as this:
-
-.. code-block:: console
-
- $ dig -t txt bank.domainname.ltd
- $ dig -t txt exchange.domainname.ltd
- $ dig -t txt backend.domainname.ltd
-
-You can also use `this tool <https://toolbox.googleapps.com/apps/dig/>`_ for the same purpose, and to check the propagation status.
-
-Now you are ready to go with the next step.
-
-Obtaining the Scripts
-+++++++++++++++++++++
-
-First, download the deployment scripts via Git:
-
-.. code-block:: console
-
- # apt update && apt install git
- $ git clone git://git.taler.net/deployment
-
-Running the Guided Configuration
-++++++++++++++++++++++++++++++++
-
-Navigate into the *regional-currency/* directory and run *main.sh* as **root**:
-
-.. code-block:: console
-
- $ cd deployment/regional-currency/
- # ./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 ISO code of the fiat currency. Use 'CHF' or 'EUR'.
-* The name of the regional currency bank. It will be shown to business
- users when they interact with the system.
-* 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 as explained before, must have been added beforehand to your
- DNS domain control panel, and they must be pointing to the
- IP address of the server on which you are running the
- installation (before you execute the installer).
-* Whether to use TLS or not. 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 use the autogenerated one.
-
-The information you entered as well as the generated bank admin password will
-be stored in a file called ``config/user.conf``. If you run the script in
-the future again (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.
-
-.. note::
-
- At this point, the setup is NOT connected to any fiat bank account! The next
- steps must always be done manually!
-
-Running the script again from scratch
-+++++++++++++++++++++++++++++++++++++
-
-If for some reason your installation doesn't work because you have answered erroneously
-some of the interactive questions, or you just want to reset the current installation and to re-deploy
-the script again for having its latest changes, you will have to proceed as follows:
-
-In brief you need to wipe completely the "content" of the file config/user.conf, this doesn't mean
-to remove the file itself, but only its content. Even though you can do this manually by editing the file manually
-with you preferred text editor, you can also do this in one single command.
-
-.. code-block:: console
-
- $ cat /dev/null > config/user.conf
-
-.. note::
-
- In future versions of the program when executed for the second time, the program itself will
- show an option to offer wiping the content of this config/user.conf file, automatically.
-
-Multi-factor authentication
-+++++++++++++++++++++++++++
-
-By default, multi-factor authentication via SMS and email is enabled. You have to manually configure both channels as described in :ref:`multi-factor authentication <libeufin-mfa>`.
-
-Web-based Configuration
-+++++++++++++++++++++++
-
-By default, the regional currency conversion rates are 1:1. You can change the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user.
-
-Connecting to a Fiat Bank: the EBICS setup
-++++++++++++++++++++++++++++++++++++++++++
-
-To complete the conversion setup, you have to set up an EBICS subscriber as described in :ref:`EBICS setup <ebics-setup>` using a bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus.
-
-System ON!
-++++++++++
-
-The last step is to enable libeufin-nexus to :ref:`import incoming bank
-transactions <receive-transaction-data>` (cash in) and to :ref:`trigger
-outgoing bank transactions <sending-payments>` (cash out).
-
-.. code-block:: console
-
- # systemctl enable --now libeufin-nexus-ebics-fetch
- # systemctl enable --now libeufin-nexus-ebics-submit
-
-.. _manual-regional-currency-setup:
-
-Manual Setup
-============
-
-This section describes how to setup a regional currency manually.
-
-You first need to setup the :ref:`libeufin-bank<libeufin-bank>` and integrate it with a Taler exchange.
-
-If you don't want your regional currency to be backed by a fiat currency, you can stop here.
-
-Enabling Currency Conversion
-++++++++++++++++++++++++++++
-
-You need to setup the :ref:`libeufin-nexus<libeufin-nexus>` using a bank account at a bank dealing in fiat currency that
-offers an online banking protocol supported by LibEuFin Nexus.
-
-Next, you have to enable conversion and should ensure that at least one TAN
-channel for :ref:`multi-factor authentication <libeufin-mfa>` is configured:
-
-.. 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
-
-Make sure to (re)start the libeufin-bank after changing
-these configuration options:
-
-.. code-block:: console
-
- # systemctl restart libeufin-bank
-
-
-Web-based Configuration
-+++++++++++++++++++++++
-
-Now you have to set the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user.
-
-.. _regional-conversion-setup:
-
-Configuring the Exchange for Conversion
-+++++++++++++++++++++++++++++++++++++++
-
-This section explains how to enable currency conversion at the exchange,
-which is critical for wallets to know how to wire fiat currency to an
-exchange to obtain regional currency.
-
-You will 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.
-
-.. note::
-
- The above command adds a **second** bank account to the exchange.
- You (or the guided setup script) should have already enabled the
- regional currency bank account (without any "conversion-url").
-
-System ON!
-++++++++++
-
-The last step is to enable libeufin-nexus to :ref:`import incoming bank
-transactions <receive-transaction-data>` (cash in) and to :ref:`trigger
-outgoing bank transactions <sending-payments>` (cash out).
-
-.. code-block:: console
-
- # systemctl enable --now libeufin-nexus-ebics-fetch
- # systemctl enable --now libeufin-nexus-ebics-submit
-
-Using the Regional Currency
-===========================
-
-Wallet Setup
-++++++++++++
-
-This section describes the interaction between the Taler graphical wallet (Android,
-iOS, WebExtensions) and the regional currency system.
-
-You need to add your regional currency exchange to the wallet. This can
-be done by scanning a QR code with a ``taler://withdraw-exchange/exchange.$DOMAIN``
-URL or by manually entering the URL into the respective ``Add exchange``
-dialogue.
-
-
-Cash-In
-+++++++
-
-Next, start the withdraw process in the Taler wallet for the respective
-currency and specify the desired amount. The wallet will then 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.
-
-.. note::
-
- Cash-in operations may be subject to conversion rates, conversion fees and
- minimum amounts to be transferred.
-
-
-Making payments
-+++++++++++++++
-
-For testing, you should be able to *deposit* regional currency directly into
-your regional currency libeufin-bank account directly from the Taler wallet.
-For this, you primarily need to know your bank account details (which should
-be accessible by clicking on your name in the bank Web site after logging in).
-
-.. note::
-
- There may be a short delay between the wallet making the deposit and
- the exchange crediting your bank account. This is because the wallet
- uses a small wire transfer delay by default when initiating a deposit
- into a bank account.
-
-For production, it is more common for a shop to configure a :ref:`Taler
-merchant backend <taler-merchant-backend-operator-manual>` or at least use an
-instance within such a setup. To configure an instance, you primarily need
-again the bank account details to :ref:`setup instance bank accounts
-<instance-bank-account>`.
-
-
-Cash-Out
-++++++++
-
-Regional currency accounts that have a positive balance could be eligible for
-cash-out. Cash-out operations may again be restricted by the regional
-currency operator and will *only* be made to the respective pre-configured
-fiat currency bank account. To cash-out, simply log into your regional
-currency account, select cash-out, specify the desired amount and pass the
-second-factor authorization challenge by entering the TAN you receive at the
-registered e-mail address or mobile phone number.
-
-.. note::
-
- Cash-out operations may be subject to conversion rates, conversion fees and
- minimum amounts to be transferred.
-
-
-Alternative Podman-based Deployment
-===================================
-
-The Podman-based deployment installs, configures, and launches any Taler and
-LibEuFin service required to operate a regional currency.
-
-Please clone ``git://git.taler.net/deployment`` and checkout the ``regio``
-branch. Navigate to the ``sandcastle-ng`` directory and read the README file.
-It should guide you through all the necessary steps to deploy a regional
-currency.
