taler-docs

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

commit e279a25441823d074d28ee5586e1821cf3aebdae
parent bc50cdfdcaa92a93759f59a3afffdaf59873db28
Author: Iván Ávalos <avalos@disroot.org>
Date:   Sat, 14 Nov 2026 22:32:31 +0100

add amouie's dd106 draft

Diffstat:
Adesign-documents/106-currency-conversion.rst | 80+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 80 insertions(+), 0 deletions(-)

diff --git a/design-documents/106-currency-conversion.rst b/design-documents/106-currency-conversion.rst @@ -0,0 +1,80 @@ +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-10-13 + + +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. + +Interledger is an open protocol suite for sending packets of value across different payment networks. +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 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. + +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. + +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). + +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. +* 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 + +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. +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. + + +Test Plan +========= + +(If this DD concerns a new or changed feature, describe how it can be tested.) + +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.) + +Alternatives +============ + +Drawbacks +========= + +Discussion / Q&A +================ + +(This should be filled in with results from discussions on mailing lists / personal communication.)