036-currency-conversion-service.rst (4296B)
1 DD 36: Currency conversion service 2 ################################## 3 4 Summary 5 ======= 6 7 This document explains the design of the currency conversion 8 service. Such service enables customers to spend their fiat 9 currency to buy Taler coins in a regional currency, and enables 10 merchants to cash-out from the regional currency to fiat. 11 12 Motivation 13 ========== 14 15 The conversion service (CCS) is fundamental for a regional 16 currency and is missing in the Taler/Libeufin ecosystem. 17 18 Definitions 19 =========== 20 21 *Fiat-issuer* is the fiat bank account that belongs to the regional currency 22 issuer; typically, such bank account belongs to one association that runs the 23 infrastructure. This bank account is hosted at the "fiat bank". *Regio-issuer* 24 is the bank account that belongs to the local 25 currency issuer but hosted at the bank that generates the regional currency. 26 Such bank is also called "circuit bank". *Regio-exchange* is the bank account 27 that belongs to the Taler exchange and that is hosted at the circuit bank. 28 *Fiat-target* is a bank account hosted in the same currency of fiat-issuer 29 and that belongs to a customer who initiated a cash-out operation. *Regio-user* 30 is a bank account hosted at the circuit bank that is different from regio-issuer. 31 *Fiat-customer* is a bank account hosted in the same currency of fiat-issuer, 32 typically owned by customers that want to withdraw Taler coins in the regional 33 currency. 34 35 Requirements 36 ============ 37 38 * CCS must not impact the libeufin-nexus structure. 39 * CCS must trigger Taler withdrawls every time a customer buys the 40 regional currency ('cash-in' operation). 41 * CCS must offer cash-out operations. 42 * CCS should react as soon as possible to cash-in and cash-out operations. 43 * CCS must show its state to administrators and offer management tools. 44 * CCS must link every fiat-side of a cash-out to its regional currency 45 counterpart. In particular, because every cash-out starts with a 46 payment *P* from regio-user to regio-issuer and ends with another 47 payment *Q* from fiat-issuer to fiat-target, CCS must link P and Q. 48 49 Proposed Solution 50 ================= 51 52 The following design assumes that CCS is coded in libeufin-bank and that 53 libeufin-bank and libeufin-nexus share the same database with separate 54 schemas. The solution relies on SQL triggers to atomically synchronise 55 cash-in and cash-out operations between the two schemas. 56 57 SQL triggers and conversion operations 58 -------------------------------------- 59 60 Libeufin-bank controls the conversion support and sets up or removes 61 conversion SQL triggers when necessary. In order for the SQL triggers to 62 perform the conversion operations, the configurable rates/fees are stored 63 in the database and the conversion operations are performed using stored 64 SQL procedures. The SQL triggers and conversion procedures are stored in 65 the libeufin-bank schema. 66 67 Cash-out operation 68 ------------------ 69 70 Libeufin-bank learns instantly about a cash-out operation, because it's 71 *the* service offering such feature. Therefore, as soon as a cash-out 72 operation gets TAN-confirmed, libeufin-bank performs a wire transfer from 73 regio-user to regio-issuer by specifying the amount without any rates/fees 74 applied. Along the same database transaction, a SQL trigger store the 75 *instructions* of another payment *P* from fiat-issuer to fiat-target, 76 but this time **with** the cash-out rates/fees. 77 78 Asynchronously, a libeufin-nexus background task picks P and sends it to 79 the fiat bank. Finally, fiat bank conducts P and fiat-target receives the 80 wanted amount. The same libeufin-nexus background task should also retry 81 previous payments like P that failed to be submitted to fiat bank. 82 83 Cash-in operation 84 ----------------- 85 86 A cashin-in operation starts as soon as the customer sends a fiat 87 payment from fiat-customer to fiat-issuer. 88 89 The libeufin-nexus component is responsible to query the fiat bank 90 via EBICS every X seconds. X should match the tightest interval allowed 91 by the bank. 92 93 When libeufin-nexus registers an incoming payment on fiat-issuer in the 94 database, a SQL trigger applies the **current** cash-in rates/fees and 95 performs a wire transfer from regio-issuer to regio-exchange. Libeufin-bank 96 makes the exchange aware via the Taler Wire Gateway API and from now on, 97 the system proceeds like it always did in Taler.