Skip to content

Commit 254d7d7

Browse files
mitchpolygonmitchpolygon
authored
Merge pull request 0xPolygon#2481 from mitchpolygon/main
Update cdk-stack.svg
2 parents 0d59952 + b432c50 commit 254d7d7

File tree

4 files changed

+360
-39
lines changed

4 files changed

+360
-39
lines changed

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

Lines changed: 235 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,236 @@
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+
<table>
10+
<tr>
11+
<td>
12+
<img alt="CDK Service Desk" src="https://github.com/mitchpolygon/polygon-docs/blob/main/docs/img/cdk/CDK-service-desk.png?raw=true" width="300"/>
13+
</td>
14+
<td>
15+
<img alt="Example Request" src="https://github.com/mitchpolygon/polygon-docs/blob/main/docs/img/cdk/Example-request.png?raw=true" width="300"/>
16+
</td>
17+
</tr>
18+
<tr>
19+
<td><strong>CDK service desk</strong></td>
20+
<td><strong>Example request</strong></td>
21+
</tr>
22+
</table>
23+
24+
Polygon will then collaborate with the Implementation Provider to **schedule** the UTC timing and dates for the upgrade.
25+
26+
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.
27+
28+
See [Example Maintenance Communication to Network Partners](#example-maintenance-communication-to-network-partners) Implementation Providers can prepare for the customer network chains.
29+
30+
The high-level steps in the collaborative process are:
31+
32+
1. Implementation Provider halting the sequencer,
33+
2. Polygon executes the upgrade transaction,
34+
3. Implementation Provider upgrades components to Fork 12 stack,
35+
4. Implementation Provider restarts the components.
36+
37+
## 2. CDK Components Versions
38+
39+
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/)
40+
41+
The table below lists the CDK Fork ID 9 components and the new CDK FEP Fork ID 12 component.
42+
43+
> 💡 **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)
44+
45+
| **CDK Components** | **Fork ID 9** | **CDK Components** | **Fork ID 12** |
46+
|--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
47+
| 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)* |
48+
| | | CDK node<br>Sequence sender<br>Aggregator | 0.3.0-rc2 |
49+
| 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) |
50+
| Executor | | Executor | hermeznetwork/zkevm-prover:v8.0.0-RC14-fork.12 |
51+
| 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 |
52+
| 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 |
53+
| zkEVM rollup node | [v6.0.0](https://github.com/0xPolygonHermez/zkevm-prover/releases/tag/v6.0.0) | zkEVM rollup node | N/A |
54+
| 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) |
55+
| 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) |
56+
| Bridge UI | [Polygon Portal](https://portal.polygon.technology/) | Bridge UI | [Polygon Portal](https://portal.polygon.technology/) |
57+
58+
## 3. Implementation Provider Preparation Steps
59+
60+
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.
61+
62+
1. The Implementation Provider downloads CDK Fork 12 components binaries/images in advance so they are ready to deploy.
63+
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)
64+
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.
65+
- 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.
66+
4. Run the CDK-Node aggregator component in sync-only mode in advance to populate its database.
67+
5. Required Erigon pre-syncing:
68+
- Generate data stream files from the current `cdk-validium-node` database.
69+
- Tool and instructions can be found here:
70+
- [https://github.com/0xPolygonHermez/zkevm-node/tree/develop/tools/datastreamer](https://github.com/0xPolygonHermez/zkevm-node/tree/develop/tools/datastreamer)
71+
- Use the Erigon tool (from `cdk-erigon` repo) to serve the DS:
72+
- `go run ./zk/debug_tools/datastream-host --file /path/to/directory`
73+
- Start CDK-Erigon, which reads from this datastream (provide `zkevm.l2-datastreamer-url: 127.0.0.1:6900` in the config).
74+
- Wait for it to sync to the tip.
75+
- CDK-Erigon can be stopped. The generated files will be used later during the upgrade process.
76+
77+
The whole process should look more orr less like this:
78+
```bash
79+
# PREREQUISITES: Install GO 1.23
80+
WORK_DIR=/tmp
81+
82+
cd $WORK_DIR
83+
git clone https://github.com/0xPolygonHermez/zkevm-node.git
84+
cd $WORK_DIR/zkevm-node/tools/datastreamer
85+
vim config/tool.config.toml
86+
# Edit [StateDB] section with your StateDB credentials
87+
make generate-file
88+
89+
cd $WORK_DIR
90+
git clone https://github.com/0xPolygonHermez/cdk-erigon.git
91+
cd $WORK_DIR/cdk-erigon
92+
go run ./zk/debug_tools/datastream-host \
93+
--file $WORK_DIR/zkevm-node/tools/datastreamer/datastream
94+
95+
# Bring up Erigon pointing to that DS (localhost:6900 if running locally)
96+
# and let it fully sync to the end of the DS.
97+
```
98+
99+
## 4. Polygon Preparation Steps
100+
101+
1. Polygon will collaborate with the Implementation Provider to **schedule** the UTC timing and dates for the upgrade, incorporating required timelocks.
102+
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.
103+
3. Polygon will prepare in advance and with agreed timelock:
104+
- Rolluptype for fork 12
105+
- Upgrade transaction to fork 12
106+
4. For chains attached to the Polygon Agglayer, Polygon will handle steps to upgrade the permissionless node.
107+
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.
108+
109+
## 5. Operational Steps
110+
111+
**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.
112+
113+
### Steps to Halt the Sequencer
114+
115+
1. Stop the sequencer.
116+
2. Reconfigure the node to enforce sequencer stops at a specific `batch_num`:
117+
- Get the current batch number from StateDB:
118+
119+
```sql
120+
-- Note resulting value as X:
121+
SELECT batch_num, wip FROM state.batch WHERE wip IS true;
122+
```
123+
124+
- Edit node configuration:
125+
126+
```yaml
127+
# SEQUENCER CONFIG
128+
# Where X is the batch number obtained from the SQL query:
129+
Sequencer.Finalizer.HaltOnBatchNumber = X+1
130+
# Optional: Reduce batch time to avoid excessive downtime
131+
Sequencer.Finalizer.BatchMaxDeltaTimestamp = "120s" # 1800s
132+
```
133+
134+
```yaml
135+
# SEQUENCE SENDER CONFIG
136+
# Optional: Reduce sending time to avoid excessive downtime
137+
SequenceSender.WaitPeriodSendSequence = "10s" # 60s
138+
SequenceSender.LastBatchVirtualizationTimeMaxWaitPeriod = "30s" # 600s
139+
```
140+
141+
```yaml
142+
# AGGREGATOR CONFIG
143+
# Recommended: Reduce verify interval to avoid excessive downtime
144+
Aggregator.VerifyProofInterval = "5m"
145+
```
146+
147+
- Restart the sequencer, sequence sender, and aggregator to apply these configs.
148+
- Check that the sequencer halts when reaching batch X+1.
149+
- Wait until all pending batches are virtualized and verified (X):
150+
151+
```sql
152+
-- Both queries should return X
153+
SELECT max(batch_num) FROM state.virtual_batch;
154+
SELECT max(batch_num) FROM state.verified_batch;
155+
```
156+
157+
3. Stop all services (node, prover/executor, bridge).
158+
159+
> 💡 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.
160+
161+
1. **Please Note:** Wait for Polygon to send the L1 transaction (tx) and confirm it.
162+
2. **Polygon:** Upgrade the Smart Contract (multisig):
163+
- Upgrade rollup to fork 12.
164+
- Wait for the Tx to be finalized.
165+
166+
### Steps to Deploy CDK FEP Fork 12 Components
167+
168+
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)
169+
- 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:
170+
171+
```yaml
172+
zkevm.l2-sequencer-rpc-url: "http://sequencer-fqdn-or-ip:8123"
173+
zkevm.l2-datastreamer-url: "sequencer-fqdn-or-ip:6900"
174+
```
175+
176+
2. Start the stateless Executor.
177+
3. Start the CDK-Erigon Sequencer.
178+
4. Verify in the sequencer’s logs that new blocks are being generated with fork ID 12.
179+
5. Start the Pool Manager (if used/needed).
180+
6. Start CDK-Erigon RPCs (if used/needed).
181+
7. Start the Bridge.
182+
8. Start the CDK aggregator and Sequence Sender components.
183+
9. Start the stateless Prover.
184+
185+
### Polygon Steps for CDK Chains Attached to the Agglayer
186+
187+
Polygon will be accountable for upgrading the Agglayer permissionless nodes during the upgrade process.
188+
189+
1. When the Implementation Provider has stopped the sequencer.
190+
2. Polygon's v-team shuts down the CDK chain permissionless nodes hosted by Polygon:
191+
- 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).
192+
- Run helm update to deploy changes, which will shut down the permissionless nodes.
193+
3. Polygon v-team updates the Agglayer config:
194+
- Change the `image.tag` to the desired version [here](https://github.com/0xPolygon/helm-charts/tree/main/charts/permissionless-nodes/nodes).
195+
4. When the Implementation Provider restarts the sequencer and everything is running as expected:
196+
5. Polygon starts the upgraded permissionless nodes to ID12:
197+
- Set `replicaCount` to 3 for `rpc` and `executor`; set `replicaCount` to 1 for `synchronizer`.
198+
- Run helm update to deploy changes.
199+
- Monitor logs/service status in Datadog for progress.
200+
201+
### Post-Upgrade Validations
202+
203+
1. Test batch lifecycle.
204+
2. Test the bridge.
205+
206+
# Example Maintenance Communication to Network Partners
207+
208+
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.
209+
210+
**Maintenance Event:**  xxx Network Upgrade from Fork ID9 to Fork ID12
211+
212+
**Date:** TBD by Implementation Provider
213+
214+
**Time:** 00:00 PM EDT / 12:00 PM UTC
215+
216+
**Duration:** 2 Hours
217+
218+
**Things to Note:**
219+
220+
- 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).
221+
- Partners should **not update their nodes until after** the xxx network upgrade is confirmed as complete.
222+
- New Node Version: [cdk-erigon:v2.1.x](https://github.com/0xPolygonHermez/cdk-erigon/releases)
223+
224+
### Upgrade Instructions for Community Partners (Testnet/Mainnet)
225+
226+
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).
227+
228+
#### Instructions to Update Nodes
229+
230+
1. Stop the RPC, Synchronizer, and Executor components.
231+
2. Update the node (RPC and Synchronizer) to [cdk-erigon:v2.1.x](https://github.com/0xPolygonHermez/cdk-erigon/releases).
232+
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).
233+
4. Start the components in this order:
234+
1. Prover/Executor
235+
2. Synchronizer
236+
3. RPC

‎docs/img/cdk/CDK-service-desk.png‎

83.4 KB
Loading

‎docs/img/cdk/Example-request.png‎

113 KB
Loading

0 commit comments

Comments
 (0)