Zksync Era

Skill based on zkSync Era (ZK Stack), generated from sources/zksync-era. Doc path: sources/zksync-era/docs/src/ (specs, guides).

zkSync Era is an EVM-compatible ZK rollup that settles on Ethereum. It uses a register-based zkEVM (Era VM), state-diff data availability, and the Boojum proof system. This skill focuses on protocol mechanics, L1 contracts, VM/compiler behavior, L1–L2 messaging, and pubdata for agents that implement tooling, integrate with L1/L2, or reason about execution and finality.

Core References

Features

L1–L2 and communication

Prover and compiler

Transactions and data

Generation Info

• Source: sources/zksync-era
• Git SHA: fdaeec3870ef5c52065aa492cfa96713b42c6756
• Generated: 2026-02-24
• Doc path: sources/zksync-era/docs/src/ (specs: specs/, guides: guides/)

L1 Smart Contracts

The main L1 interface for a single L2 is a Diamond proxy (EIP-2535–style): no external functions, only a fallback that delegatecalls into facets. Facets can be freezable; freezing the diamond blocks access to all freezable facets (dangerous if the upgrade facet is freezable).

Main facets

• GettersFacet: View/pure and diamond loupe; must not be frozen.
• AdminFacet: Governor/validator/system params, freeze/unfreeze, upgrade execution. Controlled by Governance (protocol upgrades) and Admin (e.g. validator permissions).
• MailboxFacet: L1↔L2 communication, native ETH bridging (legacy), censorship-resistance path. L1→L2 = request stored in queue, executed on L2; L2→L1 = messages/logs in pubdata.
• ExecutorFacet: Accepts L2 batches in three steps—commitBatches (timestamp, logs, prepare for proof), proveBatches (verify zk-proof), executeBatches (finalize state, process L1→L2 queue, save Merkle tree of L2 logs).

System log keys (e.g. from SystemLogKey) are emitted by L2 system contracts and validated on L1 during commit/execute (e.g. L2_TO_L1_LOGS_TREE_ROOT_KEY, STATE_DIFF_HASH_KEY, PRIORITY_TXN_HASH_KEY).

Bridges

Separate from the Diamond: L1ERC20Bridge (legacy ERC20), L1AssetRouter (ETH/WETH), L2SharedBridge (L2 side). Lock/mint and burn/unlock via L1↔L2 messaging.

Governance and ValidatorTimelock

Governance: Schedules and executes upgrades (transparent or shadow); delay-based execution or instant (Security Council only). ValidatorTimelock: Sits between validator EOA and Diamond; adds a delay between commit and execute so the chain can freeze on suspicious activity. Node reads executionDelay() from the contract.

Agent usage

• When integrating with L1: call Getters for state, Mailbox for L1→L2 requests, and never assume Admin/Mailbox are unfrozen without checking.
• For batch submission: use ExecutorFacet’s commit → prove → execute flow; respect ValidatorTimelock delay when present.
• L1→L2 sender on L2: if msg.sender != tx.origin, L2 sender is AddressAliasHelper.applyL1ToL2Alias(msg.sender) (L1 address + fixed offset).

<!-- Source references:

• sources/zksync-era/docs/src/specs/l1_smart_contracts.md

-->

Protocol Overview

ZK Stack powers zero-knowledge rollups that settle on Ethereum. The rollup uses a zkEVM for execution and publishes state diffs plus validity proofs to L1. Key roles: sequencer (collects and executes L2 transactions), prover (produces proofs of correct execution), and L1 contract (verifies proofs and finalizes state).

Flow

1. User submits a transaction to the sequencer (L2 RPC or via L1 priority queue). 2. Sequencer executes the block with the zkEVM and gives a soft confirmation. 3. Prover builds a cryptographic proof of the batch execution (Boojum proof system). 4. Executor facet on L1 receives batch data and proof: commitBatches → proveBatches → executeBatches. 5. L1 contract verifies the proof and updates the rollup state; data availability is provided via state diff (and optionally blobs).

Concepts

• Blocks vs batches: L2 blocks (miniblocks) are created frequently (~2s) for UX/explorer compatibility. L1 batches are the unit of proof: one batch = one Bootloader execution containing many transactions.
• State diff: Instead of publishing full transaction data, the rollup publishes how storage/state changed, reducing cost and enabling shared slot optimizations.
• Boojum: The current proof system; proofs can be generated with ~16GB GPU RAM, supporting decentralized proving.

When to use

