V5 Node migration guide

Aztec
1

v5.0.0-rc.1 operator changelog (from v4.3.1)

Overview

Migration difficulty: High

v5 is a major protocol upgrade with tons of new node features including a new archiver DB schema, overhauled RPC APIs, and mandatory proposer pipelining. All nodes in a network must upgrade together.

Please note that in following release candidates leading up to the first stable v5, there will be further breaking changes, which will be communicated as they arise.

Before you upgrade

  1. Run the HA database migration before starting any v5 node (see HA signing database migration).
  2. Audit your environment variables against the removed and renamed tables below. Removed vars are silently ignored; renamed vars must be updated.
  3. Update any scripts or monitoring that call JSON-RPC methods. All method prefixes have changed (see JSON-RPC namespace rename).

Breaking changes

Major version bump (v4 to v5)

The protocol major version has changed. v4 and v5 nodes cannot participate in the same network. If you start a v5 node against a v4 rollup, the node will detect the mismatch and enter standby mode automatically, consuming minimal resources until the L1 rollup is upgraded. Once the upgrade goes live, the node will exit standby and start syncing without manual intervention.

Migration: You can deploy v5 nodes ahead of the network upgrade. They will wait in standby until the v5 rollup becomes canonical on L1, then start automatically.

JSON-RPC namespace rename

The canonical JSON-RPC method prefixes have been renamed:

v4.x prefix v5.x prefix
node_* aztec_*
nodeAdmin_* aztecAdmin_*
nodeDebug_* aztecDebug_*

The old node_*, nodeAdmin_*, nodeDebug_*, and p2p_* namespaces are still registered as aliases in v5.0.0-rc.1 for backward compatibility. They will be removed in a future release. New integrations should use the aztec_* prefixes.

Migration: The old prefixes still work in v5.0.0-rc.1, so this is not an immediate breaking change. However, you should migrate monitoring scripts, Grafana dashboards, and client calls to the new prefixes before they are removed.

Block and checkpoint RPC API overhaul

Many separate RPC methods for querying blocks and checkpoints have been consolidated. Instead of calling a different method depending on whether you’re looking up by number, hash, or chain tip, v5 uses a single method where you pass the lookup criteria as a parameter.

Example: looking up a block

// v4 — separate method per lookup style
getBlock(5)
getBlockByHash("0x...")
getBlockByArchive("0x...")

// v5 — one method, pass what you're looking up by
getBlock({ number: 5 })
getBlock({ hash: "0x..." })
getBlock({ archive: "0x..." })

Example: querying chain tip block numbers

// v4
getProvenBlockNumber()
getCheckpointedL2BlockNumber()
getFinalizedL2BlockNumber()

// v5
getBlockNumber({ tag: "proven" })
getBlockNumber({ tag: "checkpointed" })
getBlockNumber({ tag: "finalized" })

Full list of removed methods and their replacements:

Removed method Replacement
getL2Tips() getChainTips()
isL1ToL2MessageSynced() getL1ToL2MessageCheckpoint()
getBlockHeader(n) getBlock({ number: n }) then read .header
getCheckpointedBlocks() getBlocks({ ... }, { onlyCheckpointed: true })
getBlockByHash(hash) getBlock({ hash })
getBlockByArchive(archive) getBlock({ archive })
getProvenBlockNumber() getBlockNumber({ tag: 'proven' })
getCheckpointedL2BlockNumber() getBlockNumber({ tag: 'checkpointed' })
getFinalizedL2BlockNumber() getBlockNumber({ tag: 'finalized' })

New block and checkpoint APIs:

// Blocks — look up by { number }, { hash }, { archive }, or { tag }
getBlock(query)
getBlocks(query)       // range: { from, limit } or { epoch }
getBlockData(query)    // block + metadata (L1 publish info, attestations)
getBlocksData(query)

// Checkpoints — look up by { number }, { slot }, or { tag }
getCheckpoint(query)
getCheckpoints(query)
getCheckpointData(query)
getCheckpointsData(query)

// Chain tips and block/checkpoint numbers
getBlockNumber({ tag })
getCheckpointNumber({ tag })
getChainTips()

New RPC methods:

Method Description
aztec_getL2ToL1MembershipWitness(...) Server-side L2-to-L1 message membership witness computation (previously client-only)
aztec_getPredictedMinFees(...) Fee predictions for upcoming slots, accounting for L1 fee transitions and congestion growth
aztec_getSyncedL2SlotNumber() Current synced L2 slot
aztec_getSyncedL2EpochNumber() Current synced L2 epoch
aztec_getSyncedL1Timestamp() Current synced L1 timestamp
aztec_getPeers() Peer list (moved from p2p_* namespace)

Migration: Replace all calls to the old methods with their v5 equivalents shown above. See the node API reference for the full updated API.

Log retrieval API redesign

