Abstract：This update enhances the compatibility of Polygon zkEVM with Ethereum, significantly improves the execution and query efficiency for nodes, and expands the possibilities for the Polygon CDK ecosystem.

As an important part of the Polygon CDK ecosystem, Lumoz has consistently focused on every upgrade of Polygon CDK, conducting multiple rounds of research, development, and optimization. They aim to explain the details of upgrades in an accessible manner to the public and hope to thoroughly outline and complete the upgrade path from the early version of CDK Validium to the Etrog version, thereby effectively broadening the development boundaries of Polygon CDK and the entire blockchain industry.

The Etrog upgrade of Polygon zkEVM was completed in February 2024. This upgrade is the most significant one since the launch of the Polygon zkEVM mainnet. It not only introduced support for several precompiled contracts at the underlying circuit level but also optimized the chain's packaging and block production mechanisms. Additionally, it restructured the entire contract architecture, laying the foundation for the future Polygon CDK ecosystem, as well as new features like AggLayer and Unified Bridge. Overall, this update enhances the compatibility of Polygon zkEVM with Ethereum, significantly improves node execution and query efficiency, and expands the possibilities for the Polygon CDK ecosystem.

This article will delve into the technical details of this upgrade from the perspective of Polygon zkEVM contracts and node code. It will also comprehensively outline and complete the upgrade path from the early version of CDK Validium to the Etrog version, based on the open-source Rollup upgrade solution.

Before the Etrog upgrade, the contracts of Polygon zkEVM primarily consisted of two parts: the consensus contract and the bridge contract.

1.Consensus Contract

The consensus contract records most of the information of the Layer 2 chain, including basic information such as chain ID, version, and real-time state information of the Layer 2 chain like batch and proof submission records. For Validium, the raw transaction data within a batch is not recorded in the consensus contract but is stored off-chain by a DA node group through an additional committee contract. By combining this basic information and real-time state information, anyone can fully reconstruct the state of the Layer 2 chain.

2.Bridge Contract

On the other hand, the bridge contract uses a set of exit root states to manage and record all cross-chain states between Layer 1 and Layer 2, facilitating asset movement between the two layers through a Lock/Mint mechanism. The child nodes of the exit root are updated by both the bridge contract and the consensus contract. The former maintains the state of deposit transactions from Layer 1 to Layer 2, while the latter maintains the withdrawal state from Layer 2 to Layer 1 through the submission of ZK proofs.

The most significant change introduced by the Etrog upgrade at the contract level is the implementation of a multi-network solution. This new solution allows a single set of contracts to support the management and maintenance of multiple Layer 2 networks, rather than just one. Additionally, the newly introduced Unified Bridge enables asset interoperability between these Layer 2 networks, providing a better foundation for the future development of the overall ecosystem.

Since the original contract structure did not support multi-network deployment, the Etrog upgrade restructured the entire contract framework:

1.Introduced the RollupManager contract to manage information for all Layer 2 networks.

2.Modified the bridge contract and GlobalExitRoot structure to maintain cross-chain states for all networks, ensuring asset interoperability between different Layer 2 networks.

For detailed contract structures, please refer to https://docs.polygon.technology/img/cdk/high-level-architecture/smart-contracts-full-view.png

For Polygon zkEVM Layer 2 networks operating below the Etrog version, these modifications are highly disruptive to contract data. Therefore, the corresponding upgrade solution presents a significant challenge. Here, we will still provide a detailed explanation of the upgrade solution's specifics, focusing separately on the consensus contract and the bridge contract.

1.Consensus Contract

The most significant change in the consensus contract section of the Etrog upgrade is the introduction of a completely new RollupManager contract. In the new version, most of the permissions management and other contract operations are centralized in the RollupManager contract. Therefore, in Polygon's official upgrade plan, the existing implementation of the Polygon zkEVM proxy will be updated to the RollupManager contract. A newly deployed sub-network contract, PolygonZkEVMExistentEtrog, will serve as the new consensus contract for the original network, and global Rollup network information will be written during the initialization call of the new RollupManager contract. The PolygonZkEVMExistentEtrog contract, compared to the typical Layer 2 network contract PolygonZkEVMEtrog after the Etrog upgrade, includes an additional initializeUpgrade method to handle transition logic during the upgrade process.

