[taler-docs] branch master updated: DD 36

[gnunet]

This is an automated email from the git hooks/post-receive script.

ms pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 8d3a405  DD 36
8d3a405 is described below

commit 8d3a4057e17f8d9ef37b2eaac8ee9ffee0044b3b
Author: MS <ms@taler.net>
AuthorDate: Mon Feb 13 14:30:06 2023 +0100

    DD 36
---
 .../036-currency-conversion-service.rst            | 94 ++++++++++++++++++++++
 1 file changed, 94 insertions(+)

diff --git a/design-documents/036-currency-conversion-service.rst 
b/design-documents/036-currency-conversion-service.rst
new file mode 100644
index 0000000..d2cc683
--- /dev/null
+++ b/design-documents/036-currency-conversion-service.rst
@@ -0,0 +1,94 @@
+DD 36: Currency conversion service.
+###################################
+
+Summary
+=======
+
+This document explains the design of the currency conversion
+service.  Such service enables customers to spend their fiat
+currency to buy Taler coins in a regional currency, and enables
+merchants to cash-out from the regional currency to fiat.
+
+Motivation
+==========
+
+The conversion service (CS) is fundamental for a regional
+currency and is missing in the Taler/Libeufin ecosystem.
+
+Definitions
+===========
+
+*Fiat-issuer* is the fiat bank account that belongs to the regional currency
+issuer; typically, such bank account belongs to one association that runs the
+infrastructure.  This bank account is hosted at the "fiat bank".  
*Regio-issuer*
+is the bank account that belongs to the local
+currency issuer but hosted at the bank that generates the regional currency.
+Such bank is also called "circuit bank".  *Regio-exchange* is the bank account
+that belongs to the Taler exchange and that is hosted at the circuit bank.
+*Fiat-target* is a bank account hosted in the same currency of fiat-issuer
+and that belongs to a customer who initiated a cash-out operation.  
*Regio-user*
+is a bank account hosted at the circuit bank that is different from 
regio-issuer.
+*Fiat-customer* is a bank account hosted in the same currency of fiat-issuer,
+typically owned by customers that want to withdraw Taler coins in the regional
+currency.
+
+Requirements
+============
+
+* CS must not impact the Nexus structure.
+* CS must create Taler withdraws every time a customer buys the
+  regional currency ('buy-in' operation).
+* CS must offer cash-out operations.
+* CS should react as soon as possible to buy-in and cash-out operations.
+* CS must show its state to administrators.
+* CS must link every fiat-side of a cash-out to its regional currency
+  counterpart.  In particular, because every cash-out starts with a
+  payment *P* from regio-user to regio-issuer and ends with another
+  payment *Q* from fiat-issuer to fiat-target, CS must link P and Q. 
+
+Proposed Solution
+=================
+
+The following design assumes that CS is coded into libeufin Sandbox.
+
+Cash-out operation
+------------------
+
+The libeufin Sandbox component learns instantly about a cash-out
+operation, because it's *the* service offering such feature.
+Therefore, as soon as a cash-out operation gets TAN-confirmed,
+Sandbox performs a first wire transfer from regio-user to regio-issuer
+by specifying the amount without any rates/fees applied.  Along
+the same database transaction, Sandbox stores the *instructions*
+of another payment *P* from fiat-issuer to fiat-target, but this time
+**with** the cash-out rates/fees.
+
+Asynchronously, a background picks P and sends it to the fiat bank.
+Finally, fiat bank conducts P and fiat-target receives the wanted
+amount.  The same background task should also retry previous payments
+like P that failed to be submitted to fiat bank.
+
+Buy-in operation
+----------------
+
+A buy-in operation starts as soon as the customer sends a fiat
+payment from fiat-customer to fiat-issuer.  Sandbox is responsible to
+detect such an incoming payment in a timely fashion.
+Because traditional banking protocols (like EBICS) don't allow to long
+poll on bank accounts, Sandbox uses background tasks to check fiat-issuer
+every X minutes.  Those background tasks rely on Nexus ability to speak
+EBICS.
+
+When Sandbox detects one incoming payment on fiat-issuer, it applies the
+buy-in rates/fees and wires the resuling amount from regio-issuer to
+regio-exchange.  At this point, Nexus detects the incoming payment on
+regio-exchange and makes the exchange aware via the Taler Wire Gateway API.
+From now on, the system proceeds like it always did in Taler.
+
+Background tasks
+================
+
+The background tasks are responsible for the communication between Sandbox
+and fiat bank, in order to drive fiat-issuer.  Their implementation requires
+to extract the current Nexus background tasks and EBICS logic into own
+libraries.

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.