Lumoz completes Etrog major upgrade
TechFlow Selected TechFlow Selected
Lumoz completes Etrog major upgrade
This update enhances Polygon zkEVM's compatibility with Ethereum, significantly optimizing node execution and query efficiency, while also expanding the possibilities for the Polygon CDK ecosystem.
Navigating Web3 tides with focused insights
Etrog Upgrade Overview
As a key component within the Polygon CDK ecosystem, Lumoz has consistently monitored every upgrade of Polygon CDK, conducting extensive research, development, and optimization efforts. We aim to clearly explain the technical details behind these upgrades, comprehensively mapping out the migration path from early versions of CDK Validium to the Etrog version, thereby expanding the boundaries of both the Polygon CDK ecosystem and the broader blockchain industry.
The Etrog upgrade for Polygon zkEVM was completed in February 2024. This marked the most significant upgrade since the mainnet launch of Polygon zkEVM. It introduced support for several precompiled contracts at the circuit level, optimized transaction bundling and block production mechanisms, and completely restructured the contract architecture. These changes laid the foundation for future developments in the Polygon CDK ecosystem, including new features such as AggLayer and Unified Bridge. Overall, this update significantly improved compatibility with Ethereum, enhanced node execution and query efficiency, and expanded the possibilities for the Polygon CDK ecosystem.
This article will analyze the technical details of the upgrade from the perspective of Polygon zkEVM's smart contracts and node code, while also providing a complete overview of the upgrade path from early CDK Validium versions to the Etrog version based on open-source Rollup upgrade frameworks.
Contract Refactoring
Prior to the Etrog upgrade, Polygon zkEVM's contracts primarily consisted of two components: consensus contracts and bridge contracts.
Consensus Contract
The consensus contract stored most of the Layer-2 chain information, including basic data such as chain ID and version, as well as real-time state information like batch submissions and proof verification records. For Validium, raw transaction data within batches is not recorded on-chain but instead stored off-chain through an additional committee contract managed by a DA (Data Availability) node group. By combining this basic and state information, anyone can fully reconstruct the state of the Layer-2 chain.
Bridge Contract
On the other hand, the bridge contract used a set of exit root states to manage and record all cross-chain states between Layer-1 and Layer-2, enabling asset transfers via a Lock/Mint mechanism. The child nodes of the exit root were updated jointly by the bridge contract and the consensus contract: the former maintained deposit transaction statuses from Layer-1 to Layer-2, while the latter maintained withdrawal statuses from Layer-2 to Layer-1 through ZK proof submissions.
The most significant change introduced by the Etrog upgrade at the contract layer was the introduction of a multi-network framework—enabling a single set of contracts to manage multiple Layer-2 networks instead of just one. Combined with the newly introduced Unified Bridge, this enables interoperability across different Layer-2 networks, laying a solid foundation for the long-term evolution of the entire ecosystem.
Since the original contract structure did not support multi-network deployment, the Etrog upgrade required a comprehensive refactoring of the entire contract architecture:
-
Introduction of the RollupManager contract to manage information for all Layer-2 networks;
-
Restructuring of the bridge contract and GlobalExitRoot to maintain cross-chain states across all networks, ensuring asset interoperability among different Layer-2 chains.
For detailed contract architecture, please refer here
For existing Polygon zkEVM Layer-2 networks running below the Etrog version, these modifications are highly disruptive to contract data, making the corresponding upgrade process particularly challenging. Below, we detail the specific implementation of the upgrade plan, separately addressing the consensus and bridge contracts.
Consensus Contract
The most significant change in the consensus contract during the Etrog upgrade was the introduction of a new RollupManager contract. As most permission management and contract operations in the new version are centralized within this new RollupManager contract, the official upgrade strategy involves upgrading the existing Polygon zkEVM proxy’s implementation to become the RollupManager contract. Meanwhile, a newly deployed subnetwork contract, PolygonZkEVMExistentEtrog, serves as the new consensus contract for the original network. During initialization of the new RollupManager contract, global rollup network information is written in. Compared to the standard post-Etrog Layer-2 contract PolygonZkEVMEtrog, PolygonZkEVMExistentEtrog additionally implements an initializeUpgrade method to handle transitional logic during the upgrade process.
To ensure consistent storage slot layout for proxy contracts after the upgrade, RollupManager inherits from a dedicated LegacyZKEVMStateVariables contract that preserves variables from the previous version. Additionally, to maintain consistency of batch states before and after the upgrade, the RollupManager performs a series of operations during initialization—reinitializing historical data into the new contract structure—and generates a forcedBatch on Layer-1 according to post-upgrade rules, serving as a transitional batch for nodes to process.
Bridge Contract
The Etrog upgrade added support for custom gas tokens in the bridge contract and revised the generation mechanism of the globalExitRoot, ensuring backward compatibility of existing data while supporting exit root updates from multiple Layer-2 chains—thus enabling cross-Layer-2 asset interoperability.
Node Updates
On the node side, the Etrog upgrade mainly updated the sequencer and synchronizer modules, along with refreshed contract ABIs to interact with the new contract versions.
Sequencer Module
-
This upgrade modified the logic for block and batch packaging. Before Etrog, each Layer-2 block contained only one transaction, and the block time matched the batch time. This design diverged significantly from Ethereum’s model, leading to poor compatibility with dApps relying on common patterns like iterating transactions by block. In response, the Etrog upgrade adjusted the block production logic to fixed-interval block creation, allowing multiple transactions per block—greatly improving compatibility with existing Ethereum tooling and applications.
-
Synchronizer module
The changes in Etrog consist of two parts. First, adapting event handling logic for the new contract versions—including processing the transition batch, handling new batch/proof submission events, and info_tree update events. Second, a complete restructuring of the overall synchronization logic. In pre-Etrog versions, synchronization was entirely sequential: permissionless nodes had to wait until all Layer-1 data was fully synced in batch order before syncing pending data from the primary node. This created persistent delays between secondary nodes and the main node. The Etrog upgrade completely overhauled this logic by splitting Layer-1 and Layer-2 synchronization tasks into separate threads, eliminating the delay and significantly accelerating Layer-1 data sync speed.
Lumoz's CDK Validium Upgrade
Standard zkEVM networks can follow the official repository’s open-source code to complete the upgrade process. However, the official team does not provide a supported upgrade path for Validium. Through independent research and development, the Lumoz team has successfully designed and implemented a Validium-specific upgrade solution, completing upgrades on several CDK Validium testnets and the Merlin mainnet. This section outlines the specific upgrade path for Validium.
Code Implementation
Contract Layer
The Validium upgrade approach closely follows the official Rollup modifications, implementing a PolygonValidiumExistentEtrog contract tailored for Validium consensus. Based on the original CDKValidium contract, it includes an initializeUpgrade method similar to zkEVMExistentEtrog, which inherits historical data during the upgrade transaction and generates an upgrade batch for node processing. A key difference from zkEVM is that the DataCommittee address in the new CDK Validium version is now maintained by the newly deployed PolygonValidiumExistentEtrog contract. Therefore, during the upgrade, the original CDKDataCommittee address must be reassigned to the dataAvailabilityProtocol variable.
Node Layer
The official new-version Validium node code lacks implementation for handling the updateEtrogSequence event, making it unusable out-of-the-box. However, this can be implemented following the Rollup processing flow. Additionally, the contract ABIs used in the code must be updated to match the Valdium contract interfaces, replacing the original Rollup contract interfaces.
Note: If choosing to skip Etrog and directly upgrade to Eldberry or later versions, additional node modifications are required due to differences in batch data handling. During the contract upgrade, the transitional forcedBatch generated on Layer-1 still follows the Etrog format. When processing this batch, nodes must use the Etrog version handler rather than the default Eldberry processor; otherwise, incompatibility issues will arise.
Upgrade Process
Before upgrading, all new-version contracts—including RollupManager, ValidiumExistentEtrog, GlobalExitRootV2, and BridgeV2—must be pre-deployed on both Layer-1 and Layer-2. Refer to the official upgrade scripts, replacing zkEVM-related contracts with their Validium counterparts. Once deployment is complete, prepare the transaction data for upgrading the CDKValidium proxy on Layer-1 in advance, calling the newly implemented initialize method to reassign data and generate the transition batch. Then, a privileged address associated with the Timelock contract schedules the upgrade transaction via the schedule method and waits for the timelock period to expire. Similarly, on Layer-2, prepare the bridge contract upgrade transaction data and schedule it within the Layer-2 Timelock contract.
Since the RollupManager's initialize logic checks whether proofs have been submitted up to the latest state—to ensure batch execution and proof verification occur under the same version—some adjustments to trusted nodes are still required after the timelock expires. To minimize downtime during the upgrade, preconfigure the StopSequencerOnBatchNum parameter in the sequencer service so that transaction packaging halts upon reaching that batch, allowing sufficient time for batch and proof submission. Additionally, because the migration files for pool_db differ between old and new versions of Validium, the relevant records related to 'supernets-0001.sql' in the database must be manually or programmatically handled to align with the new node’s database schema.
Once proofs are fully submitted and database migration is complete, a privileged address can call the execute method on the Layer-1 Timelock contract to carry out the scheduled upgrade operation, update all configuration files, and simultaneously upgrade all services on trusted nodes to the new version. After trusted nodes resume operations and restart transaction packaging, all permissionless nodes should also update their configurations and restart services using the new code. The Layer-2 upgrade can then proceed by calling execute on the Layer-2 Timelock contract once its timer expires, finalizing the bridge contract upgrade on Layer-2.
Join TechFlow official community to stay tuned
Telegram:https://t.me/TechFlowDaily
X (Twitter):https://x.com/TechFlowPost
X (Twitter) EN:https://x.com/BlockFlow_News
@LumozOrg
