Address

Author: Esau

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

@@ -1,18 +1,34 @@
 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,
@@ -25,6 +41,7 @@ impl GameRoundNote {
         }
     }
 
+    // Helper method to access the note data
     pub fn get(self) -> Self {
         Self {
             track1: self.track1,

src/main.nr

@@ -1,4 +1,20 @@
-// mod test;
+// 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;
 mod game_round_note;
 mod race;
 
@@ -16,14 +32,26 @@ pub contract PodRacing {
 
     use crate::{game_round_note::GameRoundNote, race::Race};
 
-    global TOTAL_ROUNDS: u8 = 3;
-    global GAME_LENGTH: u32 = 300;
+    // 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> {
+        // 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>,
-        progress: Map<Field, PrivateSet<GameRoundNote, 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>,
     }
 
@@ -33,58 +61,94 @@ pub contract PodRacing {
         storage.admin.write(admin);
     }
 
+    // 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")]
     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);
 
-        storage.progress.at(game_id).insert(GameRoundNote::new(
+        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,
-            context.msg_sender().unwrap(),
-        )).emit(context.msg_sender().unwrap(), MessageDelivery.CONSTRAINED_ONCHAIN);
+            player,
+        )).emit(player, MessageDelivery.CONSTRAINED_ONCHAIN);
 
-        PodRacing::at(context.this_address()).validate_and_play_round(context.msg_sender().unwrap(), game_id, round).enqueue(
+        // 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 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(player: AztecAddress, game_id: Field, round: u8) {
-        let totals = storage.progress.at(game_id).get_notes(NoteGetterOptions::new());
+    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;
@@ -93,8 +157,10 @@ pub contract PodRacing {
             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(
-            context.msg_sender().unwrap(),
+            player,
             game_id,
             total_track1,
             total_track2,
@@ -106,6 +172,9 @@ pub contract PodRacing {
         );
     }
 
+    // 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")]
     #[internal]
     fn validate_finish_game_and_reveal(
@@ -118,20 +187,31 @@ pub contract PodRacing {
         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));
     }
 
+    // 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);
     }
 }

src/race.nr

@@ -3,28 +3,43 @@ use dep::aztec::protocol_types::{
     traits::{Deserialize, Serialize, Packable},
 };
 
+// Race struct stores the public state of a game
+// This data is visible to everyone and tracks game progress
 #[derive(Deserialize, Serialize, Eq, Packable)]
 pub struct Race {
+    // Player addresses
     pub player1: AztecAddress,
     pub player2: AztecAddress,
-    pub total_rounds: u8,
+
+    // Game configuration
+    pub total_rounds: u8,  // Always 3 for this game
+
+    // Round progress tracking (which round each player is on)
     pub player1_round: u8,
     pub player2_round: u8,
+
+    // Player 1's final revealed track totals (sum of all rounds)
     // Nested structs not working on this version
     pub player1_track1_final: u64,
     pub player1_track2_final: u64,
     pub player1_track3_final: u64,
     pub player1_track4_final: u64,
     pub player1_track5_final: u64,
+
+    // Player 2's final revealed track totals (sum of all rounds)
     pub player2_track1_final: u64,
     pub player2_track2_final: u64,
     pub player2_track3_final: u64,
     pub player2_track4_final: u64,
     pub player2_track5_final: u64,
+
+    // Block number when the game expires (for timeout enforcement)
     pub end_block: u32,
 }
 
 impl Race {
+    // Creates a new game with player1 set, waiting for player2 to join
+    // All track scores initialized to 0, rounds start at 0
     pub fn new(player1: AztecAddress, total_rounds: u8, end_block: u32) -> Race {
         Self {
             player1,
@@ -46,8 +61,11 @@ impl Race {
         }
     }
 
+    // Adds player2 to an existing game
+    // Validates that player1 exists, player2 slot is empty, and player2 is not the same as player1
     pub fn join(self, player2: AztecAddress) -> Race {
         assert(!self.player1.eq(AztecAddress::zero()) & self.player2.eq(AztecAddress::zero()));
+        assert(!self.player1.eq(player2));
 
         Self {
             player1: self.player1,
@@ -69,10 +87,15 @@ impl Race {
         }
     }
 
+    // Increments a player's round counter after they complete a round
+    // Validates:
+    // - Round number is within bounds (1-3)
+    // - Player is playing rounds sequentially (can't skip rounds)
     pub fn increment_player_round(self, player: AztecAddress, round: u8) -> Race {
         assert(round < self.total_rounds + 1);
 
         let ret = if player.eq(self.player1) {
+            // Ensure player1 is playing the next sequential round
             assert(round == self.player1_round + 1);
 
             Option::some(Self {
@@ -94,7 +117,7 @@ impl Race {
                 end_block: self.end_block
             })
         } else if player.eq(self.player2) {
-            assert(round == self.player1_round + 1);
+            assert(round == self.player2_round + 1);
 
             Option::some(Self {
                 player1: self.player1,
@@ -121,8 +144,12 @@ impl Race {
         ret.unwrap()
     }
 
+    // Sets a player's final track scores after they reveal them
+    // Validates that scores haven't been set yet (all must be 0)
+    // This is called from finish_game after summing private round notes
     pub fn set_player_scores(self, player: AztecAddress, track1_final: u64, track2_final: u64, track3_final: u64, track4_final: u64, track5_final: u64) -> Race {
         let ret = if player.eq(self.player1) {
+            // Ensure player1 hasn't already revealed (prevents double-reveal exploit)
             assert(
                 self.player1_track1_final +
                 self.player1_track2_final +
@@ -183,12 +210,24 @@ impl Race {
         ret.unwrap()
     }
 
+    // Determines the game winner by comparing track scores
+    // Winner is whoever won more tracks (best of 5)
+    //
+    // Game rules:
+    // - Compare player1 vs player2 score on each of the 5 tracks
+    // - Higher score wins that track
+    // - Ties go to player2
+    // - Player who wins 3+ tracks wins the game
+    //
+    // Validates that the game has expired (current block > end_block)
     pub fn calculate_winner(self, current_block_number: u32) -> AztecAddress {
+        // Ensure game time limit has passed before declaring winner
         assert(current_block_number > self.end_block);
 
         let mut player1_wins = 0;
         let mut player2_wins = 0;
 
+        // Count how many tracks each player won
         if self.player1_track1_final > self.player2_track1_final {
             player1_wins = player1_wins + 1;
         } else {
@@ -219,6 +258,7 @@ impl Race {
             player2_wins = player2_wins + 1;
         };
 
+        // Return address of player who won more tracks
         if (player1_wins > player2_wins) {
             self.player1
         } else {