path: root/libeufin/regional-manual.rst

.. target audience: operator

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

In this manual, we explain how we model a regional currency and
how to set up one using GNU Taler and LibEuFin technology.

.. contents:: Table of Contents


How to create/destroy regional currency
=======================================

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 the fiat,
and *cash-out* to destroy regional currency and obtain fiat currency back.

The example below 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.

How are GNU Taler & LibEuFin used to create the regional currency?
==================================================================

Following are the main components 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.


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


Obtaining the scripts
+++++++++++++++++++++

First, download the deployment scripts via Git:

.. code-block:: console

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

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.
    Currently only 'NETZBON' is supported.
  * The ISO code of the fiat currency. Currently only 'CHF' is supported.
  * 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!

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

.. include:: ../frags/ebics-setup.rst

.. note::

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


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.
Follow the instructions from :ref:`EBICS subscriber setup <ebics-setup>`.

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

Then you have to enable conversion and at least one TAN channel for cashout in the configuration file.

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


You must have an exchange account with username ``exchange`` for conversion to work.
Assuming that the configuration file exists at ``$config_file``, the following
command would create one:

.. code-block:: console

  libeufin-bank create-account '{"username":"exchange","password":"password","name":"Cashout Exchange","is_taler_exchange":true}' -c $config_file

Then the following command would start the server with conversion API enabled :

.. code-block:: console

  libeufin-bank serve -c $config_file

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.

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

The last step is to run Nexus to import incoming bank
transactions (cash in) and to trigger outgoing bank transactions (cash out).
Refers to ``nexus-manual.conf`` for more details.



Configuring the merchant
========================

In order to setup a shop, you need a merchant backend to run.  The guided setup
installs and sets one backend up, but the user is required to complete the shop
configuration via the Web browser.

One fundamental piece of information are the banking details, to allow merchant
receive payments from the exchange.  If you don't have a bank account at the regional
bank, contact the administrator and get one.  After being able to login to the new
bank account, you can see your IBAN by clicking on the ``Welcome, $USERNAME`` message
in the profile page.  The IBAN is shown under the ``Internal IBAN`` box.

Next, point your browser to ``$proto://backend.$domain_name/``.  You should
be welcomed by the following merchant backoffice page:

.. image:: merchant_first_login.png

Such page offers to create a merchant profile: fill any required field (including
your access token) and click to ``confirm``.  It should now be possible to associate
the banking details to the profile just created: click to ``Bank account`` at the
left of the page.  The following page should be shown:

.. image:: no_default_account_yet.png

Click on the blue "+" sign on the top right of the page, and expect the following
page to appear:

.. image:: enter_instance_details.png

This tutorial is focused on IBAN, so choose ``iban`` as the account type, and
expect the following page to appear:

.. image:: instance_iban_config.png

After providing the details and confirming, the shop is ready to generate orders
and accept payments.

Make an order
+++++++++++++

Click on ``Orders`` at the top left corner of the merchant backoffice page; the
following page should appear

.. image:: create_orders.png

After having filled the required fields, the interface should show the following
page with the related links to check the status of the order and let wallets pay
for it.  Take note of the link beside ``Payment URI`` (we'll call it ``$payUri``).

.. image:: payment_links.png

In order to test the setup, it should be now possible to use the command line wallet
to withdraw Taler coins and spend them to buy the order we just created.

.. _withdraw-simulation:

Pay for the order
+++++++++++++++++

This section explains how to pay for the order in a scenario where the fiat bank
is simulated.  The simulation takes place by crafting ad-hoc XML files as if the
bank would have issued them.  Such XML files carry information about incoming payments
to the regional currency master bank account.  Finally, the XML files are passed
to LibEuFin nexus via a convenient CLI method.  The responsible script for such
simulation is ``withdraw.sh``.

Run ``./withdraw.sh`` without any arguments.  Assuming that you ran the command
as the ``test-user``, after the execution, 5 units of the regional currency should
be found in the CLI wallet owned by ``test-user``.


Check it with:

.. code-block:: console

  $ taler-wallet-cli balance

If so, call the wallet in the following way to finally pay for the order just created:

.. code-block:: console

  $ taler-wallet-cli handle-uri $payUri

.. note::

   Reset the state before going to production, as it impacts the way nexus
   asks records to the bank.  In particular, delete: any database and the
   files ``config/user.conf`` and ``config/internal.conf``, and finally run
   ``./main.sh`` again.


Exchange-wallet integration
===========================

Although not strictly needed to start withdrawing regional money, this
section explain how to enable the tight integration between Taler exchange
and wallet, to let wallets learn about the possibility of withdrawing
regional funds via a particular exchange.

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.

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.

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.

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.

..
  FIXME: uncomment once tested.

  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


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

  .. note::

    the TAN_SMS script relies on a Telesign account.  For this reason,
    it needs a telesign-secret file found in the PATH, that defines the
    environment variables API_KEY and CUSTOMER_ID

  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.


  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 inform wallets about
  the possibility of currency conversion (cash in) when wallets download
  ``/keys`` with bank account data from the exchange:

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

Podman deployment
=================

The Podman-based deployment installs, configures, and launches any Taler and
LibEuFin service with the aim of serving 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 steps to running the regional currency.