taler-docs

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

commit 08da115d4cc0d88ee480fc41562d78df91955f98
parent d2413d96d398cf8da60323d45072177327b34495
Author: Christian Grothoff <christian@grothoff.org>
Date:   Fri, 20 Nov 2026 23:27:11 +0100

refine UML diagram

Diffstat:
Mdesign-documents/106-currency-conversion.rst | 193++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----------------------
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