The four log-retrieval methods have been replaced with two tag-based query methods:

getPrivateLogsByTags(query)
getPublicLogsByTags(query)

getContractClassLogs and getPublicLogs(LogFilter) have been removed. Use getPublicLogsByTags instead.

The old getPrivateLogsByTags(tags, page) positional-argument signature is also gone. It now takes a single query parameter with fields for tags, block range, cursor, and per-tag pagination.

Migration: Replace all log retrieval calls with the new tag-based methods.

Archiver and PXE database schema bumps

Store v4.3.1 schema v5.0.0-rc.1 schema Behavior on mismatch
Archiver (LMDB) 5 7 Auto-wipe
PXE data 5 8 Auto-wipe
HA signer (Postgres) 1 2 Crash (manual migration required)
Local signing protection (LMDB) New in v5 2 Crash (schema mismatch policy is throw)

The archiver and PXE stores will automatically wipe on schema mismatch. The HA Postgres database and local signing protection LMDB store will not auto-wipe. They throw an error on schema mismatch, requiring explicit migration.

Migration: For archiver and PXE, no action needed. For HA Postgres, see HA signing database migration. For local signing protection, the store is new in v5 and will initialize cleanly on a fresh start.

HA signing database migration

The HA signing Postgres database schema changed from version 1 to 2 (added checkpoint_number column).

The node does not auto-migrate. At startup, db.initialize() checks the schema version and throws if it doesn’t match:

Database schema version 1 is outdated (expected 2).
Please run migrations: aztec migrate-ha-db up --database-url <url>

Run the migration before starting any v5 node:

aztec migrate-ha-db up --database-url postgresql://<user>:<password>@<host>:<port>/<database>

For Kubernetes deployments, use an init container or a separate Job:

initContainers:
  - name: db-migrate
    image: aztecprotocol/aztec:<v5-image-tag>
    command: ['node', '--no-warnings', '/usr/src/yarn-project/aztec/dest/bin/index.js', 'migrate-ha-db', 'up']
    env:
      - name: DATABASE_URL
        valueFrom:
          secretKeyRef:
            name: db-credentials
            key: connection-string

Migration: Run the migration once before starting your v5 validator pods. Concurrent migration runs from multiple pods are safe (idempotent) but unnecessary.

Network-wide consensus config enforcement

Certain environment variables are now enforced to match the network-wide config. If your local value differs from the generated network defaults, the node will refuse to start unless ALLOW_OVERRIDING_NETWORK_CONFIG=true is set.

Enforced variables include:

Timing/protocol consensus:

  • ETHEREUM_SLOT_DURATION, AZTEC_SLOT_DURATION, AZTEC_EPOCH_DURATION
  • SEQ_BLOCK_DURATION_MS, MAX_BLOCKS_PER_CHECKPOINT, CHECKPOINT_PROPOSAL_SYNC_GRACE_SECONDS

Network identity and L1 deployment parameters:

  • L1_CHAIN_ID, AZTEC_TARGET_COMMITTEE_SIZE, staking lags and thresholds
  • AZTEC_MANA_TARGET, AZTEC_PROVING_COST_PER_MANA, AZTEC_INITIAL_ETH_PER_FEE_ASSET
  • Governance and slashing round sizes, quorums, slash amounts

Node-side slashing offense parameters:

  • All SLASH_* penalty and detection parameters

Migration: Remove any custom overrides for these variables. If you have a legitimate reason to override, set ALLOW_OVERRIDING_NETWORK_CONFIG=true.

Timetable always enforced

The SEQ_ENFORCE_TIME_TABLE env var was removed. The sequencer now always enforces sub-slot deadlines: each block must be built within its allocated time window, and the checkpoint must be assembled and submitted within the slot boundary.

SEQ_BLOCK_DURATION_MS (network default: 6000 ms) controls the length of each block sub-slot and is a consensus-critical value enforced by network-wide config. The timetable uses it to derive how many blocks fit in a checkpoint. All nodes must agree on this value or they will reject each other’s proposals.

Migration: Remove SEQ_ENFORCE_TIME_TABLE from your configuration. Do not override SEQ_BLOCK_DURATION_MS unless you understand the consensus implications.

Removed CLI flags and subcommands

Removed Notes
aztec start --archiver The archiver is no longer a standalone startable component. It runs embedded in the node.
aztec start --pxe Same as archiver.

Migration: Remove --archiver and --pxe flags from all start commands, docker-compose files, and Helm values. Use --archiver.<option> sub-flags for archiver configuration.

Removed environment variables

These variables are no longer recognized. If still set, they will be silently ignored:

