commit d2413d96d398cf8da60323d45072177327b34495
parent 3368f2a93035c677a0004f6b7ec8a55635f8c5f3
Author: Christian Grothoff <christian@grothoff.org>
Date: Fri, 20 Nov 2026 22:58:09 +0100
work on DD 106
Diffstat:
7 files changed, 149 insertions(+), 23 deletions(-)
diff --git a/README b/README
@@ -7,6 +7,8 @@ To build things on a Debian (-based) system, install these packages:
- python3-sphinx-book-theme
- python3-sphinx-design
- python3-sphinxcontrib-mermaid
+ - python3-sphinxcontrib.plantuml
+ - plantuml
- graphviz
- texlive-latex-extra
- dvipng
@@ -38,6 +40,13 @@ HTML output renders them in the browser using JavaScript from the extension's
default CDN. Mermaid CLI is not needed. Put diagrams inside an "only:: html"
directive and include an equivalent prose description for other output formats.
+PlantUML diagrams (sequence diagrams in particular) use sphinxcontrib-plantuml
+and are rendered at build time, for HTML and LaTeX output alike. Write the
+diagram inline in the ".. uml::" directive, with only the :caption:, :alt:,
+:width:, :height: and :scale: options: Debian's version of the extension does
+not accept a file name argument or :align:. conf.py applies the shared style
+in images/taler-uml-style.iuml to every diagram, so do not include it.
+
Branch ‘prebuilt’ is special. Its contents (or a subset) are used as
submodules in other Git repos (e.g., Exchange, Merchant, Sync).
diff --git a/conf.py b/conf.py
@@ -36,6 +36,7 @@
import sys
import os
+import shlex
sys.path.append(os.path.abspath("_exts"))
@@ -72,8 +73,25 @@ imgmath_use_preview = True
# PlantUML diagrams (``.. uml::``), rendered at build time. Needs a
# ``plantuml`` command on PATH, provided by the Nix development shell
-# and package.
-plantuml = os.environ.get("PLANTUML", "plantuml")
+# and package, or on Debian by the plantuml and
+# python3-sphinxcontrib.plantuml packages.
+#
+# ``-config`` applies the shared Taler style to every diagram, so a
+# diagram needs no ``!include`` for it. Write diagrams inline: Debian's
+# sphinxcontrib-plantuml (0.5) takes no file name argument, and it runs
+# PlantUML in the directory sphinx-build was started from, not in that
+# of the document, so relative includes resolve differently than with
+# newer versions of the extension.
+plantuml = "{} -config {}".format(
+ os.environ.get("PLANTUML", "plantuml"),
+ shlex.quote(
+ os.path.join(
+ os.path.dirname(os.path.abspath(__file__)),
+ "images",
+ "taler-uml-style.iuml",
+ )
+ ),
+)
plantuml_output_format = "svg"
# Render HTML Mermaid diagrams in the browser using the extension's CDN assets.
diff --git a/design-documents/098-token-fountains.rst b/design-documents/098-token-fountains.rst
@@ -50,13 +50,25 @@ User Flow
The recipient scans the promotion once. The wallet obtains promotional
tokens and offers an applicable token later at checkout.
-.. uml:: images/098/promotions-user-flow.puml
- :align: center
+.. uml::
:width: 90%
:caption: Joining and using a token-fountain promotion
:alt: Scan the promotion, receive promotional tokens in the wallet, use a
token at checkout and receive the discount or benefit.
+ @startuml
+ left to right direction
+
+ rectangle "Scan the\npromotion" as scan #d3deff
+ rectangle "Wallet receives\npromotional tokens" as receive #d3deff
+ rectangle "Use a token\nat checkout" as use #d3deff
+ rectangle "Receive the\ndiscount or benefit" as benefit #d3deff
+
+ scan --> receive
+ receive --> use
+ use --> benefit
+ @enduml
+
Requirements
============
diff --git a/design-documents/106-currency-conversion.rst b/design-documents/106-currency-conversion.rst
@@ -1,12 +1,12 @@
-DD 106:Currency Conversion
-###############
+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-15
+:Last substantive change: 2026-11-20
Summary
@@ -150,6 +150,105 @@ the outgoing payment has been created and the ILP packets have reached the excha
// Would be good to have an architecture diagram showing the payment and protocol flows.
Okay I will try to do it.
+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.
+
+.. 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.
+
+ @startuml
+ autonumber
+
+ participant "Wallet" as wallet
+ box "Source currency"
+ participant "Exchange A" as exa
+ participant "Adapter A" as ada
+ participant "Rhyza A" as rha
+ end box
+ box "Target currency"
+ participant "Rhyza B" as rhb
+ participant "Adapter B" as adb
+ participant "Exchange B" as exb
+ end box
+
+ == Legitimization and incoming payment ==
+
+ 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()
+
+ == Quote ==
+
+ wallet -> ada : triggerConversion(URL, wantedAmount)
+ ada -> rha : askQuote()
+ rha -> rha : CalculateVariable()
+ rha --> ada : sendQuote(amounts,\nvalidity, rate)
+ ada --> wallet : transferQuote(amounts, validity, rate)
+
+ == Deposit and ILP payment ==
+
+ wallet -> exa : depositCoins(coins)
+ wallet -> exb : getReserve(reserve_pub), 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)
+ deactivate exb
+
+ == Withdrawal ==
+
+ wallet -> exb : withdraw(reserve_pub, blindedCoins)
+ exb --> wallet : OK (blindSignatures)
+ @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.
+
+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.
+
+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.
+
+Withdrawal
+ The wallet withdraws coins of the target currency from its reserve at
+ Exchange B.
+
Test Plan
diff --git a/design-documents/images/098/promotions-user-flow.puml b/design-documents/images/098/promotions-user-flow.puml
@@ -1,16 +0,0 @@
-@startuml promotions-user-flow
-' Recipient-facing flow for DD 98 (Token Fountains for Promotions).
-' Rendered at Sphinx build time via sphinxcontrib.plantuml.
-!include ../../../images/taler-uml-style.iuml
-
-left to right direction
-
-rectangle "Scan the\npromotion" as scan #d3deff
-rectangle "Wallet receives\npromotional tokens" as receive #d3deff
-rectangle "Use a token\nat checkout" as use #d3deff
-rectangle "Receive the\ndiscount or benefit" as benefit #d3deff
-
-scan --> receive
-receive --> use
-use --> benefit
-@enduml
diff --git a/design-documents/index.rst b/design-documents/index.rst
@@ -118,4 +118,5 @@ documents. The lifecycle metadata in each document is authoritative. See
102-systemd-service-restart-policy
103-https-wallet-links
104-wire-gateway-management-API
+ 106-currency-conversion
999-template
diff --git a/images/taler-uml-style.iuml b/images/taler-uml-style.iuml
@@ -27,6 +27,9 @@ skinparam sequence {
DividerBackgroundColor #d9e3f9
DividerBorderColor #586a88
DividerFontColor #00134a
+ BoxBackgroundColor #ffffff
+ BoxBorderColor #586a88
+ BoxFontColor #00134a
}
skinparam note {