path: root/libeufin/regional-manual.rst

..
  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

  # 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:

.. 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

  # systemd enable --now libeufin-nexus-ebics-fetch
  # systemd 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.