diff options
author | MS <ms@taler.net> | 2023-02-13 14:30:06 +0100 |
---|---|---|
committer | MS <ms@taler.net> | 2023-02-13 14:30:46 +0100 |
commit | 8d3a4057e17f8d9ef37b2eaac8ee9ffee0044b3b (patch) | |
tree | 335baa93f257c9e08fc625e17778754d6035105b /design-documents | |
parent | 600fc4f645286d30cc8446bec1aac466a27a8ec3 (diff) | |
download | docs-8d3a4057e17f8d9ef37b2eaac8ee9ffee0044b3b.tar.gz docs-8d3a4057e17f8d9ef37b2eaac8ee9ffee0044b3b.tar.bz2 docs-8d3a4057e17f8d9ef37b2eaac8ee9ffee0044b3b.zip |
DD 36
Diffstat (limited to 'design-documents')
-rw-r--r-- | design-documents/036-currency-conversion-service.rst | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/design-documents/036-currency-conversion-service.rst b/design-documents/036-currency-conversion-service.rst new file mode 100644 index 00000000..d2cc6833 --- /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. |