diff --git a/.gitignore b/.gitignore index a136337..eeaa4bf 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,5 @@ *.pdf +*.aux +*.log +*.out +*.toc diff --git a/m3/fonts/Inconsolata-Bold.ttf b/m3/fonts/Inconsolata-Bold.ttf new file mode 100644 index 0000000..035d579 Binary files /dev/null and b/m3/fonts/Inconsolata-Bold.ttf differ diff --git a/m3/fonts/Inconsolata-Regular.ttf b/m3/fonts/Inconsolata-Regular.ttf new file mode 100644 index 0000000..bbc9647 Binary files /dev/null and b/m3/fonts/Inconsolata-Regular.ttf differ diff --git a/m3/fonts/RobotoMono-Bold.ttf b/m3/fonts/RobotoMono-Bold.ttf new file mode 100644 index 0000000..8eff26c Binary files /dev/null and b/m3/fonts/RobotoMono-Bold.ttf differ diff --git a/m3/fonts/RobotoMono-BoldItalic.ttf b/m3/fonts/RobotoMono-BoldItalic.ttf new file mode 100644 index 0000000..9929964 Binary files /dev/null and b/m3/fonts/RobotoMono-BoldItalic.ttf differ diff --git a/m3/fonts/RobotoMono-Italic-VariableFont_wght.ttf b/m3/fonts/RobotoMono-Italic-VariableFont_wght.ttf new file mode 100644 index 0000000..31c87fc Binary files /dev/null and b/m3/fonts/RobotoMono-Italic-VariableFont_wght.ttf differ diff --git a/m3/fonts/RobotoMono-Italic.ttf b/m3/fonts/RobotoMono-Italic.ttf new file mode 100644 index 0000000..cf2b5b3 Binary files /dev/null and b/m3/fonts/RobotoMono-Italic.ttf differ diff --git a/m3/fonts/RobotoMono-Regular.ttf b/m3/fonts/RobotoMono-Regular.ttf new file mode 100644 index 0000000..d9371a1 Binary files /dev/null and b/m3/fonts/RobotoMono-Regular.ttf differ diff --git a/m3/fonts/RobotoMono-VariableFont_wght.ttf b/m3/fonts/RobotoMono-VariableFont_wght.ttf new file mode 100644 index 0000000..1d5371e Binary files /dev/null and b/m3/fonts/RobotoMono-VariableFont_wght.ttf differ diff --git a/m3/ngi-ap3-m3-report.tex b/m3/ngi-ap3-m3-report.tex index 7e7623c..9e6d031 100644 --- a/m3/ngi-ap3-m3-report.tex +++ b/m3/ngi-ap3-m3-report.tex @@ -1,32 +1,39 @@ -\documentclass{scrarticle} +\documentclass{scrartcl} \usepackage[a4paper]{geometry} \usepackage{hyperref} -\usepackage{xcolor} +\usepackage[dvipsnames]{xcolor} \hypersetup{ colorlinks = true, allcolors = {black}, - linkcolor = [rgb]{0.6 0.1 0.1}, - urlcolor = [rgb]{0.1 0.1 0.7} + linkcolor = DarkOrchid, + urlcolor = DarkOrchid, } \usepackage{url} +\usepackage[font=footnotesize]{caption} \usepackage{amssymb} \usepackage{amsmath} \usepackage{pdfpages} \usepackage{graphicx} \usepackage{listings} - +\usepackage{fontspec} +\setmonofont[Path = fonts/, + Extension = .ttf, + UprightFont = *-Regular, + ItalicFont = *-Italic, + BoldFont = *-Bold, + Scale=0.85]{RobotoMono} \lstdefinelanguage{typescript}{ keywords={typeof, new, true, false, catch, function, return, null, catch, switch, var, if, in, while, do, else, case, break, interface}, - keywordstyle=\color{purple}\bfseries, - ndkeywords={class, export, boolean, number, Amount, string, Timestamp, RelativeTime, EddsaPublicKey, BrandtVickreyAuction, BrandtVickreyAuctionMessage, BrandtVickreyAuctionWinner, EddsaSignature, HashCode, throw, implements, import, this}, - ndkeywordstyle=\color{blue}, + keywordstyle=\bfseries, + ndkeywords={class, export, boolean, number, Amount, string, Timestamp, RelativeTime, EddsaPublicKey, BrandtVickreyAuction, BrandtVickreyAuctionMessage, BrandtVickreyAuctionWinner, EddsaSignature, HashCode, throw, implements, import, this, BrandtVickreyReplayOutcome}, + ndkeywordstyle=\bfseries, identifierstyle=\color{black}, sensitive=false, comment=[l]{//}, morecomment=[s]{/*}{*/}, - commentstyle=\color{darkgray}\ttfamily, - stringstyle=\color{red}\ttfamily, + commentstyle=\itshape, + %stringstyle=\color{red}, morestring=[b]', morestring=[b]" } @@ -35,7 +42,7 @@ language=typescript, %backgroundcolor=\color{lightgray}, extendedchars=true, - basicstyle=\footnotesize\ttfamily, + basicstyle=\footnotesize\color{NavyBlue}\ttfamily, showstringspaces=false, showspaces=false, %numbers=left, @@ -44,7 +51,8 @@ tabsize=2, breaklines=true, showtabs=false, - captionpos=b + captionpos=b, + emphstyle=\bfseries } \begin{document} @@ -70,8 +78,8 @@ The AP³ project presents here the report for the milestone III for NGI Pointer. The deliverables for this milestone are: \begin{description} - \item[P2P payments] -- - \item[Anonymous auction] -- + \item[Anonymous auction] -- PoC for execution of anonymous sealed-bid auctions + \item[P2P payments] -- PoC UI on Android for P2P transactions in the Taler wallet \end{description} \end{abstract} @@ -79,48 +87,149 @@ The AP³ project presents here the report for the milestone III for NGI Pointer. \hfill {\footnotesize Version: 1.0} \thispagestyle{empty} -\newpage +\newpage \tableofcontents - \newpage -\section{P2P payments} +\section{Anonymous auctions - PoC} + +We departed from the design of a dedicated escrow service in GNU Taler (see +report for milestone 2) and identified a more general approach for conditional +payments---deposits with \textit{policies} attached to them. The design of +\textit{Deposit Policy Extensions} has been drafted in +\href{https://docs.taler.net/design-documents/028-deposit-policies.html}{design +document 28} and is still work-in-progress. + +\subsection{Policy extensions framework for GNU Taler} +\label{extension} + +The policy-based approach to deposit of coins allows GNU Taler to offer a +variety of condidtional payment types, including: Merchant refunds, escrowed +payments and Brandt-Vickrey auctions. + +In Brandt-Vickrey auctions, bidders put coins into escrow with the exchange in +order to participate in an Brandt-Vickrey auction. The deposit confirmation is +proof to the seller for the escrow and contains a hash of the auction meta-data +and a deadline. + +After successful execution of the auction, the seller provides a valid +transcript to the exchange from which the exchange learns which bidder(s) won +the auction for which price(s). It then transfers the amounts from the winners’ +coins to the seller. The coins' (rest) values can be refreshed by winning and +losing bidders. + +\begin{quote} + \itshape Note: Support for Brandt-Vickrey type auctions has been + implemented as Proof-of-Concept policy-extension for this milestone. +\end{quote} + +A policy can be in one of the following five states of fulfillment: + +\begin{itemize} + \item[\itshape Ready:] The policy is funded and ready. The exchange is + waiting for a proof of fulfillment to arrive before the + deadline. + \item[\itshape Insufficient:] The policy lacks funding, that is + \verb|accumulated_total| $<$ \verb|commitment| (see + Fig.~\ref{schema}), but has otherwise been accepted. Funding + can be continued by calling \verb|/deposit| or + \verb|/batch-deposit| with more coins and the same policy + details. + \item[\itshape Success:] The policy is provably fulfilled. The amounts + for the payout, fees and refresh are transferred/can be + claimed. Note that a policy fulfillment handler can change the + values for the amounts for payout, fees and refresh. + \item[\itshape Timeout:] The policy has timed out. The amounts for + payout and refresh are transferred/can be claimed. + \item[\itshape Failure:] The policy is in an failure state. Payouts and + refreshes are blocked, timeouts are ignored. +\end{itemize} + +The +\href{https://git.kesim.org/taler/exchange/src/branch/auction\_brandt/src/exchangedb/exchange-0001-part.sql\#L539-L602}% +{database-schema has been extended} to include the tables +\verb|policy_details|, which contains the details to a particular policy +associated with one or more deposits, and \verb|policy_fulfillments|, which +keeps proofs of fulfillment when they arrive, associated with one or more +policies, see Figure~\ref{schema}. + +A new stored-procedure +\href{https://git.kesim.org/taler/exchange/src/branch/auction\_brandt/src/exchangedb/procedures.sql\#L2190-L2301}% +{\ttfamily insert\_or\_update\_policy\_details} has been added to handle policy +details, including the accumulation of the total amount that has been put into +deposit for an existing policy. + +\begin{figure} + \centering + \includegraphics[width=0.95\textwidth]{pics/schema.png} + \caption{Tables and their relationships for policy extensions} + \label{schema} +\end{figure} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +The +\href{https://git.kesim.org/taler/exchange/src/branch/auction\_brandt/src/include/taler\_extensions.h}{extensions-API} +has been extended to include the following function pointers: -\newpage -\section{Anonymous auctions} +\begin{description} + \item[\href{https://git.kesim.org/taler/exchange/src/branch/auction\_brandt/src/include/taler\_extensions.h\#L167-L185}% + {\ttfamily create\_policy\_details}] When a deposit request + contains a + \href{https://docs.taler.net/core/api-exchange.html#deposit}% + {policy object} that refers to this extension, this handler + will be called before the deposit transaction. The policy + extension is responsible to generate the necessary data to fill + the \verb|policy_details| table and provide a + \verb|policy_hash_code| as unique reference to these details. + \item[\href{https://git.kesim.org/taler/exchange/src/branch/auction\_brandt/src/include/taler\_extensions.h\#L187-L202}% + {\ttfamily policy\_post\_handler}] Handler for POST-requests to + the \verb|/extensions/policy_$name| endpoint, responsible for + validating incoming proofs of fulfilment of a policy with name + \verb|$name|. +\end{description} \subsection{Transscript and Replay for libbrandt} -At the beginning of our project, the most recent implementation of -Brandt-Vickrey auctions was from Markus Teich -(\url{https://git.gnunet.org/libbrandt.git/}). In our own fork at -\url{https://git.kesim.org/oec/libbrandt}, we added the following functionality: +When we started our project, the most recent implementation of Brandt-Vickrey +auctions was from Markus Teich (\url{https://git.gnunet.org/libbrandt.git/}). +In our fork at \url{https://git.kesim.org/oec/libbrandt}, we added the +following functionality: \begin{description} - \item[Transscript generation] The unit-test file - \href{https://git.kesim.org/oec/libbrandt/src/branch/transcript/test\_brandt.c}{test\_brandt.c} - has been extended to generate and print a transscript for each - auction, containing parameters of the auction---such as number - of bidders, prices and auction type---and the list of all - messages that the seller has received during the protocol - execution. + \item[Transscript generation] The existing unit-test file + \href{https://git.kesim.org/oec/libbrandt/src/branch/transcript/test\_brandt.c}{\ttfamily test\_brandt.c} + has been extended to generate and print a transcript in JSON + encoding for each auction, containing parameters of the + auction---such as number of bidders, prices and auction + type---and the list of all messages that the seller has + received during the protocol execution. The definition of the transcript structure is given in appendix \ref{transcript}. \item[Replay of transscript] The new file - \href{https://git.kesim.org/oec/libbrandt/src/branch/transcript/replay.c}{replay.c} - reads a transcript from stdin, parses it and executes an - auction, replaying all messages from the transcript. + \label{replay} + \href{https://git.kesim.org/oec/libbrandt/src/branch/transcript/replay.c}{\ttfamily replay.c} + implements a standalone program that reads a transcript from + \verb|stdin|, parses it and executes an auction, replaying all + messages from the transcript. - On success, it prints a result in JSON form to stdout: + On success, it prints a result in + \href{https://docs.taler.net/design-documents/032-brandt-vickrey-auctions.html#transcripts}{JSON form} + to \verb|stdout|: \begin{lstlisting}[language=typescript] +interface BrandtVickreyReplayOutcome { + // If the replay of the transcript was successfull, will contain the + // the list of winners and prices. + winner?: BrandtVickreyAuctionWinner[]; + + // If an error occured during replay, will contain an error message. + error?: string; +} + interface BrandtVickreyAuctionWinner { // The index of the bidder into the // `BrandtVickreyAuctionTranscript`.bidder array. @@ -137,48 +246,184 @@ interface BrandtVickreyAuctionWinner { \end{description} -\subsection{Policy extensions framework for GNUN Taler} - -General policy extension framework \subsection{Brandt-Vickrey-auction extension for GNU Taler} -Extension \verb|policy_brandt_vickrey_auction| added +Based on the policy extensions framework for GNU Taler +(section~\ref{extension}), we implemented the +\href{https://git.kesim.org/taler/exchange/src/branch/auction\_brandt/src/extensions/policy\_brandt\_vickrey\_auction/policy\_brandt\_vickrey\_auction.c}% +{policy extension \ttfamily policy\_brandt\_vickrey\_auction} to handle +deposits of coins that are put into escrow for the participation in an auction +and the transfer or release of coins after successful proof of fulfillment, +which in this cases involves the replay of a transcript of the corresponding +Brandt-Vickrey auction. In particular, we implemented the following handlers: + +\begin{description} + \item[\href{https://git.kesim.org/taler/exchange/src/branch/auction\_brandt/src/extensions/policy\_brandt\_vickrey\_auction/policy\_brandt\_vickrey\_auction.c\#L767-L821}{\ttfamily auction\_create\_policy\_details}] + This implements the {\ttfamily create\_policy\_details} + function of the policy extension interface and generates a + hash-code for incoming policy in JSON form, by calculating the + hash $H(h_a || p_b)$, where $h_a$ is the hash of the auction + meta data and $p_b$ is the public key of the bidder. Both + parameters are part of the policy structure provided during a + deposit. + + \item[\href{https://git.kesim.org/taler/exchange/src/branch/auction\_brandt/src/extensions/policy\_brandt\_vickrey\_auction/policy\_brandt\_vickrey\_auction.c\#L694-L764}{\ttfamily auction\_policy\_post\_handler}] + This implements the {\ttfamily policy\_post\_handler} function + of teh policy extension interface. The POST-handler receives + the transcript and the list of policy-details of former + deposit-operations. It parses the transcript and calls the + external program (sec.~\ref{replay}) to replay the auction and + determine the winners and winning price. +\end{description} -\begin{itemize} - \item \verb|get_policy_details| generates hash-code for - a policy by building the hash $H(h_a || p_b)$, - where $h_a$ is the hash of the auction meta - data and $p_b$ is the public key of the bidder. - Both parameters are part of the policy - structure provided during a deposit. - \item the POST-handler receives the transcript and the - list of policy-details of former - deposit-operations. It parses the transcript - and calls an external program to replay the - auction and determine the winners and winning - price. -\end{itemize} \subsection{Future work} -\subsubsection{libbrandt} +To a fully functional and maintainable solution, further development is needed +in the following areas: -use libsodium +\begin{description} -make it compatible with current version of GNUNET +\item[libbrandt upgrade] The code base of this library is from 2017 and doesn't + compile with the lates version of + \href{https://git.gnunet.org/gnunet.git}{GNUnet}. It also + uses \href{https://gnupg.org/software/libgcrypt/index.html}% + {\ttfamily libgcrypt} as cryptographic library, which is quite + slow compared to its modern alternative + \href{https://doc.libsodium.org/}{\ttfamily libsodium}, at + least with respect to the primitives used in libbrandt. -\subsubsection{policy framework} + For future work we plan to refactor libbrandt to use libsodium + and the current version of GNUnet. -add escrow policy and merge refund to it +\item[Brandt-Vickrey-Auction continuation] The current code is a + proof-of-concept. The following known problem exist: + \begin{itemize} + \item Signature verification of the transcript and its messages + is missing + \item Unit- and Integrationtests with the exchange are missing + \item A fully featured auction(er) system, including billboard + and client softare, is missing. + \end{itemize} -\subsubsection{brandt-vickrey-auction} + We will address at least the first two issues and plan to + address the lack of an auction system once we find volunteers + and funding for it. -verify signatures of transscript +\item[Policy framework continuation] Based on the current design of policy + extensions for deposit---aka conditional payments---we plan to add + following policy extensions to the GNU Taler exchange: + \begin{itemize} + \item{\itshape Merchant refunds:} Merchant can grant customers refundable + payments. In this case, the amount of the deposit is put into + escrow by the exchange for a certain period until which the + customer can claim a refund. + + Right now, this policy is implicit and optional in the usual + deposit-flow. Future work on Taler will lift this into a + policy-extension. + + \item{\itshape Escrowed payments:} A trustor puts coins into escrow + with the exchange. It can be claimed by a beneficiary until a + certain deadline, when the claim is signed by + both, the beneficiary’s and the trustor’s keys. + + This was the basic idea behind the design we presented in + Milestone 2. It will become a policy-extension in future work. + \end{itemize} + +\end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\newpage +\section{P2P payments} + +After the implementation of Peer-to-Peer payments on the exchange for milestone +2, we continued to implement the UI's for Android and Web extensions, both as +Proof-of-Concepts. + +\subsection{Wallet Core} + +The core functionality for the P2P payment in the wallet is located at { + + \centering \url{https://git.taler.net/wallet-core.git} + +} +\noindent under +\href{https://git.taler.net/wallet-core.git/tree/packages/taler-wallet-core/src}{/packages/taler-wallet-core/src}, +in particular: + +\begin{itemize} + \item Peer-to-peer payment operations: + + \hspace{3em}\href{https://git.taler.net/wallet-core.git/tree/packages/taler-wallet-core/src/operations/pay-peer.ts}% +{\ttfamily operations/pay-peer.ts} + + \item Database schema with p2p state in it: + + \hspace{3em}\href{https://git.taler.net/wallet-core.git/tree/packages/taler-wallet-core/src/db.ts\#n2065}% +{{\ttfamily src/db.ts}, starting at line 2065} + + \item Peer-to-peer transactions in the transaction list type declarations: + + \hspace{3em}\href{https://git.taler.net/wallet-core.git/tree/packages/taler-util/src/transactions-types.ts#n251}% +{{\ttfamily src/transactions-types.ts}, starting at line 251} + +\end{itemize} + + +\subsection{Android App} + +\begin{figure} + \centering + \includegraphics[width=0.24\linewidth]{pics/photo_2022-10-17_11-52-30.jpg} + \includegraphics[width=0.24\linewidth]{pics/photo_2022-10-17_11-52-32.jpg} + \includegraphics[width=0.24\linewidth]{pics/photo_2022-10-17_11-52-33.jpg} + \includegraphics[width=0.24\linewidth]{pics/photo_2022-10-17_11-52-34.jpg} + \caption{Screenshots of the UI for P2P payments in the the Android + version of the GNU Taler wallet} + \label{android} +\end{figure} + +The implementation of the UI for P2P on the Android app is located at { + +\centering \url{https://git.taler.net/taler-android.git/} + +} \noindent under +\href{https://git.taler.net/taler-android.git/tree/wallet/src/main/java/net/taler/wallet/peer}% +{/wallet/src/main/java/net/taler/wallet/peer}. The resulting UI is shown in +the screenshots in Fig.~\ref{android}. + + + +\subsection{Web extensions UI} +WebExtension UI stuff related to peer-to-peer is in repository { + +\centering \url{https://git.taler.net/wallet-core.git/} + +} \noindent under +\href{https://git.taler.net/wallet-core.git/tree/packages/taler-wallet-webextension/src/cta/}% +{\ttfamily /packages/taler-wallet-webextension/src/cta/}, in directories +\href{https://git.taler.net/wallet-core.git/tree/packages/taler-wallet-webextension/src/cta/InvoiceCreate}% +{\ttfamily InvoiceCreate} and +\href{https://git.taler.net/wallet-core.git/tree/packages/taler-wallet-webextension/src/cta/InvoicePay}% +{\ttfamily InvoicePay}. The resulting UI is shown in the screenshots in Fig.~\ref{web} + +\begin{figure} + \centering + \framebox{\includegraphics[width=0.225\textwidth]{pics/Selection_276.png}} + \framebox{\includegraphics[width=0.225\textwidth]{pics/Selection_277.png}} + \framebox{\includegraphics[width=0.225\textwidth]{pics/Selection_278.png}} + \framebox{\includegraphics[width=0.225\textwidth]{pics/Selection_279.png}} + \caption{Screenshots of the P2P payments in the Web extension} + \label{web} +\end{figure} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \newpage \part*{Appendix} \addcontentsline{toc}{part}{Appendix} diff --git a/m3/pics/Selection_276.png b/m3/pics/Selection_276.png new file mode 100644 index 0000000..11df17c Binary files /dev/null and b/m3/pics/Selection_276.png differ diff --git a/m3/pics/Selection_277.png b/m3/pics/Selection_277.png new file mode 100644 index 0000000..49e03f3 Binary files /dev/null and b/m3/pics/Selection_277.png differ diff --git a/m3/pics/Selection_278.png b/m3/pics/Selection_278.png new file mode 100644 index 0000000..a07e92b Binary files /dev/null and b/m3/pics/Selection_278.png differ diff --git a/m3/pics/Selection_279.png b/m3/pics/Selection_279.png new file mode 100644 index 0000000..449fbb2 Binary files /dev/null and b/m3/pics/Selection_279.png differ diff --git a/m3/digitaltag-ux-chairs.jpg b/m3/pics/digitaltag-ux-chairs.jpg similarity index 100% rename from m3/digitaltag-ux-chairs.jpg rename to m3/pics/digitaltag-ux-chairs.jpg diff --git a/m3/digitaltag-ux-setup.jpg b/m3/pics/digitaltag-ux-setup.jpg similarity index 100% rename from m3/digitaltag-ux-setup.jpg rename to m3/pics/digitaltag-ux-setup.jpg diff --git a/m3/pics/photo_2022-10-17_11-52-30.jpg b/m3/pics/photo_2022-10-17_11-52-30.jpg new file mode 100644 index 0000000..1a998d6 Binary files /dev/null and b/m3/pics/photo_2022-10-17_11-52-30.jpg differ diff --git a/m3/pics/photo_2022-10-17_11-52-32.jpg b/m3/pics/photo_2022-10-17_11-52-32.jpg new file mode 100644 index 0000000..a8f274b Binary files /dev/null and b/m3/pics/photo_2022-10-17_11-52-32.jpg differ diff --git a/m3/pics/photo_2022-10-17_11-52-33.jpg b/m3/pics/photo_2022-10-17_11-52-33.jpg new file mode 100644 index 0000000..1ff7dcd Binary files /dev/null and b/m3/pics/photo_2022-10-17_11-52-33.jpg differ diff --git a/m3/pics/photo_2022-10-17_11-52-34.jpg b/m3/pics/photo_2022-10-17_11-52-34.jpg new file mode 100644 index 0000000..fc8cb7c Binary files /dev/null and b/m3/pics/photo_2022-10-17_11-52-34.jpg differ diff --git a/m3/pics/schema.png b/m3/pics/schema.png new file mode 100644 index 0000000..0a6de99 Binary files /dev/null and b/m3/pics/schema.png differ diff --git a/m3/pics/schema.svg b/m3/pics/schema.svg new file mode 100644 index 0000000..3aba7d5 --- /dev/null +++ b/m3/pics/schema.svg @@ -0,0 +1,90 @@ + + + + + + +deposit_policies + + +cluster_deposits + +deposits + + +cluster_policy_details + +policy_details + + +cluster_policy_fulfillments + +policy_fulfillments + + + +deposits + +... + +policy_details_id (null) + +... + +timestamp + +... + + + +policy_details + +id + +policy_hash_code (unique) + +deadline + +commitment (amount) + +accumulated_total (amount) + +fee (amount) + +transferable (amount) + +fulfillment_state + +fulfillment_id (null) + + + +deposits:ref->policy_details:id + + +n:1 + + + +policy_fulfillments + +id + +proof + +timestamp + +policy_hash_codes (blob) + + + +policy_details:fid->policy_fulfillments:id + + +n:1 + + +