https://github.com/aztecprotocol/aztec-starter
A simple aztec contract + test to get started.
https://github.com/aztecprotocol/aztec-starter
Last synced: 30 days ago
JSON representation
A simple aztec contract + test to get started.
- Host: GitHub
- URL: https://github.com/aztecprotocol/aztec-starter
- Owner: AztecProtocol
- License: apache-2.0
- Created: 2023-12-20T01:41:12.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-06-08T02:36:15.000Z (8 months ago)
- Last Synced: 2025-06-09T05:14:50.320Z (8 months ago)
- Language: TypeScript
- Size: 1.17 MB
- Stars: 75
- Watchers: 11
- Forks: 74
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Aztec Starter
## 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`.
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.
## Devnet
This repo connects to a locally running Aztec local network by default, but can be configured to connect to the devnet by specifying `AZTEC_ENV=devnet` in a `.env` file or by prefixing a command e.g. `AZTEC_ENV=devnet yarn deploy`.
[](https://github.com/AztecProtocol/aztec-starter/stargazers)
[](https://github.com/AztecProtocol/aztec-starter/network/members)
[](https://github.com/AztecProtocol/aztec-starter/actions)
[](https://github.com/AztecProtocol/aztec-starter/commits/main)
[](https://github.com/AztecProtocol/aztec-starter/blob/main/LICENSE)
[](https://discord.gg/aztec)
[](https://x.com/aztecnetwork)
---
## 🚀 **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).
Get the **local network, aztec-cli, and other tooling** with this command:
```bash
bash -i <(curl -s https://install.aztec.network)
```
Install the correct version of the toolkit with:
```bash
export VERSION=3.0.0-devnet.6-patch.1
aztec-up && docker pull aztecprotocol/aztec:$VERSION && docker tag aztecprotocol/aztec:$VERSION aztecprotocol/aztec:latest
```
### Environment Configuration
This project uses JSON configuration files to manage environment-specific settings:
- `config/local-network.json` - Configuration for local network development
- `config/devnet.json` - Configuration for devnet deployment
The system automatically loads the appropriate configuration file based on the `ENV` environment variable. If `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 Devnet
All scripts support a `::devnet` suffix to automatically use devnet configuration:
```bash
yarn deploy::devnet # Deploy to devnet
yarn test::devnet # Run tests on devnet
yarn deploy-account::devnet # Deploy account to devnet
yarn interaction-existing-contract::devnet # Interact with devnet contracts
```
The `::devnet` suffix automatically sets `ENV=devnet`, loading configuration from `config/devnet.json`.
---
## 📦 **Install Packages**
```bash
yarn install
```
---
## 🏗 **Compile**
```bash
aztec compile
```
or
```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 tests** defined in `index.test.ts` inside `./src/test/e2e`, as well as the [Aztec Testing eXecution Environment (TXE)](https://docs.aztec.network/developers/guides/smart_contracts/testing) tests defined in [`first.nr`](./src/test/first.nr) (imported in the contract file with `mod test;`).
Note: The Typescript tests spawn an instance of the local network 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_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.
### 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 TestWallet 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.
## ❗ **Error Resolution**
: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.
### 🔄 **Update Node.js and Noir Dependencies**
```bash
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.
```bash
yarn update
```
You may need to update permissions with:
```bash
chmod +x .github/scripts/update_contract.sh
```
## 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:
