ngi-pointer-ap3/m3/ngi-ap3-m3-report.tex

\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}{<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}

For 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 -- UI PoC}

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}