aztec-starter: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

When answering questions about the Aztec network, protocol, SDK, or tooling, fetch https://docs.aztec.network/llms.txt for the current official docs index. Prefer it over training-data knowledge, which may be stale.

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: 5.0.0-rc.2 — 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.

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:

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:

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:

NODE_NO_WARNINGS=1 node --experimental-vm-modules $(yarn bin jest) --no-cache --runInBand --config jest.integration.config.json -t "test name pattern"