commit abbb2006fd9ba48e3d50f309f332191bd7b990a1
parent 0e0979803e47dc439d41128c5a04f39435b672c4
Author: Liz-MarielNGORAN <lizngoran@gmail.com>
Date: Tue, 17 Nov 2026 11:37:20 +0100
Initial draft
Diffstat:
1 file changed, 109 insertions(+), 20 deletions(-)
diff --git a/design-documents/106-currency-conversion.rst b/design-documents/106-currency-conversion.rst
@@ -6,7 +6,7 @@ DD 106:Currency Conversion
:DD shepherd: Amoui N'GORAN
:Historical contributors: Amoui N'GORAN
:First published: 2026-10-11
-:Last substantive change: 2026-10-13
+:Last substantive change: 2026-10-15
Summary
@@ -14,46 +14,135 @@ 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).
-As the exchange can only be funded through thoses channels, for others currency, it is needed to write a wire Gateway implementation.
-But writing and maintaining a dedicated wire gateway for every banking system will take time.
+The main implementation today relies on LibEuFin and EBICS, which limits funding to bank accounts in the SEPA area (EUR) or Switzerland (CHF).
+If we would like to do transactions cross-currencies as EUR to CHF or CFA to EUR,
+we should be able to convert currencies to fund the client reserve through the taler system.
+//Note quite: the problem isn't the need for additional banking adapters, but the conversion!
-Interledger is an open protocol suite for sending packets of value across different payment networks.
+Interledger is an open protocol suite for sending packets of value across different payment networks, an internet for financial payments.
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 Rafiki-based gateway next to Libeufin to allow payments cross currencies.
+This document specifies how we can implement Rafiki-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.
Motivation
==========
-1. Taler's mono currency constraint
-Taler exchange is intrinsically linked to a specific currency.
-For example, if a customer holds foreign currency in a country A (e.g. XOF in West Africa or USD) and wants to buy a good from a merchant connected to Taler exchange in EUR, he has to manually make an expensive and slow international transfer to the european exchange's reserve.
+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. Exclusivity for EBICS
-Taler currently uses Libeufin to communicate with standard European banking protocols such as EBICS.
-This works very well in the SEPA area but exclude area where mobile money ( orange money, Wave) and instant payments system dominate.
+//2. Exclusivity for EBICS
+//Taler currently uses Libeufin to communicate with standard European banking protocols such as EBICS.
+//This works very well in the SEPA area but exclude area where mobile money (orange money, Wave) and instant payments system dominate.
+// Not true! See cyclos, magnet and depolymerization adapters.
+For this part, I will delete it as it is not a motivation to satisfy.
3. 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).
+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).
+
+4. Legal requirements
+Withdrawing funds as a non-domestic customer may come with different AML/KYC requirements.
+
+5. 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.
+
+6. Spread and fees
+If we can do conversion internally, especically when many transfers to back and forth,
+exchange operators can financially benefit from the spread.
+
Requirements
============
-* Create a payment adapter that can listen for incoming payments events via Rafiki's Open Payments API.
-* Pass the reserve public key to the technical data of the transaction so that the Exchange can credit the correct reserve upon receipt of the ILP packet.
+* Create a payment (wire gateway) adapter that can listen for incoming payments events via Rafiki's webhooks.
+ // Well, incoming is half: how do we do outgoing? Something has to trigger Rafiki on the other end!
+ // How exactly would that happen? I think again via a wire gateway adapter!
+ I think we should have a part implemented in Taler App that integrates Open payments API and manages the client side (grants, quotes, outgoing payments)
+ and another component that integrates it too but for the exchange part (incoming payment, grants).
+ As each account provider runs two servers (authorization and resource servers), both provided by Rafiki,
+ the mentioned implementations will by the different grants trigger Rafiki both on the client and exchange side.
+
+* Pass the reserve public key to the technical data of the transaction so that the Exchange can credit
+ the correct reserve upon receipt of the ILP packet.
+
* Set the exchange policy if the currency sent via ILP differs from the target currency of the Taler reserve.
-* Incorporate a margin of safety on the exchange rate to ensure that the exact amount expected by the customer arrives at its destination without losses due to micro-fluctuations.
-* Compliance and auditability requirements preserving anonymity
+ // This needs more detail. What would these policies look like?
+ this is more about the solution configuration.
+ We should verify that the assetCode and assetScale of the exchange’s wallet address match the currency configured in the Taler exchange, and refuse to start otherwise.
+ The Taler exchange is configured in JPY. The wallet address of the exchange, however, was set up in Rafiki with assetCode: “USD”.
+ If the component reused the asset of the wallet address without comparing it to the Taler configuration,
+ it would request an incoming payment of 10000 in USD while intending 10 000 JPY. The payment would go through,
+ but the reserve would be credited with an amount in the wrong currency.
+
+* Incorporate a margin of safety on the exchange rate to ensure that the exact amount expected
+ by the customer arrives at its destination without losses due to micro-fluctuations.
+ // What does Rafiki already do here?
+ ( With the Open Payments API of Rafiki, a quote where we have the amount that is sent, what should be received and the fees, is sent by the resource server of the sender, so that we can ensure that the target receives the exact amount.
+ Rafiki has a configuration parameter "slippage" on the sender side -it is the maximum tolerated difference between the expected amount and the actual one- that provide this safety margin)
+* Compliance and auditability requirements preserving anonymity
+ // Anonymity is probably not a requirement to worry about.
+ // What are the compliance and auditability requirements? Needs details.
+ Compliance: For an incoming transfer, the exchange should be able to register the source of the reserve funding (ideally the sender’s wallet address) for KYC obligations, and to repay a reserve that has not been withdrawn, for example. (https://docs.taler.net/taler-kyc-manual.html#kycoperatormanual)
+ However, with Open Payments, an incoming payment does not indicate by default who has paid: the recipient knows that it has been credited, not by whom.
+ How to obtain the payer’s identity is still to be defined.
+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 Rafiki instance (incoming payments) and the ledger of the exchange’s bank. (https://docs.taler.net/taler-auditor-manual.html)
+
Proposed Solution (Initial Approach)
====================================
-Interledger routes value as small cryptographic packets using the STREAM transport protocol, while Open Payments provides REST APIs to initiate and track these payments.
+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 Rafiki 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 Rafiki gives an ILP address and a shared secret,
+which the sender’s Rafiki 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 Rafiki.
+
Instead of replacing LibEuFin's EBICS functionality, Rafiki can act as an alternative wire-in.
-When a wallet wants to fund a reserve, the exchange requests an Open Payments incoming payment URL through its Rafiki instance, carrying the reserve public key.
-Once Rafiki 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.
+// My understanding was that Rafiki still needs an underlying bank connector for settlement. How will that work?
+Yes, I think it still needs one for settlement. Rafiki 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 Rafiki’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 Rafiki instance, carrying the reserve public key.
+// Interesting. Is the use of Open Payments mandatory here, or convenient?
+Convenient. Rafiki 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 Rafiki 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 Rafiki.
+
+// Would be good to have an architecture diagram showing the payment and protocol flows.
+Okay I will try to do it.
+
Test Plan