Scroll Upgrades

As the team continues to progress on Scroll’s roadmap, we will be upgrading the Scroll network to include new features and improvements.

The following contracts are used to initiate upgrades and execute upgrades after the two-week timelock period:

You can join our Telegram channel for technical updates, which includes future upgrade announcements and on-chain operation events.

Euclid Upgrade

Overview

This upgrade contains five main changes:

• Migration to OpenVM Prover.
• Migration to MPT state commitment.
• Optimized rollup process.
• EIP-7702 and RIP-7212 support.
• Stage-1 readiness.

These changes will result in lower fees, higher throughput, better security, better compatibility, and more advanced features that users and developers on Scroll can enjoy.

Timeline

• Scroll Sepolia
  • Phase 1: March 11th, 2025
  • Phase 2: March 13th, 2025
• Scroll Mainnet
  • Phase 1: April 16th, 2025
  • Phase 2: April 22nd, 2025

Features

OpenVM Prover

Scroll has been among the pioneers of ZK technology through our EVM bytecode compatible halo2 zkEVM. ZK technology has continued to progress rapidly ever since, and now general-purpose RISC-V zkVMs are becoming practical. In the Euclid upgrade we are deprecating our halo2 circuits in favor of a new prover built on top of OpenVM.

The new OpenVM prover offers numerous benefits. Prover code is easier to reason about and to audit. We can better reuse code among different components. We can also reduce proving costs and latency. Finally, the new prover will enable us to prove arbitrarily complex transactions, allowing us to remove the circuit capacity checker module that has been a major bottleneck on sequencer throughput.

MPT State Commitment

Scroll currently uses a zk-friendly state commitment data structure called zktrie. With the new OpenVM prover, it is now practical to prove Ethereum’s state structure: the Merkle-Patricia Trie, also known as MPT. Scroll is now deprecating the zktrie and adopting MPT.

MPT unlocks better sequencer performance and offers better compatibility for dapps relying on L2 state proofs.

Optimized Rollup Process

In Euclid, we are rolling out a series of optimizations to the rollup process. These result in major reductions in Data Availability (DA) overhead, and ultimately lower fees for users.

The main optimizations are:

• Move blob verification from contract code to zk circuits.
• Amortize message queue commitment cost.
• Move L2 block header data from calldata to blobs.
• Commit multiple blobs in a single transaction.
• These changes combined are estimated to reduce batch commitment costs by up to 90%.

In addition, Scroll L2 nodes will deprecate Clique (the current Proof-of-Authority consensus) and will start reading the authorized L2 block signer from the new system config contract on L1.

Powerful Smart Accounts

In Euclid, Scroll is adopting EIP-7702 and RIP-7212. Adopting 7702 in parallel with Ethereum’s Pectra upgrade ensures that Scroll maintains a high degree of compatibility with Ethereum. These features will also allow Scroll users and developers to tap into the latest technologies in smart accounts: Users can add smart contract functionalities to their existing accounts, use passkeys for signing authorizations, and benefit from the emerging UX improvements that these new standards enable.

Stage-1

In Euclid, we are rolling out important safety guarantees that will allow Scroll to reach Stage-1 based on the standard defined by L2BEAT.

Enforced transaction inclusion is a censorship resistance mechanism. It allows users to enqueue a transaction directly from Ethereum, forcing the sequencer to include it. Permissionless batch submission is a mechanism to prevent liveness failure. In the unlikely scenario that the Scroll sequencer stops posting or finalizing batches for an extended period of time, this mechanism allows anyone to step up and start posting and finalizing batches. Both mechanisms force the Scroll sequencer to do its job. As such, they serve as deterrents, and they offer important safety guarantees to the users.

We have also recently transferred control to the Security Council, an independent body of 12 reputable members, forming a 9/12 multisig. The Euclid upgrade will be the first upgrade to be executed by the Security Council.

Compatibility

Node Operators

Phase 1 Changes

