commit acce50c33aea094ab88782e9c705cd6db3b4eefe
parent abbb2006fd9ba48e3d50f309f332191bd7b990a1
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Tue, 17 Nov 2026 13:27:16 +0100
clarifying requirements
Diffstat:
1 file changed, 76 insertions(+), 69 deletions(-)
diff --git a/design-documents/106-currency-conversion.rst b/design-documents/106-currency-conversion.rst
@@ -12,118 +12,125 @@ DD 106:Currency Conversion
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).
-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!
+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.
-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 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
+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.
-// 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
+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).
-4. Legal requirements
+3. Legal requirements:
Withdrawing funds as a non-domestic customer may come with different AML/KYC requirements.
-5. Conversion rate
+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.
-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.
+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.
Requirements
============
-* 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.
- // 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)
-
+* 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)
+
+
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 Rafiki implements it. (https://www.youtube.com/watch?v=HeH1E7mmEh8&list=PLDHju0onYcAJakrsF-I7LK_0phEqurn46&index=2)
+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 Rafiki gives an ILP address and a shared secret,
-which the sender’s Rafiki uses to send the STREAM packets.
+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 Rafiki.
+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, Rafiki can act as an alternative wire-in.
-// 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.
+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 Rafiki instance, carrying the reserve public key.
+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. Rafiki implements it directly, so using it avoids building our own way to create payments and get authorizations.
+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”.
@@ -132,13 +139,13 @@ 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,
+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 Rafiki.
+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.