[taler-cashless2ecash] branch master updated: docs: draft payto REFUND

[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 639234e  docs: draft payto REFUND
639234e is described below

commit 639234ecba71478d20482d27a203f9224242d259
Author: Joel-Haeberli <haebu@rubigen.ch>
AuthorDate: Wed Mar 20 12:24:50 2024 +0100

    docs: draft payto REFUND
---
 docs/content/architecture/nonce2ecash.tex          |  30 +++++++++++-
 docs/content/architecture/overview.tex             |  27 +++++++++++
 docs/content/sysview/taler.tex                     |   4 +-
 docs/pictures/database/table_terminal.png          | Bin 0 -> 28726 bytes
 docs/pictures/database/table_terminal_provider.png | Bin 0 -> 18150 bytes
 docs/pictures/database/table_withdrawal.png        | Bin 0 -> 30494 bytes
 docs/pictures/diagrams/layer_diagram.png           | Bin 0 -> 26214 bytes
 docs/project.bib                                   |  54 +++++++++++++++++++++
 docs/thesis.pdf                                    | Bin 1319751 -> 1384056 
bytes
 9 files changed, 113 insertions(+), 2 deletions(-)

diff --git a/docs/content/architecture/nonce2ecash.tex 
b/docs/content/architecture/nonce2ecash.tex
index 33d1f49..a4570ac 100644
--- a/docs/content/architecture/nonce2ecash.tex
+++ b/docs/content/architecture/nonce2ecash.tex
@@ -53,4 +53,32 @@ Withdrawals with a nonce2ecash are based on withdrawal 
operations which register
 
 The database of the nonce2ecash component must track two different aspects. 
The first is the mapping of a nonce to a reserve public key to enable 
withdrawals and the second aspect is the authentication of terminals allowing 
withdrawals owned by terminal providers like \textit{Wallee}.
 
-
+\subsubsection{Terminal Provider}
+Table in \autoref{fig-erd-terminal-provider} describing providers of 
nonce2ecash terminals. The name of the provider is important, because it 
decides which flow shall be taken in order to attest the payment.
+
+\begin{figure}[h]
+  \centering
+  
\includegraphics[width=0.7\textwidth]{pictures/database/table_terminal_provider.png}
+  \caption{Terminal Provider Table}
+  \label{fig-erd-terminal-provider}
+\end{figure}
+
+\subsubsection{Terminal}
+Table in \autoref{fig-erd-terminal} contains information about terminals of 
providers. This includes the provider they belong to and an authentication 
token, which is generated by the Exchange and allows authenticating the 
terminal. A terminal belongs to one terminal provider.
+
+\begin{figure}[h]
+  \centering
+  \includegraphics[width=0.7\textwidth]{pictures/database/table_terminal.png}
+  \caption{Terminal Table}
+  \label{fig-erd-terminal}
+\end{figure}
+
+\subsubsection{Withdrawal}
+Table in \autoref{fig-erd-withdrawal} represents the withdrawal processes 
initiated by terminals. This table therefore contains information about the 
withdrawal like the amount, which terminal the withdrawal was initiated from 
and which reserve public key is used to create a reserve in the Exchange.
+
+\begin{figure}[h]
+  \centering
+  \includegraphics[width=0.7\textwidth]{pictures/database/table_withdrawal.png}
+  \caption{Withdrawal Table}
+  \label{fig-erd-withdrawal}
+\end{figure}
diff --git a/docs/content/architecture/overview.tex 
b/docs/content/architecture/overview.tex
index cafa137..58f60c8 100644
--- a/docs/content/architecture/overview.tex
+++ b/docs/content/architecture/overview.tex
@@ -73,3 +73,30 @@ The Wallet must attest its presence to the terminal by 
registering a nonce and b
     \item The Wallet sends the reserve public key and the scanned nonce to the 
Exchange
     \item The Wallet can withdraw money from the created reserve.
 \end{enumerate}
+
+\subsection{Nonce}
+The nonce is leveraged by all components to establish the connection to an 
entry in the mapping table of nonce2ecash. The nonce is therefore crucial and 
every participant of the withdrawal must eventually gain knowledge about the 
value of the nonce in order to process the withdrawal. The nonce is created by 
the Terminal and advertised to the Exchange by requesting notification, when 
the reserve public key belonging to the nonce was received and the mapping 
could be created.
+The Wallet gains the nonce value when scanning the QR code at the Terminal and 
then sends the nonce (and the other parameters) to the Exchange.
+
+\subsubsection{Nonce creation}
+Besides the entropy needed to establish a correct nonce, the hash function 
leveraged must be specified. (TODO - possibly one of FIPS 180-4 or FIPS 202 
families)
+
+\subsection{Reserve Public Key}
+The reserve public key is created by the Wallet and sent to the Exchange to 
establish the mapping between the nonce and the reserve public key. The reserve 
public key, can then be retrieved by the Terminal and used during the payment. 
The reserve public key is used to eventually create a reserve at the exchange 
which contains the money. The Wallet can then withdraw the money from this 
reserve using the withdrawal process of the wallet \cite{wallet-withdrawal}.
+
+\subsection{Payto REFUND 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.
+
+For the case of refunds, which might occur in case a credit card transaction 
does not succeed, a new \textit{target type} called REFUND 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 receiver of the payto URI is able to deduct the transaction and handle the 
specific process. Like this any refund process can be handled through this 
single \textit{target type}.
+
+The transaction identifier is not provider agnostic. This means that the 
identifier can be sourced by various formatted identifiers, depending on the 
originating system. Therefore, the transaction identifier is a hash of the 
actual identifier allowing a standardized format for the \textit{target 
identifier}. This requires the owner of the process triggering the refund to 
maintain a mapping of the \textit{target identifier} and the respective hash. 
The owner of the process triggering the  [...]
+
+The idea of the REFUND \textit{target type} is to trigger a refund process by 
the owner of the refund process without other services needing to deal with the 
refund logic. Therefore transactions which allow refund but the receiver cannot 
directly execute the refund, the payto REFUND \textit{target type} can be used 
to advice the owner to of the refund process, to execute the refund linked to 
the transaction identifier supplied using the \textit{target identifier}, which 
is a hash of the  [...]
+
+\subsubsection{Refund Target Identifier Hash}
+In order to allow a generic adoption of the REFUND \textit{target type}, the 
transaction identifier must be transformed to a general format. Therefore a 
hash function can be leveraged. This hash function must be configurable and 
therefore the \textit{generic option} called \textit{instruction} holds the 
name of the hash function. The name shall correspond to one of the offical 
terms used in e.g. FIPS 180-4 \cite{fips-180-4} (SHA-1 and SHA-2 families) or 
FIPS-202 \cite{fips-202} (SHA-3 fa [...]
+
+\subsubsection{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 nonce2ecash component can trigger the refund using the refund 
service if needed, and the payto-uri retrieved as debit account by the 
wirewatch gateway API, is leveraged to delegate the refund process to the 
Wallee Backend using the Refund Service.
+
+\pagebreak
\ No newline at end of file
diff --git a/docs/content/sysview/taler.tex b/docs/content/sysview/taler.tex
index 4817040..8801f61 100644
--- a/docs/content/sysview/taler.tex
+++ b/docs/content/sysview/taler.tex
@@ -4,4 +4,6 @@ GNU Taler is a payment system which allows paying for goods in 
an anonymous way
 
 \subsection{Wirewatch Gateway RESTful API}
 
-The wirewatch gateway helps communicating with the Exchange core using a 
convenient API. This includes retrieving information about transactions which 
were sent through the EBICS system. EBICS stands for \textit{Electronic Banking 
Internet Communication Standard} and represents an interface for interbank 
communication based on TCP/IP. Taler can retrieve incoming transaction through 
the EBICS interface using the Taler Nexus component, which acts as subscriber 
to an EBICS instance. This wi [...]
+The wirewatch gateway helps communicating with the Exchange core using a 
convenient API. It helps the Exchange to get guarantees, that a certain 
transaction went through and that the reserve can be created and withdrawn. 
This will help nonce2ecash to capture the transaction of the Terminal Backend 
to the Exchange's account and therefore allow the withdrawal by the customer. 
Therefore the wirewatch gateway API is used in nonce2ecash. When the wirewatch 
gateway captures a transaction point [...]
+
+
diff --git a/docs/pictures/database/table_terminal.png 
b/docs/pictures/database/table_terminal.png
new file mode 100644
index 0000000..e855f78
Binary files /dev/null and b/docs/pictures/database/table_terminal.png differ
diff --git a/docs/pictures/database/table_terminal_provider.png 
b/docs/pictures/database/table_terminal_provider.png
new file mode 100644
index 0000000..ac46b81
Binary files /dev/null and b/docs/pictures/database/table_terminal_provider.png 
differ
diff --git a/docs/pictures/database/table_withdrawal.png 
b/docs/pictures/database/table_withdrawal.png
new file mode 100644
index 0000000..15f33a9
Binary files /dev/null and b/docs/pictures/database/table_withdrawal.png differ
diff --git a/docs/pictures/diagrams/layer_diagram.png 
b/docs/pictures/diagrams/layer_diagram.png
new file mode 100644
index 0000000..20bc763
Binary files /dev/null and b/docs/pictures/diagrams/layer_diagram.png differ
diff --git a/docs/project.bib b/docs/project.bib
index 4fd1f2b..bfe51b3 100644
--- a/docs/project.bib
+++ b/docs/project.bib
@@ -57,3 +57,57 @@
     month =     jan,
     abstract =  {This document registers the "secret-token" URI scheme to aid 
in the identification of authentication tokens.},
 }
+
+@misc{rfc8905,
+    series =    {Request for Comments},
+    number =    8905,
+    howpublished =  {RFC 8905},
+    publisher = {RFC Editor},
+    doi =       {10.17487/RFC8905},
+    url =       {https://www.rfc-editor.org/info/rfc8905},
+    author =    {Florian Dold and Christian Grothoff},
+    title =     {{The 'payto' URI Scheme for Payments}},
+    pagetotal = 12,
+    year =      2020,
+    month =     oct,
+    abstract =  {This document defines the 'payto' Uniform Resource Identifier 
(URI) scheme for designating targets for payments. A unified URI scheme for all 
payment target types allows applications to offer user interactions with URIs 
that represent payment targets, simplifying the introduction of new payment 
systems and applications.},
+}
+
+@misc{rfc3986,
+    series =    {Request for Comments},
+    number =    3986,
+    howpublished =  {RFC 3986},
+    publisher = {RFC Editor},
+    doi =       {10.17487/RFC3986},
+    url =       {https://www.rfc-editor.org/info/rfc3986},
+    author =    {Tim Berners-Lee and Roy T. Fielding and Larry M Masinter},
+    title =     {{Uniform Resource Identifier (URI): Generic Syntax}},
+    pagetotal = 61,
+    year =      2005,
+    month =     jan,
+    abstract =  {A Uniform Resource Identifier (URI) is a compact sequence of 
characters that identifies an abstract or physical resource. This specification 
defines the generic URI syntax and a process for resolving URI references that 
might be in relative form, along with guidelines and security considerations 
for the use of URIs on the Internet. The URI syntax defines a grammar that is a 
superset of all valid URIs, allowing an implementation to parse the common 
components of a URI ref [...]
+}
+
+@misc{fips-180-4,
+  author = {Quynh Dang},
+  title = {Secure Hash Standard},
+  year = {2015},
+  month = {2015-08-04},
+  publisher = {Federal Inf. Process. Stds. (NIST FIPS), National Institute of 
Standards and Technology, Gaithersburg, MD},
+  doi = {https://doi.org/10.6028/NIST.FIPS.180-4},
+  language = {en},
+}
+
+@misc{fips-202,
+    author = { National Institute of Standards and Technology },
+    title = {SHA-3 Standard: Permutation-Based Hash and Extendable-Output 
Functions},
+    url = {https://doi.org/10.6028/NIST.FIPS.202},
+    howpublished = {\url{https://doi.org/10.6028/NIST.FIPS.202}},    
+}
+
+@misc{wallet-withdrawal,
+    author       = {Taler},
+    title        = {Withdrawal},
+    url          = {https://docs.taler.net/taler-wallet.html#withdrawal},
+    howpublished = {\url{https://docs.taler.net/taler-wallet.html#withdrawal}}
+}
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
index 40d10b6..4eca76e 100644
Binary files a/docs/thesis.pdf and b/docs/thesis.pdf differ

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