aztec-starter: Instructions file for Codex

Repository guidelines for Codex agents

This repository contains TypeScript scripts and Noir contracts for the Aztec network. Follow these guidelines when contributing:

Setup

• Use Node.js v22 with Yarn.
• Install dependencies with yarn install.
• The Aztec CLI (aztec) must be installed at the version matching Nargo.toml and package.json.
• Start the Aztec local network with aztec start --local-network before running E2E tests or scripts. This is not needed for compilation or Noir unit tests.
• After restarting the local network, always run rm -rf ./store to clear stale PXE data.

Development

• This is an ESM project ("type": "module" in package.json).
• Compile contracts with yarn compile and generate TypeScript artifacts with yarn codegen.
• Use four spaces for indentation in TypeScript and scripts.
• Do not commit generated artifacts (src/artifacts, target, or store folders).
• Never edit src/artifacts/PodRacing.ts directly; it is generated by yarn codegen.
• To target devnet instead of local network, set AZTEC_ENV=devnet (e.g. AZTEC_ENV=devnet yarn deploy).

Testing

There are two independent test systems:

• Noir TXE tests (yarn test:nr): Run in the TXE simulator, no network required.
• TypeScript E2E tests (yarn test:js): Require a running local network.
• yarn test runs both. Ensure tests pass before committing.

Simulate Before Send

Always call .simulate() before .send() for every state-changing transaction. Simulation runs the transaction locally and surfaces revert reasons immediately instead of waiting for the send timeout with an opaque error.

// Simulate first
await contract.methods.create_game(gameId).simulate({ from: address });
// Then send
await contract.methods.create_game(gameId).send({
    from: address,
    fee: { paymentMethod },
    wait: { timeout }
});

For deployments, store the deploy request to reuse it:

const deployRequest = MyContract.deploy(wallet, ...args);
await deployRequest.simulate({ from: address });
const contract = await deployRequest.send({ ... });