Aztec Starter

Sandbox

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

You can find the Easy Private Voting contract in ./src/main.nr. A simple integration test is in ./src/test/e2e/index.test.ts.

Testnet

If you are interested in trying out this repo with the testnet, try the testnet branch. The testnet branch is more suitable for simple interactions with the testnet via script, or as a reference to see how to do something against a live, remote network. The main branch should be used for getting started with writing contracts and rapid, local testing.

---

🚀 Getting Started

Use Node.js version 22.15.0.

Start your codespace from the codespace dropdown.

Get the sandbox, aztec-cli, and other tooling with this command:

bash -i <(curl -s https://install.aztec.network)

Install the correct version of the toolkit with:

aztec-up 2.0.2

Environment Configuration

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

• config/sandbox.json - Configuration for local sandbox development
• config/testnet.json - Configuration for testnet deployment

The system automatically loads the appropriate configuration file based on the ENV environment variable. If ENV is not set, it defaults to sandbox.

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

Running on Sandbox (Local Development)

Start the sandbox with:

aztec start --sandbox

Run scripts and tests with default sandbox configuration:

yarn deploy       # Deploy to sandbox
yarn test         # Run tests on sandbox

Running on Testnet

All scripts support a ::testnet suffix to automatically use testnet configuration:

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 automatically sets ENV=testnet, loading configuration from config/testnet.json.

---

📦 Install Packages

yarn install

---

🏗 Compile

aztec-nargo compile

or

yarn compile

---

🔧 Codegen

Generate the contract artifact JSON and TypeScript interface:

yarn codegen

---

⚠️ Tests and scripts set up and run the Private Execution Environment (PXE) and store PXE data in the ./store directory. If you restart the sandbox, you will need to delete the ./store directory to avoid errors.

Transaction Profiling

Make sure the sandbox is running before profiling.

aztec start --sandbox

Then run an example contract deployment profile with:

yarn profile

🧪 Test

Make sure the sandbox is running before running tests.

aztec start --sandbox

Then test with:

yarn test

Testing will run the TypeScript tests defined in index.test.ts inside ./src/test/e2e, as well as the Aztec Testing eXecution Environment (TXE) tests defined in first.nr (imported in the contract file with mod test;).

Note: The Typescript tests spawn an instance of the sandbox to test against, and close it once the TS tests are complete.

---

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_pxe.ts is an example of how to deploy a contract from one PXE 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 voting contract, including casting votes and checking vote counts.

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_pxe.ts provides a function to set up and configure the Private Execution Environment (PXE) service 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.
• ./config/config.ts provides environment-aware configuration loading, automatically selecting the correct JSON config file based on the ENV variable.

❗ Error Resolution

⚠️ Tests and scripts set up and run the Private Execution Environment (PXE) and store PXE data in the ./store directory. If you restart the sandbox, you will need to delete the ./store directory to avoid errors.

🔄 Update Node.js and Noir Dependencies

yarn update

🔄 Update Contract

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.

yarn update

You may need to update permissions with:

chmod +x .github/scripts/update_contract.sh

AI Agent Contributor Guide

This repository includes an 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: