106-currency-conversion.rst (19196B)
1 DD 106: Currency Conversion 2 ########################### 3 4 :Design status: Draft 5 :Implementation status: Not started 6 :DD shepherd: Amoui N'GORAN 7 :Historical contributors: Amoui N'GORAN 8 :First published: 2026-10-11 9 :Last substantive change: 2026-11-20 10 11 12 Summary 13 ======= 14 15 Taler is an auditable and privacy-friendly electronic payment system. It can 16 support many currencies, but each exchange serves a single currency and is 17 funded through a wire gateway. The main implementation today relies on 18 LibEuFin and EBICS, which limits funding to bank accounts in the SEPA area 19 (EUR) or Switzerland (CHF). We want to support currency-conversion where a 20 wallet holding a **source currency** (like digital EUR) can convert them to a 21 **target currency** (like digital CHF). At the time of conversion the user 22 may need to be identified, but then afterwards they would again own digital 23 cash unlinked to their identity. Since the user is withdrawing fresh digital 24 cash from an exchange, the source currency is used to fund a reserve at the 25 exchange offering the target currency. 26 27 Interledger is an open protocol suite for sending packets representing 28 financial values across different payment networks, an internet for financial 29 payments. Rhyza (https://docs.rhyza.dev/), which is the successor of Rafiki, 30 is an open-source software of Interledger that allows financial institutions 31 to easily access to Interledger and Open-Payment API. 32 33 This document specifies how we can implement Rhyza-based gateway next to 34 Libeufin to enable currency conversion. (Being able to convert currencies is 35 the hard part: once it is possible, paying across currencies follows 36 trivially.) This will mainly affect the reserve funding in the Taler flow so 37 the exchange, its bank account, the reserve and Libeufin. 38 39 40 Motivation 41 ========== 42 43 1. Taler's mono-currency constraint: 44 Each Taler exchange is intrinsically linked to a specific currency. 45 For example, if a customer holds currency in a country A (e.g. XOF in West Africa or USD) 46 and wants to buy a good from a merchant who only accepts EUR from a Taler exchange in Europe, 47 he has to manually make an expensive and slow international transfer to the European exchange's reserve. 48 Moreover, the European exchange may even reject funding a reserve via such a channel. 49 50 2. Delay of reserve funding: 51 Taler's reserve wire-in mechanism normally requires waiting for the validation of bank 52 transfer to credit the customer's reserve (often several hours or even days depending on the bank). 53 54 3. Legal requirements: 55 Withdrawing funds as a non-domestic customer may come with different AML/KYC requirements. 56 57 4. Conversion rate: 58 Customers will want to know up-front what the currency conversion rate will be, 59 just like the involved payment service providers will need to manage risks arising from rate fluctuations. 60 61 5. Spread and fees: 62 If we can do conversion internally, especically aggregating many transfers going back and forth 63 and only settling periodically the aggregate debts to avoid international wire transfers for every 64 microtransaction, we can significantly reduce costs. Furthermore, exchange operators can 65 still financially benefit from the spread. 66 67 68 Requirements 69 ============ 70 71 * Create a payment (wire gateway) adapter that can listen for incoming payments events (via Rhyza's webhooks). 72 Before accepting any incoming payment, we need to communicate our legitimization requirements 73 (see https://docs.taler.net/taler-kyc-manual.html#kycoperatormanual) to 74 the originating wallet and possibly check the legitimization data against sanction lists. Basically, 75 the customer may need to perform some arbitrary onboarding (KYC/KYB) and only then they are allowed 76 to wire the funds. 77 78 * Enable outgoing payments (in a wire gateway adapter), which must trigger the incoming payment at 79 the target exchange with the required meta-data (which reserve to fund). The outgoing payments 80 should be aggregated by ILP and then settled with international wire transfers based on the 81 underlying contractual obligations (when the conversion rate shifts too much or the liability 82 of one exchange to another exceeds a certain threshold). 83 84 * Communicate to the exchange and the wallets the current conversion rate and how long it 85 is valid, so that wallets can compute how much target currency they will receive for a 86 given amount of source currency and vice-versa. 87 88 * Auditability: The Taler auditor should be able to verify that the amount credited to a reserve 89 corresponds to an amount actually received, using the records of the exchange’s Rhyza instance 90 (incoming payments) and the ledger of the exchange’s bank. (https://docs.taler.net/taler-auditor-manual.html) 91 92 93 Proposed Solution (Initial Approach) 94 ==================================== 95 96 * https://docs.taler.net/core/api-bank-wire.html 97 - modifications / extensions required? 98 - how to map to Rhyza? 99 100 * https://docs.taler.net/manpages/taler-exchange-offline.1.html#enable-account 101 - conversion-url: how to use? See also https://docs.taler.net/core/api-bank-conversion-info.html 102 + modifications / extensions required? (here: for how long is the conversion valid!) 103 + how to map to Rhyza? 104 - credit-restriciton / debit-restriction: use to communicate legitimization requirements? 105 + https://docs.taler.net/core/api-exchange.html#post--management-wire 106 107 Interledger routes value as small cryptographic packets using the STREAM transport protocol, 108 while Open Payments provides REST APIs to initiate and track these payments. 109 110 // Is Open Payments necessary? What does it do exactly? 111 Open Payments is a standard that allows different payment systems to communicate, and Rhyza implements it. (https://www.youtube.com/watch?v=HeH1E7mmEh8&list=PLDHju0onYcAJakrsF-I7LK_0phEqurn46&index=2) 112 It is not strictly necessary for Interledger itself but it is convenient here: an entity that implements Open Payments services can ask an account provider to create an incoming payment, a quote and an outgoing payment, with authorization (grants). 113 114 // Need more details on the packet format and the STEAM protocol: 115 // - what is neede do configure the transport? 116 The transport is configured by the incoming payment: when the receiver creates it, its Rhyza gives an ILP address and a shared secret, 117 which the sender’s Rhyza uses to send the STREAM packets. 118 119 // - what information do we need (or can we put) in the 'cryptographic' packets? 120 The packets carry amounts and STREAM frames (small technical messages: amount that the receiver must obtain, errors), encrypted with a key derived from the shared secret 121 122 // - where will which data field come from? 123 The data comes from both sides: the ILP address and the shared secret from the receiver, the amounts, exchange rate and fees from the sender’s Rhyza. 124 125 Instead of replacing LibEuFin's EBICS functionality, Rhyza can act as an alternative wire-in. 126 // My understanding was that Rhyza still needs an underlying bank connector for settlement. How will that work? 127 Yes, I think it still needs one for settlement. Rhyza keeps the accounting of what is owed, but it does not move real money: the account provider’s ledger (bank, mobile money) does it, through Rhyza’s webhooks and administration API. 128 But I have not studied this part in detail yet. 129 130 When a wallet wants to fund a reserve, the exchange requests an 131 Open Payments incoming payment URL through its Rhyza instance, carrying the reserve public key. 132 // Interesting. Is the use of Open Payments mandatory here, or convenient? 133 Convenient. Rhyza implements it directly, so using it avoids building our own way to create payments and get authorizations. 134 135 // How does the wallet trigger the outgoing payment from the OTHER exchange? (https://rafiki.dev/overview/concepts/open-payments/) 136 I do not understand “other exchange”. 137 If it means the sender’s account provider (for example his bank account, mobile money operator), 138 then my understanding was that the wallet receives the incoming payment URL, 139 asks the sender’s account provider for a quote, 140 then requests a grant for the outgoing payment, the user consents, and the wallet creates the outgoing payment on the resource server of that account provider. (https://www.youtube.com/watch?v=V-18EWw0e-k&list=PLDHju0onYcAJakrsF-I7LK_0phEqurn46&index=2) 141 142 Once Rhyza confirms receipt of the funds in the Exchange's target currency, 143 the wire gateway reports the incoming transfer to the exchange, which credits the reserve. 144 145 // How are the funds credited exactly? When? 146 The funds are credited when the incoming payment is completed, 147 that is once the sender (client) has consented to the outgoing payment via his Taler App, 148 the outgoing payment has been created and the ILP packets have reached the exchange’s Rhyza. 149 150 // Would be good to have an architecture diagram showing the payment and protocol flows. 151 Okay I will try to do it. 152 153 Conversion sequence 154 ------------------- 155 156 The following sequence diagram shows the key steps of converting digital cash 157 of the source currency, issued by Exchange A, into digital cash of the target 158 currency, issued by Exchange B. Each side has its own :doc:`Taler adapter 159 </core/api-adapter>` and Rhyza instance. The wallet finds the adapters in the 160 ``accounts`` of the exchanges' :http:get:`/keys`: the Interledger account of 161 Exchange B has a ``prepared_transfer_url`` that points to Adapter B, and the 162 one of Exchange A a ``conversion_url`` that points to Adapter A. 163 164 In the HTML version of the diagram, Taler endpoints and data types link to 165 their specification and Rhyza operations to the Rhyza documentation. "(new)" 166 marks an endpoint that is yet to be specified, "(extended)" one that needs to 167 be extended. 168 169 .. uml:: 170 :caption: Key steps of a currency conversion from Exchange A to Exchange B 171 :alt: The wallet passes KYC at Exchange B and registers its reserve with 172 Adapter B, which creates a payment intent at Rhyza B. Adapter A 173 obtains a quote from Rhyza A. The wallet deposits its coins at 174 Exchange A, which wires them to the payment intent through Adapter A; 175 Rhyza A pays Rhyza B over ILP, Adapter B learns of the payment and 176 Exchange B credits the reserve. The wallet then withdraws coins 177 from the reserve at Exchange B. 178 179 @startuml 180 autonumber 181 182 participant "Wallet" as wallet 183 box "Source currency" 184 participant "Exchange A" as exa 185 participant "Adapter A" as ada 186 participant "Rhyza A" as rha 187 end box 188 box "Target currency" 189 participant "Rhyza B" as rhb 190 participant "Adapter B" as adb 191 participant "Exchange B" as exb 192 end box 193 194 == Legitimization == 195 196 wallet -> exb : POST /kyc-conversion (new) 197 exb --> wallet : KYC required (access token) 198 wallet -> exb : [[../core/api-exchange.html#post--kyc-upload-$ID POST /kyc-upload/$ID]] 199 exb -> exb : AML program 200 wallet -> exb : [[../core/api-exchange.html#get--kyc-info-$ACCESS_TOKEN GET /kyc-info/$ACCESS_TOKEN]] (extended) 201 exb --> wallet : conversion permitted 202 203 == Payment intent == 204 205 wallet -> adb : [[../core/api-bank-transfer.html#post--registration POST /registration]]\n(reserve_pub, credit_amount) 206 adb -> rhb : [[https://docs.rhyza.dev/apis/#tag/payment-intents/POST/payment-intents POST /payment-intents]]\n(incomingAmount,\nmetadata: reserve_pub) 207 rhb --> adb : openPaymentsUrl 208 adb --> wallet : [[../core/api-bank-transfer.html#tsref-type-RegistrationResponse RegistrationResponse]]\n(payto://ilp/…) 209 note over adb, exb : payto://ilp/ syntax\nto be extended 210 211 == Quote == 212 213 wallet -> ada : [[../core/api-bank-conversion-info.html#get--cashout-rate GET /cashout-rate]] (extended)\n(amount_credit, payto://ilp/…) 214 ada -> rha : [[https://docs.rhyza.dev/apis/#tag/quotes/POST/quotes POST /quotes]]\n(paymentIntentUrl,\nreceiveAmount) 215 rha <-> rhb : [[https://docs.rhyza.dev/concepts/interledger/#packets ILP quoting packet]] 216 rha --> ada : quote (debitAmount,\nexchangeRate, expiresAt) 217 ada --> wallet : [[../core/api-bank-conversion-info.html#tsref-type-CashoutConversionResponse CashoutConversionResponse]]\n(extended: expiration) 218 219 == Deposit and ILP payment == 220 221 wallet -> exa : [[../core/api-exchange.html#post--batch-deposit POST /batch-deposit]]\n(merchant_payto_uri:\npayto://ilp/…) 222 wallet -> exb : [[../core/api-exchange.html#get--reserves-$RESERVE_PUB GET /reserves/$RESERVE_PUB]]\n(long-polling) 223 activate exb 224 exa -> ada : [[../core/api-bank-wire.html#post--transfer POST /transfer]]\n(credit_account:\npayto://ilp/…) 225 ada -> rha : [[https://docs.rhyza.dev/apis/#tag/payments/POST/payments POST /payments]] (quoteId) 226 rha -> ada : [[https://docs.rhyza.dev/apis/#tag/webhook-events webhook payment.created]] 227 ada -> ada : hold amount 228 ada -> rha : [[https://docs.rhyza.dev/apis/#tag/payments/POST/payment-intents/%7BintentId%7D/payments/%7Bid%7D/approve POST …/approve]] 229 rha -> rhb : [[https://docs.rhyza.dev/concepts/interledger/#stream-protocol ILP STREAM packets]] 230 rhb -> adb : [[https://docs.rhyza.dev/apis/#tag/webhook-events webhook payment_intent.completed]]\n(metadata: reserve_pub,\nreceivedAmount) 231 adb -> exb : [[../manpages/taler-exchange-wirewatch.1.html wirewatch]] 232 exb --> wallet : 200 [[../core/api-exchange.html#tsref-type-ReserveSummary ReserveSummary]] 233 deactivate exb 234 235 == Withdrawal == 236 237 wallet -> exb : [[../core/api-exchange.html#post--withdraw POST /withdraw]] 238 exb --> wallet : 200 [[../core/api-exchange.html#tsref-type-WithdrawResponse WithdrawResponse]] 239 @enduml 240 241 Legitimization 242 The wallet asks Exchange B to permit a conversion with a new endpoint 243 ``POST /kyc-conversion``, similar to :doc:`POST /kyc-wallet 244 </core/exchange/post-kyc-wallet>`, that is yet to be specified. If KYC is 245 required, the user provides the data, for example with :doc:`POST 246 /kyc-upload/$ID </core/exchange/post-kyc-upload-ID>`, or at an external 247 provider set up with :doc:`POST /kyc-start/$ID 248 </core/exchange/post-kyc-start-ID>`, and the AML program of the exchange 249 decides. :doc:`GET /kyc-info/$ACCESS_TOKEN 250 </core/exchange/get-kyc-info-ACCESS_TOKEN>` needs to be extended to tell 251 the wallet that the conversion is permitted. 252 253 Payment intent 254 The wallet registers its reserve public key and the amount it wants with 255 :http:post:`/registration` of the prepared transfer API of Adapter B. 256 Adapter B creates a `payment intent 257 <https://docs.rhyza.dev/apis/#tag/payment-intents/POST/payment-intents>`__ 258 at Rhyza B, with that amount as ``incomingAmount`` and the reserve public 259 key in its ``metadata``, and returns its URL as a ``payto://ilp/`` URI in 260 the `RegistrationResponse`. The ``incomingAmount`` is needed: without it, 261 Rhyza does not complete the payment intent by itself. 262 263 Quote 264 The wallet asks Adapter A how much it has to deposit for the amount to 265 arrive at the payment intent. This extends :http:get:`/cashout-rate` of the 266 :doc:`conversion info API </core/api-bank-conversion-info>` with the 267 ``payto://ilp/`` URI of the payment intent, and `CashoutConversionResponse` 268 with the expiration of the quote. Adapter A obtains the quote with 269 `POST /quotes <https://docs.rhyza.dev/apis/#tag/quotes/POST/quotes>`__. 270 Rhyza A learns the amount that would arrive by sending an `ILP quoting 271 packet <https://docs.rhyza.dev/concepts/interledger/#packets>`__ to Rhyza B, 272 and returns the amounts, the exchange rate and when the quote expires. 273 274 Deposit and ILP payment 275 The wallet deposits its coins at Exchange A with :http:post:`/batch-deposit`, 276 with the ``payto://ilp/`` URI as the ``merchant_payto_uri``, and long-polls 277 its reserve at Exchange B with :http:get:`/reserves/$RESERVE_PUB`. 278 Exchange A wires the deposited amount with :http:post:`/transfer` of the 279 wire gateway of Adapter A, which creates the `payment 280 <https://docs.rhyza.dev/apis/#tag/payments/POST/payments>`__ from the quote. 281 Rhyza has no call to fund a payment: it announces the payment with the 282 ``payment.created`` `webhook 283 <https://docs.rhyza.dev/apis/#tag/webhook-events>`__, and Adapter A holds 284 the amount and `approves 285 <https://docs.rhyza.dev/apis/#tag/payments/POST/payment-intents/%7BintentId%7D/payments/%7Bid%7D/approve>`__ 286 the payment. Rhyza A then sends the `ILP STREAM packets 287 <https://docs.rhyza.dev/concepts/interledger/#stream-protocol>`__ to Rhyza B, 288 which completes the payment intent and notifies Adapter B with the 289 ``payment_intent.completed`` webhook, whose ``metadata`` holds the reserve 290 public key. :doc:`taler-exchange-wirewatch 291 </manpages/taler-exchange-wirewatch.1>` of Exchange B picks up the incoming 292 transfer from Adapter B, the exchange credits the reserve and answers the 293 long poll with the `ReserveSummary`. 294 295 Withdrawal 296 The wallet withdraws coins of the target currency from its reserve with 297 :http:post:`/withdraw`. 298 299 Open points: 300 301 * ``payto://ilp/`` as registered with RFC 8905 names an ILP address, while 302 the transfer has to go to a payment intent, identified by its Open Payments 303 URL. The payto syntax needs to be reviewed and extended, possibly with a 304 new payto method. 305 306 * ``POST /kyc-conversion`` needs to be specified, and the extensions of 307 :doc:`GET /kyc-info/$ACCESS_TOKEN 308 </core/exchange/get-kyc-info-ACCESS_TOKEN>`, :http:get:`/cashout-rate` and 309 `CashoutConversionResponse` need to be designed. 310 311 * The adapters use the `admin API 312 <https://docs.rhyza.dev/architecture/#admin-api>`__ of Rhyza, which is the 313 private interface of the financial service provider running the Rhyza 314 instance, and Rhyza sends its `webhooks 315 <https://docs.rhyza.dev/integration/#webhooks>`__ to that provider. An 316 adapter thus has to run as part of that provider. An adapter run by a third 317 party would have to use Open Payments `grants 318 <https://openpayments.dev/identity/grants/#grant-requests>`__ instead, 319 including an interactive one for every outgoing payment. 320 321 * With Rafiki instead of Rhyza, the corresponding operations are 322 `createIncomingPayment 323 <https://rafiki.dev/apis/graphql/backend/#mutation-createIncomingPayment>`__, 324 `createQuote 325 <https://rafiki.dev/apis/graphql/backend/#mutation-createQuote>`__, 326 `createOutgoingPayment 327 <https://rafiki.dev/apis/graphql/backend/#mutation-createOutgoingPayment>`__, 328 which is funded with `depositOutgoingPaymentLiquidity 329 <https://rafiki.dev/apis/graphql/backend/#mutation-depositOutgoingPaymentLiquidity>`__ 330 after the `outgoing_payment.created 331 <https://rafiki.dev/integration/requirements/webhook-events/#outgoing-payment-created>`__ 332 event, and the `incoming_payment.completed 333 <https://rafiki.dev/integration/requirements/webhook-events/#incoming-payment-completed>`__ 334 event. 335 336 337 Test Plan 338 ========= 339 340 (If this DD concerns a new or changed feature, describe how it can be tested.) 341 342 Definition of Done 343 ================== 344 345 (Only applicable to design documents that describe a new feature. While the 346 DoD is not satisfied yet, a user-facing feature **must** be behind a feature 347 flag or dev-mode flag.) 348 349 Alternatives 350 ============ 351 352 Drawbacks 353 ========= 354 355 Discussion / Q&A 356 ================ 357 358 (This should be filled in with results from discussions on mailing lists / personal communication.)