Aztec Protocol Overview

Relevant source files

• .release-please-manifest.json
• CHANGELOG.md
• barretenberg/CHANGELOG.md
• barretenberg/cpp/CMakeLists.txt
• barretenberg/ts/CHANGELOG.md
• barretenberg/ts/package.json
• noir-projects/aztec-nr/Nargo.toml
• noir-projects/aztec-nr/aztec/Nargo.toml
• noir-projects/noir-contracts/contracts/account/ecdsa_k_account_contract/Nargo.toml
• noir-projects/noir-contracts/contracts/account/ecdsa_r_account_contract/Nargo.toml
• noir-projects/noir-contracts/contracts/app/card_game_contract/Nargo.toml
• noir-projects/noir-contracts/contracts/test/avm_gadgets_test_contract/Nargo.toml
• noir-projects/noir-contracts/contracts/test/avm_gadgets_test_contract/src/main.nr
• noir-projects/noir-contracts/contracts/test/avm_test_contract/Nargo.toml
• noir-projects/noir-contracts/contracts/test/avm_test_contract/src/main.nr
• noir-projects/noir-contracts/contracts/test/benchmarking_contract/Nargo.toml
• noir-projects/noir-contracts/contracts/test/static_parent_contract/src/main.nr
• noir-projects/noir-protocol-circuits/crates/types/Nargo.toml
• yarn-project/archiver/src/archiver/archiver.test.ts
• yarn-project/archiver/src/archiver/archiver.ts
• yarn-project/archiver/src/archiver/archiver_store.ts
• yarn-project/archiver/src/archiver/archiver_store_test_suite.ts
• yarn-project/archiver/src/archiver/config.ts
• yarn-project/archiver/src/archiver/kv_archiver_store/block_store.ts
• yarn-project/archiver/src/archiver/kv_archiver_store/kv_archiver_store.ts
• yarn-project/archiver/src/archiver/kv_archiver_store/log_store.ts
• yarn-project/archiver/src/archiver/kv_archiver_store/message_store.ts
• yarn-project/archiver/src/index.ts
• yarn-project/archiver/src/test/mock_l2_block_source.ts
• yarn-project/aztec-node/src/aztec-node/server.ts
• yarn-project/aztec/CHANGELOG.md
• yarn-project/aztec/package.json
• yarn-project/cli/CHANGELOG.md
• yarn-project/cli/package.json
• yarn-project/end-to-end/src/e2e_block_building.test.ts
• yarn-project/end-to-end/src/e2e_multi_validator/e2e_multi_validator_node.test.ts
• yarn-project/end-to-end/src/e2e_p2p/preferred_gossip_network.test.ts
• yarn-project/end-to-end/src/e2e_synching.test.ts
• yarn-project/foundation/src/config/index.ts
• yarn-project/p2p/src/msg_validators/attestation_validator/attestation_validator.ts
• yarn-project/p2p/src/msg_validators/block_proposal_validator/block_proposal_validator.test.ts
• yarn-project/p2p/src/msg_validators/block_proposal_validator/block_proposal_validator.ts
• yarn-project/sequencer-client/src/client/sequencer-client.ts
• yarn-project/sequencer-client/src/config.ts
• yarn-project/sequencer-client/src/publisher/config.ts
• yarn-project/sequencer-client/src/sequencer/README.md
• yarn-project/sequencer-client/src/sequencer/block_builder.test.ts
• yarn-project/sequencer-client/src/sequencer/checkpoint_proposal_job.test.ts
• yarn-project/sequencer-client/src/sequencer/checkpoint_proposal_job.ts
• yarn-project/sequencer-client/src/sequencer/sequencer.test.ts
• yarn-project/sequencer-client/src/sequencer/sequencer.ts
• yarn-project/sequencer-client/src/sequencer/timetable.test.ts
• yarn-project/sequencer-client/src/sequencer/timetable.ts
• yarn-project/sequencer-client/src/sequencer/utils.ts
• yarn-project/stdlib/src/block/l2_block_source.ts
• yarn-project/stdlib/src/interfaces/archiver.test.ts
• yarn-project/stdlib/src/interfaces/archiver.ts
• yarn-project/stdlib/src/interfaces/aztec-node.test.ts
• yarn-project/stdlib/src/interfaces/aztec-node.ts
• yarn-project/stdlib/src/interfaces/l2_logs_source.ts
• yarn-project/stdlib/src/interfaces/validator.ts
• yarn-project/txe/src/state_machine/archiver.ts
• yarn-project/validator-client/src/block_proposal_handler.ts
• yarn-project/validator-client/src/config.ts
• yarn-project/validator-client/src/factory.ts
• yarn-project/validator-client/src/metrics.ts
• yarn-project/validator-client/src/validator.test.ts
• yarn-project/validator-client/src/validator.ts
• yarn-project/validator-client/tsconfig.json