• Reasoning about L2 execution, finality, or operator roles.
• Implementing tooling that commits/proves/executes batches or reads L1 contract state.
• Understanding data flow from L2 to L1 (pubdata, proofs).

<!-- Source references:

• sources/zksync-era/docs/src/specs/introduction.md
• sources/zksync-era/docs/src/specs/overview.md

-->

L1–L2 Communication

L1 → L2 (priority operations)

Users call requestL2Transaction (or equivalent) on the L1 Mailbox. The request is appended to the priority queue. The operator includes it in a batch; the Bootloader does not verify signatures for L1-originated txs but maintains:

• numberOfPriorityTransactions
• priorityOperationsRollingHash = rolling keccak of processed priority op hashes

On executeBatches, L1 pops the same number of priority ops from the queue and checks that the rolling hash matches. So the operator cannot forge or reorder priority ops. For each priority tx the Bootloader emits an L2→L1 user log with hash and result (e.g. for proving failed deposits).

Address aliasing: On L2, if msg.sender != tx.origin the effective sender is AddressAliasHelper.applyL1ToL2Alias(msg.sender) (L1 address + 0x1111...1111 offset) to avoid cross-chain replay/identity confusion.

Upgrade transactions: Only during protocol upgrades; one per batch, must be first; hash is emitted via system L2→L1 log before execution so it cannot be replaced by a malicious Keccak precompile.

L2 → L1

• User logs: Contracts call the L1Messenger system contract; logs are hashed into a rolling hash and Merkle tree root is published in pubdata. Proofs of log inclusion use the same leaf format as pre-Boojum for compatibility.
• System logs: Emitted by VM opcodes; fixed set per batch; hashes are part of block commitment and verified on L1.

Bridges: lock on L1 → priority op or message → mint on L2; burn on L2 → L2→L1 message → unlock on L1 via Mailbox finalizeWithdrawal / bridge finalizers.

Agent usage

• When building L1→L2 flows: use the official Mailbox interface; respect gas and fee requirements for priority ops.
• When proving L2→L1 events: use the Merkle tree of L2→L1 logs from executed batches; leaf = keccak256(abi.encodePacked(l2ShardId, isService, txNumberInBlock, sender, key, value)).
• For L2 sender in contracts: if the tx is from L1, expect aliased address unless it’s the origin.

<!-- Source references:

• sources/zksync-era/docs/src/specs/l1_smart_contracts.md (MailboxFacet)
• sources/zksync-era/docs/src/specs/contracts/settlement_contracts/priority_queue/l1_l2_communication/l1_to_l2.md
• sources/zksync-era/docs/src/specs/contracts/settlement_contracts/data_availability/pubdata.md

-->

Prover and ZK Terminology

The prover consumes executed L1 batches and produces validity proofs. It proves state diffs (account/storage changes) so the new state root is correct. Proofs are verified by the Verifier contract on L1.

Terminology (agent-oriented)

• Arithmetization: Encode computation as polynomial equations for ZK verification.
• Constraint system: Variables and gates; a witness is an assignment satisfying all constraints.
• Circuit: Encodes the computation (e.g. one opcode or one sub-computation); geometry = rows/columns of the witness table (~164 base witness columns at ZKsync); constraint degree ≤ 8.
• Lookup table: Predefined table to check relations without extra constraints (e.g. range checks).
• State diffs: Differences in accounts/storage before vs after processing a block; what the prover proves.
• Worker: Multi-threaded proving (e.g. polynomial ops in parallel).

Boojum and circuits

Boojum is the low-level ZK library (era-boojum). zkevm_circuits define the circuits; zkevm_test_harness runs circuit tests. Base layer includes MainVM (opcode execution), CodeDecommitter, Keccak/SHA256 round functions, storage sorter/application, log/L1-message sorters and hashers, etc. Circuits communicate via queues; multiple instances of a circuit type can be combined to handle larger execution (FSM input/output in public inputs).

Running circuit tests

rustup default nightly-2023-08-23
cargo update
cargo test basic_test --release -- --nocapture

(Run from era-zkevm_test_harness; test can take several minutes.)

Agent usage

• When debugging or extending proving: know that the prover proves state diff validity and that circuit geometry and sealing criteria (e.g. pubdata, opcode count) are aligned.
• When reading specs: “satisfiable” = witness satisfies constraints; “verifier” = L1 contract that checks the proof.

<!-- Source references:

• sources/zksync-era/docs/src/specs/prover/zk_terminology.md
• sources/zksync-era/docs/src/specs/prover/getting_started.md
• sources/zksync-era/docs/src/specs/prover/circuits/overview.md

-->