Removed variable Reason
ARCHIVER_MAX_LOGS Log retrieval API redesigned
P2P_DROP_TX Removed
P2P_SLOT_CHECK_INTERVAL_MS Removed
SEQ_ENFORCE_TIME_TABLE Timetable is always enforced
SEQ_GAS_PER_BLOCK_ALLOCATION_MULTIPLIER Renamed to SEQ_PER_BLOCK_ALLOCATION_MULTIPLIER
SLASH_FACTORY_CONTRACT_ADDRESS Removed
SLASH_MAX_PENALTY_PERCENTAGE Removed
SLASH_MIN_PENALTY_PERCENTAGE Removed
SLASH_PRUNE_PENALTY Removed
TX_COLLECTION_DISABLE_SLOW_DURING_FAST_REQUESTS Slow tx collection path removed
TX_COLLECTION_FILE_STORE_SLOW_BACKOFF_BASE_MS Slow tx collection path removed
TX_COLLECTION_FILE_STORE_SLOW_BACKOFF_MAX_MS Slow tx collection path removed
TX_COLLECTION_FILE_STORE_SLOW_DELAY_MS Slow tx collection path removed
TX_COLLECTION_FILE_STORE_SLOW_WORKER_COUNT Slow tx collection path removed
TX_COLLECTION_RECONCILE_INTERVAL_MS Removed
TX_COLLECTION_SLOW_NODES_INTERVAL_MS Slow tx collection path removed
TX_COLLECTION_SLOW_REQ_RESP_INTERVAL_MS Slow tx collection path removed
TX_COLLECTION_SLOW_REQ_RESP_TIMEOUT_MS Slow tx collection path removed
VALIDATOR_REEXECUTE Reexecution is always enabled
VALIDATOR_REEXECUTE_DEADLINE_MS Removed with reexecute flag
SENTINEL_HISTORIC_PROVEN_PERFORMANCE_LENGTH_IN_EPOCHS Renamed (see below)
SLASH_ATTEST_DESCENDANT_OF_INVALID_PENALTY Renamed (see below)

Renamed environment variables

v4.x name v5.x name
SEQ_GAS_PER_BLOCK_ALLOCATION_MULTIPLIER SEQ_PER_BLOCK_ALLOCATION_MULTIPLIER
SENTINEL_HISTORIC_PROVEN_PERFORMANCE_LENGTH_IN_EPOCHS SENTINEL_HISTORIC_EPOCH_PERFORMANCE_LENGTH_IN_EPOCHS
SLASH_ATTEST_DESCENDANT_OF_INVALID_PENALTY SLASH_PROPOSE_DESCENDANT_OF_CHECKPOINT_WITH_INVALID_ATTESTATIONS_PENALTY

Migration: Search your configuration files and deployment manifests for the old names and replace them.

New environment variables

These are the operator-relevant additions. Most have sensible defaults and don’t need to be set unless you’re tuning specific behavior.

Variable Default Description
ARCHIVER_SKIP_HISTORICAL_LOGS_CHECK false Skip the startup check that probes L1 for historical Rollup logs. Set to true if your L1 RPC prunes old logs.
ETHEREUM_HTTP_TIMEOUT_MS 10000 HTTP timeout for L1 RPC calls. Increase if you hit TimeoutError on slow or public L1 RPCs.
BLOB_PREFER_FILESTORES false Prefer file stores over consensus client for blob retrieval.
BLOB_FILE_STORE_TIMEOUT_MS 10000 Timeout for blob file store HTTP requests.
P2P_PEER_BAN_DURATION_SECONDS 86400 How long to ban misbehaving peers (24h default, in-memory only, cleared on restart).
P2P_RPC_PRICE_BUMP_PERCENTAGE 10 Fee bump percentage required for RPC tx replacement. Set to 0 to disable.
PUBLISHER_FUNDING_THRESHOLD unset Min ETH balance (in ether, e.g. 0.1) below which a publisher gets auto-funded. Unset disables funding.
PUBLISHER_FUNDING_AMOUNT unset Amount of ETH (in ether, e.g. 0.5) to send when funding a publisher. Unset disables funding.
OTEL_MIN_TRACE_DURATION_MS 10 Minimum trace duration to export. Set to 0 to export all traces.
OTEL_BSP_MAX_QUEUE_SIZE 2048 Max completed spans queued before export.

Troubleshooting

Node crashes with “Database schema not initialized”

You are running in HA mode and have not run the Postgres migration. Run:

aztec migrate-ha-db up --database-url postgresql://<user>:<password>@<host>:<port>/<database>

Node crashes with “Database schema version 1 is outdated”

Same as above. The v5 HA signer expects schema version 2.

Node refuses to start with “network consensus config mismatch”

You have custom overrides for consensus-critical env vars. Either remove the overrides or set ALLOW_OVERRIDING_NETWORK_CONFIG=true.

Node enters standby mode

This is expected if you started your v5 node before the network upgrade has happened. The node will automatically exit standby and begin syncing once the v5 rollup becomes canonical on L1. No action needed.

2 Likes