To ensure consistency in the slot of proxy contract variables after the upgrade, the RollupManager inherits from a contract called LegacyZKEVMStateVariables, which is specifically used to store variables from the old version. Additionally, to maintain consistency in batch states before and after the upgrade, the RollupManager performs a series of operations during initialization. This process involves reassigning historical data to the new contract and, according to the post-upgrade rules, generates a forcedBatch on Layer 1 as a transitional batch for the Etrog upgrade, which nodes will process.

2.Bridge Contract

The Etrog upgrade introduces the functionality to use custom gas tokens in the bridge contract. It also modifies the generation scheme for the globalExitRoot, ensuring compatibility with updates to the exit roots of multiple Layer 2 chains while maintaining consistency with existing data. This modification enables asset interoperability between multiple Layer 2 networks.

In terms of nodes, the Etrog upgrade mainly updates the sequencer and synchronizer modules, and also updates the contract ABI to interact with the new version of the contracts.

1.Sequencer Module

The upgrade modifies the logic for packing blocks and batches. Prior to Etrog, each Layer 2 block contained only one transaction, and the block time was the same as the batch time. This design differed significantly from Ethereum's model and was highly incompatible with common on-chain applications that rely on transaction traversal by blocks. With the Etrog upgrade, the entire Layer 2 block packing logic was adjusted to a fixed-time block production model, where each block can contain multiple transactions, thus addressing compatibility issues present in previous versions.

2.Synchronizer Module

The changes in the synchronizer module are twofold. First, it adapts to the new contract events and corresponding handling logic, including how to manage transitional batches, handle new batch/proof submission events, and process info_tree update events. The second aspect involves a complete overhaul of the synchronization logic. In versions prior to Etrog, synchronization was serial. For permissionless nodes, data synchronization from Layer 1 would only continue after the data was fully synchronized in batch order. This created a delay between the data on these nodes and the main node. The Etrog upgrade restructured this logic entirely, splitting the synchronization tasks for Layer 1 and Layer 2 into separate threads, thereby solving the delay issue and improving the efficiency of Layer 1 data synchronization.

Standard zkEVM networks can complete the upgrade process entirely using the open-source code from the official repository. However, the official upgrade solution does not support Validium. The Lumoz team, after research and development, created an upgrade solution for Validium and successfully performed upgrades on several testnets and the Merlin mainnet based on CDK Validium. This section will mainly introduce the specific upgrade path for Validium.

1.Contract Side

The upgrade solution for Validium can generally follow the changes made for official Rollups to create a PolygonValidiumExistentEtrog contract for Validium consensus. This contract will be based on the original CDKValidium contract and, like zkEVMExistentEtrog, needs to implement an initializeUpgrade method. This method handles historical data during the upgrade process and generates an upgrade batch for nodes to process. Unlike zkEVM, the new version of CDK Validium will have its DataCommittee address managed by the newly deployed PolygonValidiumExistentEtrog contract. Therefore, during the upgrade process, the original CDKDataCommittee address needs to be reset in the dataAvailabilityProtocol variable.

2.Node Side

The official new version of Validium node code does not implement the logic for handling the updateEtrogSequence event and therefore cannot be used directly. However, it can be implemented by referring to the Rollup handling process. Additionally, the contract ABI dependencies in the code need to be updated to adapt to the Validium contract interfaces, replacing the original Rollup contract interfaces.

Note that if you choose to skip Etrog and upgrade directly to versions above Eldberry, the batch data handling methods are different. Nodes will need additional modifications. During the contract upgrade, the transitional forcedBatch generated on Layer 1 will still be created in the Etrog version style. Nodes processing this batch cannot use the default Eldberry processor but must use the Etrog version processor to avoid compatibility issues.

