commit 08da115d4cc0d88ee480fc41562d78df91955f98
parent d2413d96d398cf8da60323d45072177327b34495
Author: Christian Grothoff <christian@grothoff.org>
Date: Fri, 20 Nov 2026 23:27:11 +0100
refine UML diagram
Diffstat:
1 file changed, 138 insertions(+), 55 deletions(-)
diff --git a/design-documents/106-currency-conversion.rst b/design-documents/106-currency-conversion.rst
@@ -155,17 +155,26 @@ 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 wire gateway adapter and
-Rhyza instance.
+currency, issued by Exchange B. Each side has its own :doc:`Taler adapter
+</core/api-adapter>` and Rhyza instance. The wallet finds the adapters in the
+``accounts`` of the exchanges' :http: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.
.. uml::
:caption: Key steps of a currency conversion from Exchange A to Exchange B
- :alt: The wallet passes KYC at Exchange B and obtains an incoming payment
- URL for its reserve from Adapter B and Rhyza B. Adapter A obtains a
- quote from Rhyza A. The wallet deposits its coins at Exchange A;
- Adapter A has Rhyza A send the payment over ILP to Rhyza B, and
- Adapter B reports it to Exchange B, which credits the reserve. The
- wallet then withdraws coins from the reserve at Exchange B.
+ :alt: The wallet passes KYC at Exchange B and registers its reserve with
+ Adapter B, which creates a payment intent at Rhyza B. Adapter A
+ obtains a quote from Rhyza A. The wallet deposits its coins at
+ Exchange A, which wires them to the payment intent through Adapter A;
+ Rhyza A pays Rhyza B over ILP, Adapter B learns of the payment and
+ Exchange B credits the reserve. The wallet then withdraws coins
+ from the reserve at Exchange B.
@startuml
autonumber
@@ -182,73 +191,147 @@ Rhyza instance.
participant "Exchange B" as exb
end box
- == Legitimization and incoming payment ==
+ == Legitimization ==
+
+ wallet -> exb : POST /kyc-conversion (new)
+ exb --> wallet : KYC required (access token)
+ wallet -> exb : [[../core/api-exchange.html#post--kyc-upload-$ID POST /kyc-upload/$ID]]
+ exb -> exb : AML program
+ wallet -> exb : [[../core/api-exchange.html#get--kyc-info-$ACCESS_TOKEN GET /kyc-info/$ACCESS_TOKEN]] (extended)
+ exb --> wallet : conversion permitted
- wallet -> exb : askConversionPossibility()
- exb --> wallet : requestKYC()
- wallet -> exb : submitKYC(id)
- exb -> exb : IdVerification()
- exb --> wallet : acceptCustomer()
- note over ada, rha : give access to Adapter B
- wallet -> adb : sendKey(reserve_pub)
- adb -> rhb : createIncomingPay(reserve_pub)
- rhb --> adb : sendURL()
- adb -> wallet : sendURL()
+ == Payment intent ==
+
+ wallet -> adb : [[../core/api-bank-transfer.html#post--registration POST /registration]]\n(reserve_pub, credit_amount)
+ adb -> rhb : [[https://docs.rhyza.dev/apis/#tag/payment-intents/POST/payment-intents POST /payment-intents]]\n(incomingAmount,\nmetadata: reserve_pub)
+ rhb --> adb : openPaymentsUrl
+ adb --> wallet : [[../core/api-bank-transfer.html#tsref-type-RegistrationResponse RegistrationResponse]]\n(payto://ilp/…)
+ note over adb, exb : payto://ilp/ syntax\nto be extended
== Quote ==
- wallet -> ada : triggerConversion(URL, wantedAmount)
- ada -> rha : askQuote()
- rha -> rha : CalculateVariable()
- rha --> ada : sendQuote(amounts,\nvalidity, rate)
- ada --> wallet : transferQuote(amounts, validity, rate)
+ wallet -> ada : [[../core/api-bank-conversion-info.html#get--cashout-rate GET /cashout-rate]] (extended)\n(amount_credit, payto://ilp/…)
+ ada -> rha : [[https://docs.rhyza.dev/apis/#tag/quotes/POST/quotes POST /quotes]]\n(paymentIntentUrl,\nreceiveAmount)
+ rha <-> rhb : [[https://docs.rhyza.dev/concepts/interledger/#packets ILP quoting packet]]
+ rha --> ada : quote (debitAmount,\nexchangeRate, expiresAt)
+ ada --> wallet : [[../core/api-bank-conversion-info.html#tsref-type-CashoutConversionResponse CashoutConversionResponse]]\n(extended: expiration)
== Deposit and ILP payment ==
- wallet -> exa : depositCoins(coins)
- wallet -> exb : getReserve(reserve_pub), long-polling
+ wallet -> exa : [[../core/api-exchange.html#post--batch-deposit POST /batch-deposit]]\n(merchant_payto_uri:\npayto://ilp/…)
+ wallet -> exb : [[../core/api-exchange.html#get--reserves-$RESERVE_PUB GET /reserves/$RESERVE_PUB]]\n(long-polling)
activate exb
- exa -> ada : confirmDeposit()
- ada -> ada : blockAmountToSend()
- ada -> rha : createOutgoingPayment-\nsendLiquidity()
- rha -> rhb : sendILP()
- rhb -> rhb : updateIncomingPayment\nStatus(complete)
- rhb -> adb : statePayment(complete, reserve_pub,\namounts, ILPinfos)
- adb -> exb : sendInfos(reserve_pub,\namount)
- exb -> exb : creditReserve()
- exb --> wallet : 200 OK (balance)
+ exa -> ada : [[../core/api-bank-wire.html#post--transfer POST /transfer]]\n(credit_account:\npayto://ilp/…)
+ ada -> rha : [[https://docs.rhyza.dev/apis/#tag/payments/POST/payments POST /payments]] (quoteId)
+ rha -> ada : [[https://docs.rhyza.dev/apis/#tag/webhook-events webhook payment.created]]
+ ada -> ada : hold amount
+ ada -> rha : [[https://docs.rhyza.dev/apis/#tag/payments/POST/payment-intents/%7BintentId%7D/payments/%7Bid%7D/approve POST …/approve]]
+ rha -> rhb : [[https://docs.rhyza.dev/concepts/interledger/#stream-protocol ILP STREAM packets]]
+ rhb -> adb : [[https://docs.rhyza.dev/apis/#tag/webhook-events webhook payment_intent.completed]]\n(metadata: reserve_pub,\nreceivedAmount)
+ adb -> exb : [[../manpages/taler-exchange-wirewatch.1.html wirewatch]]
+ exb --> wallet : 200 [[../core/api-exchange.html#tsref-type-ReserveSummary ReserveSummary]]
deactivate exb
== Withdrawal ==
- wallet -> exb : withdraw(reserve_pub, blindedCoins)
- exb --> wallet : OK (blindSignatures)
+ wallet -> exb : [[../core/api-exchange.html#post--withdraw POST /withdraw]]
+ exb --> wallet : 200 [[../core/api-exchange.html#tsref-type-WithdrawResponse WithdrawResponse]]
@enduml
-Legitimization and incoming payment
- The wallet asks Exchange B whether it may convert, and passes the KYC check
- that Exchange B requests. Once accepted, it may use Adapter B: it sends the
- public key of its reserve to Adapter B, which creates an incoming payment
- for that reserve at Rhyza B and returns the incoming payment URL.
+Legitimization
+ The wallet asks Exchange B to permit a conversion with a new endpoint
+ ``POST /kyc-conversion``, similar to :doc:`POST /kyc-wallet
+ </core/exchange/post-kyc-wallet>`, that is yet to be specified. If KYC is
+ required, the user provides the data, for example with :doc:`POST
+ /kyc-upload/$ID </core/exchange/post-kyc-upload-ID>`, or at an external
+ provider set up with :doc:`POST /kyc-start/$ID
+ </core/exchange/post-kyc-start-ID>`, and the AML program of the exchange
+ decides. :doc:`GET /kyc-info/$ACCESS_TOKEN
+ </core/exchange/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
+ :http:post:`/registration` of the prepared transfer API of Adapter B.
+ Adapter B creates a `payment intent
+ <https://docs.rhyza.dev/apis/#tag/payment-intents/POST/payment-intents>`__
+ at Rhyza B, with that amount as ``incomingAmount`` and the reserve public
+ key in its ``metadata``, and returns its URL as a ``payto://ilp/`` URI in
+ the `RegistrationResponse`. The ``incomingAmount`` is needed: without it,
+ Rhyza does not complete the payment intent by itself.
Quote
- The wallet passes the URL and the amount it wants to Adapter A, which asks
- Rhyza A for a quote and returns the amounts, the conversion rate and how
- long the quote is valid.
+ The wallet asks Adapter A how much it has to deposit for the amount to
+ arrive at the payment intent. This extends :http:get:`/cashout-rate` of the
+ :doc:`conversion info API </core/api-bank-conversion-info>` with the
+ ``payto://ilp/`` URI of the payment intent, and `CashoutConversionResponse`
+ with the expiration of the quote. Adapter A obtains the quote with
+ `POST /quotes <https://docs.rhyza.dev/apis/#tag/quotes/POST/quotes>`__.
+ Rhyza A learns the amount that would arrive by sending an `ILP quoting
+ packet <https://docs.rhyza.dev/concepts/interledger/#packets>`__ 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 and long-polls its reserve at
- Exchange B. Exchange A confirms the deposit to Adapter A, which blocks the
- amount to send and creates the outgoing payment at Rhyza A. Rhyza A sends
- the ILP packets to Rhyza B, which completes the incoming payment and reports
- it to Adapter B. Adapter B passes the reserve public key and the amount to
- Exchange B, which credits the reserve and answers the long-poll with the
- balance.
+ The wallet deposits its coins at Exchange A with :http:post:`/batch-deposit`,
+ with the ``payto://ilp/`` URI as the ``merchant_payto_uri``, and long-polls
+ its reserve at Exchange B with :http:get:`/reserves/$RESERVE_PUB`.
+ Exchange A wires the deposited amount with :http:post:`/transfer` of the
+ wire gateway of Adapter A, which creates the `payment
+ <https://docs.rhyza.dev/apis/#tag/payments/POST/payments>`__ from the quote.
+ Rhyza has no call to fund a payment: it announces the payment with the
+ ``payment.created`` `webhook
+ <https://docs.rhyza.dev/apis/#tag/webhook-events>`__, and Adapter A holds
+ the amount and `approves
+ <https://docs.rhyza.dev/apis/#tag/payments/POST/payment-intents/%7BintentId%7D/payments/%7Bid%7D/approve>`__
+ the payment. Rhyza A then sends the `ILP STREAM packets
+ <https://docs.rhyza.dev/concepts/interledger/#stream-protocol>`__ to Rhyza B,
+ which completes the payment intent and notifies Adapter B with the
+ ``payment_intent.completed`` webhook, whose ``metadata`` holds the reserve
+ public key. :doc:`taler-exchange-wirewatch
+ </manpages/taler-exchange-wirewatch.1>` 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 at
- Exchange B.
-
+ The wallet withdraws coins of the target currency from its reserve with
+ :http: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-conversion`` needs to be specified, and the extensions of
+ :doc:`GET /kyc-info/$ACCESS_TOKEN
+ </core/exchange/get-kyc-info-ACCESS_TOKEN>`, :http:get:`/cashout-rate` and
+ `CashoutConversionResponse` need to be designed.
+
+* The adapters use the `admin API
+ <https://docs.rhyza.dev/architecture/#admin-api>`__ of Rhyza, which is the
+ private interface of the financial service provider running the Rhyza
+ instance, and Rhyza sends its `webhooks
+ <https://docs.rhyza.dev/integration/#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
+ <https://openpayments.dev/identity/grants/#grant-requests>`__ instead,
+ including an interactive one for every outgoing payment.
+
+* With Rafiki instead of Rhyza, the corresponding operations are
+ `createIncomingPayment
+ <https://rafiki.dev/apis/graphql/backend/#mutation-createIncomingPayment>`__,
+ `createQuote
+ <https://rafiki.dev/apis/graphql/backend/#mutation-createQuote>`__,
+ `createOutgoingPayment
+ <https://rafiki.dev/apis/graphql/backend/#mutation-createOutgoingPayment>`__,
+ which is funded with `depositOutgoingPaymentLiquidity
+ <https://rafiki.dev/apis/graphql/backend/#mutation-depositOutgoingPaymentLiquidity>`__
+ after the `outgoing_payment.created
+ <https://rafiki.dev/integration/requirements/webhook-events/#outgoing-payment-created>`__
+ event, and the `incoming_payment.completed
+ <https://rafiki.dev/integration/requirements/webhook-events/#incoming-payment-completed>`__
+ event.
Test Plan