.. 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 @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 ` 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 ` 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 ` and :ref:`setup 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 ` 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 ` 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 ` (cash in) and to :ref:`trigger outgoing bank transactions ` (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.