Benchmarking Overview

Relevant source files

The following files were used as context for generating this wiki page:

• benchmarks/token_contract.benchmark.ts
• benchmarks/tokenized_vault_contract.benchmark.ts
• benchmarks/nft_contract.benchmark.ts
• benchmarks/escrow_contract.benchmark.ts
• benchmarks/logic_contract.benchmark.ts
• Nargo.toml
• package.json
• src/ts/test/utils.ts

The benchmarking system in the Aztec Standards repository provides a structured framework for measuring the performance and resource consumption of Aztec smart contracts. It utilizes a specialized base class and context from the @defi-wonderland/aztec-benchmark package to execute contract functions in a controlled environment, specifically targeting token primitives, vaults, NFTs, and escrow logic.

These benchmarks are integrated into the project's build and test lifecycle, allowing developers to track the efficiency of privacy-preserving operations such as private transfers, shielded minting, and cross-contract interactions.

Sources: package.json:20, benchmarks/token_contract.benchmark.ts:10-12, Nargo.toml:11-16

Architecture and Framework

The benchmarking architecture is built on a class-based inheritance model. Each benchmark suite extends a base Benchmark class and implements three core lifecycle methods: setup, getMethods, and teardown.

Benchmark Lifecycle

1. Setup: Prepares the Aztec environment, including deploying contracts and initializing accounts.
2. Get Methods: Defines the specific contract interactions (actions and callers) to be measured.
3. Teardown: Cleans up the environment, typically by stopping the Sandbox or removing temporary data directories.

The diagram above illustrates the sequential execution flow of a single benchmark class.
Sources: benchmarks/token_contract.benchmark.ts:31-137, src/ts/test/utils.ts:51-84

Data Structures

Benchmarks use an extended BenchmarkContext to pass state between lifecycle methods. Common properties include:

Property	Type	Description
wallet	Wallet	The Aztec wallet used for deployments and transactions.
accounts	AztecAddress[]	List of pre-funded accounts for testing.
cleanup	() => Promise<void>	Callback to destroy the testing environment.
contract	Contract	The specific artifact instance being benchmarked (e.g., Token, NFT).

Sources: benchmarks/token_contract.benchmark.ts:16-23, benchmarks/nft_contract.benchmark.ts:12-18

Benchmarked Modules

The system covers five primary contract modules as defined in the project configuration.

1. Token Benchmarks

Focuses on the performance of AIP-20 compliant tokens, covering both public and private state transitions. Key actions include mint_to_private, transfer_private_to_public, and transfer_private_to_private.

Sources: benchmarks/token_contract.benchmark.ts:65-115

2. Tokenized Vault (AIP-4626) Benchmarks

Measures the overhead of vault operations that handle underlying assets and yield-bearing shares. This includes complex scenarios involving authWitnesses for authorized private-to-public transfers.

The sequence shows the interaction between the vault and its underlying asset during a private deposit.
Sources: benchmarks/tokenized_vault_contract.benchmark.ts:58-100

3. Escrow and Logic Benchmarks

Evaluates the "Logic Library" pattern where a Logic contract manages a minimal private Escrow contract. Benchmarks measure:

• Key Derivation: deriving public keys from secret keys.
• Address Prediction: calculating the escrow address based on salt and keys.
• Withdrawals: moving tokens and NFTs from a private escrow to a recipient.

Sources: benchmarks/logic_contract.benchmark.ts:74-97, benchmarks/escrow_contract.benchmark.ts:89-115

4. NFT Benchmarks

Covers unique digital asset operations, mirroring the token benchmarks but applied to non-fungible types (AIP-721).
Sources: benchmarks/nft_contract.benchmark.ts:34-72

Execution and Configuration

Benchmarks are configured in Nargo.toml and triggered via the yarn bench script.

"scripts": {
  "bench": "NODE_NO_WARNINGS=1 aztec-benchmark --suffix _base"
}

Sources: package.json:20, Nargo.toml:11-16

Environment Setup

Benchmarks typically use setupTestSuite(true) from the test utilities. Setting the proverEnabled flag to true is critical for benchmarking as it ensures the prover is active, providing realistic transaction times and resource metrics that include witness generation and proof construction.

// src/ts/test/utils.ts
export const setupTestSuite = async (proverEnabled: boolean = false) => {
  if (proverEnabled) {
    await Barretenberg.destroySingleton();
  }
  const dataDirectory = join(tmpdir(), `aztec-standards-${randomBytes(8).toString('hex')}`);
  const pxeConfig = { ...config, dataDirectory, proverEnabled };
  // ...
};

Sources: src/ts/test/utils.ts:51-61

Summary

The benchmarking suite provides a standardized way to measure Aztec contract performance by extending a base class and defining specific interactions across Token, NFT, Vault, and Escrow implementations. By integrating with the Aztec prover and using realistic authWitness flows, the system ensures that performance metrics reflect actual usage on the Aztec Network.