Skip to content

CLAUDE.md

Latest commit

 

History

History
293 lines (201 loc) · 10.4 KB

CLAUDE.md

File metadata and controls

293 lines (201 loc) · 10.4 KB
Raw

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.

Repository Overview

This is a collection of Aztec smart contract examples written in Noir, designed for learning Aztec development hands-on. The repository contains multiple example projects showcasing different aspects of Aztec's zero-knowledge smart contract platform.

Key Technologies

  • Aztec: A privacy-first Layer 2 on Ethereum using zero-knowledge proofs
  • Noir: A domain-specific language for writing zero-knowledge circuits
  • nargo: The Noir compiler for compiling vanilla Noir circuits (install via noirup)
  • aztec compile: Aztec CLI command for compiling Aztec contracts (includes post-processing)
  • aztec-wallet: CLI tool for interacting with Aztec contracts
  • Node.js/npm/yarn: JavaScript runtime and package managers (Node.js v22+ recommended)

Project Structure

aztec-examples/
├── custom-note/             # Defining a custom private note type
├── note-send-proof/         # Off-chain note-hash proofs + Vite frontend
│   ├── circuits/           # Vanilla Noir circuit (aztec-nargo)
│   ├── uint-note/          # Local copy of the uint-note note library
│   ├── sample-contract/    # Aztec contract under test
│   ├── scripts/            # Proof/data generation (TypeScript)
│   ├── tests/              # Jest integration tests
│   └── vite/               # React frontend
├── prediction-market/       # Private CSMM prediction market (uint-note partial notes)
├── recursive_verification/  # Verify Noir UltraHonk proofs inside an Aztec contract
│   ├── circuit/            # Noir circuit that generates proofs (proves x ≠ y)
│   ├── contract/           # Aztec contract that verifies Noir proofs
│   ├── scripts/            # TypeScript utilities for proof generation and deployment
│   ├── tests/              # Vitest integration test suite
│   └── data.json           # Generated proof data (created by `yarn data`)
├── test-wallet-webapp/      # Vite/React app: embedded wallet + deploy + tx
└── .github/workflows/       # CI: one *-tests.yml per tested example

Development Commands

Prerequisites

