Contents

11.3. Regional Currency Automated Setup Manual

This manual describes how to setup a regional currency using a script that largely automates the process. If you want to do a custom setup you can follow the custom setup manual.

11.3.1. 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.

../_images/regional-currency-architecture-diagram.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.

11.3.1.1. 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.

11.3.1.2. 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.

11.3.2. Guided Automated Setup

11.3.2.1. Prerequisites

For this manual, we assume that the system is deployed on a contemporary Debian GNU/Linux Bookworm or Ubuntu Mantic 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.

11.3.2.2. 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 propagated over the Internet correctly, and they are currently publicly available.

You can check this from your terminal very easily with the “ping” command, as this:

$ ping -c1 bank.$DOMAIN_NAME
$ ping -c1 exchange.$DOMAIN_NAME
$ ping -c1 backend.$DOMAIN_NAME

You can also use this tool for the same purpose, and to check the propagation status.

Warning

Take into account some hosting providers providing virtualized servers (VPS or VDS) can enable by default the firewall program “UFW”, blocking by default the port number 443. So you have to either disable this firewall program, or open to this 443 port number to allow https.

Now you are ready to go with the next step.

11.3.2.3. Obtaining the Scripts

First, download the deployment scripts via Git:

# apt update && apt install git
$ git clone git://git.taler.net/deployment

11.3.2.4. Running the Guided Configuration

Navigate into the regional-currency/ directory and run main.sh as root:

$ cd deployment/regional-currency/
# ./main.sh

The script will start by installing the required packages and then asking you fundamental questions about the desired setup, in particular:

  1. Wether to encrypt, when stored on disk, sensible configurations such as the admin password.

  2. The name of the regional currency. It must have 3 to 11 letters.

  3. Whether to setup the regional currency to be backed by a fiat currency. You’ll need a bank account at a fiat currency bank offering an online banking protocol supported by LibEuFin Nexus. If you answer y, you will also need to provide the following information:

    1. The ISO code of the fiat currency. Use ‘CHF’ or ‘EUR’.

    2. The IBAN of the fiat bank account.

    3. The BIC of the fiat bank account.

    4. The legal name of the fiat bank account.

  4. The name of the regional currency bank. It will be shown to business users when they interact with the system.

  5. 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_NAME, exchange.$DOMAIN_NAME and backend.$DOMAIN_NAME). 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).

  6. Whether to use TLS or not. You should answer y in most cases.

  7. Whether to setup SMS two-factor authentication using Telesign, multi-factor authentication is strongly recommended, especially when regional currency can be converted to fiat currency. This requires a Customer ID and an API Key. You should answer y in most cases.

  8. The admin password for the bank. Be absolutely sure to enter a very, very long and high-entropy password, preferably using the autogenerated one.

  9. Whether to generate terms of service (ToS) for the exchange from default templates.

  10. Whether to generate a privacy policy for the exchange from default templates.

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!

11.3.2.5. 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. Even though you can do this manually by editing the file manually with your preferred text editor, you can also do this in one single command.

# rm 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 wiping the content of this config/user.conf file, automatically.

11.3.2.6. Multi-factor authentication

The script allows you to configure multi-factor authentication via SMS using Telesign as a provider. You can also configure multi-factor authentication via email or use providers other than Telesign for SMS. You will need to configure these channels manually as described in multi-factor authentication.

If you choose not to back your regional currency with a fiat currency, you can stop here.

11.3.2.7. 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.

11.3.2.8. Connecting to a Fiat Bank: the EBICS setup

To complete the conversion setup, you have to set up an EBICS subscriber using the fiat bank account you specified during the automated setup.

When you sign up for an EBICS-enabled bank account, the bank will provide you with various credentials. Those must be provided in the /etc/libeufin/libeufin-nexus.conf configuration file.

Note

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. If this is not possible, use the IGNORE_TRANSACTIONS_BEFORE configuration to ignore old transactions.

The following snippet shows the mandatory configuration values:

[nexus-ebics]
# Bank
HOST_BASE_URL = https://ebics.postfinance.ch/ebics/ebics.aspx
BANK_DIALECT = postfinance

# EBICS IDs
HOST_ID = PFEBICS
USER_ID = PFC00563
PARTNER_ID = PFC00563

Warning

This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost.

11.3.2.8.1. Reuse existing client keys

If you have client keys from a previous EBICS setup you can copy the JSON file to /var/lib/libeufin-nexus/client-ebics-keys.json.

Make sure this file is accessible to the user running libeufin-nexus, you should run:

$ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/client-ebics-keys.json

11.3.2.8.2. Create new client keys

Run the following command to start the EBICS setup process:

$ sudo -u libeufin-nexus libeufin-nexus ebics-setup

If the previous command failed when running EBICS INI with an error code of EBICS_INVALID_USER_OR_USER_STATE, you need to confirm your keys to your bank to activate your account.

