taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

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.)