[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-cashless2ecash] branch master updated: docs: enhance introduction
|
From: |
gnunet |
|
Subject: |
[taler-cashless2ecash] branch master updated: docs: enhance introduction and architecture |
|
Date: |
Sat, 25 May 2024 17:02:33 +0200 |
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 19bb782 docs: enhance introduction and architecture
19bb782 is described below
commit 19bb7824c5fa6bc73ffe299ede23d22c8cafaac3
Author: Joel-Haeberli <haebu@rubigen.ch>
AuthorDate: Sat May 25 17:02:25 2024 +0200
docs: enhance introduction and architecture
---
docs/content/architecture/c2ec.tex | 114 ++++-------------------------
docs/content/architecture/overview.tex | 63 ++++++++--------
docs/content/architecture/wallee.tex | 2 +-
docs/content/architecture/wallet.tex | 14 ----
docs/content/implementation/b-terminal.tex | 14 ++--
docs/content/introduction/goal.tex | 17 ++++-
docs/content/introduction/introduction.tex | 22 +++---
docs/pictures/diagrams/c2ec.png | Bin 96069 -> 89825 bytes
docs/pictures/diagrams/system_overview.png | Bin 99686 -> 77078 bytes
docs/thesis.pdf | Bin 2112850 -> 2112071 bytes
docs/thesis.tex | 1 -
poster/cashless2ecash_poster.pdf | Bin 808840 -> 808840 bytes
poster/cashless2ecash_poster.tex | 3 +-
simulation/c2ec-simulation | Bin 8315978 -> 8315978 bytes
specs/c2ec.plantuml | 30 ++++----
specs/system_overview.odg | Bin 28733 -> 27766 bytes
16 files changed, 94 insertions(+), 186 deletions(-)
diff --git a/docs/content/architecture/c2ec.tex
b/docs/content/architecture/c2ec.tex
index b2ea4cc..a82962f 100644
--- a/docs/content/architecture/c2ec.tex
+++ b/docs/content/architecture/c2ec.tex
@@ -1,6 +1,6 @@
\section{C2EC}
-The C2EC (\textbf{c}ashless\textbf{2ec}ash) component is the central
coordination component in the cashless withdrawal of digital cash using Taler.
It initializes the parameters and mediates between the different stakeholders
of a withdrawal, which finally allows the customer to withdraw digital cash
from a reserve owned by the \textit{Exchange}. Therefore C2EC provides API
which can be integrated and used by the \textit{Terminal}, \textit{Wallet} and
the \textit{Exchange}.
+The \textbf{c}ashless\textbf{2ec}ash (C2EC) component is the central
coordination component in the cashless withdrawal of digital cash using Taler.
It initializes the parameters and mediates between the different stakeholders
of a withdrawal, which finally allows the customer to withdraw digital cash
from a reserve owned by the \textit{Exchange}. Therefore C2EC provides API
which can be integrated and used by the \textit{Terminal}, \textit{Wallet} and
the \textit{Exchange}.
The API of the C2EC (cashless2ecash) component handles the flow from the
creation of a C2EC mapping to the creation of the reserve. For the integration
into the Taler ecosystem, C2EC must implement the Taler Wirewatch Gateway API
\cite{taler-wire-gateway-api} and the Taler Bank Integration API
\cite{taler-bank-integration-api}.
@@ -38,79 +38,32 @@ All components involved in the withdrawal process must
interact with the C2EC co
\subsubsection{Terminals API}
-That terminal can initiate and serve withdrawals in Taler, the Terminals API
\cite{taler-terminal-api} is implemented, which mirrors all actions of a
terminal at the C2EC component.
+That terminal can initiate and serve withdrawals in Taler, the Terminals API
\cite{taler-terminal-api} is implemented, which mirrors all actions of a
terminal at the C2EC component. This covers following endpoints:
-\textbf{Config}
-\begin{itemize}
- \item \textbf{Method:} GET
- \item \textbf{Endpoint:} /config
- \item \textbf{Description:} Return the protocol version and configuration
information about the C2EC API.
- \item \textbf{Response:} HTTP status code 200 OK. The exchange responds with
a \texttt{TerminalsConfig} object.
- \item \textbf{Consumers:} Terminals who want to use the API and therefore
want to load the config of the instance.
-\end{itemize}
-
-\textbf{Withdrawals}
\label{sec-architecture-c2ec-setup-wopid}
-\begin{itemize}
- \item \textbf{Method:} POST
- \item \textbf{Endpoint:} /withdrawals
- \item \textbf{Description:} Register a withdrawal operation at C2EC.
- \item \textbf{Response:} HTTP status code 200 OK. The \textit{WOPID}
generated by C2EC. On any other status code, terminate the withdrawal.
- \item \textbf{Consumers:} Terminals who want to initiate a withdrawal
operation.
-\end{itemize}
-
-\textbf{Status of the withdrawal operation}
-\begin{itemize}
- \item \textbf{Method:} GET
- \item \textbf{Endpoint:} /withdrawals/\$WOPID
- \item \textbf{Description:} Query information about a withdrawal operation,
identified by the \texttt{WOPID}.
- \item \textbf{Response:} HTTP status code 200 OK and body containing a
\texttt{BankWithdrawalOperationStatus} object or 404 Not found.
- \item \textbf{Consumers:} The API is used by the \textit{Terminal} and
\textit{Taler Wallet} to retrieve information about the current state of the
withdrawal operation. The API allows long-polling and can therefore be used by
the consumer to be updated if the status of the withdrawal operation changes.
-\end{itemize}
-\textbf{Check transaction}
-\begin{itemize}
- \item \textbf{Method:} POST
- \item \textbf{Endpoint:} /withdrawals/\$WOPID/check
- \item \textbf{Description:} Notifies C2EC about an executed payment for a
specific withdrawal.
- \item \textbf{Request:} The request body contains a
\texttt{WithdrawalConfirmationRequest} object.
- \item \textbf{Response:} HTTP status code 204 No content, 400 Bad request,
404 Not found, or 500 Internal Server error.
- \item \textbf{Consumers:} The API is used by the \textit{Terminal} to notify
the C2EC component that a payment was made and to give the C2EC component
information about the payment itself (e.g. the provider specific transaction
identifier or optional fees).
-\end{itemize}
+\begin{enumerate}
+ \item Config (/config)
+ \item Withdrawal setup (/withdrawals)
+ \item Status of the withdrawal (/withdrawals/\$WOPID)
+ \item Confirmation Request (/withdrawals/\$WOPID/check)
+ \item Terminal side abort (/withdrawals/\$WOPID/abort)
+\end{enumerate}
\textbf{Fees}
-An important aspect of the withdrawal flow using third party providers are the
fees. When the withdrawal operation is not supplied by some exchanges as
standard service, the provider possibly wants to charge fees to the customer in
order to make a profit. The provider might decide to delegate those fees to the
customer and therefore fees can be sent to the C2EC component through the
\textit{check} API specified above. It's also possible that the service of
withdrawing cash through a thir [...]
+An important aspect of the withdrawal flow using established third party
providers are the fees. When the withdrawal operation is not supplied by some
exchanges as standard service, the provider possibly wants to charge fees to
the customer in order to make a profit and cover its costs. It is likely that
these costs are rolled over to the customer in form of fees. This means that a
terminal must have the capability to inform the Terminals API about fees. This
can be achieved through the [...]
\begin{quote}
- Die Händler zahlen jedoch für den Cashback-Service bereits Gebühren an
+ \textit{de:}Die Händler zahlen jedoch für den Cashback-Service bereits
Gebühren an
die Banken. Aktuell sind es laut EHI im Schnitt 0,14 Prozent, insgesamt
waren das 2023 rund 17,2 Millionen Euro. \cite[Crefeld, ZEIT]{zeit-cashback}
\end{quote}
-\textbf{Terminal abortion}
-\begin{itemize}
- \item \textbf{Method:} DELETE
- \item \textbf{Endpoint:} /withdrawals/\$WOPID/abort
- \item \textbf{Description:} Aborts the withdrawal specified by the
\texttt{WOPID}.
- \item \textbf{Request:} The request body contains a
\texttt{WithdrawalConfirmationRequest} object.
- \item \textbf{Response:} HTTP status code 204 No content, 400 Bad request,
404 Not found, or 500 Internal Server error.
- \item \textbf{Consumers:} The API is used by the \textit{Terminal} to notify
the C2EC component that a payment was made and to give the C2EC component
information about the payment itself (e.g. the provider specific transaction
identifier or optional fees).
-\end{itemize}
-
\subsubsection{Taler Bank Integration API}
Withdrawals by the \textit{Wallet} with a C2EC are based on withdrawal
operations which register a reserve public key at the C2EC component. The
provider must first create a unique identifier for the withdrawal operation
(the \texttt{WOPID}) to interact with the withdrawal operation (as described in
\autoref{sec-architecture-c2ec-setup-wopid}) and eventually withdraw digital
cash using the \textit{Wallet}. The withdrawal operation API is an
implementation of the \textit{Bank Integration [...]
-\textbf{Config}
-\begin{itemize}
- \item \textbf{Method:} GET
- \item \textbf{Endpoint:} /config
- \item \textbf{Description:} Return the protocol version and configuration
information about the C2EC API.
- \item \textbf{Response:} HTTP status code 200 OK. The exchange responds with
a \texttt{C2ECConfig} object.
- \item \textbf{Consumers:} Wallets who want to use the API and therefore want
to load the config of the instance.
-\end{itemize}
-
\subsection{Taler Wirewatch Gateway API}
The Taler Wirewatch Gateway \cite{taler-wire-gateway-api} must be implemented
in order to capture incoming transactions and allow the withdrawal of digital
cash. The specification of the Taler Wirewatch Gateway can be found in the
official Taler documentation \cite{taler-wire-gateway-api}.
@@ -119,43 +72,6 @@ The wirewatch gateway helps the Exchange communicate with
the C2EC component usi
For C2EC not all endpoints of the Wire Gateway API are needed. Therefore the
endoints which are not needed will be implemented but always return http status
code 400 with explanatory error details as specified by the specification.
-\textbf{Config}
-\begin{itemize}
- \item \textbf{Method:} GET
- \item \textbf{Endpoint:} /config
- \item \textbf{Description:} Returns a \texttt{WireConfig} object with
configuration information about the Wirewatch Gateway API of the C2EC component.
- \item \textbf{Response:} HTTP status code 200 OK and the wirewatch gateway
configuration
- \item \textbf{Consumers:} Components who want to use the API and therefore
want to load the config of the instance.
-\end{itemize}
-
-\textbf{Transfer}
-\begin{itemize}
- \item \textbf{Method:} POST
- \item \textbf{Endpoint:} /transfer
- \item \textbf{Description:} Allows the \textit{Exchange} to make a
transaction. This API is used in case of a refund. The transfer will therefore
be pointed towards a provider specific payto-address
(\texttt{payto://wallee-transaction} in case of Wallee).
- \item \textbf{Request:} The request contains a \texttt{TransferRequest}
object.
- \item \textbf{Response:} HTTP status code 200 OK. The exchange responds with
a \texttt{TransferResponse} object.
- \item \textbf{Consumers:} The \textit{Exchange Wirewatch} who wants to
transfer money using C2EC.
-\end{itemize}
-
-\textbf{History of incoming transactions}
-\begin{itemize}
- \item \textbf{Method:} GET
- \item \textbf{Endpoint:} /history/incoming
- \item \textbf{Description:} Returns a list of transactions which were
recently created in the C2EC component. In case of C2EC, this are withdrawal
operations which are confirmed and a reserve can therefore be created by the
exchange.
- \item \textbf{Response:} HTTP status code 200 OK. The exchange responds with
a \texttt{C2ECConfig} object.
- \item \textbf{Consumers:} The \textit{Exchange Wirewatch} who will create
the reserve which then can be withdrawn by the \textit{Taler Wallet}.
-\end{itemize}
-
-\textbf{History of outgoing transactions}
-\begin{itemize}
- \item \textbf{Method:} GET
- \item \textbf{Endpoint:} /history/outgoing
- \item \textbf{Description:} Returns a list of transfers which were executed
by the C2EC component.
- \item \textbf{Response:} HTTP status code 200 OK and a list of outgoing
transfers.
- \item \textbf{Consumers:} The \textit{Exchange Wirewatch} who will create
the reserve which then can be withdrawn by the \textit{Taler Wallet}.
-\end{itemize}
-
\subsection{C2EC Entities}
\label{sec-architecture-entities}
@@ -174,7 +90,7 @@ Entity displayed in \autoref{fig-erd-withdrawal} represents
the withdrawal proce
\subsubsection{Relationships}
\label{sec-architecture-entities-relationships}
-The structure of the three entities forms a tree which is rooted at the
terminal provider. Each provider can have many terminals and each terminal can
have many withdrawals. The reverse does not apply. A withdrawal does always
belong to exactly one terminal and a terminal is always linked to exactly one
provider. These relations are installed by using foreign keys, which link the
sub-entities (Terminal and Withdrawal) to their corresponding owners (Provider
and Terminal). A provider owns [...]
+The structure of the three entities form a tree which is rooted at the
terminal provider. Each provider can have many terminals and each terminal can
have many withdrawals. The reverse does not apply. A withdrawal does always
belong to exactly one terminal and a terminal is always linked to exactly one
provider. These relations are installed by using foreign keys, which link the
sub-entities (Terminal and Withdrawal) to their corresponding owners (Provider
and Terminal). A provider owns [...]
\begin{figure}[h]
\centering
@@ -184,12 +100,12 @@ The structure of the three entities forms a tree which is
rooted at the terminal
\end{figure}
\section{Payto wallee-transaction extension}
-RFC 8905 \cite{rfc8905} specifies a URI scheme (complying with RFC 3986
\cite{rfc3986}), which allows to address a creditor with theoretically any
protocol that can be used to pay someone (such as IBAN, BIC etc.) in a
standardized way. Therefore it introduces a registry which holds the specific
official values of the standard. The registry is supervised by the GANA (GNUnet
Assigned Numbers Authority) \cite{gnunet-gana}.
+RFC 8905 \cite{rfc8905} specifies a URI scheme (complying with RFC 3986
\cite{rfc3986}), which allows to address a creditor with theoretically any
protocol that can be used to pay someone (such as IBAN, BIC etc.) in a
standardized way. It introduces a registry which holds the specific official
values of the standard. The registry is supervised by the GANA (GNUnet Assigned
Numbers Authority) \cite{gnunet-gana}.
-In case a refund becomes necessary, which might occur if a credit card
transaction does not succeed, a new \textit{target type} called
\textit{wallee-transaction} is registered. It takes a transaction identifier as
\textit{target identifier} which identifies the transaction for which a refund
process shall be triggered. The idea is that the handler of the payto URI is
able to deduct the transaction from the payto-uri and trigger the refund
process.
+In case a refund becomes necessary, which might occur if a transaction does
not succeed or a reserve is not withdrawn within the specified time, a new
\textit{target type} called \textit{wallee-transaction} is registered. It takes
a transaction identifier as \textit{target identifier} which identifies the
transaction for which a refund process shall be triggered. The idea is that the
handler of the payto URI is able to deduct the transaction from the payto-uri
and trigger the refund process.
\subsection{Payto refund using Wallee}
Wallee allows to trigger refunds using the Refund Service of the Wallee
backend. The service allows to trigger a refund given a transaction identifier.
Therefore the C2EC component can trigger the refund using the refund service if
needed. The payto-uri retrieved as debit account by the wire gateway API, is
leveraged to delegate the refund process to the Wallee Backend using the Refund
Service and parsing the transaction identifier of the payto-uri.
\subsection{Extensibility}
-The flow is extensible and other providers like Wallee might be added. They
must therefore register their own refund payto-uri (if needed) with the GANA
and then the refund process can be implemented likewise.
+The flow is extensible and other providers like Wallee might be added. They
might want to register their own refund payto-uri (if needed) with the GANA and
then the refund process can be implemented likewise.
diff --git a/docs/content/architecture/overview.tex
b/docs/content/architecture/overview.tex
index 39d5b8f..0a05188 100644
--- a/docs/content/architecture/overview.tex
+++ b/docs/content/architecture/overview.tex
@@ -7,7 +7,7 @@
\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 component diagram shows the components involved by the withdrawal using
the terminal. Besides the payment mean 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}
\label{sec-architecture-process}
@@ -19,26 +19,25 @@ The component diagram shows the components involved by the
withdrawal using the
\label{fig-diagram-all-components}
\end{figure}
-The \autoref{fig-diagram-all-components} shows a high level overview of the
components involved and how they interact. In an initial step (before the
process is effectively started as depicted), the customer or owner of the
terminal selects the \textit{Exchange}, which shall be used for the withdrawal.
The process is then started. The numbers in the diagrams are picked up by the
description of the steps what is done between the different components:
+\autoref{fig-diagram-all-components} shows a high level overview of the
components involved and how they interact. In an initial step (before the
process is effectively started as depicted), the customer or owner of the
terminal selects the Exchange, which is to be used for the withdrawal. The
process is then started. 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 POS initiates a payment to the account of the GNU Taler
Exchange. For the payment the POS terminal requests a payment card and a PIN
for authorizing the payment.
- \item The Terminal triggers the payment at the Wallee Backend.
- \item The Terminal receives the result of the payment.
+ \item Wallee terminal requests to be notified when parameters are
\textit{selected} by C2EC (step 0).
+ \item The wallet scans the QR code at the terminal (step 1).
+ \item The wallet registers a reserve public key and initializes the
mapping to the \textit{WOPID} (step 2).
+ \item The Terminals API of C2EC notifies the terminal, that the parameters
were selected (step 3).
+ \item The POS initiates a payment to the account of the GNU Taler
Exchange. For the payment the POS terminal requests a payment mean and the
verification such as a pin code to authorize the payment (step 4).
+ \item The terminal triggers the payment through the Wallee backend (step
5).
+ \item The terminal receives the result of the payment (step 6).
\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.
+ \item The terminal sends a payment confirmation request to the Bank
Integration API of C2EC (step 7).
+ \item The C2EC component seeks confirmation for the payment by requesting
the transaction of the Wallee backend (step 8).
+ \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 (step 9).
+ \item The Exchange-Wirewatch asks the Wire Gateway API of C2EC for a list
of transactions. Confirmed transaction will lead to the generation of a reserve
at the Exchange (step 10)
+ \item The wallet asks the Exchange to be notified, when a reserve with the
reserve public key becomes available. The digital cash is then withdrawn by the
wallet (step 11)
\end{enumerate}
\begin{figure}[h]
@@ -48,29 +47,29 @@ The \autoref{fig-diagram-all-components} shows a high level
overview of the comp
\label{fig-diagram-all-sequence}
\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 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.
+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}
+\subsection{The terminal}
-The Terminal initiates the withdrawal leveraging an application which works as
follows:
+The terminal initiates the withdrawal leveraging an application which works as
follows:
\begin{enumerate}
\item At startup of the application, the terminal loads the C2EC
configuration
- \item When a user wishes to do a withdrawal, the owner of the terminal
opens the application and initiates a new withdrawal. A withdrawal is basically
a funds transfer to the IBAN account of the \textit{Exchange}.
+ \item When a user wishes to do a withdrawal, the owner of the terminal
opens the application and initiates a new withdrawal. A withdrawal is basically
a funds transfer to the IBAN account of the Exchange.
\begin{enumerate}
- \item Terminal sets up a withdrawal by aksing C2EC to setup a
\textit{WOPID}
- \item The application starts long polling at the C2EC and awaits the
selection of the reserve parameters mapped to the \textit{WOPID}. The
parameters are sent by the Wallet to C2EC.
+ \item terminal sets up a withdrawal by aksing C2EC to setup a
\textit{WOPID}
+ \item The application starts long polling at the C2EC and awaits the
selection of the reserve parameters mapped to the \textit{WOPID}. The
parameters are sent by the wallet to C2EC.
\item \textit{WOPID} is packed into a QR code (with Exchange and
amount entered by the terminal owner)
- \item Terminal calculates fees and shows summary and the Terms of
Service (ToS) of Taler.
+ \item terminal calculates fees and shows summary and the Terms of
Service (ToS) of Taler.
\item The user accepts the offer, agrees with the ToS
\item QR code is displayed
\end{enumerate}
- \item The user now scans the QR Code using his Wallet.
+ \item The user now scans the QR Code using his wallet.
\item The application receives the notification of the C2EC, that the
parameters for the withdrawal were selected.
- \item The Terminal executes the payment (after user presented their credit
card, using the Terminal Backend).
- \item The terminal initiate the fund transfer to the \textit{Exchange}.
The customer has to authorize the payment by presenting his payment card and
authorizing the transaction with his PIN. The terminal processes the payment
over the an available connector configured on the \textit{Wallee Backend}.
Possible connectors are Master Card, VISA, TWINT, Maestro, Post Finance, and
others \cite{wallee-available-connectors}.
+ \item The terminal executes the payment (after user presented their credit
card, using the terminal backend).
+ \item The terminal initiate the fund transfer to the Exchange. The
customer has to authorize the payment by presenting his payment card and
authorizing the transaction with his PIN. The terminal processes the payment
over the an available connector configured on the Wallee backend. Possible
connectors are for example Master Card, VISA, TWINT, Maestro, Post Finance, and
others \cite{wallee-available-connectors}.
\begin{enumerate}
\item It presents the result to the user.
\item It tells the C2EC, that the payment was successful.
@@ -79,11 +78,11 @@ The Terminal initiates the withdrawal leveraging an
application which works as f
\subsection{The C2EC}
-The C2EC component manages the withdrawal using a third party provider (e.g.
Wallee) and seeks guarantees in order to create a reserve containing digital
cash which can be withdrawn by the Wallet.
+The C2EC component manages the withdrawal using a third party provider (e.g.
Wallee) and seeks guarantees in order to create a reserve containing digital
cash which can be withdrawn by the wallet.
\begin{enumerate}
\item C2EC retrieves setup request for withdrawal which will lead to
generation of the \textit{WOPID}.
- \item C2EC retrieves a long polling request for a \textit{WOPID} (from the
Terminal).
+ \item C2EC retrieves a long polling request for a \textit{WOPID} (from the
terminal).
\item C2EC retrieves a request including a \textit{WOPID} and a reserve
public key.
\item C2EC validates the request and adds the key to the mapping. This
establishes the \textit{WOPID} to reserve public key mapping.
\item C2EC ends the long polling from the terminal.
@@ -94,11 +93,11 @@ The C2EC component manages the withdrawal using a third
party provider (e.g. Wal
\subsection{The Wallet}
-The Wallet must attest its presence to the terminal by registering a
\textit{WOPID} and belonging reserve public key which will hold the digital
cash that can eventually be withdrawn by the Wallet.
+The wallet must attest its presence to the terminal by registering a reserve
public key with the respective \textit{WOPID} which will hold the digital cash
that can eventually be withdrawn by the wallet. The process of the wallet is
already implemented through the Bank-Integration API \cite{wallet-withdrawal}
and only documented for completeness.
\begin{enumerate}
- \item The Wallet scans the QR Code (\textit{WOPID}, Exchange information
and amount) on the Terminal
+ \item The wallet scans the QR Code (\textit{WOPID}, Exchange information
and amount) on the terminal
\item It creates a reserve key pair
- \item The Wallet sends the reserve public key and the scanned
\textit{WOPID} to the C2EC
- \item The Wallet can withdraw digital cash from the created reserve.
+ \item The wallet sends the reserve public key to the C2EC using the
\textit{WOPID} to pin the public key to a withdrawal operation.
+ \item The wallet can eventually withdraw digital cash from the created
reserve.
\end{enumerate}
diff --git a/docs/content/architecture/wallee.tex
b/docs/content/architecture/wallee.tex
index 19e757b..f123a81 100644
--- a/docs/content/architecture/wallee.tex
+++ b/docs/content/architecture/wallee.tex
@@ -35,4 +35,4 @@ The \textit{Transaction Service} is used by C2EC to attest a
transaction was suc
The \textit{Refund Service} is used by C2EC in case of a refund. Therefore the
C2EC gets notified by the \textit{Exchange} that the transaction shall be
refunded. To trigger the refund process at the Wallee backend, the \texttt{POST
/api/refund/refund} is used.
\subsubsection{Wallee Transaction State}
-In order to decide if a transaction was successful, the states of a
transaction within Wallee must be mapped to the world of Taler. This means that
a reserve shall only be created, if the transaction is in a state which allows
Taler not having any liabilities regarding the transaction and that Wallee
could process the payment successfully. The documentation states that
\textit{only} in the transaction state \textit{fulfill}, the delivery of the
goods (in case of withdrawal this means, th [...]
+To decide if a transaction was successful, the states of a transaction within
Wallee must be mapped to the world of Taler. This means that a reserve shall
only be created, if the transaction is in a state which allows Taler not having
any liabilities regarding the transaction and that Wallee could process the
payment successfully. The documentation states that \textit{only} in the
transaction state \textit{fulfill}, the delivery of the goods (in case of
withdrawal this means, that the re [...]
diff --git a/docs/content/architecture/wallet.tex
b/docs/content/architecture/wallet.tex
deleted file mode 100644
index 483d49c..0000000
--- a/docs/content/architecture/wallet.tex
+++ /dev/null
@@ -1,14 +0,0 @@
-\section{Taler Wallet}
-
-The \textit{Taler Wallet} is responsible to create a reserve key pair which
will allow him the withdrawal using the \textit{Exchange} using the reserve
public key of the key pair.
-
-The reserve public key is created by the \textit{Taler Wallet} and sent to
C2EC to establish the mapping between the \textit{wopid} and the reserve public
key. The reserve public key is used to eventually create a reserve at the
exchange which contains the digital cash. The \textit{Taler Wallet} can then
withdraw the digital cash from this reserve using the withdrawal process of the
wallet \cite{wallet-withdrawal}. The process for the case of C2EC is slightly
different from the present p [...]
-
-\subsection{Taler Wallet Perspective}
-From the perspective of the Wallet, the system looks as follows:
-
-\begin{itemize}
- \item Uses the QR Code displayed on the \textit{Wallee Terminal} to
identify nonce and read exchange information.
- \item Uses the Bank-Integration API of \textit{C2EC} to register the
reserve public key and retrieve information about the confirmation of the
withdrawal.
- \item Uses the \textit{Exchange} to withdraw the digital cash.
-\end{itemize}
\ No newline at end of file
diff --git a/docs/content/implementation/b-terminal.tex
b/docs/content/implementation/b-terminal.tex
index 98d04e0..e57c6ab 100644
--- a/docs/content/implementation/b-terminal.tex
+++ b/docs/content/implementation/b-terminal.tex
@@ -75,22 +75,24 @@ When the transaction was processed successfully, the
summary of the transaction
\label{fig-terminal-screen-authorized}
\end{figure}
-\subsection{Abortion Handling}
+\subsection{Abort Handling}
-During the flow various steps can fail or lead to the abortion of the
withdrawal. Therefore these edge cases must be considered and handled the right
way. Generally we can split the abortion handling on the terminal side into two
different phases. The implementation of the Wallee POS Terminal therefore
follows a strict \textit{abort on failure} strategy. This means that if
anything goes wrong the withdrawal is aborted and must be started again.
Generally the abortion handling strategy is [...]
+During the flow various steps can fail or lead to the abort of the withdrawal.
These edge cases must be considered and handled the right way. Generally we can
split the abort handling on the terminal side into two different phases. The
implementation of the Wallee POS Terminal follows a strict \textit{abort on
failure} strategy. This means that if anything goes wrong the withdrawal is
aborted and must be started again. Generally the abort handling strategy is to
abort the withdrawal when [...]
-\subsubsection{Abortion before authorization}
+\subsubsection{Abort before authorization}
-The first phase are abortions \textit{before} the payment is authorized. In
this case the withdrawal operation can be aborted using the \textit{abort}
operation described in \autoref{sec-implementation-terminal-api}. Every problem
which cannot be recovered or not further processed must therefore lead to the
abortion of the withdrawal.
+The first phase are abortions \textit{before} the payment is authorized. In
this case the withdrawal operation can be aborted using the \textit{abort}
operation described in \autoref{sec-implementation-terminal-api}. Every problem
which cannot be recovered or not further processed must lead to the abort of
the withdrawal.
-\subsubsection{Abortion after authorization}
+\subsubsection{Abort after authorization}
When the transaction was authorized, the process is a little bit more complex.
The customer has two possibilities. The first one is automatically covered with
the given implementation, while the second is not guaranteed and needs manual
interaction of the customer with the Taler Exchange operator.
\textbf{Wait for automatic refund due to closing of the reserve}
-The Taler Exchange configures a duration for which a reserve is kept open (and
therefore can be withdrawn). When the configured duration exceeds the reserve
is closed autmatically and the money transferred back to the customer. In the
case of Wallee payments, this is realized through a refund request at the
provider backend upon receiving a transfer request at the wire-gateway API
\autoref{sec-implementation-wire-gateway-api} of the C2EC component.
+The Taler Exchange configures a duration for which a reserve is kept open (and
can be withdrawn). When the configured duration exceeds the reserve is closed
autmatically and the money transferred back to the customer. In the case of
Wallee payments, this is realized through a refund request at the provider
backend upon receiving a transfer request at the wire-gateway API
\autoref{sec-implementation-wire-gateway-api} of the C2EC component.
\textbf{Manual request to refund money}
Depending on the operator of the Taler Exchange it might be possible to
somehow manually trigger a refund and get back the money spent for the
withdrawal.
+% TODO new section for Authorize -> Complete -> Execute Final Balance flow
+
\newpage
\ No newline at end of file
diff --git a/docs/content/introduction/goal.tex
b/docs/content/introduction/goal.tex
index 96d83d3..d8d9cb9 100644
--- a/docs/content/introduction/goal.tex
+++ b/docs/content/introduction/goal.tex
@@ -1,10 +1,19 @@
\section{Goal}
-The goal of this thesis is to propose a framework for cashless withdrawals and
implement the process which allows withdrawing Taler using a credit card at a
terminal of the terminal provider \textit{Wallee}.
+The goal of this thesis is to design and implement a framework for cashless
withdrawals of digital cash in GNU Taler. The implementation of the process
which allows withdrawing digital cash in GNU Taler at a terminal of an
established payment service provider shows how the framework can be used. The
withdrawal process on the side of the provider terminal shall be implemented on
the Paydroid platform supplied by the payment provider \textit{Wallee}.
+
+The framework aims to achieve the following key objectives:
+
+\begin{enumerate}
+ \item Finality: Liability for the money is not on the side of the Taler
operator
+ \item Convenience: The user-experience follows established patterns
+ \item Abort: Robust and secure payment flow allowing abort handling
without loss of money
+\end{enumerate}
\subsection{C2EC}
-Therefore a new component, named C2EC, will be implemented as part of the
Taler Exchange. C2EC will mediate between the Taler Exchange and the terminal
provider. This includes checking that the transaction of the debitor reaches
the account of the Exchange and therefore the digital currency can be withdrawn
by the user, using its Wallet.
+To achieve these goals a new component named cashless2ecash (C2EC) is
implemented as part of the Taler. C2EC mediates between the Taler Exchange and
the terminal provider. This includes checking that the transaction of the
debitor reaches the account of the Exchange and the digital cash can be
withdrawn by the user using their Wallet.
+
+\subsection{Paydroid POS Terminal}
-\subsection{Wallee POS Terminal}
-The Wallee payment terminal, also called Point of Sales (POS) terminal,
interfaces with payment cards (Credit Cards, Debit Cards) to make electronic
fund transfers, i.e. a fund transfer to a given GNU Taler Exchange. For our
purpose, we will extend the functionality of the terminal to initiate the
corresponding counter payment from the exchange to the GNU Taler wallet of the
payee.
+The Wallee payment terminal, also called Point of Sales (POS) terminal,
interfaces with payment cards (Credit Cards, Debit Cards) and other means of
payment (e.g. Twint) to make electronic fund transfers, i.e. a fund transfer to
a given GNU Taler Exchange. For our purpose, we extend the functionality of the
terminal to initiate the corresponding counter payment from the Exchange to the
GNU Taler wallet of the payee.
diff --git a/docs/content/introduction/introduction.tex
b/docs/content/introduction/introduction.tex
index 5c6ff0e..9ef97f4 100644
--- a/docs/content/introduction/introduction.tex
+++ b/docs/content/introduction/introduction.tex
@@ -2,28 +2,28 @@
Which payment systems do you use in your daily live and why? Probably one you
know it is universally accepted, reliable, secure and the payment goes through
more or less instantly.
-The \textbf{universal acceptance} was identified as one of the most important
aspects in a report which was published on behalf of the ECB (European Central
Bank) in march 2022 as result of a focus group concerning the acceptance of a
digital euro \cite{panetta-speech-march-30} as new payment system. The
universal acceptance was even identified as \textit{the} most important
property amongst the general public and tech-savvy people in the report
\cite{study-new-digital-payment-methods}.
+An \textbf{easy onboarding} was identified as one of the most important
aspects in a report which was commissioned by the ECB (European Central Bank)
in march 2022 as result of a focus group concerning the acceptance of a Digital
Euro \cite{panetta-speech-march-30} as new payment system. With the possibiliy
of an easy onboarding of new users, the universal acceptance can be increased.
The universal acceptance was identified as \textit{the} most important property
amongst the general publ [...]
-In a world, where everything is connected and everything is accessible from
everywhere (one might think), it is therefore very important to make it as easy
as possible to on-board people on a product. This is also the case for Taler.
For a wide acceptance of the payment system Taler, it is important that various
ways exist to withdraw digital cash in Taler.
+In a world, where everything is connected and everything is accessible from
everywhere (one might think), it is therefore very important to make it as easy
as possible to on-board people on a product. This is also the case for GNU
Taler. For a wide acceptance of the payment system Taler, it is important that
various ways exist to withdraw digital cash in Taler.
-This is where this thesis hooks in. Currenlty it is possible to withdraw
digital cash using Taler at a Bank which runs a \textit{Taler Exchange} and
integrates the respective API. At time of this writing only one Bank is in the
process of running a \textit{Taler Exchange}. At the Berner Fachhochschule an
\textit{Exchange} is operated and digital cash can be withdrawn at the
secretariat using cash.
+This is where this thesis hooks in. Currently it is possible to withdraw
digital cash using Taler at a Bank which runs a Taler Exchange and integrates
the respective API. At time of this writing only one Bank is in the process of
running a Taler Exchange. At the Berner Fachhochschule an Exchange is operated
and digital cash can be withdrawn at the secretariat using cash.
-To make the access to digital cash using Taler easier and allow faster
spreading of the payment system Taler, a framework for cashless withdrawal of
digital cash is proposed and implemented in order to open new doors for the
integration and adoption of the Taler payment system within the society.
+To make the access to digital cash using Taler easier and allow a faster
uptake of the payment system Taler, a framework for cashless withdrawal of
digital cash is proposed and implemented in order to open new doors for the
integration and adoption of the Taler payment system within the society.
-To make the withdrawals using a credit card possible, various loose ends must
be put together within the Taler ecosystem and the terminal provider.
+To make the withdrawal using a credit card or other means of payment possible,
various loose ends must be put together. These loose ends must enable the
communication between the Taler ecosystem and payment service providers and
their terminals.
-Therefore a new component C2EC shall help, establishing a trustworthy
relationship, which makes it possible for the \textit{Exchange} to issue
digital cash to a customer. Therefore the \textit{Exchange} is not putting his
trust on cash received but rather on the promise of a trusted third party (a
terminal provider) to put the received digital cash in a location, controlled
by the \textit{Exchange} eventually (e.g. a bank account owned by the
\textit{Exchange}).
+The a new component C2EC shall help, establishing a trustworthy relationship,
which makes it possible for the Exchange to issue digital cash to a customer.
Therefore the Exchange is not putting his trust on cash received but rather on
the promise of a trusted third party (a terminal provider) to put the received
digital cash in a location, controlled by the Exchange eventually (e.g. a bank
account owned by the Exchange).
This enables a broader group of people to leverage Taler for their payments.
Which eventually leads to a wider adoption of the payment system Taler.
\section{Perspectives}
-During the initial analysis of the task, three areas of work were discovered.
One is the \textit{Taler Exchange}, one the Application for the terminal and
the (Taler) \textit{Wallet}. This led to different views on the system by two
different players within it. To allow a more concise view on the system and to
support the readers and implementer, two perspectives shall be kept in mind.
They have different views on the process but need to interact with each other
seamlessly.
+During the initial analysis of the task, three areas of work were discovered.
One is the Taler Exchange, one the Application for the terminal and the Taler
wallet. This led to different views on the system by two different players
within it. To allow a more concise view on the system and to support the
readers and implementer, two perspectives shall be kept in mind. They have
different views on the process but need to interact with each other seamlessly.
\subsection{Taler Exchange (C2EC)}
-The perspective of the \textit{Taler Exchange} includes all processes within
C2EC component and the interaction with the terminal application, terminal
backend and the wallet of the user. The \textit{Taler Exchange} wants to allow
withdrawal of digital digital cash only to users who pay the equivalent value
to the \textit{Exchange}. The \textit{Exchange} wants to stay out of any legal
implications at all costs.
+The perspective of the Taler Exchange includes all processes within C2EC
component and the interaction with the terminal application, terminal backend
and the wallet of the user. The Taler Exchange wants to allow withdrawal of
digital digital cash only to users who pay the equivalent value to the
Exchange. The Exchange wants to stay out of any legal implications at all costs.
\subsection{Terminal Application}
-The perspective of the terminal application includes all processes within the
application which interacts with the user, their \textit{Wallet} and credit
card allowing the withdrawal of digital cash. The terminal application wants to
conveniently allow the withdrawal of digital cash and charge fees to cover its
costs and risks.
+The perspective of the terminal application includes all processes within the
application which interacts with the user, their wallet and credit card
allowing the withdrawal of digital cash. The terminal application wants to
conveniently allow the withdrawal of digital cash and charge fees to cover its
costs and risks.
-\subsection{Taler Wallet}
-The \textit{Wallet} holds the digital cash owned by the customer. The
\textit{Wallet} wants to eventually gather the digital cash from the
\textit{Taler Exchange}. The owner of the \textit{Wallet} must therefore
present their credit card at a \textit{Terminal} of the terminal provider and
pay the \textit{Exchange} as well accept the fees of the provider.
+\subsection{Taler wallet}
+The wallet holds the digital cash owned by the customer. The wallet wants to
eventually collect the digital cash from the Taler Exchange. The owner of the
wallet must present their credit card at a terminal of the payment service
provider and pay the Exchange as well accept optional fees of the provider.
Fees must be considered, since the withdrawal process is a service which costs
the payment service provider money in form of integration and maintenance
efforts. To cover its costs, the [...]
diff --git a/docs/pictures/diagrams/c2ec.png b/docs/pictures/diagrams/c2ec.png
index 6260a13..ef53c6d 100644
Binary files a/docs/pictures/diagrams/c2ec.png and
b/docs/pictures/diagrams/c2ec.png differ
diff --git a/docs/pictures/diagrams/system_overview.png
b/docs/pictures/diagrams/system_overview.png
index efa520a..6fb679e 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 9e79b1b..26ab596 100644
Binary files a/docs/thesis.pdf and b/docs/thesis.pdf differ
diff --git a/docs/thesis.tex b/docs/thesis.tex
index 096aacf..c3a368a 100644
--- a/docs/thesis.tex
+++ b/docs/thesis.tex
@@ -196,7 +196,6 @@
\chapter{Architecture}
\label{sec-architecture}
\input{content/architecture/c2ec}
-\input{content/architecture/wallet}
\input{content/architecture/wallee}
\chapter{Implementation}
diff --git a/poster/cashless2ecash_poster.pdf b/poster/cashless2ecash_poster.pdf
index effb4ba..247e267 100644
Binary files a/poster/cashless2ecash_poster.pdf and
b/poster/cashless2ecash_poster.pdf differ
diff --git a/poster/cashless2ecash_poster.tex b/poster/cashless2ecash_poster.tex
index ce60151..264088b 100644
--- a/poster/cashless2ecash_poster.tex
+++ b/poster/cashless2ecash_poster.tex
@@ -25,7 +25,6 @@
columns=5,
rows=8,
spacing=1cm,
- %showframe, %Gitter einblenden. Für Platzierung häufig
hilfreich
}]
\begin{posterboxenv}[title=Motivation]{name=intro,column=1,row=1,span=3,rowspan=2}
@@ -140,7 +139,7 @@
\end{posterboxenv}
-\space
+ \space
\begin{posterboxenv}[title=C2EC is extensible]{name=Integrate
your platform, column=1,row=8,span=5,rowspan=1}
diff --git a/simulation/c2ec-simulation b/simulation/c2ec-simulation
index 2491488..8d3d881 100755
Binary files a/simulation/c2ec-simulation and b/simulation/c2ec-simulation
differ
diff --git a/specs/c2ec.plantuml b/specs/c2ec.plantuml
index fd21957..f724974 100644
--- a/specs/c2ec.plantuml
+++ b/specs/c2ec.plantuml
@@ -13,32 +13,30 @@ User -> TerminalOwner: "Hi, I want to withdraw 20 CHF using
Taler with my Credit
TerminalOwner -> Terminal: start Taler Withdrawal Application and enters amount
Terminal -> Terminal: Generate WOPID
Terminal -> C2EC: (0) Setup Withdrawal
-Terminal -> C2EC: (1) Start long polling (WOPID)
+Terminal -> C2EC: Start long polling (WOPID)
activate C2EC
Terminal -> Terminal: Create QR code (WOPID, Exchange, Amount)
-Terminal -> Wallet: (2) Scan QR code
+Terminal -> Wallet: (1) 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) Register reserve public key
+Wallet -> C2EC: (2) Register reserve public key
C2EC -> C2EC: Link WOPID to reserve public key
-C2EC --> Terminal: (4) End long polling (selected)
+C2EC --> Terminal: (3) End long polling (selected)
deactivate C2EC
-Terminal -> Terminal: Show summary with Fees (if any)
-User -> Terminal: (5) Approve and authorize transaction
-Terminal -> TerminalBackend: (6) Execute transaction
-TerminalBackend --> Terminal: (7) transaction response (success/failure)
+Terminal -> Terminal: Show summary with Fees (optional)
+User -> Terminal: (4) Approve and authorize transaction
+Terminal -> TerminalBackend: (5) Execute transaction
+TerminalBackend --> Terminal: (6) transaction response (success/failure)
+Terminal -> C2EC: (7) Send Confirmation Request (SUCCESS)
+C2EC -> TerminalBackend: (8) Verify transaction
alt transaction successful
- Terminal -> C2EC: (8) Send Confirmation Request (SUCCESS)
- C2EC -> TerminalBackend: (9) Verify transaction
- C2EC -> C2EC: (10) confirm or abort withdrawal
- Exchange -> C2EC: (11) get transaction history
+ C2EC -> C2EC: (9a) confirm withdrawal
+ Exchange -> C2EC: (10) get transaction history
Exchange -> Exchange: Create Reserve with amount and reserve public key.
- Wallet -> Exchange: (12) Await creation of the reserve
- Wallet -> Exchange: (13) Withdraw digital cash
+ Wallet -> Exchange: (11) Withdraw digital cash when reserve is ready
deactivate Wallet
else transaction not successful
- Terminal -> C2EC: (8) Send Confirmation Request (UNSUCESSFUL)
- C2EC -> C2EC: Transition withdrawal to abort state.
+ C2EC -> C2EC: (9b) abort withdrawal
end
@enduml
diff --git a/specs/system_overview.odg b/specs/system_overview.odg
index 77a87f8..f161341 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.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-cashless2ecash] branch master updated: docs: enhance introduction and architecture,
gnunet <=