• Node operators should migrate to the new MPT version of l2geth. This requires a full resync (from network or from snapshot). We will provide a node release and snapshots later. Please refer to Node Runner State Migration Guideline for node runner state migration guide.
• Zktrie nodes will continue to operate, but they will stop verifying state roots on the received block headers. We encourage node operators to migrate to mpt nodes shortly before Euclid.

Phase 2 Changes

• Node operators need to be aware of stage-1 (permissionless batches). While this mechanism will most likely not be triggered in practice, if it is, it will require manual steps to recover the nodes. We will provide detailed documentation about this in our next node release notes.

Dapps and Indexers

Phase 1 Changes

• State commitment structure switches from zktrie to MPT
• Any dapp relying on zktrie proofs must migrate to MPT proofs
• Batch versions will use v5 and v6 (format identical to previous v4 batches)

Phase 2 Changes

• Batch headers and blob payload will use a new encoding. The batch versions used in phase-2 will be v7.

• Commit batch calldata will no longer contain block headers. Projects that need this information from L1 must fetch and decode the blob.

• Previously, one CommitBatch event would correspond to one commit transaction that carried a single blob. After Euclid phase-2, a single commit transaction can carry multiple batches. This means that indexers should be able to process multiple batches from the same L1 transaction. We maintain the 1 batch = 1 blob semantics and emit a CommitBatch event for each batch.

• In permissionless batch mode, the batch submitter commits and finalizes a single batch in a single atomic step through the newly added commitAndFinalizeBatch function. While this will be rare in practice, indexers should prepare to handle this case.

• Function signatures will change for commit, finalize, and revert batch. Projects that decode transaction calldata should add support for the new signatures. See the contract changes for the detailed function signatures.

  Pre-Euclid-phase-2: commitBatchWithBlobProof, finalizeBundleWithProof, revertBatch

  Post-Euclid-phase-2: commitBatches, finalizeBundlePostEuclidV2, commitAndFinalizeBatch, revertBatch (new).

• The committedBatches array in the ScrollChain will become sparse: Only the last batch hash from each commit batch transaction will be stored in the contract state.

• We will migrate to a new message queue contract (L1MessageQueueV2) that will store messages by a different (rolling) hash.

In addition, L2 unsafe blocks will no longer include a signature or vanity tag in the ExtraData field.

Resources

• Contract changes on GitHub
• DA codec repository

Projects requiring additional guidance should open a ticket on Discord.

DarwinV2 Upgrade

Overview

During internal testing, we identified that blocks may not always be compressible under certain conditions, which leads to unprovable chunks and batches. To fix this issue, a minor upgrade has been conducted so that uncompressed blobs will be enabled when this special case is detected.

Timeline

As this is a security related patch, we bypassed the 7-day timelock mechanism.

• Scroll Sepolia: August 28th, 2024
• Scroll Mainnet: September 2nd, 2024

Compatibility

Sequencer and Follower Nodes (l2geth)

The new node version is v5.7.0. See the release notes for more information.

This upgrade does not change Scroll’s state transition function, so it is backward compatible. However, the format of the batch data committed to Ethereum changes. As a result, nodes that enabled rollup verification (--rollup.verify) must upgrade to be able to follow the chain.

Dapps and Indexers

A change has been implemented to Scroll Mainnet to enhance sequencer throughput, which adjusted the maximum reorg depth to 17 blocks. Previously, the system performed thorough capacity checks within the signer thread to determine whether transactions exceed the circuit limit. While this ensures that all transactions within a block are compliant, it also requires additional CPU resources. We introduced a new circuit capacity checking scheme on Mainnet. The sequencer thread now will continue to perform capacity checks, but in a more approximate manner. In parallel, 16 worker threads will accurately verify the capacity of previous blocks. As a result, a reorg could occur with a maximum depth of 17 blocks, although the likelihood of this is low.

For indexers, the BatchHeader version has been upgraded to 4. This is backward compatible (the only exception is for developers decoding the blob payload, which has changed slightly).

Darwin Upgrade

Overview

This upgrade will reduce gas fees by 34% by using a single aggregated proof for multiple batches, eliminating the need to finalize each batch individually.

• Darwin uses a new V3 batch codec.