# Install Aztec tools (required)
bash -i <(curl -s https://install.aztec.network)

# Set specific version (examples may require different versions)
aztec-up 5.0.0-rc.1  # For recursive_verification

Building Contracts

From a contract directory containing Nargo.toml:

# Compile an Aztec contract (includes post-processing)
aztec compile

# For recursive_verification example (using yarn)
yarn ccc  # Compiles contract and generates TypeScript bindings

Building Vanilla Noir Circuits

The compatible nargo (version 1.0.0-beta.22) is bundled with the Aztec CLI at ~/.aztec/current/bin/aztec-nargo. As of Aztec v4.3.0, bundled binaries are exposed only under their aztec- prefixed names — invoke aztec-nargo (a drop-in for nargo) rather than the bare name, which is no longer on PATH. Ensure ~/.aztec/current/bin is on your PATH (the Aztec installer adds this automatically).

# Verify nargo is available
aztec-nargo --version

# Compile a vanilla Noir circuit
aztec-nargo compile

Running Local Development Environment

# Start Aztec local network (node + PXE)
aztec start --local-network

# Start without PXE (when using aztec-wallet)
NO_PXE=true aztec start --local-network

# Import test accounts to aztec-wallet
aztec-wallet import-test-accounts

Testing

# Run tests (starts TXE automatically)
aztec test

# Or manually with TXE for debug output:
# Terminal 1: Start Testing Execution Environment
aztec start --txe --port=8081

# Terminal 2: Run tests with output
aztec-nargo test --oracle-resolver http://127.0.0.1:8081 --show-output

# Run integration tests (recursive_verification)
cd recursive_verification
yarn test

# Run full test suite with compilation
./run-tests.sh

Deploying and Interacting with Contracts

# Deploy a contract (without constructor)
aztec-wallet deploy --no-init target/<contract-name>.json --from test0 --alias <alias>

# Call a contract function
aztec-wallet send <function_name> --args <args...> --contract-address <alias> -f test0

# Simulate a function call (read-only)
aztec-wallet simulate <function_name> --args <args...> --contract-address <alias> -f test0

# Profile gas/gates for a function
aztec-wallet profile <function_name> --args <args...> --contract-address <alias> -f test0

Performance Analysis

# Generate gate flamegraph for private functions
SERVE=1 aztec flamegraph target/<contract>.json <function_name>

# Profile gate count for deployed contract
aztec-wallet profile <function_name> --args <args...> --contract-address <alias> -f test0

Example-Specific Workflows

Recursive Verification Example

Complete workflow for the proof verification example:

# 1. Install dependencies (requires Node.js and yarn)
cd recursive_verification
yarn install

# 2. Verify nargo is available (bundled with Aztec CLI)
aztec-nargo --version

# 3. Compile the Noir circuit
cd circuit && aztec-nargo compile && cd ..

# 4. Compile the Aztec contract
yarn ccc  # Runs: aztec compile && aztec codegen

# 5. Generate proof data (UltraHonk proof, verification key, public inputs)
yarn data  # Creates data.json with proof for x=1, y=2

# 6. Start Aztec local network (in separate terminal)
aztec start --local-network

# 7. Deploy contract and verify proof on-chain
yarn recursion  # Deploys ValueNotEqual contract and verifies proof

# 8. Run tests
yarn test

# Optional: Run circuit tests
cd circuit && aztec-nargo test

Contract Architecture

Aztec Contract Structure

Aztec contracts use the #[aztec] macro and define functions as either:

  • #[private]: Executed client-side with zero-knowledge proofs
  • #[public]: Executed on-chain by the protocol
  • #[initializer]: Constructor-like functions for setup
  • #[unconstrained]: View functions that don't modify state

Key considerations:

  • Private functions: Optimize for circuit size (gates), unconstrained functions don't add gates
  • Public functions: Optimize for gas cost, unconstrained functions do add cost
  • Unconstrained functions: Used for computation that doesn't need proving, must verify results in constrained context

Proof Verification Pattern (recursive_verification)

The recursive verification example demonstrates:

  • Off-chain proof generation: Noir circuits compiled and executed with Barretenberg
  • On-chain verification: Using bb_proof_verification::verify_honk_proof in Aztec contracts
  • UltraHonk proving system: Generates proofs with 458 field elements, verification keys with 115 fields
  • VK Hash Storage: Verification key hash stored in PublicImmutable storage, readable from private context
  • Public state management: Using PublicMutable for per-user counters

Testing Pattern

Tests use the Testing Execution Environment (TXE):

use dep::aztec::test::helpers::test_environment::TestEnvironment;

#[test]
unconstrained fn test_function() {
    let mut env = TestEnvironment::new();
    let user = env.create_account_contract(1);
    env.impersonate(user);

    // Deploy and interact with contracts
    let contract = env.deploy_self("ContractName").without_initializer();
    // Test contract functions
}

Dependencies

Aztec Contract Dependencies

Aztec contracts specify dependencies in Nargo.toml:

[dependencies]
aztec = { git = "https://github.com/AztecProtocol/aztec-nr/", tag = "v5.0.0-rc.1", directory = "aztec" }
uint_note = { git = "https://github.com/AztecProtocol/aztec-nr/", tag = "v5.0.0-rc.1", directory = "uint-note" }

Version Compatibility: All examples use the same Aztec version:

  • All examples: v5.0.0-rc.1

JavaScript/TypeScript Dependencies

TypeScript projects use:

  • @aztec/aztec.js: Aztec SDK for contract deployment and interaction
  • @aztec/accounts: Account management for Aztec
  • @aztec/bb.js: Barretenberg backend for proof generation (recursive_verification)
  • @aztec/noir-noir_js: Noir.js for circuit execution (recursive_verification)

Runtime Requirements

  • Node.js: v22+ for all TypeScript examples
  • yarn: Package manager used across the TypeScript examples
  • Docker: Required for running Aztec local network
  • Memory: 8GB+ RAM recommended for proof generation

CI/CD

GitHub Actions workflows automatically test examples on pull requests to next (and pushes to next). Each tested example has its own workflow under .github/workflows/:

  • recursive-verification-tests.yml
  • prediction-market-tests.yml
  • note-send-proof-tests.yml
  • test-wallet-webapp-tests.yml
  • custom-note-tests.yml

Each workflow installs the pinned Aztec CLI (AZTEC_VERSION), starts a local network when the example's tests need one, compiles circuits/contracts, and runs that example's tests (uploading logs on failure). The custom-note workflow is contract-only, so it just compiles.

Common Issues and Solutions

Issue: "Cannot find module './contract/artifacts/'"

Solution: Run yarn ccc or aztec compile to generate contract artifacts

Issue: "Failed to connect to PXE"

Solution: Ensure Aztec local network is running with aztec start --local-network

Issue: "Proof verification failed"

Solution: Regenerate proof data after circuit changes with yarn data

Issue: Memory issues during proof generation

Solution: Close other applications or use a machine with more RAM (8GB+ recommended)

Issue: Version compatibility errors

Solution: Check the Aztec version required for each example and set with aztec-up <version>

Best Practices

  1. Version Management: Always check and set the correct Aztec version for each example
  2. Testing: Run tests locally before pushing changes
  3. Documentation: Update READMEs when modifying examples
  4. Clean Builds: When encountering issues, try removing target/, artifacts/, and node_modules/ directories
  5. Local Network Management: Always ensure local network is running when deploying/testing contracts