diff options
| -rw-r--r-- | images/Makefile | 5 | ||||
| -rw-r--r-- | images/regional-arch.dot | 36 | ||||
| -rw-r--r-- | libeufin/bank-manual.rst | 29 | ||||
| -rw-r--r-- | libeufin/nexus-manual.rst | 2 | ||||
| -rw-r--r-- | libeufin/regional-manual.rst | 320 | ||||
| -rw-r--r-- | taler-exchange-manual.rst | 12 |
6 files changed, 186 insertions, 218 deletions
diff --git a/images/Makefile b/images/Makefile index 56f9fbac..3a7fdab9 100644 --- a/images/Makefile +++ b/images/Makefile @@ -1,7 +1,9 @@ -diagrams: arch-api.png coin.png deposit.png reserve.png transaction-common-states.png transaction-withdrawal-states.png transaction-payment-states.png transaction-refund-states.png transaction-refresh-states.png transaction-reward-states.png transaction-deposit-states.png transaction-push-debit-states.png transaction-push-credit-states.png transaction-pull-credit-states.png transaction-pull-debit-states.png challenger.png +diagrams: regional-arch.png arch-api.png coin.png deposit.png reserve.png transaction-common-states.png transaction-withdrawal-states.png transaction-payment-states.png transaction-refund-states.png transaction-refresh-states.png transaction-reward-states.png transaction-deposit-states.png transaction-push-debit-states.png transaction-push-credit-states.png transaction-pull-credit-states.png transaction-pull-debit-states.png challenger.png arch-api.png: arch-api.dot dot -Tpng arch-api.dot > arch-api.png +regional-arch.png: regional-arch.dot + dot -Tpng regional-arch.dot > regional-arch.png challenger.png: challenger.dot dot -Tpng challenger.dot > challenger.png transaction-common-states.png: transaction-common-states.dot @@ -32,4 +34,3 @@ deposit.png: deposit.dot dot -Tpng deposit.dot > deposit.png reserve.png: reserve.dot dot -Tpng reserve.dot > reserve.png - diff --git a/images/regional-arch.dot b/images/regional-arch.dot new file mode 100644 index 00000000..8a61ed5e --- /dev/null +++ b/images/regional-arch.dot @@ -0,0 +1,36 @@ +digraph G { + subgraph cluster_2 { + ubank; + nexus; + rank="same"; ebank; mbank; + label="Fiat currency"; + }; + subgraph cluster_1 { + user; + exchange; + shop; + rbank; + label="Regional currency"; + }; + subgraph cluster_2b { + } + user[label="Customer (Wallet)"]; + shop[label="Merchant (Backend)"]; + exchange[label="Exchange"]; + ubank[label="Customer Fiat Bank"]; + ebank[label="Exchange Fiat Bank"]; + mbank[label="Merchant Fiat Bank"]; + rbank[label="Regional Currency Bank"]; + user->ubank [label="1. Initiate withdraw"]; + ubank->ebank [label="2. Wire transfer"]; + ebank->nexus [label="3. EBICS (CAMT)"]; + nexus->rbank [label="4. Conversion (Cash-in)"]; + rbank->exchange [label="5. Wirewatch"]; + exchange->user [label="6. Withdraw E-Cash"]; + user->shop [label="7. Spend E-Cash"]; + shop->exchange [label="8. Deposit E-Cash"]; + exchange->rbank [label="9. Credit Shop"]; + rbank->nexus [xlabel="10. Conversion (Cash-out)"]; + nexus->ebank [label="11. EBICS (PAIN)"]; + ebank->mbank [label="12. Wire-transfer"]; +} diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst index e9b5425f..f8f2dd28 100644 --- a/libeufin/bank-manual.rst +++ b/libeufin/bank-manual.rst @@ -24,7 +24,7 @@ Bank Setup Manual ################# -LibEuFin Bank implements a simple core banking system with +libeufin-bank implements a simple core banking system with account and REST APIs, including REST APIs for a Web interface and REST APIs to interact with GNU Taler components. @@ -99,6 +99,7 @@ The following snippet shows the mandatory configuration values: Refer to the manpage ``libeufin-man.conf(5)`` for the full array of configuration values. +.. _libeufin-mfa: Configuring multi-factor authentication --------------------------------------- @@ -226,12 +227,30 @@ be wired. After pressing "Send", you may have to pass a 2-FA check. Integration with the Taler Exchange =================================== -Exchange configuration ----------------------- +.. note:: + + This step is fully automated if you use the :ref:`guided automated setup <automated-regional-currency-setup>`. + +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":"$EXCHANGE_PASSWORD","name":"Cashout Exchange","is_taler_exchange":true}' -c "$CONFIG_FILE" + +.. note:: + + You can also set up the exchange account as "admin" using the Web interface of libeufin-bank. + +Having done so, take note of two key pieces of information, namely the ``$EXCHANGE_PASSWORD`` and the "payto://"-URI of the exchange bank account. This information must then be used to configure the exchange as described in +:ref:`exchange bank account configuration <exchange-account-signing>`. When using the libeufin-bank in the context +of a regional currency with conversion, you must +additionally specify a "conversion-url" when setting +up the exchange account. See the section on :ref:`conversion setup <regional-conversion-setup>` in the regional currency setup chapter for details. -TODO. Withdrawing e-cash to a Taler wallet ------------------------------------- +==================================== TODO. diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst index bff74ef8..b8f2458d 100644 --- a/libeufin/nexus-manual.rst +++ b/libeufin/nexus-manual.rst @@ -173,6 +173,7 @@ created (or updated) to the current Nexus version using the following command: where ``$CONFIG_FILE`` is again the path to a configuration that contains at least the above ``[nexus-postgres]`` section. +.. _sending-payments: Sending payments ================ @@ -265,6 +266,7 @@ initiated payment according to their submission state, and return. $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" +.. _receive-transaction-data: Downloading payment records =========================== diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst index bccec641..f145b69c 100644 --- a/libeufin/regional-manual.rst +++ b/libeufin/regional-manual.rst @@ -1,6 +1,6 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2023 Taler Systems SA + 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 @@ -23,23 +23,47 @@ 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. +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 +<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 +<automated-regional-currency-setup>` helpful. .. contents:: Table of Contents :local: -How to create/destroy regional currency -======================================= +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 the fiat, -and *cash-out* to destroy regional currency and obtain fiat currency back. +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 example below assumes that one single unit of regional currency is always backed +The design assumes that one single unit of regional currency is always backed by one single unit of fiat currency. + Cash-in +++++++ @@ -49,8 +73,12 @@ fiat payment of N units, it triggers the creation of N units of regional currenc 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. +to own them. + +.. note:: + + *Valid* fiat payments are those with a Taler-relevant subject that should be generated by a Taler wallet. + Cash-out ++++++++ @@ -60,23 +88,19 @@ a regional payment of N units to the *admin bank account*. This latter triggers 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. +.. _automated-regional-currency-setup: +Guided Automated Setup +====================== -Guided basic setup -================== +You can either manually follow the steps to :ref:`setup libeufin-nexus +<libeufin-nexus>` and :ref:`setup libeufin-bank <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 +++++++++++++ @@ -92,7 +116,7 @@ automatic deployment scripts provided in the ``deployment.git`` Git repository in the ``regional-currency/`` folder. -Obtaining the scripts +Obtaining the Scripts +++++++++++++++++++++ First, download the deployment scripts via Git: @@ -101,8 +125,8 @@ First, download the deployment scripts via Git: $ git clone git://git.taler.net/deployment -Guided Configuration -++++++++++++++++++++ +Running the Guided Configuration +++++++++++++++++++++++++++++++++ This approach sets up a regional currency with cash-in/-out rates of 1:1. @@ -116,8 +140,7 @@ 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 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. @@ -135,7 +158,7 @@ desired setup, in particular: 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)). + 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 @@ -148,46 +171,32 @@ Grab a coffee. .. note:: - At this point, the setup is NOT connected to any fiat bank account! + 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 -========================= -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. +Connecting to a Fiat Bank: the EBICS setup +========================================== -Prerequisites -+++++++++++++ - -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. - -.. note:: - - For debug setups where the cash-ins are simulated :ref:`this way <withdraw-simulation>`, - this step can be entirely skipped. +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 +<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. -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 setup <ebics-setup>`. -Configuration -+++++++++++++ +Enabling Currency Conversion +============================ -Then you have to enable conversion and at least one TAN channel for cashout in the configuration file. +Next, you have to enable conversion and should ensure that at least one TAN +channel for :ref:`multi-factor authentication <libeufin-mfa>` is configured: .. code-block:: ini @@ -199,20 +208,13 @@ Then you have to enable conversion and at least one TAN channel for cashout in t # And/Or TAN_EMAIL = libeufin-tan-email.sh +Make sure to (re)start the libeufin-bank after changing +these configuration options: -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 -.. code-block:: console + # systemctl restart libeufin-bank - libeufin-bank serve -c $config_file Web-based Configuration +++++++++++++++++++++++ @@ -220,30 +222,22 @@ 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. - +.. _regional-conversion-setup: +Configuring the Exchange for Conversion ++++++++++++++++++++++++++++++++++++++++ -Exchange-wallet integration -=========================== +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. -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. +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 @@ -262,7 +256,26 @@ 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 +.. 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 <receive-transaction-data>` (cash in) and to :ref:`trigger +outgoing bank transactions <sending-payments>` (cash out). + +.. code-block:: console + + # systemd enable --now libeufin-nexus-ebics-fetch + # systemd enable --now libeufin-nexus-ebics-submit + +Wallet Setup ============ This section describes the interaction between the Taler graphical wallet (Android, @@ -286,119 +299,14 @@ exchange to perform such deposit. So once the exchange has credited the regiona 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 -================= +Alternative Podman-based Deployment +=================================== The Podman-based deployment installs, configures, and launches any Taler and -LibEuFin service with the aim of serving a regional currency. +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 steps to running the regional currency. +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. diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 742b0c8e..ec209f76 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -1811,6 +1811,8 @@ periodically, as it signs the various online signing keys of the exchange which periodically expire. +.. _exchange-account-signing: + Account signing --------------- @@ -2013,7 +2015,7 @@ AML Forms --------- AML forms are defined by the DD 54 dynamic forms. -The shipped implementation with of the exchange is installed in +The shipped implementation with of the exchange is installed in .. code-block:: shell-session @@ -2026,11 +2028,11 @@ every entry in the list the next properties are expected to be present: ``label``: used in the UI as the name of the form ``id``: identification name, this will be saved in the exchange database -along with the values to correctly render the form again. +along with the values to correctly render the form again. It should simple, short and without any character outside numbers, letters and underscore. -``version``: when editing a form, instead of just replacing fields +``version``: when editing a form, instead of just replacing fields it will be better to create a new form with the same id and new version. That way old forms in the database will used old definition of the form. It should be a number. @@ -2040,12 +2042,12 @@ See DD 54 dynamic forms. .. attention:: - do not remove a form the list if it has been used. Otherwise you + do not remove a form the list if it has been used. Otherwise you won't be able to see the information save in the exchange database. To add a new one you can simply copy and paste one element, and edit it. -It is much easier to download ``@gnu-taler/aml-backoffice-ui`` source +It is much easier to download ``@gnu-taler/aml-backoffice-ui`` source from ``https://git.taler.net/wallet-core.git/``, compile and copy the file from the ``dist/prod``. |