23.106. DD 106: Currency Conversion#
- Design status:
Draft
- Implementation status:
Not started
- DD shepherd:
Amoui N’GORAN
- Historical contributors:
Amoui N’GORAN
- First published:
2026-10-11
- Last substantive change:
2026-11-20
23.106.1. Summary#
Taler is an auditable and privacy-friendly electronic payment system. It can support many currencies, but each exchange serves a single currency and is funded through a wire gateway. The main implementation today relies on LibEuFin and EBICS, which limits funding to bank accounts in the SEPA area (EUR) or Switzerland (CHF). We want to support currency-conversion where a wallet holding a source currency (like digital EUR) can convert them to a target currency (like digital CHF). At the time of conversion the user may need to be identified, but then afterwards they would again own digital cash unlinked to their identity. Since the user is withdrawing fresh digital cash from an exchange, the source currency is used to fund a reserve at the exchange offering the target currency.
Interledger is an open protocol suite for sending packets representing financial values across different payment networks, an internet for financial payments. Rhyza (https://docs.rhyza.dev/), which is the successor of Rafiki, is an open-source software of Interledger that allows financial institutions to easily access to Interledger and Open-Payment API.
This document specifies how we can implement Rhyza-based gateway next to Libeufin to enable currency conversion. (Being able to convert currencies is the hard part: once it is possible, paying across currencies follows trivially.) This will mainly affect the reserve funding in the Taler flow so the exchange, its bank account, the reserve and Libeufin.
23.106.2. Motivation#
1. Taler’s mono-currency constraint: Each Taler exchange is intrinsically linked to a specific currency. For example, if a customer holds currency in a country A (e.g. XOF in West Africa or USD) and wants to buy a good from a merchant who only accepts EUR from a Taler exchange in Europe, he has to manually make an expensive and slow international transfer to the European exchange’s reserve. Moreover, the European exchange may even reject funding a reserve via such a channel.
2. Delay of reserve funding: Taler’s reserve wire-in mechanism normally requires waiting for the validation of bank transfer to credit the customer’s reserve (often several hours or even days depending on the bank).
3. Legal requirements: Withdrawing funds as a non-domestic customer may come with different AML/KYC requirements.
4. Conversion rate: Customers will want to know up-front what the currency conversion rate will be, just like the involved payment service providers will need to manage risks arising from rate fluctuations.
5. Spread and fees: If we can do conversion internally, especically aggregating many transfers going back and forth and only settling periodically the aggregate debts to avoid international wire transfers for every microtransaction, we can significantly reduce costs. Furthermore, exchange operators can still financially benefit from the spread.
23.106.3. Requirements#
Create a payment (wire gateway) adapter that can listen for incoming payments events (via Rhyza’s webhooks). Before accepting any incoming payment, we need to communicate our legitimization requirements (see https://docs.taler.net/taler-kyc-manual.html#kycoperatormanual) to the originating wallet and possibly check the legitimization data against sanction lists. Basically, the customer may need to perform some arbitrary onboarding (KYC/KYB) and only then they are allowed to wire the funds.
Enable outgoing payments (in a wire gateway adapter), which must trigger the incoming payment at the target exchange with the required meta-data (which reserve to fund). The outgoing payments should be aggregated by ILP and then settled with international wire transfers based on the underlying contractual obligations (when the conversion rate shifts too much or the liability of one exchange to another exceeds a certain threshold).
Communicate to the exchange and the wallets the current conversion rate and how long it is valid, so that wallets can compute how much target currency they will receive for a given amount of source currency and vice-versa.
Auditability: The Taler auditor should be able to verify that the amount credited to a reserve corresponds to an amount actually received, using the records of the exchange’s Rhyza instance (incoming payments) and the ledger of the exchange’s bank. (https://docs.taler.net/taler-auditor-manual.html)
23.106.4. Proposed Solution (Initial Approach)#
https://docs.taler.net/core/api-bank-wire.html - modifications / extensions required? - how to map to Rhyza?
https://docs.taler.net/manpages/taler-exchange-offline.1.html#enable-account - conversion-url: how to use? See also https://docs.taler.net/core/api-bank-conversion-info.html
modifications / extensions required? (here: for how long is the conversion valid!)
how to map to Rhyza?
credit-restriciton / debit-restriction: use to communicate legitimization requirements? + https://docs.taler.net/core/api-exchange.html#post–management-wire
Interledger routes value as small cryptographic packets using the STREAM transport protocol, while Open Payments provides REST APIs to initiate and track these payments.
// Is Open Payments necessary? What does it do exactly? 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) 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).
// Need more details on the packet format and the STEAM protocol: // - what is neede do configure the transport? The transport is configured by the incoming payment: when the receiver creates it, its Rhyza gives an ILP address and a shared secret, which the sender’s Rhyza uses to send the STREAM packets.
// - what information do we need (or can we put) in the ‘cryptographic’ packets? 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
// - where will which data field come from? 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.
Instead of replacing LibEuFin’s EBICS functionality, Rhyza can act as an alternative wire-in. // My understanding was that Rhyza still needs an underlying bank connector for settlement. How will that work? 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. But I have not studied this part in detail yet.
When a wallet wants to fund a reserve, the exchange requests an Open Payments incoming payment URL through its Rhyza instance, carrying the reserve public key. // Interesting. Is the use of Open Payments mandatory here, or convenient? Convenient. Rhyza implements it directly, so using it avoids building our own way to create payments and get authorizations.
// How does the wallet trigger the outgoing payment from the OTHER exchange? (https://rafiki.dev/overview/concepts/open-payments/) I do not understand “other exchange”. If it means the sender’s account provider (for example his bank account, mobile money operator), then my understanding was that the wallet receives the incoming payment URL, asks the sender’s account provider for a quote, 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)
Once Rhyza confirms receipt of the funds in the Exchange’s target currency, the wire gateway reports the incoming transfer to the exchange, which credits the reserve.
// How are the funds credited exactly? When? The funds are credited when the incoming payment is completed, that is once the sender (client) has consented to the outgoing payment via his Taler App, the outgoing payment has been created and the ILP packets have reached the exchange’s Rhyza.
// Would be good to have an architecture diagram showing the payment and protocol flows. Okay I will try to do it.
23.106.4.1. Conversion sequence#
The following sequence diagram shows the key steps of converting digital cash
of the source currency, issued by Exchange A, into digital cash of the target
currency, issued by Exchange B. Each side has its own Taler adapter and Rhyza instance. The wallet finds the adapters in the
accounts of the exchanges’ GET /keys: the Interledger account of
Exchange B has a prepared_transfer_url that points to Adapter B, and the
one of Exchange A a conversion_url that points to Adapter A.
In the HTML version of the diagram, Taler endpoints and data types link to their specification and Rhyza operations to the Rhyza documentation. “(new)” marks an endpoint that is yet to be specified, “(extended)” one that needs to be extended.
Key steps of a currency conversion from Exchange A to Exchange B
- Legitimization
The wallet asks Exchange B to permit a conversion with a new endpoint
POST /kyc-conversion, similar to POST /kyc-wallet, that is yet to be specified. If KYC is required, the user provides the data, for example with POST /kyc-upload/$ID, or at an external provider set up with POST /kyc-start/$ID, and the AML program of the exchange decides. GET /kyc-info/$ACCESS_TOKEN needs to be extended to tell the wallet that the conversion is permitted.- Payment intent
The wallet registers its reserve public key and the amount it wants with
POST /registrationof the prepared transfer API of Adapter B. Adapter B creates a payment intent at Rhyza B, with that amount asincomingAmountand the reserve public key in itsmetadata, and returns its URL as apayto://ilp/URI in the RegistrationResponse. TheincomingAmountis needed: without it, Rhyza does not complete the payment intent by itself.- Quote
The wallet asks Adapter A how much it has to deposit for the amount to arrive at the payment intent. This extends
GET /cashout-rateof the conversion info API with thepayto://ilp/URI of the payment intent, and CashoutConversionResponse with the expiration of the quote. Adapter A obtains the quote with POST /quotes. Rhyza A learns the amount that would arrive by sending an ILP quoting packet to Rhyza B, and returns the amounts, the exchange rate and when the quote expires.- Deposit and ILP payment
The wallet deposits its coins at Exchange A with
POST /batch-deposit, with thepayto://ilp/URI as themerchant_payto_uri, and long-polls its reserve at Exchange B withGET /reserves/$RESERVE_PUB. Exchange A wires the deposited amount withPOST /transferof the wire gateway of Adapter A, which creates the payment from the quote. Rhyza has no call to fund a payment: it announces the payment with thepayment.createdwebhook, and Adapter A holds the amount and approves the payment. Rhyza A then sends the ILP STREAM packets to Rhyza B, which completes the payment intent and notifies Adapter B with thepayment_intent.completedwebhook, whosemetadataholds the reserve public key. taler-exchange-wirewatch of Exchange B picks up the incoming transfer from Adapter B, the exchange credits the reserve and answers the long poll with the ReserveSummary.- Withdrawal
The wallet withdraws coins of the target currency from its reserve with
POST /withdraw.
Open points:
payto://ilp/as registered with RFC 8905 names an ILP address, while the transfer has to go to a payment intent, identified by its Open Payments URL. The payto syntax needs to be reviewed and extended, possibly with a new payto method.POST /kyc-conversionneeds to be specified, and the extensions of GET /kyc-info/$ACCESS_TOKEN,GET /cashout-rateand CashoutConversionResponse need to be designed.The adapters use the admin API of Rhyza, which is the private interface of the financial service provider running the Rhyza instance, and Rhyza sends its webhooks to that provider. An adapter thus has to run as part of that provider. An adapter run by a third party would have to use Open Payments grants instead, including an interactive one for every outgoing payment.
With Rafiki instead of Rhyza, the corresponding operations are createIncomingPayment, createQuote, createOutgoingPayment, which is funded with depositOutgoingPaymentLiquidity after the outgoing_payment.created event, and the incoming_payment.completed event.
23.106.5. Test Plan#
(If this DD concerns a new or changed feature, describe how it can be tested.)
23.106.6. Definition of Done#
(Only applicable to design documents that describe a new feature. While the DoD is not satisfied yet, a user-facing feature must be behind a feature flag or dev-mode flag.)
23.106.7. Alternatives#
23.106.8. Drawbacks#
23.106.9. Discussion / Q&A#
(This should be filled in with results from discussions on mailing lists / personal communication.)