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


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.