Skip to content

Commit 19a40c4

Browse files
kmurphypolygonkmurphypolygon
authored
Merge pull request 0xPolygon#440 from 0xPolygon/cdk/erigon-setup
CDK: erigon docs
2 parents ba71ea5 + 16c2b07 commit 19a40c4

File tree

9 files changed

+366
-2
lines changed

9 files changed

+366
-2
lines changed

‎docs/cdk/concepts/rollup-vs-validium.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,12 @@ Rollups use Ethereum as a [data availability](https://docs.polygon.technology/cd
88

99
Using Ethereum to store transaction data is generally considered the most secure option for DA as it leverages Ethereum's security and decentralization. However, this approach is costly, as the L2 must pay Ethereum’s high gas fees for storing data on the L1, which typically results in higher gas fees for users.
1010

11-
Within the rollup category, there are further nuances to storing transaction data on Ethereum. Some rollups post serialized transaction data directly, whereas others post state differences instead. Some rollups use [calldata](https://docs.soliditylang.org/en/v0.8.26/types.html#data-location) to store transaction data, while others use more recent Ethereum features such as Blobs, introduced in [EIP-4844](https://www.eip4844.com/).
11+
Within the rollup category, there are further nuances to storing transaction data on Ethereum. Some rollups post serialized transaction data directly, whereas others post state differences instead. Some rollups use [calldata](https://docs.soliditylang.org/en/v0.8.26/types.html#data-location) to store transaction data, while others use more recent Ethereum features such as blobs, introduced in [EIP-4844](https://www.eip4844.com/).
1212

1313
The CDK provides full flexibility to developers to choose what to do with transaction data, including the ability to build rollups that store data on Ethereum as a rollup like the Polygon zkEVM.
1414

1515
!!! note
16-
Currently, the rollup mode of Polygon CDK does not support BLOB mode (EIP4844), but this functionality is coming soon.
16+
Currently, the rollup mode of Polygon CDK does not support blobs (EIP-4844), but this functionality is coming soon.
1717

1818
## Validiums
1919

‎docs/cdk/erigon/chain-config.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
To use chains other than the [defaults](releases.md#current-status), supply a set of custom configuration files.
2+
3+
1. Ensure the chain name starts with the word `dynamic` e.g. `dynamic-mynetwork`.
4+
5+
2. Create the following files for dynamic configs. The examples for Cardona are in `zk/examples/dynamic-configs` and can be edited as required:
6+
7+
- `dynamic-{network}-allocs.json` - the allocs file.
8+
- `dynamic-{network}-chainspec.json` - the chainspec file.
9+
- `dynamic-{network}-conf.json` - an additional configuration file.
10+
- `dynamic-{network}.yaml` - the run config file for erigon.
11+
12+
You can use any of the example yaml files at the root of the repo as a base and edit as required, but ensure the `chain` field is in the format `dynamic-mynetwork` and matches the names of the config files above.
13+
14+
3. Put the erigon config file, along with the other files, in the directory of your choice. For example `dynamic-mynetwork`.
15+
16+
!!! tip
17+
- If you have allocs in the Polygon format from the original network launch, save this file to the root of the `cdk-erigon` code base and run `go run cmd/hack/allocs/main.go [your-file-name]` to convert it to the format needed by erigon.
18+
- This creates the `dynamic-{network}-allocs.json` file.
19+
20+
!!! tip
21+
Find the following contract addresses for the `dynamic-{network}.yaml` in the output files created at network launch:
22+
23+
- `zkevm.address-sequencer` => `create_rollup_output.json` => `sequencer`
24+
- `zkevm.address-zkevm` => `create_rollup_output.json` => `rollupAddress`
25+
- `zkevm.address-admin` => `deploy_output.json` => `admin`
26+
- `zkevm.address-rollup` => `deploy_output.json` => `polygonRollupManagerAddress`
27+
- `zkevm.address-ger-manager` => `deploy_output.json` => `polygonZkEVMGlobalExitRootAddress`
28+
29+
4. Mount the directory containing the config files on a Docker container. For example `/dynamic-mynetwork`.
30+
31+
5. To use the new config when starting erigon, use the `--config` flag with the path to the config file e.g. `--config="/dynamic-mynetwork/dynamic-mynetwork.yaml"`.

‎docs/cdk/erigon/deploy-cdk-erigon.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
## Prerequisites
2+
3+
### Hardware requirements
4+
5+
* A Linux-based OS (e.g. Ubuntu 22.04 LTS).
6+
* At least 32GB RAM with a 4-core CPU.
7+
* Both Apple Silicon and AMD64 are supported.
8+
9+
!!! tip
10+
- On x86, the following packages are required to use the optimal, vectorized-Poseidon-hashing for the sparse Merkle tree:
11+
12+
- Linux: `libgtest-dev libomp-dev libgmp-dev`
13+
- MacOS: `brew install libomp` `brew install gmp`
14+
15+
- For Apple silicon, the `iden3` library is used instead.
16+
17+
### Software
18+
19+
The installation requires [Go 1.19](https://go.dev/doc/manage-install).
20+
21+
### Set up
22+
23+
1. Clone the repo and `cd` to the root:
24+
25+
```sh
26+
git clone https://github.com/0xPolygonHermez/cdk-erigon
27+
cd cdk-erigon/
28+
```
29+
30+
2. Install the relevant libraries for your architecture by running:
31+
32+
```sh
33+
make build-libs
34+
```
35+
36+
## L1 interaction
37+
38+
In order to retrieve data from L1, the L1 syncer needs to know how to request the highest block.
39+
40+
This can be configured by the flag: `zkevm.l1-highest-block-type`.
41+
42+
The flag defaults to retrieving the `finalized` block. However, there are cases where you may wish to pass `safe` or `latest`.
43+
44+
## Set up sequencer
45+
46+
!!! warning "Work in progress"
47+
- Sequencer is production ready from `v2.x.x` onwards.
48+
- Please check the [roadmap](releases.md#roadmap) for more information.
49+
50+
Enable the sequencer by setting the following environment variable:
51+
52+
```sh
53+
CDK_ERIGON_SEQUENCER=1 ./build/bin/cdk-erigon <flags>
54+
```
55+
56+
### Special mode - L1 recovery
57+
58+
The sequencer supports a special recovery mode which allows it to continue the chain using data from the L1.
59+
60+
To enable this add the following flag:
61+
62+
```sh
63+
`zkevm.l1-sync-start-block: [first l1 block with sequencer data]`.
64+
```
65+
66+
!!! important
67+
Find the first block on the L1 from the sequencer contract that contains the `sequenceBatches` event.
68+
69+
When the node starts up it pulls the L1 data into the `cdk-erigon` database and uses this during execution rather than waiting for transactions from the transaction pool, effectively rebuilding the chain from the L1 data.
70+
71+
You can use this in tandem with unwinding the chain, or using the `zkevm.sync-limit` flag to limit the chain to a certain block height before starting the L1 recovery. This is useful if you have an RPC node available to speed up the process.
72+
73+
!!! warning
74+
If using the `zkevm.sync-limit` flag, you need to go to the boundary of a `batch+1` block; so if batch `41` ends at block `99` then set the flag to `100`.
75+
76+
## Enable zkEVM APIs
77+
78+
In order to enable the `zkevm_ namespace`, add `zkevm` to the [`http.api`](#configurations) flag.
79+
80+
### Supported functions
81+
82+
- `zkevm_batchNumber`
83+
- `zkevm_batchNumberByBlockNumber`
84+
- `zkevm_consolidatedBlockNumber`
85+
- `zkevm_isBlockConsolidated`
86+
- `zkevm_verifiedBatchNumber`
87+
- `zkevm_isBlockVirtualized`
88+
- `zkevm_virtualBatchNumber`
89+
- `zkevm_getFullBlockByHash`
90+
- `zkevm_getFullBlockByNumber`
91+
- `zkevm_virtualCounters`
92+
- `zkevm_traceTransactionCounters`
93+
94+
### Supported functions (remote)
95+
96+
- `zkevm_getBatchByNumber`
97+
98+
### Not yet supported
99+
100+
- `zkevm_getNativeBlockHashesInRange`
101+
102+
### Deprecated
103+
104+
- `zkevm_getBroadcastURI` - removed by zkEVM.
105+
106+
## Limitations/warnings
107+
108+
- The golden poseidon hashing is much faster on x86, so developers using MacOS M1/M2 chips may experience slower processing.
109+
- Falling behind the network significantly causes an SMT rebuild which takes some time to complete on longer chains.
110+
111+
## Configuration files
112+
113+
- Config files are the easiest way to configure `cdk-erigon`.
114+
- There are examples files in the repository for each network; e.g. [`hermezconfig-mainnet.yaml.example`](https://github.com/0xPolygonHermez/cdk-erigon/blob/1d56fb0a5a64160fd8c05e11ffc8b668bd70b9e8/hermezconfig-mainnet.yaml.example#L4).
115+
- Depending on your RPC provider, you may wish to alter `zkevm.rpc-ratelimit` in the yaml file.
116+
117+
## Running CDK Erigon
118+
119+
1. Build the node with the following command:
120+
121+
```sh
122+
make cdk-erigon
123+
```
124+
125+
2. Set up your config file by copying one of the examples found in the repository root directory, and edit as required and add your network name to the following command.
126+
127+
```sh
128+
run ./build/bin/cdk-erigon --config="./hermezconfig-{network}.yaml"
129+
```
130+
131+
!!! warn
132+
Be aware that the `--externalcl` flag is removed upstream in `cdk-erigon` so take care when reusing commands/configurations.
133+
134+
### Run modes
135+
136+
`cdk-erigon` can run as an RPC node which uses the data stream to fetch new block/batch information and track a remote sequencer. This is the default behavior.
137+
138+
It can also run as a sequencer. To enable the sequencer, set the `CDK_ERIGON_SEQUENCER` environment variable to `1` and start the node.
139+
140+
!!! warning "Work in progress"
141+
- Sequencer is production ready from `v2.x.x` onwards.
142+
- Please check the [roadmap](releases.md#roadmap) for more information.
143+
144+
`cdk-erigon` supports migrating a node from being an RPC node to a sequencer and vice versa. To do this, stop the node, set the `CDK_ERIGON_SEQUENCER` environment variable to the desired value and restart the node. Please ensure that you do include the sequencer specific flags found below when running as a sequencer. You can include these flags when running as an RPC to keep a consistent configuration between the two run modes.
145+
146+
### Docker (DockerHub)
147+
148+
The image comes with three preinstalled default configurations which you can edit according to the configuration section below; otherwise you can mount your own config to the container as necessary.
149+
150+
A datadir must be mounted to the container to persist the chain data between runs.
151+
152+
#### Example `docker` commands
153+
154+
##### Mainnet
155+
156+
```sh
157+
docker run -d -p 8545:8545 -v ./cdk-erigon-data/:/home/erigon/.local/share/erigon hermeznetwork/cdk-erigon --config="./mainnet.yaml" --zkevm.l1-rpc-url=https://rpc.eth.gateway.fm
158+
```
159+
160+
##### Cardona
161+
162+
```sh
163+
docker run -d -p 8545:8545 -v ./cdk-erigon-data/:/home/erigon/.local/share/erigon hermeznetwork/cdk-erigon --config="./cardona.yaml" --zkevm.l1-rpc-url=https://rpc.sepolia.org
164+
```
165+
166+
#### Example `docker-compose` commands
167+
168+
##### Mainnet
169+
170+
```sh
171+
NETWORK=mainnet L1_RPC_URL=https://rpc.eth.gateway.fm docker-compose -f docker-compose-example.yml up -d
172+
```
173+
174+
##### Cardona:
175+
176+
```sh
177+
NETWORK=cardona L1_RPC_URL=https://rpc.sepolia.org docker-compose -f docker-compose-example.yml up -d
178+
```
179+
180+
## Configurations
181+
182+
The following examples are comprehensive. There are key fields which must be set, such as `datadir`, and some you may wish to change to increase performance, such as `zkevm.l1-rpc-url` as the provided RPCs may have restrictive rate limits.
183+
184+
- `datadir`: Path to your node's data directory.
185+
- `chain`: Specifies the L2 network to connect with; e.g. `hermez-mainnet`. For dynamic configs this should always be in the format `dynamic-{network}`.
186+
- `http`: Enables HTTP RPC server (set to `true`).
187+
- `private.api.addr`: Address for the private API, typically `localhost:9091`. Change this to run multiple instances on the same machine.
188+
- `zkevm.l2-chain-id`: Chain ID for the L2 network; e.g. 1101.
189+
- `zkevm.l2-sequencer-rpc-url`: URL for the L2 sequencer RPC.
190+
- `zkevm.l2-datastreamer-url`: URL for the L2 data streamer.
191+
- `zkevm.l1-chain-id`: Chain ID for the L1 network.
192+
- `zkevm.l1-rpc-url`: L1 Ethereum RPC URL.
193+
- `zkevm.address-sequencer`: The contract address for the sequencer.
194+
- `zkevm.address-zkevm`: The address for the zkevm contract.
195+
- `zkevm.address-admin`: The address for the admin contract.
196+
- `zkevm.address-rollup`: The address for the rollup contract.
197+
- `zkevm.address-ger-manager`: The address for the GER manager contract.
198+
- `zkevm.rpc-ratelimit`: Rate limit for RPC calls.
199+
- `zkevm.data-stream-port`: Port for the data stream. This needs to be set to enable the datastream server.
200+
- `zkevm.data-stream-host`: The host for the data stream i.e. `localhost`. This must be set to enable the datastream server.
201+
- `zkevm.datastream-version`: Version of the data stream protocol.
202+
- `externalcl`: External consensus layer flag.
203+
- `http.api`: List of enabled HTTP API modules.
204+
205+
### Sequencer specific config
206+
207+
- `zkevm.executor-urls`: A csv list of the executor URLs. These are used in a round robbin fashion by the sequencer.
208+
- `zkevm.executor-strict`: Default is true but can be set to false when running the sequencer without verifications (_use with extreme caution_).
209+
- `zkevm.witness-full`: Default is true. Controls whether the full or partial witness is used with the executor.
210+
- `zkevm.sequencer-initial-fork-id`: The fork id to start the network with.
211+
212+
### Useful config entries
213+
214+
- `zkevm.sync-limit`: This ensures the network only syncs to a given block height.

‎docs/cdk/erigon/index.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
[Erigon](https://github.com/ledgerwatch/erigon), previously known as Turbo-Geth, is a high-performance Ethereum client designed to handle the growing demands of the Ethereum blockchain. It focuses on optimizing performance, disk space, and synchronization speed.
2+
3+
Erigon has a modular architecture, which makes it highly efficient and customizable for various common blockchain tasks.
4+
5+
## Key features
6+
7+
### Modular architecture
8+
Erigon's modular design allows different components to be developed, optimized, and updated independently. This separation of concerns helps in improving the performance and reliability of each module.
9+
10+
### Performance optimization
11+
Erigon employs advanced techniques for data handling, such as memory-mapped files and optimized data structures, to ensure high-speed processing of blockchain data.
12+
13+
### Reduced disk usage
14+
By implementing a more efficient database schema, Erigon significantly reduces disk usage compared to other Ethereum clients.
15+
16+
### Fast synchronization
17+
Erigon's fast sync method allows nodes to catch up with the blockchain more quickly by downloading only the most recent state of the blockchain, rather than the entire history.
18+
19+
## Erigon as a sequencer
20+
21+
Blockchain sequencers play a critical role in ordering transactions and creating new blocks. Erigon's sequencer processes incoming transactions, organizes them into blocks, and propagates these blocks across the network.
22+
23+
## RPC node
24+
25+
The remote procedure call (RPC) interface in Erigon allows external applications to interact with the underlying blockchain. This interface is essential for decentralized applications such as dApps, wallets, and other blockchain services. The RPC provides methods for querying blockchain data, sending transactions, and managing accounts.
26+
27+
The following sequence diagram shows how a transaction is processed by the Erigon node.
28+
29+
![Erigon transactions](../../img/cdk/erigon/erigon.png)
30+
31+
## CDK erigon
32+
33+
The CDK implementation of Erigon, available at [0xPolygonHermez/cdk-erigon](https://github.com/0xPolygonHermez/cdk-erigon), is a specialized adaptation that provides a framework for creating and managing zkEVM networks with that run using the zkEVM protocol.
34+
35+
### Differences from the standard erigon
36+
37+
- zkEVM consensus mechanisms: The CDK implementation integrates with zkEVM consensus protocols.
38+
39+
- Optimized for layer 2 solutions: This adaptation is optimized for layer 2 scaling solutions which focus on high throughput and reduced transaction costs.
40+
41+
- Enhanced modular architecture: While Erigon is already modular, the CDK implementation extends this modularity, allowing developers to more easily customize and replace components, such as the consensus mechanism, transaction pool, and state management.
42+
43+
- Integration with the Polygon ecosystem: CDK Erigon is designed to seamlessly integrate with the broader Polygon ecosystem, facilitating interoperability with Polygon products and services, scaling solutions and tools.
44+
45+
- Tailored RPC interface: The RPC interface in the CDK implementation is adapted to support the zkEVM protocol's functionalities and optimizations, enabling more efficient communication and interaction with the network.

‎docs/cdk/erigon/network-recovery.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
CDK-erigon supports two simple methods for network recovery:
2+
3+
- Partial L1 recovery; from a partially synced datadir.
4+
- Full L1 recovery; from a completely empty datadir.
5+
6+
## Partial recovery
7+
8+
### Sync limit step
9+
10+
First, find out the following:
11+
12+
- What batch to set as the first batch to start recovering from.
13+
- What is the last block of the batch prior to this. It can be found by querying the RPC or checking the L1 data from the sequencer contract.
14+
15+
Once we know the last block number, we can begin a fresh sync to get to that block height. To do this use the same configuration that you would normally use for the network but add an additional flag in `--zkevm.sync-limit=[block you need + 1]`.
16+
17+
!!! info "Example"
18+
In order to sync to block 100, enter `101` for the flag value.
19+
20+
Let the node run and it eventually sits in a loop at this block height. Once the node reaches the required height, you can stop the node as normal.
21+
22+
### L1 recovery step
23+
24+
First determine the earliest L1 block height suitable for recovery.
25+
26+
You can do this by looking for the L1 block number for the earliest transaction against the sequencer contract (found in the cdk-erigon config).
27+
28+
Once you have the info you need, start the node up with a new flag: `zkevm.l1-sync-start-block=[l1block height]`.
29+
30+
!!! important
31+
Remove the `zkevm.sync-limit` flag from the previous step at this point if you are running a partial recovery.
32+
33+
It is important to pick the earliest block on the network so that the L1 info tree update events are gathered correctly. If not, you run the risk of the indexes
34+
not lining up.
35+
36+
## Full recovery
37+
38+
Follow the L1 recovery step as above, and use a completely fresh datadir.

‎docs/cdk/erigon/releases.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
[`cdk-erigon`](https://github.com/0xPolygonHermez/cdk-erigon) is a fork of [erigon](https://github.com/ledgerwatch/erigon) and is currently in alpha.
2+
3+
It is optimized for syncing with the Polygon zkEVM network.
4+
5+
## Current chain/fork support status
6+
7+
At the time of writing, `cdk-erigon` supports the following chains and fork ids:
8+
9+
- zkEVM Cardona testnet: full support.
10+
- zkEVM mainnet: beta support.
11+
- CDK chains: beta support (forkid.9 and above).
12+
13+
## Roadmap
14+
15+
- `v1.1.x`: RPC (full support).
16+
- `v2.x.x`: Sequencer (full support).
17+
- `v3.x.x`: Erigon 3 based (snapshot support).

‎docs/cdk/erigon/resources.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
## Networks
2+
3+
| Network Name | Chain ID | ForkID | Genesis File | RPC URL | Rootchain | Rollup Address |
4+
|---------------|----------|--------|--------------|--------------------------------------------------|------------------|----------------------------------------------|
5+
| zkEVM Mainnet | 1101 | 9 | [Link](https://hackmd.io/bpmxb5QaSFafV0nB4i-KZA) | [Mainnet RPC](https://zkevm-rpc.com/) | Ethereum Mainnet | `0x5132A183E9F3CB7C848b0AAC5Ae0c4f0491B7aB2` |
6+
| zkEVM Cardona | 2442 | 9 | [Link](https://hackmd.io/Ug9pB613SvevJgnXRC4YJA) | [Cardona RPC](https://rpc.cardona.zkevm-rpc.com/) | Sepolia | `0x32d33D5137a7cFFb54c5Bf8371172bcEc5f310ff` |
7+
8+
## Block explorers
9+
10+
- Mainnet: [PolygonScan mainnet](https://zkevm.polygonscan.com/)
11+
- Cardona: [PolygonScan Cardona](https://cardona-zkevm.polygonscan.com/)

‎docs/img/cdk/erigon/erigon.png‎

181 KB
Loading

‎mkdocs.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,14 @@ nav:
7575
- Manage allowlists with policies: cdk/how-to/manage-policies.md
7676
- Quickly test a running stack: cdk/how-to/quick-test-stack.md
7777
- Connect to CDK testnets: cdk/how-to/connect-testnet.md
78+
- Erigon:
79+
- Erigon: cdk/erigon/index.md
80+
- Releases: cdk/erigon/releases.md
81+
- Deploy a node: cdk/erigon/deploy-cdk-erigon.md
82+
- How to:
83+
- Configure chains dynamically: cdk/erigon/chain-config.md
84+
- Recover the network: cdk/erigon/network-recovery.md
85+
- Resources: cdk/erigon/resources.md
7886
- Architecture:
7987
- CDK rollup: cdk/architecture/cdk-zkevm.md
8088
- CDK validium: cdk/architecture/cdk-validium.md

0 commit comments

Comments
 (0)