path: root/libeufin/regional-manual.rst

.. target audience: operator

Regional Currency Setup Manual
##############################

.. contents:: Table of Contents

GNU Taler can be used to operate a regional currency. For this, LibEuFin Bank
is setup to operate bank accounts in the regional currency that ultimately
interact with the GNU Taler exchange.  Optionally, LibEuFin Nexus can be used to
integrate with the traditional core banking system, and then the LibEuFin
Conversion triggers help convert fiat currency to regional currency and vice
versa.  Conversion rates and limits can be applied when converting between
the regional currency and the fiat currency.


In this manual, we explain how to setup such a regional currency.


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

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


Obtaining the scripts
---------------------

First, download the deployment scripts via Git:

.. code-block:: console

  $ git clone git://git.taler.net/deployment

Guided Configuration
--------------------

Navigate into the *netzbon/* 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 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 generated by a tool
    like "uuidgen".
  * 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 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.

Connecting to a Fiat Bank
=========================

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.

Prerequisites
-------------

You must have 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 highly advised to
use a fresh bank account, with an empty transaction history.

Today, the LibEuFin implementation supports EBICS 2.5 and 3.0 and has been
tested with the GLS Bank (EUR) and the Postfinance (CHF). Please note that
banks tend to have their own dialects of finance messages and thus other
retail banks may or may not work.  Contact us if you need support for another
bank or core banking protocol.

EBICS setup
-----------

Follow the instructions from
:ref:`EBICS subscriber setup <ebics-setup>` to
configure the LibEuFin Nexus for access to your
fiat bank account, but do edit the config file at
``/etc/libeufin/libeufin-nexus.conf``, since the
other components expect it.

.. note::

  For debug setups where the cash-ins are simulated
  :ref:`this way <withdraw-simulation>`, this step can
  be entirely skipped.

Once you have accepted the bank keys, you should
setup currency conversion before actually starting
to import transactions.

Enable regional currency conversion
===================================

Prerequisites
-------------

This step assumes that you already have a working regional currency bank
and have successfully connected to a backing fiat bank account.

Additionally, for each account that is allowed to convert regional currency
into fiat, you must configure the (fiat) bank account number of the fiat
currency with the respective account profile.  Only the bank ``admin`` is
allowed to set fiat bank account numbers.

Furthermore, to achieve a reasonable security level, you must enable two
factor authentication for "cash out" transactions. This requires you to
configure an e-mail address or phone number for every account that supports
"cash out" transactions --- and to setup your system for sending e-mails or
SMS. This manual does not cover setting up e-mail.  For SMS delivery, you will
need to obtain credentials from an SMS provider and provide a script to send
messages via such a provider.

Configuration
-------------

You have to enable conversion and at least one TAN channel for cashout in the
``/etc/libeufin/libeufin-bank.conf`` configuration file:

.. code-block:: console

  [libeufin-bank]
  ALLOW_CONVERSION = yes
  FIAT_CURRENCY = EUR

  TAN_SMS = libeufin-tan-sms.sh
  # And/Or
  TAN_EMAIL = libeufin-tan-email.sh

Afterwards, restart the bank:

.. code-block:: console

  # systemctl restart libeufin-bank


Note: the scripts TAN_SMS/EMAIL must accept the phone number as the ``$1``
parameter and the content in their standard input.  The LibEuFin repository
offers them in ``contrib/``: adjust to your setup!

Web-based Configuration
-----------------------

Now you should be able to setup conversion rates though the Web
interface of the bank as the ``admin`` user.


Conversion ON!
--------------

The last step is to enable the Nexus services to import incoming bank
transactions (cash in) and to trigger outgoing bank transactions (cash out):

.. code-block:: console

  # systemd enable --now libeufin-nexus-ebics-fetch
  # systemd enable --now libeufin-nexus-ebics-submit


Going live!
===========

Exchange setup
--------------

First, you 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.


.. _withdraw-simulation:

Testing the installation
------------------------

In the same ``netzbon/`` folder, run the script ``./withdraw.sh``.  If it completes
successfuly, the command ``taler-wallet-cli`` got 5 units more of regional currency
to spend!

Visit the default Web shop at ``$protocol://backend.$DOMAIN`` and finish your purchases
by feeding the wallet CLI with the taler://-URI to send the payment.  The following
example sends a payment to ``$payUri``

.. code-block:: console

  $ taler-wallet-cli handle-uri $payUri


.. note::

   Delete the database records before going to production, as they alter the way
   nexus-fetch asks records to the bank.

Wallet setup
------------

Next, you need to add your regional currency exchange to the wallet.  This can
be done by scanning a QR code with a ``taler://add-exchange/exchange.$DOMAIN``
URL or by manually entering the URL into the respective ``Add exchange``
dialogue.

With this, you should then be able to ``add`` funds in the regional currency
to your exchange by starting the withdraw process in the wallet. After
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.

For testing, you should be able to *deposit* regional currency directly
into a LibEuFin Bank account from the Taler wallet.  Once the exchange
has credited the regional currency account, log into the bank account
using the Web interface. Assuming the cash out rules are satisfied, you
should then be able to start a cash out operation. This will trigger a
transfer from your regional currency account to the regional currency
master ``bank`` account which will effectively destroy the respective
amount of regional currency. The conversion triggers will inform Nexus
about the destruction, and Nexus will then wire the corresponding amount
in fiat to the associated fiat bank account.