Etrog Upgrade Overview
The Etrog upgrade of Polygon zkEVM was completed in February 2024. This upgrade is the most significant upgrade since the launch of Polygon zkEVM's autonomous network. It not only completes the support of several precompiled contracts in the underlying circuit, but also optimizes the packaging and block generation mechanism of the chain itself. At the same time, it reconstructs the entire contract architecture, providing a foundation for the subsequent Polygon CDK ecosystem, as well as new features such as AggLayer and Unified Bridge. Overall, this update improves the compatibility of Polygon zkEVM with Ethereum, brings great optimization to the execution and query efficiency of nodes, and broadens the possibilities of the Polygon CDK ecosystem.
This article will analyze the technical details of this upgrade from the perspective of Polygon zkEVM contracts and node code. At the same time, based on the open source Rollup upgrade solution, it will comprehensively sort out and complete the upgrade path from the early version of CDK Validium to the Etrog version.
Contract Reconstruction
Before the Etrog upgrade, the Polygon zkEVM contract mainly consisted of two parts: the consensus contract and the bridge contract.
Consensus Contract
The consensus contract will record most of the information of the second-layer chain, including some basic information such as chain ID and version, as well as real-time status information of the second-layer chain such as batch and proof submission records. In addition, for Validium, the original transaction data in the batch will not be recorded in the consensus contract, but will be saved in the DA node group under the chain through an additional committee contract. By combining these basic information and real-time status information, anyone can fully restore the status of a second-layer chain.
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 the first layer and the second layer, and completes the asset flow between the first layer and the second layer through the Lock/Mint mode. The child nodes of the exit root are updated by the bridge contract and the consensus contract at the same time. The former maintains the deposit transaction status from the first layer to the second layer, and the latter maintains the withdrawal status from the second layer to the first layer through the submission of ZK proofs.
The biggest change brought by the Etrog upgrade at the contract level is the introduction of a multi-network solution, using a set of contracts to support multiple, rather than the original single second-layer network management and maintenance. At the same time, relying on the newly introduced Unified Bridge to open up the asset interoperability between these second-layer networks, it provides a better foundation for the future development of the overall ecosystem.
Since the original contract structure does not support multi-network deployment, the Etrog upgrade reconstructed the entire contract structure.
The RollupManger contract is introduced to manage all layer 2 network information;
The structure of the bridge contract and GlobalExitRoot has been modified to enable them to maintain the cross-chain status of all networks to ensure asset interoperability between different second-layer networks.
For detailed contract structure, please refer to
For the Polygon zkEVM second-layer network running below the Etrog version, these modifications are highly destructive to the contract data, so the corresponding upgrade plan is a considerable challenge. Here we still introduce the specific details behind the upgrade plan in detail from the two parts of consensus contract and bridge contract.
Consensus Contract
The biggest change in the consensus contract part of the Etrog upgrade is the introduction of a new RollupManager contract. Since most of the contract operations such as permission management in the new version are concentrated in the newly introduced RollupManager contract, the official upgrade plan of Polygon will update the original Polygon zkEVM proxy implementation to the RollupManager contract, and at the same time use a newly deployed sub-network contract PolygonZkEVMExistentEtrog as the new consensus contract of the original network, and write the global information of the Rollup network when the new RollupManger contract is initialized. Compared with the usual second-layer network contract PolygonZkEVMEtrog after the Etrog upgrade, this PolygonZkEVMExistentEtrog implements an initializeUpgrade method for the transition logic during the upgrade process.
In order to ensure the consistency of slots of proxy contract variables after the upgrade, RollupManager inherits a LegacyZKEVMStateVariables contract specifically used to store old variables. On the other hand, in order to ensure the consistency of batch states before and after the upgrade, RollupManager also performs a series of operations during initialization, reassigns historical data to the new contract, and generates a forcedBatch as a transition batch for Etrog upgrade in a layer according to the upgraded rules for node processing.
Bridge Contract
The Etrog upgrade provides the bridge contract with the function of customizing gas tokens. It also modifies the generation scheme of globalExitRoot to ensure compatibility with the exit root updates of multiple second-layer chains while maintaining the consistency of the original data, so as to achieve asset interoperability between multiple second-layer chains.
Node Update
In terms of nodes, the Etrog upgrade mainly updates the sequencer and synchronizer modules, and also updates the contract abi for interaction with the new version of the contract.
sequencer module
This upgrade modified the packaging logic of blocks and batches. Before Etrog, each second-layer block contained only one transaction, and the block time was consistent with the batch time of the block. This design is quite different from the Ethereum model. For on-chain applications, the commonly used logic of traversing transactions according to blocks is very incompatible. Therefore, after the Etrog upgrade, the packaging logic of the entire second-layer block was adjusted to a fixed time block, and a single block can contain multiple transactions, improving the incompatibility issues in historical versions.
synchronizer module
The changes in Etrog are divided into two parts. The first is to adapt to the events and corresponding processing logic of the new version of the contract, including how to handle transition batches, how to handle new batch/proof submission events and info_tree update events, etc. The other part is to reconstruct the overall synchronization logic. In the version before Etrog, the synchronization logic was serial as a whole. For permissionless nodes, it is necessary to wait for the first layer of data to be fully synchronized in batch order before continuing to synchronize the data to be submitted from the main node. This makes there always a delay between the data of these nodes and the main node. The Etrog upgrade completely reconstructed this part of the logic, splitting the synchronization tasks of the first and second layers into their own threads for management. While solving the above-mentioned delay problem, it also speeds up the synchronization efficiency of the first layer of data.
Lumoz's CDK Validium upgrade
Conventional zkEVM networks can use the open source code in the official repository to complete the upgrade process, but the official does not support the upgrade plan for Validium. After research and development, the Lumoz team completed the upgrade plan for Validium and successfully upgraded several test networks and the Merlin main network based on CDK Validium. This section will mainly introduce the specific upgrade path for Validium.
Code Implementation
Contractual aspects
The upgrade plan for Validium can basically refer to the changes in the official Rollup to implement a PolygonValidiumExistentEtrog contract for the Validium consensus contract. This contract will be based on the original CDKValidium contract, and like zkEVMExistentEtrog, it needs to implement an initializeUpgrade method to inherit historical data during the execution of the upgrade transaction and generate an upgrade batch for the node to process. Unlike zkEVM, the DataCommittee address of the new version of CDK Validium will be maintained by the newly deployed PolygonValidiumExistentEtrog contract, so the original CDKDataCommittee address needs to be re-set to the dataAvailabilityProtocol variable during the upgrade process.
Node
The official new version of Validium node code does not implement the processing logic for the event updateEtrogSequence, so it cannot be used directly, but it can still be implemented here by referring to the Rollup processing flow. On the other hand, it is also necessary to modify the contract abi that the code depends on to adapt it to the Valdium contract interface and replace the original Rollup contract interface.
Note that if you choose to skip Etrog and upgrade directly to Eldberry or above, the node needs to make some additional modifications due to the different batch data processing methods. During the contract upgrade process, the transition forcedBatch generated by the first layer is still generated in the Etrog version. When processing the batch, the node cannot use the default Eldberry processor, but needs to use the Etrog version processor again, otherwise incompatibility issues will occur.
Upgrade Process
Before upgrading, you need to deploy all new versions of contracts on the first and second layer networks respectively, including RollupManager, ValidiumExistentEtrog, GlobalExitRootV2, BridgeV2, etc. For details, please refer to the official upgrade script and replace the zkEVM-related contracts with Validium-related contracts. After the deployment of the relevant contracts is completed, you can pre-generate the transaction data of the Proxy that upgrades CDKValidium on the first layer, and call the newly implemented initialize method to complete the above data re-assignment and transition batch generation operations. After that, the relevant permission address of the Timelock contract calls the schdule method to schedule the upgrade transaction and wait for the lock time of the timelock contract. Similar to the operation on the first layer, it is also necessary to pre-generate the upgrade transaction data of the bridge contract on the second layer, and schedule the upgrade transaction in the Timelock contract on the second layer.
Since the initialize logic of RollupManager needs to check whether the Proof is submitted to the latest version to ensure that the execution and proof of the batch before and after the upgrade are under the same version, some adjustments to the trusted nodes are still required after the lock time is reached. In order to minimize the downtime during the upgrade, the StopSequencerOnBatchNum parameter in the sequencer service can be preset in advance to stop the packaging of transactions after reaching the batch, so as to leave enough time for the submission of the batch and the corresponding proof. On the other hand, since the new and old versions of Validium have modified the migration files of pool_db, the relevant records of 'supernets-0001.sql' in the database need to be processed manually or in the node code to align the database structure of the new version of the node.
After the proof is submitted to the latest version and the database is organized, the execute method can be called using the relevant permission address of the first-layer Timelock contract to perform the previously scheduled upgrade operation, update all configuration files, and update all service versions of the trusted nodes at the same time. After the trusted node resumes service and restarts packaging transactions, all permissionless nodes also need to update the configuration files and restart the service with the new version code. The upgrade operation of the second layer can also execute the execute method after the time set by Timelock is reached to complete the upgrade of the second-layer bridge contract.
As an important part of the Polygon CDK ecosystem, Lumoz has been paying attention to every upgrade of Polygon CDK, conducting multiple surveys, development and optimization, and explaining the details behind the upgrade to the public in an easy-to-understand way, hoping to comprehensively sort out and complete the upgrade path from the early version of CDK Validium to the Etrog version, thereby effectively broadening the boundaries of the development of Polygon CDK and even the entire blockchain industry.