Before the upgrade, it is necessary to pre-deploy all new version contracts on both Layer 1 and Layer 2 networks, including RollupManager, ValidiumExistentEtrog, GlobalExitRootV2, and BridgeV2. For specifics, refer to the official upgrade scripts and replace zkEVM-related contracts with Validium-related contracts. Once the relevant contracts are deployed, pre-generate the transaction data for upgrading the CDKValidium proxy on Layer 1, invoke the newly implemented initialize method to complete data reassignments and generate the transitional batch. Then, the relevant permission address of the Timelock contract will call the schedule method to schedule the upgrade transaction and wait for the Timelock contract's lock period.

Similarly to the Layer 1 operations, pre-generate the bridge contract upgrade transaction data on Layer 2 and schedule the upgrade transaction in the Layer 2 Timelock contract.

Since the initialize logic of the RollupManager needs to check if the Proof has been submitted to the latest version to ensure that the execution and proof of batches before and after the upgrade are under the same version, adjustments to trusted nodes are required after reaching the lock period. To minimize downtime during the upgrade, pre-configure the StopSequencerOnBatchNum parameter in the sequencer service to stop transaction packing upon reaching that batch, allowing sufficient time for batch and proof submissions. Additionally, due to modifications in the pool_db migration file between the old and new Validium versions, manually handle or modify relevant records in 'supernets-0001.sql' in the database to align with the new version node's database structure.

After the Proof is submitted to the latest version and the database is organized, use the relevant permission address of the Layer 1 Timelock contract to call the execute method to perform the scheduled upgrade operations, update all configuration files, and update all service versions of trusted nodes. Once trusted nodes resume service and restart transaction packing, all permissionless nodes also need to update their configuration files and restart services with the new version code. Similarly, execute the upgrade operation on Layer 2 after reaching the time set by Timelock to complete the upgrade of the Layer 2 bridge contract.

Abstract：This update enhances the compatibility of Polygon zkEVM with Ethereum, significantly improves the execution and query efficiency for nodes, and expands the possibilities for the Polygon CDK ecosystem.

As an important part of the Polygon CDK ecosystem, Lumoz has consistently focused on every upgrade of Polygon CDK, conducting multiple rounds of research, development, and optimization. They aim to explain the details of upgrades in an accessible manner to the public and hope to thoroughly outline and complete the upgrade path from the early version of CDK Validium to the Etrog version, thereby effectively broadening the development boundaries of Polygon CDK and the entire blockchain industry.

The Etrog upgrade of Polygon zkEVM was completed in February 2024. This upgrade is the most significant one since the launch of the Polygon zkEVM mainnet. It not only introduced support for several precompiled contracts at the underlying circuit level but also optimized the chain's packaging and block production mechanisms. Additionally, it restructured the entire contract architecture, laying the foundation for the future Polygon CDK ecosystem, as well as new features like AggLayer and Unified Bridge. Overall, this update enhances the compatibility of Polygon zkEVM with Ethereum, significantly improves node execution and query efficiency, and expands the possibilities for the Polygon CDK ecosystem.

This article will delve into the technical details of this upgrade from the perspective of Polygon zkEVM contracts and node code. It will also comprehensively outline and complete the upgrade path from the early version of CDK Validium to the Etrog version, based on the open-source Rollup upgrade solution.

Before the Etrog upgrade, the contracts of Polygon zkEVM primarily consisted of two parts: the consensus contract and the bridge contract.

1.Consensus Contract

The consensus contract records most of the information of the Layer 2 chain, including basic information such as chain ID, version, and real-time state information of the Layer 2 chain like batch and proof submission records. For Validium, the raw transaction data within a batch is not recorded in the consensus contract but is stored off-chain by a DA node group through an additional committee contract. By combining this basic information and real-time state information, anyone can fully reconstruct the state of the Layer 2 chain.