To that end, the previous run should have left a PDF document that you can print, sign and send to the bank. Look for the message that looks like PDF file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'.

Once the bank has received and processed this document you can continue.

11.3.2.8.3. Get bank keys

Run the following command to finish the EBICS setup process:

$ sudo -u libeufin-nexus libeufin-nexus ebics-setup

The EBICS setup is finished once the bank keys have been accepted.

11.3.2.9. Configuring the Exchange for Conversion

In our automated setup the second account is automatically set up correctly without fees or special restrictions. However, various additional restrictions and options could be configured. Details are explained in the regional conversion setup section for the manual setup and in the the manpage of taler-exchange-offline.

11.3.3. System ON!

The last step is to enable libeufin-nexus to import incoming bank transactions (cash in) and to trigger outgoing bank transactions (cash out).

First, check that libeufin-nexus is correctly configured by running the following commands:

# sudo -u libeufin-nexus libeufin-nexus ebics-setup
# sudo -u libeufin-nexus libeufin-nexus ebics-fetch --transient
# sudo -u libeufin-nexus libeufin-nexus ebics-submit --transient

If you have old transactions after the date YYYY-MM-DD that you wish to import into the database, run the following command:

# sudo -u libeufin-nexus libeufin-nexus ebics-fetch --transientt --pinned-start YYYY-MM-DD

None of those commands should fail. If they all work, you can enable the services:

# systemctl enable --now libeufin-nexus.target

Now that we know that libeufin-nexus is working correctly, we still need to check that communication with your bank is working properly. We will test this later, at the end of the manual. The system should only be considered functional after a successful cash in and cash out.

11.3.4. Configuring exchange terms

You can use your own terms of service and privacy policy. You can use the default templates in /usr/share/taler/terms as a guide. Assuming you have custom terms of service and privacy policy rst teamplte files at TOS_PATH and PRIVACY_PATH, the following commands generate the terms files:

# taler-terms-generator -i "$TOS_PATH"
# taler-terms-generator -i "$PRIVACY_PATH"

You now have to specify the terms file names in the exchange config:

# TERMS_ETAG="$(basename "$TOS_PATH" .rst)"
# PRIVACY_ETAG="$(basename "$PRIVACY_PATH" .rst)"


[exchange]
TERMS_ETAG=${TERMS_ETAG}
PRIVACY_ETAG=${PRIVACY_ETAG}

Make sure to restart taler-exchange after changing these configuration options:

# systemctl restart taler-exchange.target

11.3.5. Using the Regional Currency

The very first step you should check after the installation process has been completed successfully, is to make sure all three URLs (bank, backend and exchange), are available (this means to see a Website, and not any NGINX error).

11.3.5.1. Bank backend walkthrough

  • As stated above, please visit before “https://bank.$DOMAIN_NAME”, to make sure it is available.

  • Now login with the username “admin” and the password you have choosen during the installation process, or use the one which might have been generated automatically (and shown on your terminal screen), during the installation process. Once inside the Bank Administrator area, please create the “very first” customer account.

  • Transfer some funds from the “admin” bank account to this new customer account.

  • Now logout from the “admin” account, and login again using the recently “customer” account you have created, and make sure the funds you have transfered from admin, have arrived correctly.

  • Now, please choose the option “Send Money to a Taler Wallet”, and try to send for example 100 units of your regional currency to the wallet installed on your browser or mobile phone.

  • Now try to spend some of these funds from your wallet, and try to buy something somewhere, with the same digital currency you have choosen, during your installation process, let’s say Netzbon.

  • Lastly, you can also try to transfer funds to another “bank account”,for that you will need to know the recipient’s username or the bank account ID.

If you have successfully accomplished all the previous steps, for the bank administrator backend and your installed Wallet, you can move now to test other components such as the Merchant backend (https://backend.$DOMAIN_NAME).

11.3.5.2. 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_NAME/$MASTER_PUBLIC_KEY URL or by manually entering the URL into the respective Add exchange dialogue.

11.3.5.3. 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.

Warning

Cash-in operations can take a long time, hours at the best of times, and even days on weekends or holidays when the bank is closed.

11.3.5.4. 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 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 setup instance bank accounts.

11.3.5.5. 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.

Warning

Cash-out operations can take a long time, hours at the best of times, and even days on weekends or holidays when the bank is closed.

11.3.5.6. Installing Updates

The standard procedure for installing updates is to:

  • First, make a backup (!)

  • Stop Taler services

  • Install new version

  • Upgrade databases

  • Start Taler services

The “upgrade.sh” script in the “regional-currency/” folder of “deployment.git” shows how to do the above steps except for the backup. For the backup, all critical bits of data will be in the Postgresql databases. Thus, we recommend following the database manual on making backups.

previous

11.2. Bank Setup Manual

next

11.4. Regional Currency Custom Setup Manual