• In addition to the previous notions of chunk and batch, we have introduced a new concept called bundle.

  • Chunk: A unit of zkEVM proving, consisting of a list of L2 blocks.
  • Batch: A collection of chunks encoded into one EIP-4844 blob, serving as the unit of Data Availability.
  • Bundle: A series of batches that functions as the unit of finalization.

  The main difference compared to Curie is that Scroll will now finalize multiple batches using a single aggregated bundle proof.

• The on-chain bundle proof verifier uses a new public input layout.

Timeline

• Scroll Sepolia
  • Network Upgrade: August 14th, 2024
• Scroll Mainnet
  • Upgrade Initiation: August 5th, 2024
  • Timelock Completion & Upgrade: August 21st, 2024

Technical Details

Contract Changes

Note: Since the previous Curie upgrade, we have migrated the Scroll contracts to a new repo at scroll-contracts.

The code changes for this upgrade are implemented in this PR. The key changes are as follows:

• We have introduced a new BatchHeaderV3Codec.
• We have changed how messages are processed in the L1MessageQueue contract. Prior to Darwin, we would process messages when a batch is finalized. After Darwin, most of this processing is moved to the commit step.
• We have introduced a new public input format for bundle proofs. This is implemented in a new contract IZkEvmVerifierV2, which is in turn added to MultipleVersionRollupVerifier.
• In the ScrollChain contract version=3 batches will now be committed through a new function called commitBatchWithBlobProof. Bundles will be finalized using a new function called finalizeBundleWithProof.

See the contract release notes for more information.

Node Changes

The new node version is v5.6.0. See the release notes for more information.

The main changes are:

• Implementation of timestamp-based hard forks.
• Processing V3 batch codec in rollup-verifier.

zkEVM circuit changes

The new version of zkevm circuits is v0.12.0. See here for the release log.

We have introduced a RecursionCircuit that will bundle multiple sequential batches by recursively aggregating the SNARKs from the BatchCircuit (previously AggregationCircuit). The previously 5 layer proving system is now 7 layers as we introduce:

• 6th Layer (layer5): RecursionCircuit that recursively aggregates BatchCircuit SNARKs.
• 7th Layer (layer6): CompressionCircuit that compresses the RecursionCircuit SNARK and produce an EVM-verifiable validity proof.

The public input to the BatchCircuit is now context-aware of the “previous” batch, which allows us to implement the recursion scheme we adopted (described here in-depth).

Audits

• TrailofBits: coming soon!

Compatibility

Sequencer and Follower Nodes (l2geth)

This upgrade does not alter the state transition function and is therefore backward-compatible. However, we strongly recommend node operators to upgrade to v5.6.0.

Dapps and Indexers

There are some major changes to how we commit and finalize batches after Darwin.

• Batches will be encoded using the new V3 batch codec. This version adds two new fields:

  1. lastBlockTimestamp (the timestamp of the last block in this batch).
  2. blobDataProof (the KZG challenge point evaluation proof).

  This version removes skippedL1MessageBitmap. There will be no changes to how the blob data is encoded and compressed.

• Batches will be committed using the commitBatchWithBlobProof function (instead of the previous commitBatch).

  New function signature:

  function commitBatchWithBlobProof(uint8 _version, bytes calldata _parentBatchHeader, bytes[] memory _chunks, bytes calldata _skippedL1MessageBitmap, bytes calldata _blobDataProof)

• Batches will be finalized using the finalizeBundleWithProof function (instead of the previous finalizeBatchWithProof4844).

  New function signature:

  function finalizeBundleWithProof(bytes calldata _batchHeader, bytes32 _postStateRoot, bytes32 _withdrawRoot, bytes calldata _aggrProof)

• The semantics of the FinalizeBatch event will change: It will now mean that all batches between the last finalized batch and the event’s _batchIndex have been finalized. The event’s stateRoot and withdrawRoot values belong to the last finalized batch in the bundle. Finalized roots for intermediate batches are no longer available.

  The semantics of the CommitBatch and RevertBatch events will not change.

Recommendations:

• Indexers that decode committed batch data should be adjusted to use the new codec and the new function signature.
• Indexers that track batch finalization status should be adjusted to consider the new event semantics.

Curie Upgrade

Overview

This significant upgrade will reduce gas fees on the Scroll chain by 1.5x. Highlights include:

• Compresses the data stored in blobs using the zstd algorithm. This compression reduces the data size, allowing each blob to store more transactions, thereby reducing data availability cost per transaction.
• Adopts a modified version of the EIP-1559 pricing model which is compatible with the EIP-1559 transaction interface, bringing beneftis such as more accurate transaction pricing and a more predictable and stable fee structure.
• Support for new EVM opcodes TLOAD, TSTORE, and MCOPY. Users can safely use the latest Solidity compiler version 0.8.26 to build the contracts.
• Introduces a dynamic block time. During periods of traffic congestion, a block will be packed when the number of transactions reaches the circuit limit instead of waiting for the 3-second interval.

Timeline

• Scroll Sepolia
  • Network Upgrade: June 17th, 2024
• Scroll Mainnet
  • Upgrade Initiation: June 20th, 2024
  • Timelock Completion & Upgrade: July 3rd, 2024

Technical Details

Contract Changes

The code changes for this upgrade are documented in the following PRs:

• Accept compressed batches
• Update L1GasPriceOracle
• Change MAX_COMMIT_SCALAR and MAX_BLOB_SCALAR to 1e18
• Remove batch index check when updating a verifier

The main changes are as follows:

• The rollup contract (ScrollChain) will now accept batches with both versions 1 and 2. Version 1 is used for uncompressed blobs (pre-Curie), while version 2 is used for compressed blobs (post-Curie).
• The L1GasPriceOracle contract will be updated to change the data fee formula to account for blob DA, providing a more accurate estimation of DA costs:
  • Original formula: (l1GasUsed(txRlp) + overhead) * l1BaseFee * scalar
  • New formula: l1BaseFee * commitScalar + len(txRlp) * l1BlobBaseFee * blobScalar

Node Changes

The new node version is v5.5.0. See the release notes for the list of changes.

zkEVM circuit changes

The new version of zkevm circuits is v0.11.4. See here for the release log.

Audits

• TrailofBits: coming soon!
• Zellic

Compatibility

Sequencer and Follower Nodes (l2geth)

This upgrade is a hard fork, introducing the TLOAD, TSTORE, and MCOPY opcodes. Operators running an l2geth node are required to upgrade before the hard fork block. For more information, see the node release note.

Dapps and Indexers

For dApps, this upgrade is backward compatible. Developers should adjust the gas fee settings to incorporate the EIP-1559 pricing model. Note that dApps can no longer rely on the fixed 3-second block time in the application logic.

For indexers, the data format remains the same. The will be however changes to the data content:

• The version field in BatchHeader will be changed to 2 since Curie block.
• The data stored in blob will be compressed and can be decompressed by zstd v1.5.6.

Bernoulli Upgrade

Overview

This upgrade features a significant reduction in transaction costs by introducing support for EIP-4844 data blobs and supporting the SHA2-256 precompile.

Timeline

• Scroll Sepolia
  • Network Upgrade: April 15th, 2024
• Scroll Mainnet
  • Upgrade Initiation: April 15th, 2024
  • Timelock Completion & Upgrade: April 29th, 2024

Technical Details

Contract changes

The contract changes for this upgrade are in this PR, along with the audit fixes here. The main changes are as follows:

• ScrollChain now accepts batches with either calldata or blob encoding in commitBatch.
• ScrollChain now supports finalizing blob-encoded batches through finalizeBatchWithProof4844.
• MultipleVersionRollupVerifier can now manage different on-chain verifiers for each batch encoding version.

Node changes

The new node version is v5.3.0. See here for the release log.

zkEVM circuit changes

The new version of zkevm circuits is v0.10.3. See here for the release log.

Audits

• OpenZeppelin
• TrailofBits

Compatibility

Sequencer and follower nodes (l2geth)

This upgrade is a hard fork as it introduces the new blob data type and the SHA2-256 precompiled contract. Operators running an l2geth node are required to upgrade before the hard fork block. See the node releases for more information.

