v5 Upgrade (AZUP-2)
The code for the v5 protocol upgrade is ready. v5 is the largest protocol upgrade since the Alpha Network launch. It overhauls how blocks are built and proposed, activates real economic penalties for misbehavior, redesigns the node API surface, and delivers substantial improvements to proving performance, developer tooling, and client-side infrastructure.
This upgrade bundles 13 AZIPs under AZUP-2:
| AZIP | Title |
|---|---|
| AZIP-2 | Governance can’t brick rollups |
| AZIP-5 | Optimise prover rewards for consistency |
| AZIP-6 | Pipelined block building |
| AZIP-7 | Update slashing rules |
| AZIP-8 | Public key hash to mitigate harvest-now risks |
| AZIP-9 | Private immutables |
| AZIP-10 | Add message-signing and fallback public keys |
| AZIP-12 | Reduce protocol contract set |
| AZIP-13 | Barretenberg v5 prover optimisations |
| AZIP-14 | Multiple roots per epoch in Outbox |
| AZIP-16 | Activate equivocation slashing and update economic parameters |
| AZIP-17 | Optimized rollup verifier |
| AZIP-19 | Committee-Attested Fees |
The deploy script, payload contract, and validation tooling are all available for anyone to use.
What v5 is and how to launch it
The governance process is the same as v4:
- Anyone may deploy the v5 rollup contracts, escape hatch, reward distributor, and upgrade payload to Ethereum using the provided forge script.
- Sequencers signal support.
- Token holders vote.
- After the execution delay, the proposal is executed and v5 becomes the canonical rollup.
Deploying the rollup and payload
The deploy script (PR #23752) is self-contained. Every configuration value is hardcoded and cross-checked against live chain state before deployment. No configuration environment is needed.
# Clone and build
git clone https://github.com/AztecProtocol/aztec-packages.git
cd aztec-packages
git checkout v5-next
# Deploy to L1
cd l1-contracts
export PRIVATE_KEY=0x...
export RPC_URL=https://...
export ETHERSCAN_API_KEY=...
export FOUNDRY_PROFILE=production
forge clean
forge build
forge script script/deploy/DeployRollupForUpgradeV5.s.sol \\
--sig 'run()' --rpc-url "$RPC_URL" --private-key "$PRIVATE_KEY" --broadcast --verify --batch-size 8
The script deploys:
- A new
RewardDistributorfor v5 - The v5
Rollupcontract (with realHonkVerifier) - An
EscapeHatchfor the v5 rollup - The
V5UpgradePayload— the single governance payload that:
- Drains the v4
RewardDistributorinto the v5 one - Registers the v5 rollup in the
Registryand updates the reward distributor - Registers the v5 rollup in the
GSE - Activates the escape hatch on the v5 rollup
- Migrates the ~428k AZTEC flush incentive into a v5-bound
FlushRewarder
After deployment, you can re-validate a deployed payload at any time:
forge script script/deploy/DeployRollupForUpgradeV5.s.sol \\
--rpc-url $RPC_URL --sig 'validate(address)' <PAYLOAD_ADDRESS>
Validation asserts the payload’s immutables, action encodings, genesis roots, rollup config, staking queue config, slasher stack, and simulates the full governance lifecycle (propose → vote → execute) against a state snapshot.
Major changes since v4
Proposer pipelining (AZIP-6)
The single biggest architectural change in v5. It fundamentally changes *when* block building happens relative to the slot it targets.
In v4, the proposer for slot N built blocks, collected attestations, and submitted the checkpoint all during slot N. Most of the slot was dead time mostly waiting for L1 inclusion. Users submitting transactions during this window had to wait for the next slot.
In v5, the proposer for slot N builds blocks during slot N-1. By the time slot N starts, the checkpoint is already assembled, attested, and ready for L1 submission.
| Phase | When it happens |
|---|---|
| Block building | Slot N-1 |
| Checkpoint proposal broadcast | Slot N-1 |
| Committee validation and attestation | Slot N-1 |
| L1 submission | Slot N |
Pipelining significantly reduces the dead window and improves user-perceived latency.
Optimistic proving
In v4, the prover node waited for an entire epoch to complete before starting any proving work. In v5, provers begin proving each checkpoint as soon as it’s confirmed on L1, during the epoch, not after it.
A redesigned CheckpointStore gives each checkpoint its own content-addressed prover that starts its sub-tree pipeline immediately on arrival. When the epoch ends, most of the sub-tree work is already done; only the top-tree proof (which ties the checkpoints together) remains. This should dramatically reduce the wall-clock time from “epoch complete” to “proof submitted on L1.”
The redesign also makes the prover resilient to L1 reorgs: if a checkpoint is pruned and re-added with the same content, in-flight sub-tree work is reused rather than replayed.
Slashing: from detection to enforcement (AZIP-7, AZIP-16)
v4 introduced slashing detection infrastructure with all penalties set to zero. v5 flips the switch.
Equivocation is now penalized. DUPLICATE_PROPOSAL and DUPLICATE_ATTESTATION carry LARGE penalties. v5 also detects a new equivocation variant: a proposer that gossips one checkpoint via P2P but submits a different one to L1.
Slash amounts are differentiated. v4 had a single penalty tier (2,000 for everything). v5 splits into three tiers:
| Tier | v4 | v5 (mainnet) |
|---|---|---|
SMALL |
2,000 | 2,000 |
MEDIUM |
2,000 | 5,000 |
LARGE |
2,000 | 5,000 |
With an initial stake of 200,000 and `LARGE = 5,000`, a validator is ejected after three major offenses. This provides operational headroom for a one-off misconfiguration while removing validators with a sustained pattern of misbehavior.
Invalid checkpoint proposals: BROADCASTED_INVALID_CHECKPOINT_PROPOSAL is activated at SMALL, using P2P-based detection without requiring state re-execution.
Proving performance (AZIP-13, AZIP-17)
- bb-prover migrated to bb.js API. All server-side proof verifications moved from spawning `bb`/`bb-avm` binaries to using the bb.js TypeScript API over Unix sockets, eliminating temporary file I/O.
- SRS point compression. BN254 G1 CRS now ships compressed (32 bytes/point vs 64), cutting download from ~6.4GB to ~3.2GB.
- Round-parallel Pippenger MSM. Multi-scalar multiplication throughput improved with round-parallel implementation.
- Lock-free sharded AVM TraceContainer. 4x faster trace generation through lock-free, sharded architecture with atomic pointers.
- Optimized rollup verifier (AZIP-17). The rollup verification contract is optimized for approximately 40% less L1 gas costs.
- tcmalloc in Docker images. ~5%+ performance improvement on multi-core workloads.
- Verifier process pooling. Long-lived bb verifier processes pooled instead of spawned per call.
- provingCostPerMana halved from 25,000,000 to 12,500,000, tracking the ~50% reduction in prover compute time and L1 verification gas. This directly lowers base fees for users.
Cryptography hardening
A massive optimization effort across the protocol circuits and proving system gives a 2.0–2.5x client-side proving speedup for transactions on v5 vs v4.
Notable improvements include a ~2x reduction in ECDSA verification cost, a ~3x speedup for Poseidon2 hashing, a ~50% reduction in protocol circuit gate count, and improved multithreading efficiency.
Governance and L1 contracts (AZIP-2, AZIP-5, AZIP-12, AZIP-14)
- Governance can’t brick rollups (AZIP-2): Governance safeguards prevent actions that could render the rollup inoperable.
- Prover reward optimization (AZIP-5): Prover reward distribution redesigned for consistency, with new `RewardBooster` parameters that incentivize consistent prover participation.
- Reduced protocol contract set (AZIP-12): `AuthRegistry`, `PublicChecks`, and `MultiCallEntrypoint` demoted from canonical protocol contracts, reducing protocol surface area.
- Multiple roots per epoch in Outbox (AZIP-14): The Outbox now supports multiple L2-to-L1 message roots per epoch, removing a bottleneck for cross-chain messaging.
- Epoch-proof fee protection: Fee values are now committed in committee-attested checkpoint headers and verified against stored hashes at proof submission.
Privacy improvements (AZIP-8, AZIP-9, AZIP-10)
- Public key hashing (AZIP-8): Public key hashes replace full public keys in on-chain registrations, mitigating “harvest-now-decrypt-later” risks where adversaries collect public keys today hoping to break the underlying cryptography in the future.
- Private immutables (AZIP-9): An immutables_hash field is added to contract instances and incorporated into address derivation, enabling contracts to have private constructor-set state that is committed to in the contract address.
- Message-signing and fallback keys (AZIP-10): New key types for message signing and key recovery/fallback, expanding the key management capabilities for accounts.
Node JSON-RPC API overhaul
The RPC surface was redesigned. Method prefixes changed from node_* to aztec_* (old prefixes kept as aliases). ~26 block/checkpoint methods consolidated into query-based methods. Four log-retrieval methods collapsed into two tag-based methods. New methods include getPredictedMinFees, getL2ToL1MembershipWitness, and sync status queries.
P2P network
- Fee-based tx rejection and eviction: Transactions below current block fees are rejected outright. Pool txs evicted after blocks if fees drop below the new minimum.
- RPC transaction replacement: Conflicting txs must pay 10% more in priority fee to replace.
- Persistent peer bans: Misbehaving peers banned for 24 hours (previously decayed within ~1 hour).
- IP change detection: Nodes detect public IP changes at runtime and update their ENR.
Publisher funding
Operators running multiple L1 publisher keys can now configure automatic ETH top-ups via PUBLISHER_FUNDING_THRESHOLD and PUBLISHER_FUNDING_AMOUNT, removing the need for manual balance monitoring.
Node operator migration
The v5 operator migration guide has detailed instructions, including:
-
HA signing database migration (must run before starting v5 nodes)
-
Environment variable audit (removed, renamed, and new variables)
-
JSON-RPC method migration guide
-
Consensus config enforcement details
Operators can deploy v5 nodes in standby mode ahead of the upgrade. They will automatically activate once the governance proposal executes.
What’s new for developers in v5
Private messaging and delivery
Offchain note delivery
You can now deliver a private note to its recipient without writing anything on-chain for them to discover. The sender passes the encrypted note data to the recipient directly, out of band, and the recipient’s contract ingests it on sync. This “send and forget” path removes the per-recipient on-chain cost that used to accompany every private transfer.
A handshake registry lets two parties who have never transacted derive the shared tagging secrets non-interactively, so offchain delivery works even on a first interaction.
Constrained onchain delivery
When you do deliver through on-chain logs, that delivery can now run in constrained (proven) contract code instead of relying on unconstrained oracles. The recipient’s tagging index is computed and asserted inside the circuit, so a contract can guarantee correct delivery as part of its own proof rather than trusting the client to have done it.
Custom, reorg-resistant message processing
Contracts can define their own message-processing and note-discovery flows (partial notes, offchain delivery, bespoke schemes) entirely in contract code, and have them survive L1 and L2 reorgs automatically. A fact store holds the intermediate state these flows depend on, which is re-derives it against the canonical chain on every sync.
The result: you can ship a new delivery or discovery scheme without any custom wallet or PXE changes. This is the extensibility story for private messaging, and it’s the reason the reorg handling below exists.
More capable utility functions
Utility (unconstrained) functions gained the building blocks those flows need. They can now read msg_sender, call other utility functions including across contracts, and emit messages. More of a contract’s discovery and delivery logic can live in reusable utility code instead of being special-cased.
PXE syncing and anchor block control
XE no longer has to sync automatically on a fixed cadence. You can drive synchronization manually (PXE_AUTO_SYNC=false) for tighter control over when state updates, and apps can hook into syncing through a custom sync state callback.
You can also choose the anchor block your transactions build and prove against rather than always taking the latest tip: node.getContract and related queries accept an optional reference block, and PXE can sync on top of the proposed chain or stick to a checkpointed or proven tip.
This trades latency against reorg safety on your terms. Underneath, PXE now tracks a canonical block map and handles reorgs automatically.
SQLite with encryption at rest
PXE’s key-value storage moved off IndexedDB to SQLite-wasm (over OPFS in the browser). Stored private state, including notes and keys, is now encrypted at rest with page-level encryption, so it no longer sits in the browser in the clear.
The SQLite backend is also more robust under concurrent access than the old IndexedDB store, and ships in a form that works in stricter browser environments.
Tooling and testing
Faster simulation and tests
Local simulation and test runs are notably faster in v5. Simulations now run without the kernel circuits by default, the test execution environment (TXE) got direct speedups, and you can override public data tree state in simulation to set up scenarios without on-chain writes.
Automatic recompilation in aztec test
aztec test now recompiles your contracts before running them, so a stale build no longer silently runs your old bytecode. You no longer have to remember to rebuild after every change.
Dependency version mismatch detection
Tooling now checks that your aztec-nr dependency version matches your CLI and toolchain, and warns on mismatch instead of failing later with opaque bytecode errors. Contract artifacts are stamped with the aztec version they were built with, and incompatible oracle versions produce a clear error page instead of a crash.
Closing
The v5 code is available on the v5-next branch. The deploy script, payload, and validation tooling are in PR #23752. All 13 AZIPs bundled in AZUP-2 have been accepted through the governance process.