2.Bridge Contract

On the other hand, the bridge contract uses a set of exit root states to manage and record all cross-chain states between Layer 1 and Layer 2, facilitating asset movement between the two layers through a Lock/Mint mechanism. The child nodes of the exit root are updated by both the bridge contract and the consensus contract. The former maintains the state of deposit transactions from Layer 1 to Layer 2, while the latter maintains the withdrawal state from Layer 2 to Layer 1 through the submission of ZK proofs.

The most significant change introduced by the Etrog upgrade at the contract level is the implementation of a multi-network solution. This new solution allows a single set of contracts to support the management and maintenance of multiple Layer 2 networks, rather than just one. Additionally, the newly introduced Unified Bridge enables asset interoperability between these Layer 2 networks, providing a better foundation for the future development of the overall ecosystem.

Since the original contract structure did not support multi-network deployment, the Etrog upgrade restructured the entire contract framework:

1.Introduced the RollupManager contract to manage information for all Layer 2 networks.

2.Modified the bridge contract and GlobalExitRoot structure to maintain cross-chain states for all networks, ensuring asset interoperability between different Layer 2 networks.

For detailed contract structures, please refer to https://docs.polygon.technology/img/cdk/high-level-architecture/smart-contracts-full-view.png

For Polygon zkEVM Layer 2 networks operating below the Etrog version, these modifications are highly disruptive to contract data. Therefore, the corresponding upgrade solution presents a significant challenge. Here, we will still provide a detailed explanation of the upgrade solution's specifics, focusing separately on the consensus contract and the bridge contract.

1.Consensus Contract

The most significant change in the consensus contract section of the Etrog upgrade is the introduction of a completely new RollupManager contract. In the new version, most of the permissions management and other contract operations are centralized in the RollupManager contract. Therefore, in Polygon's official upgrade plan, the existing implementation of the Polygon zkEVM proxy will be updated to the RollupManager contract. A newly deployed sub-network contract, PolygonZkEVMExistentEtrog, will serve as the new consensus contract for the original network, and global Rollup network information will be written during the initialization call of the new RollupManager contract. The PolygonZkEVMExistentEtrog contract, compared to the typical Layer 2 network contract PolygonZkEVMEtrog after the Etrog upgrade, includes an additional initializeUpgrade method to handle transition logic during the upgrade process.

To ensure consistency in the slot of proxy contract variables after the upgrade, the RollupManager inherits from a contract called LegacyZKEVMStateVariables, which is specifically used to store variables from the old version. Additionally, to maintain consistency in batch states before and after the upgrade, the RollupManager performs a series of operations during initialization. This process involves reassigning historical data to the new contract and, according to the post-upgrade rules, generates a forcedBatch on Layer 1 as a transitional batch for the Etrog upgrade, which nodes will process.

2.Bridge Contract

The Etrog upgrade introduces the functionality to use custom gas tokens in the bridge contract. It also modifies the generation scheme for the globalExitRoot, ensuring compatibility with updates to the exit roots of multiple Layer 2 chains while maintaining consistency with existing data. This modification enables asset interoperability between multiple Layer 2 networks.

In terms of nodes, the Etrog upgrade mainly updates the sequencer and synchronizer modules, and also updates the contract ABI to interact with the new version of the contracts.

1.Sequencer Module

The upgrade modifies the logic for packing blocks and batches. Prior to Etrog, each Layer 2 block contained only one transaction, and the block time was the same as the batch time. This design differed significantly from Ethereum's model and was highly incompatible with common on-chain applications that rely on transaction traversal by blocks. With the Etrog upgrade, the entire Layer 2 block packing logic was adjusted to a fixed-time block production model, where each block can contain multiple transactions, thus addressing compatibility issues present in previous versions.

2.Synchronizer Module

