From 60180e78e5dfe7e4cb257e8262b7074b6fd72d80 Mon Sep 17 00:00:00 2001
From: Alessandro Coglio <coglio@kestrel.edu>
Date: Mon, 8 Aug 2022 16:34:28 -0700
Subject: [PATCH] [examples] Add explanations to auction example.

---
 examples/auction/src/main.leo | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/examples/auction/src/main.leo b/examples/auction/src/main.leo
index fe75658ac9..a31c8f4493 100644
--- a/examples/auction/src/main.leo
+++ b/examples/auction/src/main.leo
@@ -1,3 +1,14 @@
+// This example is suggestive of an auction smart contract,
+// but it is much simpler of a full auction smart contract.
+
+// This is a record that contains the current state of the auction,
+// which in this example just consists of
+// the address of the currently winning bidder
+// and the currently winning amount.
+// The owner and gates fields are required in a record;
+// the owner address in general differs from the curent auction winner:
+// the owner is the one running the auction itself.
+
 record Auction {
     owner: address,
     gates: u64,
@@ -5,6 +16,26 @@ record Auction {
     winning_bid: u64
 }
 
+// This function realizes the checking and possible incorporation of a new bid.
+// Unlike a traditional auction, where the currently winning bid is known,
+// and only higher bids would be normally brought up in the room,
+// in a zero-knowledge context presumably bidding is blind,
+// i.e. a bidder does not know the currently highest bid.
+// Thus, this function represents a possible update of the auction state
+// with a new bid:
+// if the amount exceeds the currently winning one,
+// the record is updated with the new bid and the new bidder's address;
+// the latter is also passed as input.
+// Again, this is just a simple example;
+// in a serious auction smart contract,
+// there will be some additional checks,
+// and presumably ways to tie bidder and amount (e.g. commitments).
+//
+// In order to run this function, an Auction record must be passed to it.
+// This is done in the input file, inputs/auction.in.
+// Note that, when building that record,
+// the owner address must be the same as the one in the program.json file.
+
 @program
 function main(current: Auction, bidder: address, bid: u64) -> Auction {
     let winning_bidder: address = current.winning_bidder;