regional currency description

1 files changed, 51 insertions, 21 deletions

diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst
index 125b1e63..e37c6c1a 100644
--- a/libeufin/regional-manual.rst
+++ b/libeufin/regional-manual.rst
@@ -3,18 +3,55 @@
 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
 
-GNU Taler can be used to operate a regional currency. For this, LibEuFin Bank
-is setup to operate bank accounts in the regional currency that ultimately
-interact with the GNU Taler exchange.  Optionally, LibEuFin Nexus can be used to
-integrate with the traditional core banking system, and then the LibEuFin
-Conversion triggers help convert fiat currency to regional currency and vice
-versa.  Conversion rates and limits can be applied when converting between
-the regional currency and the fiat currency.
 
+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.
 
-In this manual, we explain how to setup such a regional currency.
+- LibEuFin Nexus: is responsible to drive the master (fiat) bank account both to learn
+  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
@@ -94,13 +131,11 @@ Grab a coffee.
 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.
+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
 -------------
@@ -346,9 +381,4 @@ If so, call the wallet in the following way to finally pay for the order just cr
   into a LibEuFin Bank account from the Taler wallet.  Once the exchange
   has credited the regional currency account, log into the bank account
   using the Web interface. Assuming the cash out rules are satisfied, you
-  should then be able to start a cash out operation. This will trigger a
-  transfer from your regional currency account to the regional currency
-  master ``bank`` account which will effectively destroy the respective
-  amount of regional currency. The conversion triggers will inform Nexus
-  about the destruction, and Nexus will then wire the corresponding amount
-  in fiat to the associated fiat bank account.
+  should then be able to start a cash out operation.