\documentclass{scrartcl} \usepackage[a4paper]{geometry} \usepackage{hyperref} \usepackage[dvipsnames]{xcolor} \hypersetup{ colorlinks = true, allcolors = {black}, 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=\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=\itshape, %stringstyle=\color{red}, morestring=[b]', morestring=[b]" } \lstset{ language=typescript, %backgroundcolor=\color{lightgray}, extendedchars=true, basicstyle=\footnotesize\color{NavyBlue}\ttfamily, showstringspaces=false, showspaces=false, %numbers=left, %numberstyle=\footnotesize, %numbersep=9pt, tabsize=2, breaklines=true, showtabs=false, captionpos=b, emphstyle=\bfseries } \begin{document} \title{AP³\\ Report for Milestone III\\ NGI Pointer} \author{Özgür Kesim\\ Christan Grothoff\\ Florian Dold\\ Stefan Kügel\\ Emmanuel Benoist\\[\bigskipamount] \normalsize Mentor: Mirko Ross \href{mailto:m.ross@digital-worx.de}{}\\[\medskipamount] } \date{October 15, 2022} \maketitle \section*{Management summary} \begin{abstract} The AP³ project presents here the report for the milestone III for NGI Pointer. The deliverables for this milestone are: \begin{description} \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} \vfill \hfill {\footnotesize Version: 1.0} \thispagestyle{empty} \newpage \tableofcontents \newpage \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 conditional 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: \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{Transcript and Replay for libbrandt} 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 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 \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 \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. bidder: number; // The index of the winning price into the // `BrandtVickreyAuction`.prices array. price_idx: number; // The winning price price: Amount; } \end{lstlisting} \end{description} \subsection{Brandt-Vickrey-auction extension for GNU Taler} 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 the 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} \subsection{Future work} To a fully functional and maintainable solution, further development is needed in the following areas: \begin{description} \item[libbrandt upgrade] The code base of this library is from 2017 and doesn't compile with the latest 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. For future work we plan to refactor libbrandt to use libsodium and the current version of GNUnet. \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 integration-tests with the exchange are missing \item A fully featured auction(er) system, including billboard and client software, is missing. \end{itemize} 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. \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 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} \appendix \section{Definition of a Transcript of Brandt-Vickrey-auctions} \label{transcript} The following definition is provided in TypeScript and taken from \url{https://docs.taler.net/core/api-exchange.html#tsref-type-BrandtVickreyAuction}. \begin{lstlisting}[language=typescript] // This structure defines an auction of Brandt-Vickory kind. // It is used for the PolicyBrandtVickreyAuction. interface BrandtVickreyAuction { // Start date of the auction time_start: Timestamp; // Maximum duration per round. There are four rounds in an auction of // Brandt-Vickrey kind. time_round: RelativeTime; // This integer m refers to the (m+1)-type of the Brandt-Vickrey-auction. // - Type 0 refers to an auction with one highest-price winner, // - Type 1 refers to an auction with one winner, paying the second // highest price, // - Type 2 refers to an auction with two winners, paying // the third-highest price, // - etc. auction_type: number; // The vector of prices for the Brandt-Vickrey auction. The values MUST // be in strictly increasing order. prices: Amount[]; // The type of outcome of the auction. // In case the auction is declared public, each bidder can calculate the // winning price. This field is not relevant for the replay of a // transcript, as the transcript must be provided by the seller who sees // the winner(s) and winning price of the auction. outcome_public: boolean; // The public key of the seller. pubkey: EddsaPublicKey; // The seller's account details. payto_uri: string; } // This structure defines the transcript of an auction // of Brandt-Vickrey kind. interface BrandtVickreyAuctionTranscript { // The auction definition. auction: BrandtVickreyAuction; // The public keys of the bidders, in Crockford Base32 encoding. bidders: EddsaPublicKey[]; // Signatures of the auction in Crockford Base32 encoding. // One signature per bidder. signatures: EddsaSignature[]; // List of policy hash codes that identify policy details associated with // each bidder. Those codes were generated by the policy extension // policy_brandt_vickrey_auction during the deposit of coins for this // auction. policy_hash_codes: HashCode[]; // The transcript of all messages received by the seller. transcript: BrandtVickreyAuctionMessage[]; // Optionally, the seller can provide the winners it had calculated. winners?: BrandtVickreyAuctionWinner[]; // The signature over the hash of this JSON object, without the // key ``sig`` and in normalized form, basically over // H(auction, bidders, signatures, transcripts, winners?) // It is signed by the private key that corresponds to the public key // in `BrandtVickreyAuction`.``pubkey``. // This signature is in Crockford Base32 encoding. sig: EddsaSignature; } interface BrandtVickreyAuctionMessage { // The index of the bidder into the // `BrandtVickreyAuctionTranscript`.``bidders`` array. bidder: number; // The raw message in Crockford Base32 encoding. msg: string; // The signature over the message. The signature is in Crockford Base32 // encoding. It must be signed by the private key corresponding to the // bidder's public key in `BrandtVickreyAuctionTranscript`.``bidders``. sig: EddsaSignature; } \end{lstlisting} \end{document}