[taler-cashless2ecash] branch master updated: docs: fix diagrams according to the feedback

[gnunet]

This is an automated email from the git hooks/post-receive script.

joel-haeberli pushed a commit to branch master
in repository cashless2ecash.

The following commit(s) were added to refs/heads/master by this push:
     new eb8f6b2  docs: fix diagrams according to the feedback
eb8f6b2 is described below

commit eb8f6b2d75dec32f4a8be462484e21d0d1b349f2
Author: Joel-Haeberli <haebu@rubigen.ch>
AuthorDate: Tue Mar 26 21:41:48 2024 +0100

    docs: fix diagrams according to the feedback
---
 docs/content/architecture/overview.tex             |  40 +++++--
 docs/pictures/diagrams/c2ec.png                    | Bin 0 -> 110487 bytes
 docs/pictures/diagrams/nonce2ecash.png             | Bin 98987 -> 0 bytes
 .../diagrams/nonce2ecash_class_diagram.png         | Bin 62429 -> 0 bytes
 docs/pictures/diagrams/system_overview.png         | Bin 93245 -> 100725 bytes
 docs/thesis.pdf                                    | Bin 1571422 -> 1589959 
bytes
 specs/c2ec.plantuml                                |  47 ++++++++
 specs/nonce2ecash.plantuml                         | 133 ---------------------
 specs/system_overview.odg                          | Bin 26993 -> 28197 bytes
 9 files changed, 78 insertions(+), 142 deletions(-)

diff --git a/docs/content/architecture/overview.tex 
b/docs/content/architecture/overview.tex
index 731002a..edc5b24 100644
--- 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 proces [...]
+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
new file mode 100644
index 0000000..ad448d5
Binary files /dev/null and b/docs/pictures/diagrams/c2ec.png differ
diff --git a/docs/pictures/diagrams/nonce2ecash.png 
b/docs/pictures/diagrams/nonce2ecash.png
deleted file mode 100644
index 33dcf12..0000000
Binary files a/docs/pictures/diagrams/nonce2ecash.png and /dev/null differ
diff --git a/docs/pictures/diagrams/nonce2ecash_class_diagram.png 
b/docs/pictures/diagrams/nonce2ecash_class_diagram.png
deleted file mode 100644
index 5b71ff8..0000000
Binary files a/docs/pictures/diagrams/nonce2ecash_class_diagram.png and 
/dev/null differ
diff --git a/docs/pictures/diagrams/system_overview.png 
b/docs/pictures/diagrams/system_overview.png
index 33c6ed6..cbef44a 100644
Binary files a/docs/pictures/diagrams/system_overview.png and 
b/docs/pictures/diagrams/system_overview.png differ
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
index 017dbea..162a819 100644
Binary files a/docs/thesis.pdf and b/docs/thesis.pdf differ
diff --git a/specs/c2ec.plantuml b/specs/c2ec.plantuml
new file mode 100644
index 0000000..6c766e1
--- /dev/null
+++ 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
deleted file mode 100644
index ba2a214..0000000
--- a/specs/nonce2ecash.plantuml
+++ /dev/null
@@ -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
index 5a98be7..dac9bc7 100644
Binary files a/specs/system_overview.odg and b/specs/system_overview.odg differ

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.