commit 289bbd7a3be772e64ccc1fcc141f255c543c9e9e
parent e69d507a90b51984a92550b38140a8258b92936d
Author: Antoine A <>
Date: Wed, 14 Feb 2024 22:17:52 +0100
Improve regional currency manual
Diffstat:
2 files changed, 52 insertions(+), 52 deletions(-)
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
@@ -95,6 +95,9 @@ 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:
diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst
@@ -23,21 +23,16 @@
Regional Currency Setup Manual
##############################
-In this manual, we explain how to set up a regional currency with or without
-currency conversion from and to fiat currency. Most of this manual is about
-setting up the currency conversion logic with a fiat bank that offers an EBICS
-interface.
-
-If you want to run a regional currency without any conversion from or to a
-fiat currency, all you need to do is set up the :ref:`libeufin-bank
-<libeufin-bank>` and integrate it with a Taler exchange. As a result, several
-sections in this manual related to currency conversion can be
-skipped. However, you may still find the :ref:`guided setup
-<automated-regional-currency-setup>` helpful.
+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
============
@@ -89,18 +84,12 @@ a fiat payment of N units to the fiat bank account owned by the user who initiat
cash-out.
-
.. _automated-regional-currency-setup:
Guided Automated Setup
======================
-You can either manually follow the steps to :ref:`setup libeufin-nexus
-<libeufin-nexus>` and :ref:`setup libeufin-bank <libeufin-bank>` or use the
-script described in this section which largely automates the process. If you
-choose to use the manual setup, you should skip the final step that actually
-starts the Nexus commands to initate payments and download transaction data
-until most of the setup steps below have been completed!
+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
+++++++++++++
@@ -111,11 +100,6 @@ 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 ``regional-currency/`` folder.
-
-
Obtaining the Scripts
+++++++++++++++++++++
@@ -123,13 +107,12 @@ 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
++++++++++++++++++++++++++++++++
-This approach sets up a regional currency with cash-in/-out rates of 1:1.
-
Navigate into the *regional-currency/* directory and run *main.sh* as **root**:
.. code-block:: console
@@ -144,6 +127,13 @@ desired setup, in particular:
* 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, 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).
* 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``.
@@ -153,13 +143,6 @@ desired setup, in particular:
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 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 as well as the generated bank admin password will
be stored in a file called ``config/user.conf``. Should you run the script in
@@ -175,26 +158,44 @@ Grab a coffee.
At this point, the setup is NOT connected to any fiat bank account! The next
steps must always be done manually!
+Web-based Configuration
++++++++++++++++++++++++
+
+This script sets up a regional currency with conversion rates of 1:1. You can change conversion rates and ``admin`` debt limit through the Web interface of the bank as the ``admin`` user.
Connecting to a Fiat Bank: the EBICS setup
-==========================================
+++++++++++++++++++++++++++++++++++++++++++
-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.
+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.
-First, you must 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. 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.
+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
+
+ # systemd enable --now libeufin-nexus-ebics-fetch
+ # systemd 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:
@@ -220,9 +221,7 @@ these configuration options:
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.
-
+Now you have to setup conversion rates and ``admin`` debt limit through the Web interface of the bank as the ``admin`` user.
.. _regional-conversion-setup:
@@ -237,7 +236,7 @@ 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
+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
@@ -263,9 +262,8 @@ in our setup.
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
@@ -276,7 +274,6 @@ outgoing bank transactions <sending-payments>` (cash out).
# systemd enable --now libeufin-nexus-ebics-fetch
# systemd enable --now libeufin-nexus-ebics-submit
-
Using the Regional Currency
===========================
