Add CLAUDE.md with project guidance for Claude Code

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: critesjosh

CLAUDE.md

@@ -0,0 +1,115 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Aztec Starter — a Pod Racing game contract built with Noir on the Aztec network. Two players allocate points across 5 tracks over 3 rounds with private state; scores are revealed at the end (commit-reveal pattern). The player who wins more tracks (best of 5) wins.
+
+**Aztec version: `4.0.0-devnet.2-patch.1`** — pinned across `Nargo.toml`, `package.json`, `config/*.json`, and README. All must stay in sync when updating.
+
+## Build & Development Commands
+
+Always use `yarn compile` or `aztec compile` to compile contracts, never `nargo compile`.
+
+```bash
+yarn compile              # Compile Noir contract (aztec compile)
+yarn codegen              # Generate TS artifacts from compiled contract
+yarn compile && yarn codegen  # Full rebuild (always run both together)
+yarn clean                # Remove compiled artifacts (src/artifacts, target)
+yarn clear-store          # Remove PXE data store (rm -rf ./store)
+```
+
+## Testing
+
+Two independent test systems:
+
+```bash
+yarn test:nr              # Noir TXE tests — no network needed, runs in simulator
+yarn test:js              # TypeScript E2E tests — requires running local network
+yarn test                 # Runs both (test:js then test:nr)
+```
+
+**E2E tests require a running local network:**
+
+```bash
+aztec start --local-network   # Start local network first
+rm -rf ./store                # Always clear store after network restart
+```
+
+Jest config: `jest.integration.config.json` — 600s test timeout, ESM mode via `ts-jest`, matches `./src/**/*.test.ts`.
+
+Run a single E2E test:
+
+```bash
+NODE_NO_WARNINGS=1 node --experimental-vm-modules $(yarn bin jest) --no-cache --runInBand --config jest.integration.config.json -t "test name pattern"
+```
+
+## Deployment & Scripts
+
+All scripts support `::devnet` suffix for devnet targeting (sets `AZTEC_ENV=devnet`):
+
+```bash
+yarn deploy               # Deploy contract to local network
+yarn deploy::devnet       # Deploy contract to devnet
+yarn deploy-account       # Deploy a Schnorr account
+yarn multiple-wallet      # Deploy from one wallet, interact from another
+yarn profile              # Profile a transaction deployment
+```
+
+## Environment Configuration
+
+- `AZTEC_ENV` variable selects config: `local-network` (default) or `devnet`
+- Config files: `config/local-network.json`, `config/devnet.json`
+- `config/config.ts` — singleton `ConfigManager` loads the appropriate JSON based on `AZTEC_ENV`
+- `.env` stores secrets (SECRET, SIGNING_KEY, SALT, contract keys) — never commit
+
+## Project Structure
+
+**Contract (Noir):**
+
+- `src/main.nr` — PodRacing contract: public functions (`create_game`, `join_game`, `finalize_game`), private functions (`play_round`, `finish_game`), and internal `#[only_self]` validators
+- `src/race.nr` — `Race` struct: public game state (players, round counters, track scores, end_block)
+- `src/game_round_note.nr` — `GameRoundNote`: private note storing one round's point allocation per player
+
+**Tests (Noir TXE):**
+
+- `src/test/mod.nr` — test module root
+- `src/test/pod_racing.nr` — unit tests using TXE simulator (`env.call_public`, `env.call_private`, `env.public_context_at`)
+- `src/test/utils.nr` — test setup helper
+- `src/test/helpers.nr` — test helpers (game setup, allocation strategies)
+
+**Tests (TypeScript E2E):**
+
+- `src/test/e2e/index.test.ts` — full game lifecycle tests against real network
+- `src/test/e2e/accounts.test.ts` — account tests
+- `src/test/e2e/public_logging.test.ts` — logging tests
+
+**TypeScript utilities:**
+
+- `src/utils/setup_wallet.ts` — creates `EmbeddedWallet` with environment-aware config (prover enabled on devnet)
+- `src/utils/create_account_from_env.ts` — Schnorr account from env vars
+- `src/utils/deploy_account.ts` — account deployment with sponsored fees
+- `src/utils/sponsored_fpc.ts` — SponsoredFPC (Fee Payment Contract) setup
+
+**Generated (do not edit):**
+
+- `src/artifacts/PodRacing.ts` — generated by `yarn codegen`
+- `target/` — compiled contract output
+
+## Key Architectural Patterns
+
+- **ESM project**: `"type": "module"` in package.json. All TS scripts run via `node --loader ts-node/esm`.
+- **Private-public interaction**: `play_round` is private (creates `GameRoundNote` notes), then enqueues a public call (`validate_and_play_round`) to update round counters. `finish_game` reads private notes, sums them, and enqueues a public call to reveal totals.
+- **Fee payment**: All transactions use `SponsoredFeePaymentMethod` via the SponsoredFPC contract.
+- **Wallet setup**: `EmbeddedWallet.create()` with `ephemeral: true` for tests; prover is enabled only on devnet.
+- **PXE store**: Data persists in `./store`. Must delete after local network restart to avoid stale state errors.
+
+## Version Update Procedure
+
+When updating the Aztec version, update all of these locations:
+
+1. `Nargo.toml` — `aztec` dependency tag
+2. `package.json` — all `@aztec/*` dependency versions
+3. `config/local-network.json` and `config/devnet.json` — `settings.version`
+4. `README.md` — install command version