commit eb8f6b2d75dec32f4a8be462484e21d0d1b349f2
parent b186387b512b941c080fb123daa4eed193d807ef
Author: Joel-Haeberli <haebu@rubigen.ch>
Date: Tue, 26 Mar 2024 21:41:48 +0100
docs: fix diagrams according to the feedback
Diffstat:
9 files changed, 78 insertions(+), 142 deletions(-)
diff --git a/docs/content/architecture/overview.tex b/docs/content/architecture/overview.tex
@@ -7,27 +7,49 @@
\label{fig-logo-components}
\end{figure}
-The component diagram shows the components involved by the withdrawal using the terminal. Besides the credit card owned by the user, two systems are involved and within each system two components are required to fulfill the task. The Taler ecosystem which represents the Taler Wallet and the Taler Exchange (C2EC is a part of the Exchange) involved in the withdrawal process. In the Terminal system, the terminal and the backend system of the terminal manufacturer are leveraged in the process. The numbers in the diagrams are picked up by the description of the process further down.
+The component diagram shows the components involved by the withdrawal using the terminal. Besides the credit card owned by the user, two systems are involved and within each system two components are required to fulfill the task. The Taler ecosystem which represents the Taler Wallet and the Taler Exchange (C2EC is a part of the Exchange) involved in the withdrawal process. In the Terminal system, the terminal and the backend system of the terminal manufacturer are leveraged in the process.
\section{Process}
\begin{figure}[h]
\centering
- \includegraphics[width=0.7\textwidth]{pictures/diagrams/nonce2ecash.png}
- \caption{Process of a withdrawal using a credit card}
- \label{fig-diagram-all-sequence}
+ \includegraphics[width=0.7\textwidth]{pictures/diagrams/system_overview.png}
+ \caption{Diagram of included components and their interactions}
+ \label{fig-diagram-all-components}
\end{figure}
-The diagram in \autoref{fig-diagram-all-sequence} shows the high level flow to withdraw digital cash using the credit card terminal and Taler. It shows when the components of \autoref{fig-diagram-all-components} interact with each other. It shows the implementation of the flow. Terminal, Wallet and Exchange are linked leveraging a \textit{wopid} initially generated by the terminal and presented to the Exchange by the withdrawing Wallet accompanied by a reserve public key.
+The \autoref{fig-diagram-all-components} shows a high level overview of the components involved and how they interact. The numbers in the diagrams are picked up by the description of the steps what is done between the different components:
+
+\begin{enumerate}
+ \item Wallee Terminal requests to be notified when parameters are \textit{selected} by C2EC.
+ \item The Wallet scans the QR code at the Terminal.
+ \item The Wallet registers a reserve public key and the \textit{wopid}.
+ \item The Bank-Integration API of C2EC notifies the Terminal, that the parameters were selected.
+ \item The Terminal accepts the credit card of the customer.
+ \item The Terminal triggers the payment at the Wallee Backend.
+ \item The Terminal receives the result of the payment.
+ \begin{enumerate}
+ \item successful
+ \item unsuccessful
+ \end{enumerate}
+ \item The Terminal sends the payment notification to the Bank Integration API of C2EC.
+ \item The C2EC component approves the payment by requesting the transaction of the Wallee Backend.
+ \item C2EC updates the database by either setting the status of the withdrawal operation to \textit{confirmed} or \textit{abort} (depending on the response of the Wallee Backend).
+ \item Now decoupled from each other the Exchange-Wirewatch asks the Wire Gateway API of C2EC for a list of transactions and the Bank-Integration API sends a \textit{confirmed} or \textit{abort} message to the wallet.
+ \item The Wallet asks the Exchange to be notified, when a reserve with the reserve public key becomes available.
+ \item The Exchange can send the digital cash back to the Wallet.
+\end{enumerate}
\begin{figure}[h]
\centering
- \includegraphics[width=0.7\textwidth]{pictures/diagrams/system_overview.png}
- \caption{Diagram of included components and their interactions}
- \label{fig-diagram-all-components}
+ \includegraphics[width=0.7\textwidth]{pictures/diagrams/c2ec.png}
+ \caption{Process of a withdrawal using a credit card}
+ \label{fig-diagram-all-sequence}
\end{figure}
-The process requires three parties interacting with each other. The Terminal, the Wallet and the Exchange must therefore interact with each other. In this section the highlevel process as showed in \autoref{fig-diagram-all-sequence} is explained.
+The diagram in \autoref{fig-diagram-all-sequence} shows the high level flow to withdraw digital cash using the credit card terminal and Taler. It shows when the components of \autoref{fig-diagram-all-components} interact with each other. It shows the implementation of the flow. Terminal, Wallet and Exchange are linked leveraging a \textit{wopid} initially generated by the terminal and presented to the Exchange by the withdrawing Wallet accompanied by a reserve public key.
+
+The process requires the Terminal, the Wallet, the C2EC component and the Exchange which interact with each other. In this section the highlevel process as showed in \autoref{fig-diagram-all-sequence} is explained.
\subsection{The Terminal}
diff --git a/docs/pictures/diagrams/c2ec.png b/docs/pictures/diagrams/c2ec.png
Binary files differ.
diff --git a/docs/pictures/diagrams/nonce2ecash.png b/docs/pictures/diagrams/nonce2ecash.png
Binary files differ.
diff --git a/docs/pictures/diagrams/nonce2ecash_class_diagram.png b/docs/pictures/diagrams/nonce2ecash_class_diagram.png
Binary files differ.
diff --git a/docs/pictures/diagrams/system_overview.png b/docs/pictures/diagrams/system_overview.png
Binary files differ.
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
Binary files differ.
diff --git a/specs/c2ec.plantuml b/specs/c2ec.plantuml
@@ -0,0 +1,47 @@
+@startuml
+
+actor User as "User (with Credit Card)"
+participant Wallet
+participant C2EC
+participant Exchange
+participant TerminalBackend as "Terminal Backend"
+participant Terminal
+actor TerminalOwner as "Terminal Owner"
+
+Terminal -> Terminal: configures Exchange (configured, overwritable)
+User -> TerminalOwner: "Hi, I want to withdraw 20 coins with my Credit Card"
+TerminalOwner -> Terminal: start Taler Withdrawal Application and enters amount
+Terminal -> Terminal: Generate wopid
+Terminal -> C2EC: (1) Start long polling (wopid)
+activate C2EC
+Terminal -> Terminal: Create QR code (Wopid, Exchange, Amount)
+Terminal -> Wallet: (2) Scan QR code
+activate Wallet
+Wallet -> Wallet: If ToS for Exchange not yet accepted, do here.
+Wallet -> Wallet: Create Reserve Key-Pair
+Wallet -> C2EC: (3) Send Wopid, ReservePublicKey
+Wallet -> C2EC: Start long polling (wopid)
+C2EC -> C2EC: Create mapping (Nonce, ReservePublicKey, Amount)
+C2EC --> Terminal: (4) End long polling (selected)
+deactivate C2EC
+Terminal -> Terminal: Show summary with Fees
+User -> Terminal: (5) Approve and present card
+Terminal -> TerminalBackend: (6) Execute Payment
+TerminalBackend --> Terminal: (7) Payment response (success/failure)
+alt Payment successful
+ Terminal -> C2EC: (8) Send PaymentNotification (SUCCESS)
+ C2EC -> C2EC: Change Mapping state to confirmed
+ C2EC -> TerminalBackend: (9) Verify payment
+ C2EC -> C2EC: (10) set status to confirmed or abort
+ C2EC -> Wallet: (11) notify Wallet that payment has been processed.
+ Exchange -> C2EC: (11) get transaction history
+ Exchange -> Exchange: Create Reserve with amount and reserve public key.
+ Wallet -> Exchange: (12) withdraw when reserve is created
+ Wallet -> Exchange: (13) Withdraw digital cash
+else Payment not successful
+ Terminal -> C2EC: (8) Send PaymentNotification (UNSUCESSFUL)
+ C2EC -> C2EC: Remove entry in N2C mapping table.
+ C2EC --> Wallet: End long polling (abort)
+ Wallet -> Wallet: Remove Wopid and Public Key
+end
+@enduml
diff --git a/specs/nonce2ecash.plantuml b/specs/nonce2ecash.plantuml
@@ -1,133 +0,0 @@
-Flow:
-1. Terminal asks to choose Exchange
-
-I think this might be part of the terminal *settings*, or maybe optional (to change default).
-But forcing this every time seems bad UX.
- -> agree, assuming exchange will seldomly be changed and be kind of static.
-
-2. Terminal asks to choose Denomination
-
-Definitively not. Each exchange defines the currency and denominations, nothing needed here.
-What we do probably need is to get the fee structure here (/config, /keys) and confirm that
-the exchange is currently running.
- -> ok i did get that wrong about how the exchange works. I assumed an exchange is able to cashout various denominations but only allows one to be payed with.
-
-3. Terminal generates a Nonce
-4. Terminal starts long polling activity at Exchange including the generated Nonce
-
-For now, this is OK. But when implementing, we probably want to distinguish the
-(legacy) exchange "core" logic, and the cashless2ecash-specific extensions of the
-exchange. So this part of the architecture will need a more precise look *later*.
- -> sorry, I don't understand this comment
-
-5. Terminal creates QR code including Nonce and Exchange
-6. Wallet scans QR code
-
-Unless user already did so, this might be the place to show the exchange Terms of Service
-and have the user accept them!
- -> Can we tell the user, that by scanning the QR code, the user accepts the Terms of Service (sure a link or similar is presented to the user)
- or does the user actively needs to press an ok button or set a cross?
-
-7. Wallet creates a Reserve Key-Pair
-8. Wallet sends Nonce and ReservePublicKey to specified Exchange
-9. The Wallet starts long polling at Exchange to learn when payment was processed
-10. Exchange creates a mapping from the Nonce to the ReservePublicKey
-11. Exchange ends long polling from step 4 by sending N2C_ESTABLISHED
-12. Terminal lets User enter amount to withdraw
-
-Why this late? I think the user has to do too much here. It would be better if
-the *staff* (optionally) selected the exchange and entered the amount at the
-start. Then the user _only_ has to scan the QR code and swipe the card. That's
-a common process at stores (cashier provides amount, you scan/swipe). Plus QR
-scan and card swipe are steps the user is familiar with. Having the user actually
-do data entry seems like a usability problem and security risk. And we also don't
-want the devices to be passed too much back and forth (and possibly not even have
-a user-accessible keyboard). So scan + swipe should be all, and exchange-selection
-and amount should be with the staff earlier.
- -> ok get that, makes sense to me. User will only scan QR code and present the card. TerminalOwner will enter amount.
-
-13. Terminal shows summary with calculated Fees
-14. User approves and presents card
-15. Terminal executes Payment using the TerminalBackend
-16. TerminalBackend responds if payment was successful.
-16.1 If payment was successful Terminal does:
-16.1.1 Send OK to Exchange (including nonce)
-
-Probably should send more than the OK+nonce, like the full 'proof' of payment,
-so that ideally exchange doesn't even have to talk to TerminalBackend anymore.
- -> so we dont double check with the TerminalBackend that the payment went through if the terminal is able to respond? Isn't this the idea of the TerminalBackend involvment, that we only trust the TerminalBackend to present payment guarantees to the exchange?
- -> so this would lead to two alternative flows, depending on if the terminal provider responds to the exchange or not.
- -> sub-flow one: Terminal responds inside defined timeout. we trust the response of the terminal.
- -> sub-flow two: Terminal fails to respond inside defined timeout. exchange asks terminal TerminalBackend for payment information.
-
-16.1.2 Exchange changes Mapping table state to N2C_PAYED
-16.1.3 Exchange checks TerminalBackend and asserts that the payment went through (Also setting the amount of money in the mapping table assuring the Wallet cannot trick the Exchange. Beware of the fees!!).
-
-We should do this automatically (independent of the 16.1.1 message that might be lost);
-at least do a job in the background to check periodically in case 16.1.1 and 16.2.2
-do not happen in a timely fashion.
- -> ok makes sense long polling or time based after some timeout (at the terminal backend)?
-
-16.1.4 Exchange ends long polling from step 9 by sending N2C_PAYED and the Nonce to the wallet
-16.1.5 Wallet executes a AcceptManualWitdrawalOp (which eventually leads to Exchange signed coins in the wallet of the user)
-
-Eh, what do you mean by "manual" here? Wallet should probably simply "Execute withdrawal operation".
- -> AcceptManualWithdrawalOp is a type in the Wallet Core implementation. I was looking up what operation could be used and this operation seemed the right op to me.
-
-16.2 If payment was not successful Terminal does:
-16.2.1 Send NOK to Exchange (including nonce)
-16.2.2 Exchange changes Mapping table state to N2C_PAYMENT_FAILED
-
-Is there a reason to keep the mapping table state? Why not just delete the row?
- -> i was thinking about regulatory/liability reasons (that the exchange can proof payment did not went through). But if that's not needed, we can delete the entry here.
-
-16.2.3 Exchange ends long polling from step 9 by sending N2C_PAYMENT_FAILED and the Nonce to the wallet
-
-I see no need to send the nonce back to the wallet here.
- -> get it -> it's a long polling. so the process on the wallet knows which nonce it is dealing with.
-
-16.2.4 The Wallet removes nonce and public key from internal mapping table.
-
-@startuml
-
-actor User as "User (with Credit Card)"
-participant Wallet
-participant Exchange
-participant TerminalBackend as "Terminal Backend"
-participant Terminal
-actor TerminalOwner as "Terminal Owner"
-
-Terminal -> Terminal: configures Exchange (configured, overwritable)
-User -> TerminalOwner: "Hi, I want to withdraw 20 coins with my Credit Card"
-TerminalOwner -> Terminal: start Taler Withdrawal Application and enters amount
-Terminal -> Terminal: Generate Nonce
-Terminal -> Exchange: Start long polling (Nonce)
-activate Exchange
-Terminal -> Terminal: Create QR code (Nonce, Exchange, Amount)
-Terminal -> Wallet: Scan QR code
-activate Wallet
-Wallet -> Wallet: If ToS for Exchange not yet accepted, do here.
-Wallet -> Wallet: Create Reserve Key-Pair
-Wallet -> Exchange: Send Nonce, ReservePublicKey
-Wallet -> Exchange: Start long polling
-Exchange -> Exchange: Create mapping (Nonce, ReservePublicKey, Amount)
-Exchange --> Terminal: End long polling (N2C_ESTABLISHED)
-deactivate Exchange
-Terminal -> Terminal: Show summary with Fees
-User -> Terminal: Approve and present card
-Terminal -> TerminalBackend: Execute Payment
-TerminalBackend --> Terminal: Payment response (success/failure)
-alt Payment successful
- Terminal -> Exchange: Send PaymentNotification (SUCCESS)
- Exchange -> Exchange: Change Mapping state to N2C_PAYED
- Exchange -> TerminalBackend: Verify payment\nSet payed amount in mapping table of Exchange
- Exchange -> Exchange: Create Reserve with amount and reserve public key.
- Exchange --> Wallet: End long polling (N2C_RESERVE_CREATED, Nonce)
- Wallet -> Exchange: Execute Withdrawal (AcceptManualWithdrawalOp)
-else Payment not successful
- Terminal -> Exchange: Send PaymentNotification (UNSUCESSFUL)
- Exchange -> Exchange: Remove entry in N2C mapping table.
- Exchange --> Wallet: End long polling (N2C_PAYMENT_FAILED, Nonce)
- Wallet -> Wallet: Remove Nonce and Public Key
-end
-@enduml
diff --git a/specs/system_overview.odg b/specs/system_overview.odg
Binary files differ.
