commit efe1f8752b2921b1d013effdf57c55d8c65db3ec
parent 114f40cfc85eae3a0e2140a93b22e9f159af9ec3
Author: Joel-Haeberli <haebu@rubigen.ch>
Date: Sun, 9 Jun 2024 11:51:20 +0200
docs: enhance
Diffstat:
3 files changed, 30 insertions(+), 11 deletions(-)
diff --git a/docs/content/implementation/b-terminal.tex b/docs/content/implementation/b-terminal.tex
@@ -9,16 +9,35 @@ On the amount screen the terminal operator enters the amount to withdraw and cli
In the register parameters screen, a QR code is displayed, which must be scanned by the withdrawer using their wallet app. When the user scanned the QR Code and the terminal gets the withdrawal operation in state 'selected' from C2EC, the wallet has successfully registered its withdrawal parameters. In this case the terminal application changes to the authorization screen in which the withdrawing person must authorize the transaction using their credit card (or another supported payment mean). In any other case, the withdrawal operation is aborted and terminated. When the terminals backend sends the response of the authorization to the terminal, it sends the Terminals API of C2EC the confirmation request. This will start the confirmation process of the withdrawal immediately. If the confirmation request is successful, the terminal shows a summary of the transaction.
+% \begin{figure}[H]
+% \centering
+% \includegraphics[width=0.7\textwidth]{pictures/diagrams/terminal_flow.png}
+% \caption{The flow of the terminal app}
+% \label{fig-diagram-terminal-flow}
+% \end{figure}
+
+\newpage
+\KOMAoptions{paper=landscape,pagesize}
+\recalctypearea
+\thispagestyle{empty}
+\newgeometry{left=4cm, right=4cm, top=3cm, bottom=0cm}
+
\begin{figure}[H]
\centering
- \includegraphics[width=0.7\textwidth]{pictures/diagrams/terminal_flow.png}
+ \includegraphics[width=1.7\textwidth]{pictures/diagrams/terminal_flow.png}
\caption{The flow of the terminal app}
\label{fig-diagram-terminal-flow}
\end{figure}
+\restoregeometry
+\newpage
+\KOMAoptions{paper=portrait,pagesize}
+\recalctypearea
+
+
\subsection{Screens}
-The Application is implemented using jetpack compose \cite{app-jetpack-compose} and each of the screens described in \autoref{sec-wallee-withdrawal-flow} is implemented as composable screen. This allows to handle the entire withdrawal flow in one single activity and therefore makes state handling easier. For the summary a standalone activity is used. The state is bound to the activity and compose will make sure to rebuild the UI if values change. It also prevents illegal states and that different withdrawals interfere each other. The state is maintained in a view model as described by Android's documentation \cite{app-viewmodel}. The withdrawal activity handles the lifecycle of the view model instance and initializes the routing of the screens using Android's navigation controller as documented \cite{app-navigation}. The navigation integration of Android allows the declarative definition of the in-app routing and is defined at the creation of the withdrawal activity.
+The application is implemented using Jetpack Compose \cite{app-jetpack-compose} and each of the screens described in \autoref{sec-wallee-withdrawal-flow} is implemented as composable screen. This allows to handle the entire withdrawal flow in one single activity and therefore makes state handling easier. For the summary a standalone activity is used. The state is bound to the activity and compose will make sure to rebuild the UI if values change. It also prevents illegal states and that different withdrawals interfere each other. The state is maintained in a view model as described by Android's documentation \cite{app-viewmodel}. The withdrawal activity handles the lifecycle of the view model instance and initializes the routing of the screens using Android's navigation controller as documented \cite{app-navigation}. The navigation integration of Android allows the declarative definition of the in-app routing and is defined at the creation of the withdrawal activity.
\subsubsection{Start Screen}
@@ -32,8 +51,9 @@ When the app is started there will be two options for the user. The first option
\end{figure}
\subsubsection{Manage Screen}
+\label{sec-implementation-terminal-manage-screen}
-There are options and special functionalities which can be configured by the terminal operator. These operations are implemented in the manage screen of the app. The app allows to execute the final balance actions which will settle all authorized transactions of this specific terminal. The test transaction was used during the development to learn how the transaction is triggered. In the newest release it won't be part of the manage screen. The operator might want to test the implementation without having a wallet at hand. This can be done by enabling the wallet simulation. It will lead to the creation of a mocked reserve public key which will not be withdrawable by a wallet. Triggering a payment using the wallet simulation will lead to temporary loss of money (it will eventually be bounced and refunded through the Exchange when the reserve is closed). However, the fees charged will be gone. The wallet simulation should therefore only be used in a test environment. The last option allows the activation of instant settlement. This means that the final balance action will be triggered after each payment authorization. This is not enabled by default, because at the time of writing this document it was not clear if executing the final balance can cause additional costs to the operator.
+There are options and special functionalities which can be configured by the terminal operator. These operations are implemented in the manage screen of the app. The app allows to execute the final balance actions which will settle all authorized transactions of this specific terminal. The test transaction was used during the development to learn how the transaction is triggered. In the newest release it won't be part of the manage screen. The operator might want to test the implementation without having a wallet at hand. This can be done by enabling the wallet simulation. It will lead to the creation of a mocked reserve public key which will not be withdrawable by a wallet. Triggering a payment using the wallet simulation will lead to temporary loss of money (it will eventually be bounced and refunded through the Exchange when the reserve is closed). However, the fees charged will be gone. The wallet simulation should therefore only be used in a test environment. The last option allows the activation of instant settlement. This means that the final balance action will be triggered after each payment authorization.
\begin{figure}[H]
\centering
@@ -44,7 +64,7 @@ There are options and special functionalities which can be configured by the ter
\subsubsection{Choose Exchange Screen}
-When a new withdrawal is started, the user chooses the exchange to withdraw from. This allows the terminal to support withdrawals from various exchanges and therefore enhances the flexibility. When the user selected the exchange, the configuration of the exchange is loaded. This will define the currency of the withdrawal and tell the terminal where to reach the Terminals API of the C2EC server.
+When a new withdrawal is started, the user chooses the exchange to withdraw from (\autoref{fig-terminal-screen-choose-exchange}). This allows the terminal to support withdrawals from various exchanges and therefore enhances the flexibility. When the user selected the exchange, the configuration of the exchange is loaded. This will define the currency of the withdrawal and tell the terminal where to reach the Terminals API of the C2EC server.
\begin{figure}[H]
\centering
@@ -64,7 +84,7 @@ The amount screen in \autoref{fig-terminal-screen-amount} is used to ask the use
\label{fig-terminal-screen-amount}
\end{figure}
-In case the withdrawal amount is invalid, the withdrawal is not possible and an error shown to the customer.
+In case the withdrawal amount is invalid, the withdrawal is not possible and an error shown to the customer as depicted in \autoref{fig-terminal-screen-amount-invalid}.
\begin{figure}[H]
\centering
@@ -75,7 +95,7 @@ In case the withdrawal amount is invalid, the withdrawal is not possible and an
\subsubsection{Parameter Registration Screen}
-After entering the amount, a QR code containing the taler withdraw URI is displayed. The customers scan it using their Taler wallet app and register the parameters for the withdrawal (namely the reserve public key). The withdrawal can be aborted on the screen. This step is important to make sure, that the customer has a working Taler wallet installed and allows them to accept the terms of service for the respective exchange if they did not yet registered the exchange on their wallet. Once this is done the authorization can be started by clicking on the \textit{authorize} button. When clicking on the \textit{abort} button the withdrawal is aborted.
+After entering the amount, a QR code containing the taler withdraw URI is displayed (\autoref{fig-terminal-screen-register-parameters}). The customers scan it using their Taler wallet app and register the parameters for the withdrawal (namely the reserve public key). The withdrawal can be aborted on the screen. This step is important to make sure, that the customer has a working Taler wallet installed and allows them to accept the terms of service for the respective exchange if they did not yet registered the exchange on their wallet. Once this is done the authorization can be started by clicking on the \textit{authorize} button. When clicking on the \textit{abort} button the withdrawal is aborted.
\begin{figure}[H]
\centering
@@ -97,7 +117,7 @@ The authorization uses the \textit{Android Till SDK} \cite{wallee-till-sdk} to a
\subsubsection{Summary Screen}
-When the transaction was processed a summary of the transaction is displayed to the customer.
+When the transaction was processed a summary of the transaction is displayed to the customer (\autoref{fig-terminal-screen-authorized}).
\begin{figure}[H]
\centering
@@ -108,7 +128,7 @@ When the transaction was processed a summary of the transaction is displayed to
\subsubsection{Failure Screen}
-To give the customer a feedback when anything goes wrong or when the withdrawal is aborted, the terminal will always show the rudimentary abort screen. This gives the users feedback what happened. What can go wrong and how the terminal acts upon these failures is described in \autoref{sec-implementation-abort-handling}.
+To give the customer a feedback when anything goes wrong or when the withdrawal is aborted, the terminal will always show the rudimentary abort screen (\autoref{fig-terminal-screen-abort}). This gives the users feedback what happened. What can go wrong and how the terminal acts upon these failures is described in \autoref{sec-implementation-abort-handling}.
\begin{figure}[H]
\centering
@@ -138,7 +158,6 @@ Depending on the operator of the Taler Exchange it might be possible to somehow
\subsection{Fulfilling Transactions}
-To achieve finality and real-time behaviour of the withdrawal flow, the transaction must be forcefully transitioned to the \textit{fulfill} state in the Wallee backend. For this reason, the payments are not only authorized but also automatically completed in the background. After the successful completion, the payment can be directly settled and with this guarantee the finality property. If the completion fails, the withdrawal will be aborted.
-% TODO Wallee Feedback einbauen
+To achieve finality and real-time behaviour of the withdrawal flow, the transaction must be forcefully transitioned to the \textit{fulfill} state in the Wallee backend. For this reason, the payments are not only authorized but also automatically completed in the background. After the successful completion, the payment can be directly settled and with this guarantee the finality property. If the completion fails, the withdrawal will be aborted. Wallee was asked if the instant settlement using the final balance call has cost effects for the merchant. It appears that this is not the case. But Wallee wrote it is not the idea to trigger the final balance every minute. Because of this, the instant settlement is deactivated by default and the terminal operator might decide on their own if they want to activate it or not. Instant settlement can be activated in the manage screen as described in \autoref{sec-implementation-terminal-manage-screen}.
\newpage
\ No newline at end of file
diff --git a/docs/content/results/discussion.tex b/docs/content/results/discussion.tex
@@ -14,7 +14,7 @@ Towards the end of the implementation it became obvious that a simple authorizat
Our work makes a faster uptake of GNU Taler possible. Potential customers will not need a bank account or other things to withdraw digital cash. They can now use C2EC and the terminal app for Wallee to withdraw digital cash using GNU Taler.
-\section{Limitations and Future Work}
+\section{Limitations And Future Work}
Due to the short time available during the thesis, features and integrations are missing which can make C2EC even more valuable. Because of this I provide a list of future work. Maybe there are other students or collaborators who want to join in and add their features to the existing code. The list might not be complete and any new ideas are appreciated. I splitted the list into the list of extensions and improvements. The improvements list also shows some limitations of the implementation done during the thesis.
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
Binary files differ.
