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

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.

.. contents:: Table of Contents
  :local:


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

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!

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 ``regional-currency/`` folder.


Obtaining the Scripts
+++++++++++++++++++++

First, download the deployment scripts via Git:

.. code-block:: console

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

.. note::

  At this point, the setup is NOT connected to any fiat bank account! The next
  steps must always be done manually!


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.

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.


Enabling Currency Conversion
============================

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 should be able to setup conversion rates and ``admin`` debt limit though the Web
interface of the bank 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
-------

After starting the withdraw process and 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.

.. FIXME: bad english below

For testing, you should be able to *deposit* regional currency directly
into your LibEuFin Bank account from the Taler wallet.  Note: the wallet relies on the
exchange to perform such deposit.  So once the exchange has credited the regional
currency account to your account and assuming the cash out rules are satisfied, you
should then be able to start a cash out operation.


Cash-Out
--------

.. FIXME: #8174


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.