Purpose and Scope

This document provides a high-level introduction to the Aztec Protocol codebase architecture, covering the relationship between Layer 1 (Ethereum) settlement, Layer 2 execution, and the zero-knowledge proving system. It describes the major components, their interactions, and how they fit together to enable privacy-preserving smart contracts on Ethereum.

For detailed information on specific subsystems:

• Repository structure and build system: see Repository Structure and Monorepo Architecture
• Core terminology (epochs, slots, checkpoints, etc.): see Key Concepts and Terminology
• Noir contract development: see Noir Smart Contract Framework
• Public execution environment: see Aztec Virtual Machine (AVM)
• Zero-knowledge proof generation: see Core Cryptography and Proving
• Private transaction handling: see Private Execution Environment (PXE)
• Node operation and consensus: see Node Architecture and Consensus
• Ethereum integration: see Layer 1 Integration

Three-Tier Architecture

The Aztec Protocol follows a three-tier architecture: the Client Layer for user-facing operations, the Node Layer for L2 network coordination, and the Settlement Layer on Ethereum L1 for finality and proof verification.

Sources: yarn-project/aztec-node/src/aztec-node/server.ts136-230 yarn-project/sequencer-client/src/sequencer/sequencer.ts1-230 yarn-project/archiver/src/archiver/archiver.ts1-223

Client Layer

The client layer provides user-facing interfaces for interacting with the Aztec network:

Component	Location	Purpose
aztec.js	yarn-project/aztec.js	TypeScript SDK for contract interaction and wallet management
PXE (Private Execution Environment)	yarn-project/pxe	Handles private transaction simulation, key management, and client-side proving
Wallet implementations	yarn-project/accounts	Account abstraction implementations (ECDSA, Schnorr, etc.)

The PXE runs locally or in a trusted environment and maintains private state for users, simulating private functions before submission to the network.

Sources: yarn-project/aztec.js yarn-project/pxe yarn-project/accounts

Node Layer

The node layer coordinates L2 network operations. The AztecNodeService class orchestrates all major components:

Component	Class/File	Responsibilities
Sequencer	SequencerClient in yarn-project/sequencer-client/src/sequencer/sequencer.ts56	Block building, checkpoint proposal, attestation collection
Archiver	Archiver in yarn-project/archiver/src/archiver/archiver.ts151	Monitors L1 for events, retrieves blob data, stores historical blockchain data
WorldState	WorldStateSynchronizer	Maintains Merkle trees (note hash, nullifier, public data, archive)
P2P	P2P interface	Handles transaction gossip, block proposals, attestations via libp2p
Validator	ValidatorClient in yarn-project/validator-client/src/validator.ts47	Validates block proposals, generates attestations
Prover	ProverClient	Orchestrates proof generation, coordinates with Barretenberg backend

Sources: yarn-project/aztec-node/src/aztec-node/server.ts136-526 yarn-project/sequencer-client/src/sequencer/sequencer.ts56-230 yarn-project/archiver/src/archiver/archiver.ts151-223 yarn-project/validator-client/src/validator.ts47-90

Settlement Layer

The settlement layer on Ethereum L1 provides finality and manages the validator set:

Contract	Purpose
Rollup.sol	Core rollup contract that accepts checkpoint proposals and epoch proofs
Verifier contracts	Verify zero-knowledge proofs submitted by provers
Inbox.sol / Outbox.sol	Handle L1-to-L2 and L2-to-L1 message passing
Governance contracts	Manage validator registration, staking, slashing

The RollupContract class in TypeScript wraps the L1 contract for read/write operations:

Sources: l1-contracts/src/core/Rollup.sol yarn-project/ethereum/src/contracts/rollup_contract.ts

