Update docs for auction example

examples/auction/README.md

@@ -1,13 +1,66 @@
-# Auction Record Example
+# Blind Auction
 
-## Build Guide
+An auction application written in Leo.
 
-To compile this program:
-```bash
-leo build
+## Summary
+
+A first-price sealed-bid auction (or blind auction) is a type of auction in which each participant submits a bid without knowing the bids of the other participants. 
+The bidder with the highest bid wins the auction.
+
+In this model, there are two parties: the auctioneer and the bidders.
+- **Bidder**: A participant in the auction.
+- **Auctioneer**: The party responsible for conducting the auction.
+
+We make following assumptions about the auction:
+- The auctioneer is honest. That is, the auctioneer will resolve **all** bids in the order they are received. The auctioneer will not tamper with the bids.
+- There is no limit to the number of bids.
+- The auctioneer knows the identity of all bidders, but bidders do not necessarily know the identity of other bidders.
+
+Under this model, we require that:
+- Bidders do not learn any information about the value of other bids.
+
+### Auction Flow
+The auction is conducted in a series of stages.
+- **Bidding**: In the bidding stage, bidders submit bids to the auctioneer. They do so by invoking the `place_bid` function.
+- **Resolution**:  In the resolution stage, the auctioneer resolves the bids in the order they were received. The auctioneer does so by invoking the `resolve` function. The resolution process produces a single winning bid.
+- **Finishing**: In this stage, the auctioneer finishes the auction by invoking the `finish` function. This function returns the winning bid to the bidder, which the bidder can then use to claim the item.
+
+
+## Language Features and Concepts
+- `record` declarations
+- `console.assert_eq`
+- record ownership
+
+## Running the Program
+
+Leo provides users with a command line interface for compiling and running Leo programs.
+Users may either specify input values via the command line or provide an input file in `inputs/`.
+
+### Configuring Accounts
+The `program.json` file contains a private key and address. 
+This is the account that will be used to sign transactions and is checked for record ownership.
+When executing programs as different parties, be sure to set the `private_key` and `address` fields in `program.json` to the appropriate values.
+See `./run.sh` for an example of how to run the program as different parties.
+
+
+The [Aleo SDK](https://github.com/AleoHQ/leo/tree/testnet3) provides a command line interface for generating new accounts.
+To generate a new account, run 
+```
+leo account new
 ```
 
-To run this program:
+
+### Providing inputs via the command line.
+1. Run
 ```bash
-leo run
+leo run <function_name> <input_1> <input_2> ...
+```
+See `./run.sh` for an example.
+
+
+### Using an input file.
+1. Modify `inputs/auction.in` with the desired inputs.
+2. Run
+```bash
+leo run <function_name>
 ```

examples/auction/src/main.leo

@@ -1,4 +1,10 @@
-// This record defines a bid in the auction.
+// A bid in an auction.
+// - `owner`     : The address of the account that owns the record associated with this bid.
+//                 This is separate from the address of the account that placed the bid.
+// - `gates`     : The value associated with the record (always zero).
+// - `bidder`    : The address of the account that placed the bid.
+// - `amount`    : The amount of the bid.
+// - `is_winner` : Whether the bid is the winning bid.
 record Bid {
     owner: address,
     gates: u64,
@@ -7,11 +13,12 @@ record Bid {
     is_winner: bool,
 }
 
-// This function creates a new bid.
-// This function checks that `bidder` invoked the function.
-// Note that the owner of the record is set to the entity responsible for running the auction.
-//   The entity's address is aleo1fxs9s0w97lmkwlcmgn0z3nuxufdee5yck9wqrs0umevp7qs0sg9q5xxxzh.
-//   This is necessary to allow the entity running the auction to process bids.
+// Returns a new bid.
+// - `bidder` : The address of the account that placed the bid.
+// - `amount` : The amount of the bid.
+// Requires that `bidder` matches the function caller.
+// The owner of the record is set to the entity responsible for running the auction (auction runner).
+// The address of the auction runner is aleo1fxs9s0w97lmkwlcmgn0z3nuxufdee5yck9wqrs0umevp7qs0sg9q5xxxzh.
 @program
 function place_bid(bidder: address, amount: u64) -> Bid {
     console.assert_eq(self.caller, bidder);
@@ -24,9 +31,12 @@ function place_bid(bidder: address, amount: u64) -> Bid {
     };
 }
 
-// This function consumes two bids, selecting the winning one. In the event of a tie, the first bid is selected.
-// This function should be invoked once the bidding period has ended.
-// This function can only be called by the entity running the auction.
+// Returns the winning bid.
+// - `first`  : The first bid.
+// - `second` : The second bid.
+// Requires that the function caller is the auction runner.
+// Assumes that the function is invoked only after the bidding period has ended.
+// In the event of a tie, the first bid is selected.
 @program
 function resolve(first: Bid, second: Bid) -> Bid {
     console.assert_eq(self.caller, aleo1fxs9s0w97lmkwlcmgn0z3nuxufdee5yck9wqrs0umevp7qs0sg9q5xxxzh);
@@ -37,9 +47,10 @@ function resolve(first: Bid, second: Bid) -> Bid {
     }
 }
 
-// This function returns ownership of the `Bid` record to the original bidder.
-// This function should be called after all bids have been resolved.
-// This function can only be called by the entity running the auction.
+// Returns ownership of the bid to bidder.
+// - `bid` : The winning bid.
+// Requires that the function caller is the auction runner.
+// Assumes that the function is invoked only after all bids have been resolved.
 @program
 function finish(bid: Bid) -> Bid {
     console.assert_eq(self.caller, aleo1fxs9s0w97lmkwlcmgn0z3nuxufdee5yck9wqrs0umevp7qs0sg9q5xxxzh);