taler-docs

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

commit d2413d96d398cf8da60323d45072177327b34495
parent 3368f2a93035c677a0004f6b7ec8a55635f8c5f3
Author: Christian Grothoff <christian@grothoff.org>
Date:   Fri, 20 Nov 2026 22:58:09 +0100

work on DD 106

Diffstat:
MREADME | 9+++++++++
Mconf.py | 22++++++++++++++++++++--
Mdesign-documents/098-token-fountains.rst | 16++++++++++++++--
Mdesign-documents/106-currency-conversion.rst | 105++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
Ddesign-documents/images/098/promotions-user-flow.puml | 16----------------
Mdesign-documents/index.rst | 1+
Mimages/taler-uml-style.iuml | 3+++
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 {