Contract Development and Execution Pipeline

Smart contracts on Aztec are written in Noir and compiled through multiple stages before execution:

Compilation Stages

1. Noir Compilation: Noir source code (.nr files) compiles to:

   • Brillig bytecode for unconstrained/private function execution
   • ACIR (Abstract Circuit Intermediate Representation) for constraint generation

2. AVM Transpilation: The avm-transpiler converts Brillig bytecode to AVM bytecode for public functions that execute on-chain

3. Execution Environments:

   • Private functions: Execute in the ACVM (Abstract Circuit Virtual Machine) within the PXE
   • Public functions: Execute in the AVM (Aztec Virtual Machine) within the sequencer

4. Proving: Barretenberg generates zero-knowledge proofs for both private and public execution

Sources: noir-projects/aztec-nr avm-transpiler barretenberg/cpp

Constants Synchronization

Protocol constants are defined once in Noir and generated for all languages:

This ensures values like MAX_NOTE_HASHES_PER_TX, AZTEC_EPOCH_DURATION, etc. stay synchronized across the entire stack.

Sources: noir-projects/noir-protocol-circuits/crates/types/src/constants.nr

Transaction Lifecycle

A complete transaction flows through multiple stages from user submission to L1 finality:

Transaction Processing Steps

1. Private Execution (PXE):

   • User submits transaction via aztec.js
   • PXE simulates private functions using ACVM
   • Generates client-side proof (private kernel proof)
   • Creates public call enqueuing data
   • Method: PXE.sendTx()

2. P2P Propagation:

   • Transaction broadcasts to P2P network
   • Validators receive and validate format
   • Transaction enters sequencer mempool
   • Class: P2P.sendTx() in yarn-project/p2p

3. Sequencer Selection:

   • Sequencer checks if it's proposer for current slot
   • Selects transactions from mempool
   • Method: Sequencer.work() in yarn-project/sequencer-client/src/sequencer/sequencer.ts201

4. Public Execution:

   • AVM executes public functions for each transaction
   • Generates side effects (storage writes, nullifiers, note hashes)
   • Creates execution trace
   • Component: PublicProcessor executing AVM bytecode

5. Block Building:

   • Sequencer assembles transactions into a block
   • Creates block header with state commitments
   • Class: BlockBuilder in yarn-project/sequencer-client

6. Attestation Collection:

   • Validators receive block proposal
   • Validate block integrity and re-execute
   • Sign attestation if valid
   • Sequencer collects committee attestations
   • Class: ValidatorClient.attestToProposal() in yarn-project/validator-client/src/validator.ts197-230

7. Checkpoint Proposal:

   • Sequencer submits checkpoint to L1 with attestations
   • L1 Rollup contract verifies quorum
   • Checkpoint becomes pending
   • Method: SequencerPublisher.enqueueProposeCheckpoint() in yarn-project/sequencer-client/src/publisher/sequencer-publisher.ts

8. Proof Generation:

   • Prover generates ZK proofs for the epoch
   • Aggregates block proofs into epoch proof
   • Submits to L1
   • Component: ProverClient coordinating with Barretenberg

9. L1 Finalization:

   • L1 verifier contract checks proof validity
   • Updates proven tip if valid
   • Checkpoint becomes proven and finalized

Sources: yarn-project/pxe yarn-project/sequencer-client/src/sequencer/sequencer.ts201-229 yarn-project/validator-client/src/validator.ts197-230 yarn-project/sequencer-client/src/publisher/sequencer-publisher.ts

Core Abstractions and Data Structures

Blocks, Checkpoints, and Epochs

The protocol organizes data into a hierarchical structure:

Abstraction	Type	Description
Transaction	Tx in yarn-project/stdlib/src/tx/tx.ts	Single user operation with private and public components
Block	L2Block / L2BlockNew in yarn-project/stdlib/src/block/l2_block.ts	Batch of transactions with header and tx effects
Checkpoint	Checkpoint in yarn-project/stdlib/src/checkpoint/checkpoint.ts	One or more blocks proposed together, unit of L1 submission
Epoch	Epoch boundaries defined by slot ranges	Period after which proofs must be submitted

Sources: yarn-project/stdlib/src/tx/tx.ts yarn-project/stdlib/src/block/l2_block.ts yarn-project/stdlib/src/checkpoint/checkpoint.ts