Indexers and Bridges

This upgrade changes the format that Scroll uses to publish data to Ethereum. Projects that rely on this data should carefully review the new data format, and check whether their decoders need to be adjusted. A summary of the new format:

• The format of BlockContext will not change.
• Chunks will no longer include the L2 transaction data. This will instead be stored in a blob attached to the commitBatch transaction.
• BatchHeader now contains one new field, BlobVersionedHash.

Provers

This upgrade involves a breaking change in zkevm-circuits. Operators running a prover node are required to upgrade.

Bridge Upgrade

Overview

To reduce bridging costs, we implemented several gas optimizations on our bridge and rollup contract suite. The optimization techniques used include the following:

• We will now use constants to store some companion contract addresses, instead of using storage variables. This is possible since these values should (almost) never change. With this change we can save on a few storage load operations.
• We updated the intrinsic gas estimation in L1MessageQueue to use a simple upper bound instead of an exact calculation. The two results will be similar for most bridge transactions but the new implementation is significantly cheaper.
• We merged two contracts L1MessageQueue and L2GasPriceOracle to save on call costs from one contract to the other.

Timeline

• Scroll Sepolia:
  • Network Upgrade: January 19, 2024
• Scroll Mainnet:
  • Upgrade Initiation: February 7, 2024
  • Timelock Completion & Upgrade: February 21, 2024

Technical Details

Code Changes

• Bridge Cost Optimization
• Audit Fixes
• Previously deployed version (commit ff380141a8cbcc214dc65f17ffa44faf4be646b6)
• Version deployed (commit 6030927680a92d0285c2c13e6bb27ed27d1f32d1)

Audits

• OpenZeppelin

List of Changes

Changes to L1 contracts:

• In ScrollChain, change messageQueue and verifier to immutable.
• In L1ScrollMessenger, change counterpart, rollup, and messageQueue to immutable.
• In all token gateways, change counterpart, router, and messenger to immutable.
• Merge L1MessageQueue and L2GasPriceOracle into a single contract L1MessageQueueWithGasPriceOracle (deployed on the same address as the previous L1MessageQueue). In this contract, we also change messenger and scrollChain to immutable, and simplify calculateIntrinsicGasFee.

Changes to L2 contracts:

• In L2ScrollMessenger, change counterpart to immutable.
• In all token gateways, change counterpart, router, and messenger to immutable.

Contracts affected:

• L1: L1MessageQueue, L2GasPriceOracle, ScrollChain, L1WETHGateway, L1StandardERC20Gateway, L1GatewayRouter, L1ScrollMessenger, L1CustomERC20Gateway, L1ERC721Gateway, L1ERC1155Gateway.
• L2: L2ScrollMessenger, L2WETHGateway, L2StandardERC20Gateway, L2GatewayRouter, L2CustomERC20Gateway, L2ERC721Gateway, L2ERC1155Gateway.

Compatibility

Sequencer and follower nodes (l2geth)

Operators running an l2geth node do not need to upgrade. The changes in this upgrade will not affect l2geth.

Dapps and indexers

Dapps and indexers (and similar off-chain infrastructure) that query contracts or rely on contract interfaces would, in most cases, not need to be changed. The majority of the contract changes are internal and/or backward compatible.

If your application depends on L2GasPriceOracle to monitor how Scroll keeps track of the L2 gas price on L1, from the upgrade block number you will need to start monitoring L1MessageQueueWithGasPriceOracle.

The original gas price oracle contract will be deprecated: it will no longer be updated or used by the Scroll bridge.

• Ethereum:
  • L2GasPriceOracle: 0x987e300fDfb06093859358522a79098848C33852
  • L1MessageQueueWithGasPriceOracle: 0x0d7E906BD9cAFa154b048cFa766Cc1E54E39AF9B
• Sepolia:
  • L2GasPriceOracle: 0x247969F4fad93a33d4826046bc3eAE0D36BdE548
  • L1MessageQueueWithGasPriceOracle: 0xF0B2293F5D834eAe920c6974D50957A1732de763