commit cd092fed0a6c67edd6e612d3e80067c2b617196e
parent b5c9c6a9649d4c1fb83f4c3c731116d3fc5fcd8f
Author: Antoine A <>
Date: Wed, 28 Feb 2024 17:26:12 +0100
Improve regional currency manual
Diffstat:
2 files changed, 23 insertions(+), 32 deletions(-)
diff --git a/libeufin/regional-automated-manual.rst b/libeufin/regional-automated-manual.rst
@@ -93,9 +93,15 @@ Navigate into the *regional-currency/* directory and run *main.sh* as **root**:
The script will start by installing required packages and then 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'.
+#. Whether to setup your regional currency to be backed by a fiat currency. You will need bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus. If you say `y` you will have to also provide the following information:
+
+ #. The ISO code of the fiat currency. Use 'CHF' or 'EUR'.
+ #. The IBAN of the fiat bank account.
+ #. The BIC of the fiat bank account.
+ #. The legal name of the fiat bank account.
+
#. 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).
+#. 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_NAME``, ``exchange.$DOMAIN_NAME`` and ``backend.$DOMAIN_NAME``). 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 store Taler Exchange keys on this server or externally on another server. 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.
#. Whether to setup SMS two-factor authentication using `Telesign <https://www.telesign.com>`_, multi-factor authentication is strongly recommended, especially when regional currency can be converted to fiat currency. This requires `a Customer ID and an API Key <https://developer.telesign.com/enterprise/docs/authentication#basic-authentication>`_. You should answer ``y`` in most cases.
@@ -122,9 +128,9 @@ If for some reason your installation doesn't work because you have answered erro
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
+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.
+with your preferred text editor, you can also do this in one single command.
.. code-block:: console
@@ -140,6 +146,8 @@ Multi-factor authentication
The script allows you to configure multi-factor authentication via SMS using Telesign as a provider. You can also configure multi-factor authentication via email or use providers other than Telesign for SMS. You will need to configure these channels manually as described in :ref:`multi-factor authentication <libeufin-mfa>`.
+If you choose not to back your regional currency with a fiat currency, you can stop here.
+
Web-based Configuration
+++++++++++++++++++++++
@@ -148,7 +156,7 @@ By default, the regional currency conversion rates are 1:1. You can change the c
Connecting to a Fiat Bank: the EBICS setup
++++++++++++++++++++++++++++++++++++++++++
-To complete the conversion setup, you have to set up an EBICS subscriber using a fiat bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus.
+To complete the conversion setup, you have to set up an EBICS subscriber using the fiat bank account you specified during the automated setup.
When you sign up for an EBICS-enabled bank account, the bank will provide you
with various credentials. Those must be provided in the
@@ -173,11 +181,6 @@ The following snippet shows the mandatory configuration values:
USER_ID = PFC00563
PARTNER_ID = PFC00563
- # Account information
- IBAN = CH7789144474425692816
- BIC = POFICHBEXXX
- NAME = John Smith S.A.
-
.. 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.
@@ -226,30 +229,20 @@ The EBICS setup is finished once the bank keys have been accepted.
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):
+By default, the exchange is setup to perform conversion without any restrictions. You may 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:
.. code-block:: console
$ sudo -u taler-exchange-offline taler-exchange-offline \
enable-account \
- payto://iban/$IBAN?receiver-name=$NAME \
- conversion-url "${PROTO}://bank.$DOMAIN/conversion-info/" \
+ "${CONVERSION_PAYTO}" \
+ conversion-url "${PROTO}://bank.$DOMAIN_NAME/conversion-info/" \
+ # restrictions ...
upload
+.. note::
+ Refer to the manpage ``taler-exchange-offline`` for a full array or possible restrictions.
+
System ON!
++++++++++
diff --git a/libeufin/regional-custom-manual.rst b/libeufin/regional-custom-manual.rst
@@ -44,7 +44,9 @@ You need to setup the :ref:`libeufin-nexus<libeufin-nexus>` using a bank account
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:
+channel for :ref:`multi-factor authentication <libeufin-mfa>` is configured.
+
+The following snippet shows how to enable conversion in ``libeufin-bank`` configuration:
.. code-block:: ini
@@ -52,10 +54,6 @@ channel for :ref:`multi-factor authentication <libeufin-mfa>` is configured:
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:
