added listings for auction defs

m3/ngi-ap3-m3-report.tex

@@ -13,6 +13,39 @@
 \usepackage{amsmath}
 \usepackage{pdfpages}
 \usepackage{graphicx}
+\usepackage{listings}
+
+
+\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},
+  identifierstyle=\color{black},
+  sensitive=false,
+  comment=[l]{//},
+  morecomment=[s]{/*}{*/},
+  commentstyle=\color{darkgray}\ttfamily,
+  stringstyle=\color{red}\ttfamily,
+  morestring=[b]',
+  morestring=[b]"
+}
+
+\lstset{
+   language=typescript,
+   %backgroundcolor=\color{lightgray},
+   extendedchars=true,
+   basicstyle=\footnotesize\ttfamily,
+   showstringspaces=false,
+   showspaces=false,
+   %numbers=left,
+   %numberstyle=\footnotesize,
+   %numbersep=9pt,
+   tabsize=2,
+   breaklines=true,
+   showtabs=false,
+   captionpos=b
+}
 
 \begin{document}
 
@@ -63,9 +96,46 @@ The AP³ project presents here the report for the milestone III for NGI Pointer.
 
 \subsection{Transscript and Replay for libbrandt}
 
-Added transscript generation to 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:
 
-Added replay of transscript of libbrandt
+\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.
+
+		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.
+
+		On success, it prints a result in JSON form to stdout:
+
+		\begin{lstlisting}[language=typescript]
+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{Policy extensions framework for GNUN Taler}
 
@@ -98,13 +168,14 @@ use libsodium
 
 make it compatible with current version of GNUNET
 
+\subsubsection{policy framework}
+
+add escrow policy and merge refund to it
+
 \subsubsection{brandt-vickrey-auction}
 
 verify signatures of transscript
 
-\subsubsection{policy framework}
-
-
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -113,6 +184,99 @@ verify signatures of transscript
 \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}
+
 \newpage
 %\includepdf[pagecommand=\section{Age restriction and Legal Issues}\label{legal},frame=true,pages=1,scale=.9]{Age_restriction_and_legal_issues.pdf}
 %\includepdf[pages=2-,scale=.9,frame=true]{Age_restriction_and_legal_issues.pdf}