.. 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 ############################## 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`. If you want to setup a regional currency backed by a fiat currency, you can use the :ref:`guided automated setup`, which largely automates the process. You can also follow the :ref:`manual 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` 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 propogated over the Internet correctly, and they are currently publicly available. You can check this from your terminal very easyly 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 `_ 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. Eventhough 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 to wipe the content of this user.conf file, automatically. Multi-factor authentification +++++++++++++++++++++++++++++ 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 `. 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 ` 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 ` (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 .. _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` 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` 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 ` 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 ` (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 +++++++ 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 ` 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 `. 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.