aztec-starter

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 120 Open GitHub ↗

A simple aztec contract + test to get started.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Aztec Starter

**For AI agents:** 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.

## Local Network

This repo is meant to be a starting point for learning to write Aztec contracts and tests on the Aztec local network (local development environment). It includes an example contract, useful commands in `package.json` and helpful scripts in `./scripts`.

**New to Aztec? Start with the [Onboarding Guide](./ONBOARDING.md)** — a progressive walkthrough that takes Ethereum developers from reading code to deploying contracts.

You can find the **Pod Racing Game contract** in `./src/main.nr`. A simple integration test is in `./src/test/e2e/index.test.ts`.

The Pod Racing contract is a two-player competitive game where players allocate points across 5 tracks over multiple rounds. The game demonstrates Aztec's private state capabilities - round choices remain private until players reveal their final scores.

## Testnet

This repo connects to a locally running Aztec local network by default, but can be configured to connect to testnet:

- **Testnet**: `AZTEC_ENV=testnet` — test network on the `testnet` branch

Set the variable in a `.env` file or prefix a command, e.g. `AZTEC_ENV=testnet yarn deploy`.

> **Branch model:** Local development code lives on the `next` branch. Testnet code lives on the `testnet` branch. Each branch may run a different Aztec version.

[![GitHub Repo stars](https://img.shields.io/github/stars/AztecProtocol/aztec-starter?logo=github&color=yellow)](https://github.com/AztecProtocol/aztec-starter/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/AztecProtocol/aztec-starter?logo=github&color=blue)](https://github.com/AztecProtocol/aztec-starter/network/members)
[![Build](https://github.com/AztecProtocol/aztec-starter/actions/workflows/update.yaml/badge.svg)](https://github.com/AztecProtocol/aztec-starter/actions)
[![GitHub last commit](https://img.shields.io/github/last-commit/AztecProtocol/aztec-starter?logo=git)](https://github.com/AztecProtocol/aztec-starter/commits/next)
[![License](https://img.shields.io/github/license/AztecProtocol/aztec-starter)](https://github.com/AztecProtocol/aztec-starter/blob/next/LICENSE)
[![Discord](https://img.shields.io/badge/discord-join%20chat-5B5EA6)](https://discord.gg/aztec)
[![Twitter Follow](https://img.shields.io/twitter/follow/aztecnetwork?style=flat&logo=twitter)](https://x.com/aztecnetwork)

</div>

---

## 🚀 **Getting Started**

Use **Node.js version 22.15.0**.

[Start your codespace from the codespace dropdown](https://docs.github.com/en/codespaces/getting-started/quickstart).

Install the **Aztec toolkit** (local network, CLI, and other tooling) at the correct version:

```bash
export VERSION=5.0.0-rc.2
curl -fsSL "https://install.aztec.network/${VERSION}" | VERSION="${VERSION}" bash -s
```

Then install project dependencies:

### Environment Configuration

This project uses JSON configuration files to manage environment-specific settings:

- `config/local-network.json` - Configuration for local network development
- `config/testnet.json` - Configuration for testnet deployment

The system automatically loads the appropriate configuration file based on the `AZTEC_ENV` environment variable. If `AZTEC_ENV` is not set, it defaults to `local-network`.

The configuration files contain network URLs, timeouts, and environment-specific settings. You can modify these files to customize your development environment.

### Running on Local Network (Local Development)

Start the local network with:

```bash
aztec start --local-network
```

Run scripts and tests with default local network configuration:

```bash
yarn compile && yarn codegen  # Compile contract and generate TS
yarn deploy       # Deploy to local network
yarn test         # Run tests on local network
```

### Running on Testnet

All scripts support a `::testnet` suffix:

```bash
yarn deploy::testnet              # Deploy to testnet
yarn test::testnet                # Run tests on testnet
yarn deploy-account::testnet      # Deploy account to testnet
yarn interaction-existing-contract::testnet  # Interact with testnet contracts
```

The `::testnet` suffix sets `AZTEC_ENV=testnet`, loading configuration from `config/testnet.json`.

> **Note:** Testnet code should be developed and merged into the `testnet` branch, not `next`. The `testnet` branch may use a different Aztec version than the `next` branch.

---

## 📦 **Install Packages**

```bash
yarn install
```

---

## 🏗 **Compile**

```bash
aztec compile
```

```bash
yarn compile
```

---

## 🔧 **Codegen**

Generate the **contract artifact JSON** and TypeScript interface:

```bash
yarn codegen
```

---

:warning: Tests and scripts set up and run the Private Execution Environment (PXE) and store PXE data in the `./store` directory. If you restart the local network, you will need to delete the `./store` directory to avoid errors.

## Transaction Profiling

**Make sure the local network is running before profiling.**

```bash
aztec start --local-network
```

Then run an example contract deployment profile with:

```bash
yarn profile
```

You can specify the bb binary path for faster native proving, e.g.

```bash
BB_BINARY_PATH="/home/user/.bb/bb" BB_WORKING_DIRECTORY="/tmp/bb" CRS_PATH="/tmp/bb" yarn profile
```

See the [demo-wallet for an example](https://github.com/AztecProtocol/demo-wallet/blob/main/app/scripts/copyBB.js) of how to fetch the appropriate bb binary (version and OS) in an application.

## 🧪 **Test**

**Make sure the local network is running before running tests.**

```bash
aztec start --local-network
```

Then test with:

```bash
yarn test
```

Testing will run the **TypeScript E2E tests** defined in `./src/test/e2e/`, as well as the [Aztec Testing eXecution Environment (TXE)](https://docs.aztec.network/developers/guides/smart_contracts/testing) tests defined in [`./src/test/`](./src/test/) (imported in the contract file with `mod test;`).

Note: The TypeScript tests require a running local network. The Noir TXE tests (`yarn test:nr`) run without a network.

---

## Scripts

You can find a handful of scripts in the `./scripts` folder.

- `./scripts/deploy_account.ts` is an example of how to deploy a schnorr account.
- `./scripts/deploy_contract.ts` is an example of how to deploy a contract.
- `./scripts/fees.ts` is an example of how to pay for a contract deployment using various fee payment methods.
- `./scripts/multiple_wallet.ts` is an example of how to deploy a contract from one wallet instance and interact with it from another.
- `./scripts/profile_deploy.ts` shows how to profile a transaction and print the results.
- `./scripts/interaction_existing_contract.ts` demonstrates how to interact with an already deployed pod racing contract, including creating games.
- `./scripts/get_block.ts` is an example of how to retrieve and display block information from the Aztec node.
- `./scripts/read_debug_logs.ts` demonstrates the `#[external("utility")]` pattern for client-side state inspection — runs a full game lifecycle, then calls the `debug_game_state` utility function to read public state and log it via `debug_log_format` without an on-chain transaction. Run with `yarn read-logs` (`LOG_LEVEL` is pre-configured by the yarn script).

### Utility Functions

The `./src/utils/` folder contains utility functions:

- `./src/utils/create_account_from_env.ts` provides functions to create Schnorr accounts from environment variables (SECRET, SIGNING_KEY, and SALT), useful for account management across different environments.
- `./src/utils/setup_wallet.ts` provides a function to set up and configure the EmbeddedWallet with proper configuration based on the environment.
- `./src/utils/deploy_account.ts` provides a function to deploy Schnorr accounts to the network with sponsored fee payment, including key generation and deployment verification.
- `./src/utils/sponsored_fpc.ts` provides functions to deploy and manage the SponsoredFPC (Fee Payment Contract) for handling sponsored transaction fees.
- `./config/config.ts` provides environment-aware configuration loading, automatically selecting the correct JSON config file based on the `ENV` variable.

## Simulate Before Send

Always call `.simulate()` before `.send()` for every state-changing transaction. Simulation runs the transaction locally and surfaces revert reasons immediately. Without it, a failing transaction will hang until the send timeout with an opaque error.

```typescript
// Simulate first — surfaces revert reasons instantly
await contract.methods.create_game(gameId).simulate({ from: address });

// Then send — only after simulation succeeds
await contract.methods.create_game(gameId).send({
    from: address,
    fee: { paymentMethod },
    wait: { timeout }
});
```

For deployments, store the deploy request to avoid constructing it twice:

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

## ❗ **Error Resolution**

### 🔄 **Update Contract from Monorepo**

Get the **contract code from the monorepo**. The script will look at the versions defined in `./Nargo.toml` and fetch that version of the code from the monorepo:

```bash
chmod +x .github/scripts/update_contract.sh
.github/scripts/update_contract.sh <version-tag>
```

## AI Agent Contributor Guide

This repository includes an [AGENTS.md](./AGENTS.md) file with detailed
instructions for setting up your environment, running tests, and creating
pull requests. Please read it before contributing changes.

### 💬 Join the Community:

aztec-starter

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README