diff options
Diffstat (limited to 'libeufin/regional-manual.rst')
| -rw-r--r-- | libeufin/regional-manual.rst | 482 |
1 files changed, 0 insertions, 482 deletions
diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst deleted file mode 100644 index e497e8c9..00000000 --- a/libeufin/regional-manual.rst +++ /dev/null @@ -1,482 +0,0 @@ -.. 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. |