Skip to content

Commit fd27f5f

Browse files
kmurphypolygonkmurphypolygon
committed
commit first chunk
1 parent 974688a commit fd27f5f

File tree

4 files changed

+172
-1
lines changed

4 files changed

+172
-1
lines changed

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
The following instructions show you how to set up configurations to use a chain other than the default chains.
2+
3+
1. Create a directory `~/dynamic-configs` in the user home directory.
4+
5+
2. Use a chain name that starts with the word `dynamic` e.g. `dynamic-my-network`, and create three files in the `dynamic-configs` directory:
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+
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-{network}` and matches the names of the config files above.
13+
14+
3. Check the examples for Cardona in [`zk/examples/dynamic-configs`](https://github.com/0xPolygonHermez/cdk-erigon/tree/zkevm/zk/examples/dynamic-configs), copy these into your dynamic-configs folder, and edit as required.
15+
16+
!!! tip "Allocs file format conversation"
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 the following:
18+
19+
```sh
20+
go run cmd/hack/allocs/main.go [your-file-name]
21+
```
22+
23+
This converts the file to the format required by erigon and forms the `dynamic-{network}-allocs.json` file.
24+
25+
!!! tip "Contract addresses"
26+
Find the contract addresses for the `dynamic-{network}.yaml` in the files output when launching the network:
27+
28+
- zkevm.address-sequencer => create_rollup_output.json => sequencer
29+
- zkevm.address-zkevm => create_rollup_output.json => rollupAddress
30+
- zkevm.address-admin => deploy_output.json => admin
31+
- zkevm.address-rollup => deploy_output.json => polygonRollupManagerAddress
32+
- zkevm.address-ger-manager => deploy_output.json => polygonZkEVMGlobalExitRootAddress
33+
34+
4. The mount point for the folder on docker container is `~/dynamic-configs`, i.e. the home directory of the erigon user.
35+
36+
5. To use the new config when starting erigon, update the `--config` flag with the path to the config file e.g. `--config="/path/to/home-dir/dynamic-networks/dynamic-mynetwork.yaml"`.

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

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
Prereqs
2+
In order to use the optimal vectorized poseidon hashing for the Sparse Merkle Tree, on x86 the following packages are required (for Apple silicon it will fall back to the iden3 library and as such these dependencies are not required in that case.
3+
4+
Please install:
5+
6+
Linux: libgtest-dev libomp-dev libgmp-dev
7+
MacOS: brew install libomp brew install gmp
8+
Using the Makefile command: make build-libs will install these for the relevant architecture.
9+
10+
Due to dependency requirements Go 1.19 is required to build.
11+
12+
Sequencer (WIP)
13+
Enable Sequencer: CDK_ERIGON_SEQUENCER=1 ./build/bin/cdk-erigon <flags>
14+
15+
Special mode - L1 recovery
16+
The sequencer supports a special recovery mode which allows it to continue the chain using data from the L1. To enable this add the flag zkevm.l1-sync-start-block: [first l1 block with sequencer data]. It is important to find the first block on the L1 from the sequencer contract that contains the sequenceBatches event. When the node starts up it will pull of the L1 data into the cdk-erigon database and use this during execution rather than waiting for transactions from the txpool, effectively rebuilding the chain from the L1 data. This can be used 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 (useful if you have an RPC node available to speed up the process).
17+
18+
Important Note: 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 sync limit flag to 100.
19+
20+
zkEVM-specific API Support
21+
In order to enable the zkevm_ namespace, please add 'zkevm' to the http.api flag (see the example config below).
22+
23+
Supported
24+
zkevm_batchNumber
25+
zkevm_batchNumberByBlockNumber
26+
zkevm_consolidatedBlockNumber
27+
zkevm_isBlockConsolidated
28+
zkevm_verifiedBatchNumber
29+
zkevm_isBlockVirtualized
30+
zkevm_virtualBatchNumber
31+
zkevm_getFullBlockByHash
32+
zkevm_getFullBlockByNumber
33+
Supported (remote)
34+
zkevm_getBatchByNumber
35+
Not yet supported
36+
zkevm_getNativeBlockHashesInRange
37+
Deprecated
38+
zkevm_getBroadcastURI - it was removed by zkEvm
39+
Limitations/Warnings
40+
The golden poseidon hashing will be much faster on x86, so developers on Mac may experience slowness on Apple silicone
41+
Falling behind the network significantly will cause a SMT rebuild - which will take some time for longer chains
42+
Configuration Files
43+
Config files are the easiest way to configure cdk-erigon, there are examples in the repository for each network e.g. hermezconfig-mainnet.yaml.example.
44+
45+
Depending on the RPC provider you are using, you may wish to alter zkevm.rpc-ratelimit.
46+
47+
Running CDK-Erigon
48+
Build using make cdk-erigon
49+
Set up your config file (copy one of the examples found in the repository root directory, and edit as required)
50+
run ./build/bin/cdk-erigon --config="./hermezconfig-{network}.yaml" (complete the name of your config file as required)
51+
NB: --externalcl flag is removed in upstream erigon so beware of re-using commands/config
52+
53+
Run modes
54+
cdk-erigon can be run as an RPC node which will use the data stream to fetch new block/batch information and track a remote sequencer (the default behaviour). It can also run as a sequencer. To enable the sequencer, set the CDK_ERIGON_SEQUENCER environment variable to 1 and start the node. 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.
55+
56+
Docker (DockerHub)
57+
The image comes with 3 preinstalled default configs which you may wish to edit according to the config section below, otherwise you can mount your own config to the container as necessary.
58+
59+
A datadir must be mounted to the container to persist the chain data between runs.
60+
61+
Example commands:
62+
63+
Mainnet
64+
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
65+
Cardona
66+
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
67+
docker-compose example:
68+
69+
Mainnet:
70+
NETWORK=mainnet L1_RPC_URL=https://rpc.eth.gateway.fm docker-compose -f docker-compose-example.yml up -d
71+
Cardona:
72+
NETWORK=cardona L1_RPC_URL=https://rpc.sepolia.org docker-compose -f docker-compose-example.yml up -d
73+
Config
74+
The examples are comprehensive but there are some key fields which will need setting e.g. datadir, and others you may wish to change to increase performance, e.g. zkevm.l1-rpc-url as the provided RPCs may have restrictive rate limits.
75+
76+
For a full explanation of the config options, see below:
77+
78+
datadir: Path to your node's data directory.
79+
chain: Specifies the L2 network to connect with, e.g., hermez-mainnet. For dynamic configs this should always be in the format dynamic-{network}
80+
http: Enables HTTP RPC server (set to true).
81+
private.api.addr: Address for the private API, typically localhost:9091, change this to run multiple instances on the same machine
82+
zkevm.l2-chain-id: Chain ID for the L2 network, e.g., 1101.
83+
zkevm.l2-sequencer-rpc-url: URL for the L2 sequencer RPC.
84+
zkevm.l2-datastreamer-url: URL for the L2 data streamer.
85+
zkevm.l1-chain-id: Chain ID for the L1 network.
86+
zkevm.l1-rpc-url: L1 Ethereum RPC URL.
87+
zkevm.address-sequencer: The contract address for the sequencer
88+
zkevm.address-zkevm: The address for the zkevm contract
89+
zkevm.address-admin: The address for the admin contract
90+
zkevm.address-rollup: The address for the rollup contract
91+
zkevm.address-ger-manager: The address for the GER manager contract
92+
zkevm.rpc-ratelimit: Rate limit for RPC calls.
93+
zkevm.data-stream-port: Port for the data stream. This needs to be set to enable the datastream server
94+
zkevm.data-stream-host: The host for the data stream i.e. localhost. This must be set to enable the datastream server
95+
zkevm.datastream-version: Version of the data stream protocol.
96+
externalcl: External consensus layer flag.
97+
http.api: List of enabled HTTP API modules.
98+
Sequencer specific config:
99+
100+
zkevm.executor-urls: A csv list of the executor URLs. These will be used in a round robbin fashion by the sequencer
101+
zkevm.executor-strict: Defaulted to true, but can be set to false when running the sequencer without verifications (use with extreme caution)
102+
zkevm.witness-full: Defaulted to true. Controls whether the full or partial witness is used with the executor.
103+
zkevm.sequencer-initial-fork-id: The fork id to start the network with.
104+
Useful config entries:
105+
106+
zkevm.sync-limit: This will ensure the network only syncs to a given block height.
107+
108+
## Networks
109+
110+
| Network Name | Chain ID | ForkID | Genesis File | RPC URL | Rootchain | Rollup Address |
111+
|---------------|----------|--------|--------------|--------------------------------------------------|------------------|----------------------------------------------|
112+
| zkEVM Mainnet | 1101 | 9 | [Link](https://hackmd.io/bpmxb5QaSFafV0nB4i-KZA) | [Mainnet RPC](https://zkevm-rpc.com/) | Ethereum Mainnet | `0x5132A183E9F3CB7C848b0AAC5Ae0c4f0491B7aB2` |
113+
| zkEVM Cardona | 2442 | 9 | [Link](https://hackmd.io/Ug9pB613SvevJgnXRC4YJA) | [Cardona RPC](https://rpc.cardona.zkevm-rpc.com/) | Sepolia | `0x32d33D5137a7cFFb54c5Bf8371172bcEc5f310ff` |

‎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+
The PoErigon is a performant implementation of the Ethereum execution plus optional consensus layers. The Polygon fork optimizes syncing with the Polygon zkEVM.
4+
5+
## Release roadmap
6+
7+
- `v0.9.x`: Support for the Polygon Cardona testnet.
8+
- `v1.x.x`: Support for Polygon mainnet.
9+
- `v3.x.x`: Erigon 3 based (snapshot support).
10+
11+
### Current status
12+
13+
At the time of writing, `cdk-erigon` supports the following chains and fork ids:
14+
15+
- zkEVM Cardona testnet: beta support.
16+
- zkEVM mainnet: alpha support.
17+
- CDK chains: experimental support (forkid.8 and above).

‎mkdocs.yml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,12 @@ nav:
5454
- CDK: cdk/index.md
5555
- Overview: cdk/overview.md
5656
- Version compatibility matrix: cdk/version-matrix.md
57-
- Get started: '!import https://github.com/0xPolygon/kurtosis-cdk?branch=main'
57+
- Get started - Kurtosis: '!import https://github.com/0xPolygon/kurtosis-cdk?branch=main'
58+
- Get started - Erigon:
59+
- Releases: cdk/erigon/releases.md
60+
- Deploy a node: cdk/erigon/deploy-cdk-erigon.md
61+
- How to:
62+
- Configure chains dynamically: cdk/erigon/chain-config.md
5863
- Architecture:
5964
- CDK rollup: cdk/architecture/cdk-zkevm.md
6065
- CDK validium: cdk/architecture/cdk-validium.md

0 commit comments

Comments
 (0)