Skip to content

Commit 97c2486

Browse files
mitchpolygonmitchpolygon
authored
Update forkid-9-12.md
still need to add images
1 parent 71b4881 commit 97c2486

File tree

1 file changed

+224
-2
lines changed

1 file changed

+224
-2
lines changed

‎docs/cdk/how-to/migrate/forkid-9-12.md‎

Lines changed: 224 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,225 @@
1-
!!! tip
2-
The migration instructions for moving from fork 9 to fork 12 are coming soon.
1+
> 💡 For CDK fork ID9 chains **NOT attached to the AggLayer** (Isolated), go straight to section 5.
32
3+
> 💡 For CDK fork ID9 chains **attached to the AggLayer**, follow steps in sections 1 to 5. This is a coordinated effort between Polygon and the Implementation Provider.
4+
5+
## 1. Summary of the Procedure
6+
7+
To initiate a CDK chain upgrade, the Implementation Provider can request support from Polygon by submitting the "*Request Help for an Issue with an Existing CDK Chain*" through the service desk.
8+
9+
| ![CDK Service Desk](path/to/CDK%20service%20desk.png) | ![Example Request](path/to/Example%20request.png) |
10+
|-------------------------------------------------------|---------------------------------------------------|
11+
| **CDK service desk**| **Example request**|
12+
13+
Polygon will then collaborate with the Implementation Provider to **schedule** the UTC timing and dates for the upgrade.
14+
15+
This planning enables the Implementation Provider to schedule testnet and mainnet maintenance windows for the respective networks, ensuring proper communication and coordination with their communities.
16+
17+
See [Example Maintenance Communication to Network Partners](#example-maintenance-communication-to-network-partners) Implementation Providers can prepare for the customer network chains.
18+
19+
The high-level steps in the collaborative process are:
20+
21+
1. Implementation Provider halting the sequencer,
22+
2. Polygon executes the upgrade transaction,
23+
3. Implementation Provider upgrades components to Fork 12 stack,
24+
4. Implementation Provider restarts the components.
25+
26+
## 2. CDK Components Versions
27+
28+
Please read carefully to fully understand the new architecture before starting the process: [https://docs.polygon.technology/cdk/getting-started/cdk-erigon/](https://docs.polygon.technology/cdk/getting-started/cdk-erigon/)
29+
30+
The table below lists the CDK Fork ID 9 components and the new CDK FEP Fork ID 12 component.
31+
32+
> 💡 **Please note:** Latest CDK FEP Fork ID 12 components are listed in the [Polygon Knowledge Layer](https://docs.polygon.technology/cdk/releases/stack-components/#cdk-fep-components)
33+
34+
| **CDK Components** | **Fork ID 9** | **CDK Components** | **Fork ID 12** |
35+
|--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
36+
| CDK Validium node<br>Sequence sender<br>Aggregator | [0.6.7+cdk.1](https://hub.docker.com/layers/0xpolygon/cdk-validium-node/0.6.7-cdk.1/images/sha256-dafb15f9355331b4b7174f47ac416b275915ff24a9ed89c211c7c15c8adfc6b8?context=explore) | CDK Erigon RPC & CDK node | [cdk-erigon](https://github.com/0xPolygonHermez/cdk-erigon) 2.1.1 -- forkid.12 release *(Will link final version when released)* |
37+
| | | CDK node<br>Sequence sender<br>Aggregator | 0.3.0-rc2 |
38+
| Tx pool manager | [zkevm-pool-manager](https://github.com/0xPolygon/zkevm-pool-manager) | Tx pool manager | [zkevm-pool-manager](https://github.com/0xPolygon/zkevm-pool-manager) |
39+
| Executor | | Executor | hermeznetwork/zkevm-prover:v8.0.0-RC14-fork.12 |
40+
| Prover | [v6.0.0](https://github.com/0xPolygonHermez/zkevm-prover/releases/tag/v6.0.0) | Prover | hermeznetwork/zkevm-prover:v8.0.0-RC14-fork.12 |
41+
| CDK data availability | [v0.0.7](https://hub.docker.com/layers/0xpolygon/cdk-data-availability/0.0.7/images/sha256-17590789a831259d7a07d8a042ea87e381c5708dec3a7daef6f3f782f50b2c00?context=explore) | CDK data availability | [cdk-data-availability](https://github.com/0xPolygon/cdk-data-availability) v0.0.10 |
42+
| zkEVM rollup node | [v6.0.0](https://github.com/0xPolygonHermez/zkevm-prover/releases/tag/v6.0.0) | zkEVM rollup node | N/A |
43+
| Contracts | [v6.0.0](https://github.com/0xPolygonHermez/zkevm-contracts/releases/tag/v6.0.0-rc.1-fork.9) | Contracts | [zkevm-contracts](https://github.com/0xPolygonHermez/zkevm-contracts) |
44+
| Bridge service | [v0.4.2-cdk.1](https://hub.docker.com/layers/hermeznetwork/zkevm-bridge-service/v0.4.2-cdk.1/images/sha256-f22ad8c9ad058c7a97a3d38f53cac5b1053858916523b96211d33ae40a9b45f8?context=explore) | Bridge service | [zkevm-bridge-service](https://github.com/0xPolygonHermez/zkevm-bridge-service) |
45+
| Bridge UI | [Polygon Portal](https://portal.polygon.technology/) | Bridge UI | [Polygon Portal](https://portal.polygon.technology/) |
46+
47+
## 3. Implementation Provider Preparation Steps
48+
49+
The Implementation Provider must prepare in advance for the upgrade to ensure a smooth transition from fork ID 9 to fork ID 12. Failure to complete these steps ahead of time could result in delays or even cancellation of the scheduled upgrade.
50+
51+
1. The Implementation Provider downloads CDK Fork 12 components binaries/images in advance so they are ready to deploy.
52+
2. Map to the latest prover files which can be found here: [https://storage.googleapis.com/zkevm/zkproverc/v8.0.0-rc.9-fork.12.tgz](https://storage.googleapis.com/zkevm/zkproverc/v8.0.0-rc.9-fork.12.tgz)
53+
3. Scale up the number of provers in advance. It is recommended that you at least double the number of provers up and running for the scheduled upgrade maintenance window.
54+
- Ensure all (majority) of the network batches are verified before starting the upgrade process, otherwise there will be additional downtime as we wait for the network to be ready.
55+
4. Run the CDK-Node aggregator component in sync-only mode in advance to populate its database.
56+
5. Required Erigon pre-syncing:
57+
- Generate data stream files from the current `cdk-validium-node` database.
58+
- Tool and instructions can be found here:
59+
- [https://github.com/0xPolygonHermez/zkevm-node/tree/develop/tools/datastreamer](https://github.com/0xPolygonHermez/zkevm-node/tree/develop/tools/datastreamer)
60+
- Use the Erigon tool (from `cdk-erigon` repo) to serve the DS:
61+
- `go run ./zk/debug_tools/datastream-host --file /path/to/directory`
62+
- Start CDK-Erigon, which reads from this datastream (provide `zkevm.l2-datastreamer-url: 127.0.0.1:6900` in the config).
63+
- Wait for it to sync to the tip.
64+
- CDK-Erigon can be stopped. The generated files will be used later during the upgrade process.
65+
66+
The whole process should look more orr less like this:
67+
```bash
68+
# PREREQUISITES: Install GO 1.23
69+
WORK_DIR=/tmp
70+
71+
cd $WORK_DIR
72+
git clone https://github.com/0xPolygonHermez/zkevm-node.git
73+
cd $WORK_DIR/zkevm-node/tools/datastreamer
74+
vim config/tool.config.toml
75+
# Edit [StateDB] section with your StateDB credentials
76+
make generate-file
77+
78+
cd $WORK_DIR
79+
git clone https://github.com/0xPolygonHermez/cdk-erigon.git
80+
cd $WORK_DIR/cdk-erigon
81+
go run ./zk/debug_tools/datastream-host \
82+
--file $WORK_DIR/zkevm-node/tools/datastreamer/datastream
83+
84+
# Bring up Erigon pointing to that DS (localhost:6900 if running locally)
85+
# and let it fully sync to the end of the DS.
86+
```
87+
88+
## 4. Polygon Preparation Steps
89+
90+
1. Polygon will collaborate with the Implementation Provider to **schedule** the UTC timing and dates for the upgrade, incorporating required timelocks.
91+
2. Polygon will set up Google Meet calls between Polygon and the Implementation Provider's engineers to conduct planned upgrades for both testnet and mainnet on agreed dates.
92+
3. Polygon will prepare in advance and with agreed timelock:
93+
- Rolluptype for fork 12
94+
- Upgrade transaction to fork 12
95+
4. For chains attached to the Polygon Agglayer, Polygon will handle steps to upgrade the permissionless node.
96+
5. Polygon will share [example communication](https://docs.google.com/document/d/1zyXojlg4n2Th6P3y3Wqe8px15HL8FnBpSIWd54co1tE/edit) that Implementation Providers can use to prepare their customer network partners and communities.
97+
98+
## 5. Operational Steps
99+
100+
**Please Note:** To avoid creating reorgs or other unwanted situations, it's important that all L2 transactions are verified before performing a fork upgrade. This means all batches should be closed, sequenced, and verified on L1.
101+
102+
### Steps to Halt the Sequencer
103+
104+
1. Stop the sequencer.
105+
2. Reconfigure the node to enforce sequencer stops at a specific `batch_num`:
106+
- Get the current batch number from StateDB:
107+
108+
```sql
109+
-- Note resulting value as X:
110+
SELECT batch_num, wip FROM state.batch WHERE wip IS true;
111+
```
112+
113+
- Edit node configuration:
114+
115+
```yaml
116+
# SEQUENCER CONFIG
117+
# Where X is the batch number obtained from the SQL query:
118+
Sequencer.Finalizer.HaltOnBatchNumber = X+1
119+
# Optional: Reduce batch time to avoid excessive downtime
120+
Sequencer.Finalizer.BatchMaxDeltaTimestamp = "120s" # 1800s
121+
```
122+
123+
```yaml
124+
# SEQUENCE SENDER CONFIG
125+
# Optional: Reduce sending time to avoid excessive downtime
126+
SequenceSender.WaitPeriodSendSequence = "10s" # 60s
127+
SequenceSender.LastBatchVirtualizationTimeMaxWaitPeriod = "30s" # 600s
128+
```
129+
130+
```yaml
131+
# AGGREGATOR CONFIG
132+
# Recommended: Reduce verify interval to avoid excessive downtime
133+
Aggregator.VerifyProofInterval = "5m"
134+
```
135+
136+
- Restart the sequencer, sequence sender, and aggregator to apply these configs.
137+
- Check that the sequencer halts when reaching batch X+1.
138+
- Wait until all pending batches are virtualized and verified (X):
139+
140+
```sql
141+
-- Both queries should return X
142+
SELECT max(batch_num) FROM state.virtual_batch;
143+
SELECT max(batch_num) FROM state.verified_batch;
144+
```
145+
146+
3. Stop all services (node, prover/executor, bridge).
147+
148+
> 💡 For an **isolated chain not attached to the Polygon Agglayer**, the chain admin can perform operational step 6 on their chain’s rollup manager contract. Polygon is not involved.
149+
150+
1. **Please Note:** Wait for Polygon to send the L1 transaction (tx) and confirm it.
151+
2. **Polygon:** Upgrade the Smart Contract (multisig):
152+
- Upgrade rollup to fork 12.
153+
- Wait for the Tx to be finalized.
154+
155+
### Steps to Deploy CDK FEP Fork 12 Components
156+
157+
1. [With the network stopped, repeat Erigon sync to get it fully synced to the current state.](https://www.notion.so/CDK-chain-upgrade-procedure-from-Fork-ID9-to-Fork-ID12-11980500116a802ab22cec6f7eea6080?pvs=21)
158+
- This instance is ready to act as Sequencer and/or RPC. Clone the whole Erigon config/datadir as many times as instances are needed. Pick one to be the new Sequencer (by setting the environment variable **`CDK_ERIGON_SEQUENCER=1`**), and configure all other instances (permissionless RPCs) to point to the Sequencer:
159+
160+
```yaml
161+
zkevm.l2-sequencer-rpc-url: "http://sequencer-fqdn-or-ip:8123"
162+
zkevm.l2-datastreamer-url: "sequencer-fqdn-or-ip:6900"
163+
```
164+
165+
2. Start the stateless Executor.
166+
3. Start the CDK-Erigon Sequencer.
167+
4. Verify in the sequencer’s logs that new blocks are being generated with fork ID 12.
168+
5. Start the Pool Manager (if used/needed).
169+
6. Start CDK-Erigon RPCs (if used/needed).
170+
7. Start the Bridge.
171+
8. Start the CDK aggregator and Sequence Sender components.
172+
9. Start the stateless Prover.
173+
174+
### Polygon Steps for CDK Chains Attached to the Agglayer
175+
176+
Polygon will be accountable for upgrading the Agglayer permissionless nodes during the upgrade process.
177+
178+
1. When the Implementation Provider has stopped the sequencer.
179+
2. Polygon's v-team shuts down the CDK chain permissionless nodes hosted by Polygon:
180+
- Set `replicaCount` to 0 for `rpc`, `synchronizer`, and `executor` in the desired node definition as found [here](https://github.com/0xPolygon/helm-charts/tree/main/charts/permissionless-nodes/nodes).
181+
- Run helm update to deploy changes, which will shut down the permissionless nodes.
182+
3. Polygon v-team updates the Agglayer config:
183+
- Change the `image.tag` to the desired version [here](https://github.com/0xPolygon/helm-charts/tree/main/charts/permissionless-nodes/nodes).
184+
4. When the Implementation Provider restarts the sequencer and everything is running as expected:
185+
5. Polygon starts the upgraded permissionless nodes to ID12:
186+
- Set `replicaCount` to 3 for `rpc` and `executor`; set `replicaCount` to 1 for `synchronizer`.
187+
- Run helm update to deploy changes.
188+
- Monitor logs/service status in Datadog for progress.
189+
190+
### Post-Upgrade Validations
191+
192+
1. Test batch lifecycle.
193+
2. Test the bridge.
194+
195+
# Example Maintenance Communication to Network Partners
196+
197+
There is a planned maintenance window upgrade of the xxxx network on the following dates. This is to upgrade the xxx network from Fork ID9 to Fork ID12.
198+
199+
**Maintenance Event:**  xxx Network Upgrade from Fork ID9 to Fork ID12
200+
201+
**Date:** TBD by Implementation Provider
202+
203+
**Time:** 00:00 PM EDT / 12:00 PM UTC
204+
205+
**Duration:** 2 Hours
206+
207+
**Things to Note:**
208+
209+
- This upgrade is from Fork ID9 to Fork ID12. The change log can be viewed [here](https://github.com/0xPolygonHermez/zkevm-contracts/releases/tag/v8.0.0-rc.1-fork.12).
210+
- Partners should **not update their nodes until after** the xxx network upgrade is confirmed as complete.
211+
- New Node Version: [cdk-erigon:v2.1.x](https://github.com/0xPolygonHermez/cdk-erigon/releases)
212+
213+
### Upgrade Instructions for Community Partners (Testnet/Mainnet)
214+
215+
Update FROM node version [0.6.7+cdk.1](https://hub.docker.com/layers/0xpolygon/cdk-validium-node/0.6.7-cdk.1/images/sha256-dafb15f9355331b4b7174f47ac416b275915ff24a9ed89c211c7c15c8adfc6b8?context=explore) up to [cdk-erigon:v2.1.x](https://github.com/0xPolygonHermez/cdk-erigon/releases).
216+
217+
#### Instructions to Update Nodes
218+
219+
1. Stop the RPC, Synchronizer, and Executor components.
220+
2. Update the node (RPC and Synchronizer) to [cdk-erigon:v2.1.x](https://github.com/0xPolygonHermez/cdk-erigon/releases).
221+
3. Update the Prover/Executor to [v8.0.0-RC12-fork.12](https://hub.docker.com/layers/hermeznetwork/zkevm-prover/v8.0.0-RC12-fork.12/images/sha256-7657c7ac473acd4f67ab6de81bb61595a1d52c97287bb2d043bff235a4803a66?context=explore).
222+
4. Start the components in this order:
223+
1. Prover/Executor
224+
2. Synchronizer
225+
3. RPC

0 commit comments

Comments
 (0)