The changes in the synchronizer module are twofold. First, it adapts to the new contract events and corresponding handling logic, including how to manage transitional batches, handle new batch/proof submission events, and process info_tree update events. The second aspect involves a complete overhaul of the synchronization logic. In versions prior to Etrog, synchronization was serial. For permissionless nodes, data synchronization from Layer 1 would only continue after the data was fully synchronized in batch order. This created a delay between the data on these nodes and the main node. The Etrog upgrade restructured this logic entirely, splitting the synchronization tasks for Layer 1 and Layer 2 into separate threads, thereby solving the delay issue and improving the efficiency of Layer 1 data synchronization.

Standard zkEVM networks can complete the upgrade process entirely using the open-source code from the official repository. However, the official upgrade solution does not support Validium. The Lumoz team, after research and development, created an upgrade solution for Validium and successfully performed upgrades on several testnets and the Merlin mainnet based on CDK Validium. This section will mainly introduce the specific upgrade path for Validium.

1.Contract Side

The upgrade solution for Validium can generally follow the changes made for official Rollups to create a PolygonValidiumExistentEtrog contract for Validium consensus. This contract will be based on the original CDKValidium contract and, like zkEVMExistentEtrog, needs to implement an initializeUpgrade method. This method handles historical data during the upgrade process and generates an upgrade batch for nodes to process. Unlike zkEVM, the new version of CDK Validium will have its DataCommittee address managed by the newly deployed PolygonValidiumExistentEtrog contract. Therefore, during the upgrade process, the original CDKDataCommittee address needs to be reset in the dataAvailabilityProtocol variable.

2.Node Side

The official new version of Validium node code does not implement the logic for handling the updateEtrogSequence event and therefore cannot be used directly. However, it can be implemented by referring to the Rollup handling process. Additionally, the contract ABI dependencies in the code need to be updated to adapt to the Validium contract interfaces, replacing the original Rollup contract interfaces.

Note that if you choose to skip Etrog and upgrade directly to versions above Eldberry, the batch data handling methods are different. Nodes will need additional modifications. During the contract upgrade, the transitional forcedBatch generated on Layer 1 will still be created in the Etrog version style. Nodes processing this batch cannot use the default Eldberry processor but must use the Etrog version processor to avoid compatibility issues.

Before the upgrade, it is necessary to pre-deploy all new version contracts on both Layer 1 and Layer 2 networks, including RollupManager, ValidiumExistentEtrog, GlobalExitRootV2, and BridgeV2. For specifics, refer to the official upgrade scripts and replace zkEVM-related contracts with Validium-related contracts. Once the relevant contracts are deployed, pre-generate the transaction data for upgrading the CDKValidium proxy on Layer 1, invoke the newly implemented initialize method to complete data reassignments and generate the transitional batch. Then, the relevant permission address of the Timelock contract will call the schedule method to schedule the upgrade transaction and wait for the Timelock contract's lock period.

Similarly to the Layer 1 operations, pre-generate the bridge contract upgrade transaction data on Layer 2 and schedule the upgrade transaction in the Layer 2 Timelock contract.

Since the initialize logic of the RollupManager needs to check if the Proof has been submitted to the latest version to ensure that the execution and proof of batches before and after the upgrade are under the same version, adjustments to trusted nodes are required after reaching the lock period. To minimize downtime during the upgrade, pre-configure the StopSequencerOnBatchNum parameter in the sequencer service to stop transaction packing upon reaching that batch, allowing sufficient time for batch and proof submissions. Additionally, due to modifications in the pool_db migration file between the old and new Validium versions, manually handle or modify relevant records in 'supernets-0001.sql' in the database to align with the new version node's database structure.

After the Proof is submitted to the latest version and the database is organized, use the relevant permission address of the Layer 1 Timelock contract to call the execute method to perform the scheduled upgrade operations, update all configuration files, and update all service versions of trusted nodes. Once trusted nodes resume service and restart transaction packing, all permissionless nodes also need to update their configuration files and restart services with the new version code. Similarly, execute the upgrade operation on Layer 2 after reaching the time set by Timelock to complete the upgrade of the Layer 2 bridge contract.