regional-custom-manual.rst (6678B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2014-2024 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Florian Dold 17 @author Marcello Stanisci 18 @author Christian Grothoff 19 20 21 .. target audience: operator 22 23 Regional Currency Custom Setup Manual 24 ##################################### 25 26 This manual describes how to setup a regional currency manually. If you want a guided setup you can follow the :doc:`automated setup manual<regional-automated-manual>`. 27 28 .. include:: ../frags/regional-manual-architecture.rst 29 30 Custom Manual Setup 31 =================== 32 33 You first need to setup the :ref:`libeufin-bank<libeufin-bank>` and integrate it with a Taler exchange. 34 35 If you don't want your regional currency to be backed by a fiat currency, you can stop here. 36 37 Enabling Currency Conversion 38 ++++++++++++++++++++++++++++ 39 40 You need to setup the :ref:`libeufin-nexus<libeufin-nexus>` using a bank account at a bank dealing in fiat currency that 41 offers an online banking protocol supported by LibEuFin Nexus. 42 43 Next, you have to enable conversion and should ensure that at least one TAN 44 channel for :ref:`multi-factor authentication <libeufin-mfa>` is configured. 45 46 The following snippet shows how to enable conversion in ``libeufin-bank`` configuration: 47 48 .. code-block:: ini 49 50 [libeufin-bank] 51 ALLOW_CONVERSION = YES 52 FIAT_CURRENCY = EUR 53 54 Make sure to (re)start the libeufin-bank after changing 55 these configuration options: 56 57 .. code-block:: console 58 59 # systemctl restart libeufin-bank 60 61 62 Web-based Configuration 63 +++++++++++++++++++++++ 64 65 Now you have to set the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user. 66 67 .. _regional-conversion-setup: 68 69 Configuring the Exchange for Conversion 70 +++++++++++++++++++++++++++++++++++++++ 71 72 An exchange that supports currency conversion needs to advertise two bank 73 accounts, one in the regional currency and a second in the fiat currency. The 74 conversion logic ensures that wire transfers in either account are 75 immediately reflected in the other account. 76 77 This section explains how to enable currency conversion at the exchange, 78 which is critical for wallets to know how to wire fiat currency to an 79 exchange to obtain regional currency. 80 81 You will need to use the ``taler-exchange-offline`` tool to inform the 82 exchange about the **fiat** bank account that can be used for cash in 83 operations and also specify the URL for currency conversion. Additionally, 84 you may also configure restrictions on the bank accounts that may originate 85 the funds, for example, to prevent international wire transfers that may expose 86 you to additional compliance risks. 87 88 Given the ``$IBAN`` of the fiat currency bank account and ``$NAME`` as 89 the (URL-encoded) name of the exchange-account owner, the following 90 ``taler-exchange-offline`` invocation can be used to notify wallets about 91 the possibility of currency conversion (cash in): 92 93 .. code-block:: console 94 95 # source config/user.conf 96 # sudo -u taler-exchange-offline \ 97 taler-exchange-offline \ 98 wire-fee now iban "${CURRENCY}":0 "${CURRENCY}":0 \ 99 enable-account \ 100 "${CONVERSION_PAYTO}" \ 101 conversion-url "${PROTO}://bank.$DOMAIN_NAME/conversion-info/" \ 102 display-hint 10 "CHF" \ 103 debit-restriction deny \ 104 credit-restriction \ 105 regex \ 106 'payto://iban/.*/CH.*?receiver-name=.*' \ 107 'Swiss only' \ 108 '{"de":"nur Schweiz","fr":"Suisse uniquement"}' \ 109 upload 110 111 Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion 112 endpoint of the bank, which should be 113 ``https://bank.$DOMAIN/conversion-info/`` in our setup. 114 115 The above commands set up the exchange to perform conversion with a 116 restriction to only accept credit transfers from Swiss bank accounts. You may 117 want to configure such restrictions on the bank accounts that may originate 118 funds to prevent international wire transfers that may expose you to 119 additional compliance risks. 120 121 You can leave out the "credit-restriction" if you want to allow international 122 inbound wire transfers. 123 124 The "debit-restriction" is largely mandatory as in this setup the 125 ``taler-exchange-transfer`` is only configured to deal with the regional 126 currency bank. Crediting fiat bank accounts must thus be done via the 127 cash-out functionality of the regional currency bank account. 128 129 The "display-hint" gives priority (10) for the fiat cash-in account over the 130 regional currency account in the withdraw dialog of the wallets and labels the 131 account with "CHF". 132 133 .. note:: 134 135 The above command adds a **second** bank account to the exchange. 136 You (or the guided setup script) should have already enabled the 137 regional currency bank account (without any "conversion-url"). 138 139 .. include:: ../frags/regional-system-on.rst 140 .. include:: ../frags/deploying-tos.rst 141 142 143 Maintenance 144 +++++++++++ 145 146 The ``taler-exchange-offline`` commands given above set fees only for the 147 current year (``now``). Thus, before January 1st of each year, you must to set 148 up new fees for the new calendar year. In a regional currency setup, this 149 typically requires up to three annual settings: 150 151 .. code-block:: console 152 153 # YEAR=2025 # edit if necessary 154 # FIAT_CURRENCY=CHF # edit if necessary 155 # REGIO_CURRENCY=NETZBON # edit if necessary 156 # sudo -u taler-exchange-offline \ 157 taler-exchange-offline \ 158 wire-fee "$YEAR" \ 159 iban "${FIAT_CURRENCY}":0 "${FIAT_CURRENCY}":0 \ 160 wire-fee "$YEAR" \ 161 x-taler-bank "${REGIO_CURRENCY}":0 "${REGIO_CURRENCY}":0 \ 162 global-fee $YEAR \ 163 "${REGIO_CURRENCY}:0" \ 164 "${REGIO_CURRENCY}:0" \ 165 "${REGIO_CURRENCY}:0" \ 166 4w 6y 4 \ 167 upload 168 169 If the fees are not all zero, simply change the respective place to specify 170 a non-zero fee. 171 172 .. note:: 173 174 Additionally, the denomination signing keys will only have been 175 pre-generated for some time, depending on your ``LOOKAHEAD_SIGN`` 176 configuration option. Thus, you may need to periodically run 177 the "taler-exchange-offline download sign upload" sequence as well!