State Representation

The protocol maintains several Merkle trees for state commitments:

Each tree is identified by MerkleTreeId and maintained by the WorldStateSynchronizer. Trees use LMDB for persistent storage.

Sources: yarn-project/world-state yarn-project/stdlib/src/trees

Key Storage Classes

Component	Location	Storage Technology	Purpose
ArchiverDataStore	yarn-project/archiver/src/archiver/archiver_store.ts24	LMDB	Historical blocks, logs, contracts
KVArchiverDataStore	yarn-project/archiver/src/archiver/kv_archiver_store/kv_archiver_store.ts27	LMDB	Concrete implementation
WorldStateSynchronizer	yarn-project/world-state	LMDB	Merkle tree state
PXEDatabase	yarn-project/pxe	KV store	User private state

Sources: yarn-project/archiver/src/archiver/archiver_store.ts24-50 yarn-project/archiver/src/archiver/kv_archiver_store/kv_archiver_store.ts27-35

Data Synchronization Flow

The archiver continuously synchronizes L1 data and propagates it to other components:

Archiver Responsibilities

The Archiver class (defined in yarn-project/archiver/src/archiver/archiver.ts151) performs:

1. L1 Event Monitoring: Listens for CheckpointProposed, MessageSent, and other events
2. Blob Retrieval: Fetches EIP-4844 blob data containing transaction data
3. Block Decoding: Reconstructs L2 blocks from blob data
4. Storage: Persists blocks, logs, and contract data to ArchiverDataStore
5. Sync Status: Tracks L1 block number and L2 block tips

Key method: Archiver.sync() at yarn-project/archiver/src/archiver/archiver.ts300-450

World State Synchronization

The WorldStateSynchronizer updates Merkle trees based on archiver data:

1. Subscribes to new blocks from archiver
2. Applies tx effects to note hash, nullifier, public data trees
3. Updates archive tree with block roots
4. Provides query interface for state commitments

Sources: yarn-project/archiver/src/archiver/archiver.ts151-223 yarn-project/world-state

Node Configuration and Initialization

The AztecNodeService.createAndSync() method (at yarn-project/aztec-node/src/aztec-node/server.ts186-230) initializes the full node stack:

Initialization Sequence

1. Ethereum Client Setup: Create viem public client for L1 interaction
2. L1 Contract Addresses: Resolve addresses from registry
3. Archiver Creation: Initialize with L1 sync starting point
4. World State: Create merkle trees and synchronizer
5. Proof Verifier: Initialize Barretenberg-based verifier
6. P2P Client: Set up libp2p with discovery and gossip
7. Validator Client (optional): Create if not disabled
8. Sequencer (optional): Initialize if validator and not disabled
9. Wait for Sync: Block until initial synchronization completes

Configuration Schema

Configuration is validated against schemas defined in *ConfigSchema objects throughout the codebase. Example from yarn-project/sequencer-client/src/config.ts:

Sources: yarn-project/aztec-node/src/aztec-node/server.ts186-526 yarn-project/sequencer-client/src/config.ts

Summary

The Aztec Protocol implements a three-tier architecture where:

1. Clients execute private functions locally and submit transactions
2. Nodes coordinate L2 consensus, execute public functions, and build blocks
3. L1 Settlement provides finality through proof verification

The system bridges privacy and public execution through a sophisticated pipeline involving:

• Noir contract compilation to Brillig and AVM bytecode
• Private execution in ACVM with client-side proving
• Public execution in AVM with sequencer coordination
• Aggregated proof generation via Barretenberg
• L1 verification and state commitment

Key orchestration classes:

• AztecNodeService coordinates all node components
• Sequencer manages block building and proposal
• Archiver synchronizes L1 data to L2
• ValidatorClient participates in consensus
• PXE handles private user operations

This architecture enables privacy-preserving smart contracts with public state while maintaining Ethereum-level security through zero-knowledge proofs.

Sources: yarn-project/aztec-node/src/aztec-node/server.ts136-789 yarn-project/sequencer-client/src/sequencer/sequencer.ts56-660 yarn-project/archiver/src/archiver/archiver.ts151-1100 yarn-project/validator-client/src/validator.ts47-430 yarn-project/pxe barretenberg/cpp/CMakeLists.txt1-202