Merge pull request #229 from AztecProtocol/pod-racing

feat: add new starter example

Author: sklppy88

Nargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "private_voting_contract"
+name = "pod_racing_contract"
 type = "contract"
 authors = [ "" ]
 compiler_version = ">=0.18.0"

package.json

@@ -1,5 +1,5 @@
 {
-  "name": "private_voting_codespace",
+  "name": "pod_racing_codespace",
   "version": "1.0.0",
   "main": "index.js",
   "repository": "https://github.com/critesjosh/private_voting_codespace.git",

src/game_round_note.nr

@@ -0,0 +1,56 @@
+use aztec::{macros::notes::note, protocol_types::{traits::Packable, address::AztecAddress}};
+
+// GameRoundNote is a private note that stores a player's point allocation for one round
+// These notes remain private until the player calls finish_game to reveal their totals
+//
+// Privacy model:
+// - Each player creates 3 of these notes (one per round) when playing
+// - Only the owner can read their own notes
+// - During finish_game, the player sums all their notes and reveals the totals publicly
+// - This implements a commit-reveal scheme for fair play
+#[derive(Eq, Packable)]
+#[note]
+pub struct GameRoundNote {
+    // Points allocated to each of the 5 tracks in this round
+    // Must sum to less than 10 points per round
+    pub track1: u8,
+    pub track2: u8,
+    pub track3: u8,
+    pub track4: u8,
+    pub track5: u8,
+
+    // Which round this note represents (1, 2, or 3)
+    pub round: u8,
+
+    // The player who created this note (only they can read it)
+    pub owner: AztecAddress,
+}
+
+impl GameRoundNote {
+    // Creates a new note with the player's round choices
+    // This note gets stored privately and can only be read by the owner
+    pub fn new(track1: u8, track2: u8, track3: u8, track4: u8, track5: u8, round: u8, owner: AztecAddress) -> Self {
+        Self {
+            track1,
+            track2,
+            track3,
+            track4,
+            track5,
+            round,
+            owner,
+        }
+    }
+
+    // Helper method to access the note data
+    pub fn get(self) -> Self {
+        Self {
+            track1: self.track1,
+            track2: self.track2,
+            track3: self.track3,
+            track4: self.track4,
+            track5: self.track5,
+            round: self.round,
+            owner: self.owner,
+        }
+    }
+}

src/main.nr

@@ -1,73 +1,217 @@
+// Pod Racing Game Contract
+//
+// This is a two-player competitive racing game where players allocate points across 5 tracks
+// over multiple rounds. The game flow:
+// 1. Player 1 creates a game with a time limit
+// 2. Player 2 joins the game
+// 3. Both players play rounds privately (allocating points across tracks)
+// 4. After all rounds, players reveal their total scores per track
+// 5. Winner is determined by who won more tracks (best of 5)
+//
+// Key mechanics:
+// - Each round, players distribute up to 9 points across 5 tracks
+// - Round choices are private until the finish phase
+// - The player with higher total points on a track wins that track
+// - The player who wins 3+ tracks wins the game
+
 mod test;
-use dep::aztec::macros::aztec;
+mod game_round_note;
+mod race;
 
-/**
- * WARNING: this is no-longer considered a good example of an Aztec contract,
- * because it touches low-level functions and concepts that oughtn't be 
- * seen by a typical user.
- * The syntax and user-experience of Aztec contracts has since improved, so you
- * should seek alternative examples, please.
- */
+use dep::aztec::macros::aztec;
 
 #[aztec]
-pub contract PrivateVoting {
+pub contract PodRacing {
     use dep::aztec::{
-        keys::getters::get_public_keys,
+        note::note_getter_options::NoteGetterOptions,
+        messages::message_delivery::MessageDelivery,
         macros::{functions::{external, initializer, internal}, storage::storage},
     };
-    use dep::aztec::protocol_types::{
-        address::AztecAddress,
-        hash::poseidon2_hash,
-        traits::{Hash, ToField},
-    };
-    use dep::aztec::state_vars::{Map, PublicImmutable, PublicMutable};
+    use dep::aztec::protocol_types::address::AztecAddress;
+    use dep::aztec::state_vars::{Map, PublicMutable, PrivateSet};
+
+    use crate::{game_round_note::GameRoundNote, race::Race};
+
+    // Game configuration constants
+    global TOTAL_ROUNDS: u8 = 3;  // Each game consists of 3 rounds
+    global GAME_LENGTH: u32 = 300;  // Games expire after 300 blocks
 
     #[storage]
     struct Storage<Context> {
-        admin: PublicMutable<AztecAddress, Context>, // admin can end vote
-        tally: Map<Field, PublicMutable<Field, Context>, Context>, // we will store candidate as key and number of votes as value
-        vote_ended: PublicMutable<bool, Context>, // vote_ended is boolean
-        active_at_block: PublicImmutable<u32, Context>, // when people can start voting
+        // Contract administrator address
+        admin: PublicMutable<AztecAddress, Context>,
+
+        // Maps game_id -> Race struct containing public game state
+        // Stores player addresses, round progress, and final track scores
+        races: Map<Field, PublicMutable<Race, Context>, Context>,
+
+        // Maps game_id -> player_address -> private notes containing that player's round choices
+        // Each GameRoundNote stores the point allocation for one round
+        // This data remains private until the player calls finish_game
+        progress: Map<Field, Map<AztecAddress, PrivateSet<GameRoundNote, Context>, Context>, Context>,
+
+        // Maps player address -> total number of wins
+        // Public leaderboard tracking career victories
+        win_history: Map<AztecAddress, PublicMutable<u64, Context>, Context>,
     }
 
     #[external("public")]
     #[initializer]
-    // annotation to mark function as a constructor
     fn constructor(admin: AztecAddress) {
         storage.admin.write(admin);
-        storage.vote_ended.write(false);
-        storage.active_at_block.initialize(context.block_number());
     }
 
+    // Creates a new game instance
+    // The caller becomes player1 and waits for an opponent to join
+    // Sets the game expiration to current block + GAME_LENGTH
+    #[external("public")]
+    fn create_game(game_id: Field) {
+        // Ensure this game_id hasn't been used yet (player1 must be zero address)
+        assert(storage.races.at(game_id).read().player1.eq(AztecAddress::zero()));
+
+        // Initialize a new Race with the caller as player1
+        let game = Race::new(context.msg_sender().unwrap(), TOTAL_ROUNDS, context.block_number() + GAME_LENGTH);
+        storage.races.at(game_id).write(game);
+    }
+
+    // Allows a second player to join an existing game
+    // After joining, both players can start playing rounds
+    #[external("public")]
+    fn join_game(game_id: Field) {
+        let maybe_existing_game = storage.races.at(game_id).read();
+
+        // Add the caller as player2 (validates that player1 exists and player2 is empty)
+        let joined_game = maybe_existing_game.join(context.msg_sender().unwrap());
+        storage.races.at(game_id).write(joined_game);
+    }
+
+    // Plays a single round by allocating points across 5 tracks
+    // This is a PRIVATE function - the point allocation remains hidden from the opponent
+    // Players must play rounds sequentially (round 1, then 2, then 3)
+    //
+    // Parameters:
+    // - track1-5: Points allocated to each track (must sum to less than 10)
+    // - round: Which round this is (1, 2, or 3)
     #[external("private")]
-    // annotation to mark function as private and expose private context
-    fn cast_vote(candidate: Field) {
-        let msg_sender_nullifier_public_key_message_hash =
-            get_public_keys(context.msg_sender().unwrap()).npk_m.hash();
-
-        let secret = context.request_nsk_app(msg_sender_nullifier_public_key_message_hash); // get secret key of caller of function
-        let nullifier = poseidon2_hash([context.msg_sender().unwrap().to_field(), secret]); // derive nullifier from sender and secret
-        context.push_nullifier(nullifier);
-        PrivateVoting::at(context.this_address()).add_to_tally_public(candidate).enqueue(
+    fn play_round(game_id: Field, round: u8, track1: u8, track2: u8, track3: u8, track4: u8, track5: u8) {
+        // Validate that total points don't exceed 9 (you can't max out all tracks)
+        assert(track1 + track2 + track3 + track4 + track5 < 10);
+
+        let player = context.msg_sender().unwrap();
+
+        // Store the round choices privately as a note in the player's own storage
+        // This creates a private commitment that can only be read by the player
+        storage.progress.at(game_id).at(player).insert(GameRoundNote::new(
+            track1,
+            track2,
+            track3,
+            track4,
+            track5,
+            round,
+            player,
+        )).emit(player, MessageDelivery.CONSTRAINED_ONCHAIN);
+
+        // Enqueue a public function call to update the round counter
+        // This reveals that a round was played, but not the point allocation
+        PodRacing::at(context.this_address()).validate_and_play_round(player, game_id, round).enqueue(
             &mut context,
         );
     }
 
+    // Internal public function to validate and record that a player completed a round
+    // Updates the public game state to track which round each player is on
+    // Does NOT reveal the point allocation (that remains private)
     #[external("public")]
     #[internal]
-    fn add_to_tally_public(candidate: Field) {
-        assert(storage.vote_ended.read() == false, "Vote has ended"); // assert that vote has not ended
-        let new_tally = storage.tally.at(candidate).read() + 1;
-        storage.tally.at(candidate).write(new_tally);
+    fn validate_and_play_round(player: AztecAddress, game_id: Field, round: u8) {
+        let game_in_progress = storage.races.at(game_id).read();
+        // Increment the player's round counter (validates sequential play)
+        storage.races.at(game_id).write(game_in_progress.increment_player_round(player, round));
     }
 
+    // Called after all rounds are complete to reveal a player's total scores
+    // This is PRIVATE - only the caller can read their own GameRoundNotes
+    // The function sums up all round allocations per track and publishes totals
+    //
+    // This is the "reveal" phase where private choices become public
+    #[external("private")]
+    fn finish_game(game_id: Field) {
+        let player = context.msg_sender().unwrap();
+
+        // Retrieve all private notes for this player in this game
+        let totals = storage.progress.at(game_id).at(player).get_notes(NoteGetterOptions::new());
+
+        // Sum up points allocated to each track across all rounds
+        let mut total_track1: u64= 0;
+        let mut total_track2: u64= 0;
+        let mut total_track3: u64= 0;
+        let mut total_track4: u64= 0;
+        let mut total_track5: u64= 0;
+
+        // Iterate through exactly TOTAL_ROUNDS notes (only this player's notes)
+        for i in 0..TOTAL_ROUNDS {
+            total_track1 += totals.get(i as u32).note.track1 as u64;
+            total_track2 += totals.get(i as u32).note.track2 as u64;
+            total_track3 += totals.get(i as u32).note.track3 as u64;
+            total_track4 += totals.get(i as u32).note.track4 as u64;
+            total_track5 += totals.get(i as u32).note.track5 as u64;
+        }
+
+        // Enqueue public function to store the revealed totals on-chain
+        // Now the revealing player's track totals will be publicly visible
+        PodRacing::at(context.this_address()).validate_finish_game_and_reveal(
+            player,
+            game_id,
+            total_track1,
+            total_track2,
+            total_track3,
+            total_track4,
+            total_track5,
+            ).enqueue(
+            &mut context,
+        );
+    }
+
+    // Internal public function to store a player's revealed track totals
+    // Validates that the player hasn't already revealed their scores (all must be 0)
+    // After both players call finish_game, all scores are public and can be compared
     #[external("public")]
-    fn end_vote() {
-        assert(storage.admin.read().eq(context.msg_sender().unwrap()), "Only admin can end votes"); // assert that caller is admin
-        storage.vote_ended.write(true);
+    #[internal]
+    fn validate_finish_game_and_reveal(
+        player: AztecAddress,
+        game_id: Field,
+        total_track1: u64,
+        total_track2: u64,
+        total_track3: u64,
+        total_track4: u64,
+        total_track5: u64
+    ) {
+        let game_in_progress = storage.races.at(game_id).read();
+
+        // Store the player's track totals (validates they haven't been set yet)
+        storage.races.at(game_id).write(game_in_progress.set_player_scores(player, total_track1, total_track2, total_track3, total_track4, total_track5));
     }
-    #[external("utility")]
-    unconstrained fn get_vote(candidate: Field) -> Field {
-        storage.tally.at(candidate).read()
+
+    // Determines the winner after both players have revealed their scores
+    // Can only be called after the game's end_block (time limit expired)
+    // Compares track totals and declares the player who won more tracks as winner
+    //
+    // Winner determination:
+    // - Compare each of the 5 tracks
+    // - Player with higher total on a track wins that track
+    // - Player who wins 3+ tracks wins the game (best of 5)
+    // - Updates the winner's career win count
+    #[external("public")]
+    fn finalize_game(
+        game_id: Field
+    ) {
+        let game_in_progress = storage.races.at(game_id).read();
+
+        // Calculate winner by comparing track scores (validates game has ended)
+        let winner = game_in_progress.calculate_winner(context.block_number());
+
+        // Update the winner's total win count in the public leaderboard
+        let previous_wins = storage.win_history.at(winner).read();
+        storage.win_history.at(winner).write(previous_wins + 1);
     }
 }