Skip to content

Commit a97a4ec

Browse files
kmurphypolygonkmurphypolygon
committed
complete changes
1 parent 568f1ba commit a97a4ec

File tree

1 file changed

+127
-72
lines changed

1 file changed

+127
-72
lines changed

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

Lines changed: 127 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,21 @@
22

33
1. The installation requires [Go 1.19](https://go.dev/doc/manage-install).
44

5-
2. Install the relevant libraries for your architecture by running:
5+
2. Clone the repo and `cd` to the root:
6+
7+
```sh
8+
git clone https://github.com/0xPolygonHermez/cdk-erigon
9+
cd cdk-erigon/
10+
```
11+
12+
3. Install the relevant libraries for your architecture by running:
613

714
```sh
815
make build-libs
916
```
1017

1118
!!! tip "Hardware specifics"
12-
- On x86, the following packages are used by the optimal, vectorized, Poseidon hashing for the sparse Merkle tree:
19+
- On x86, the following packages are used by the optimal, vectorized-Poseidon-hashing for the sparse Merkle tree:
1320

1421
- Linux: `libgtest-dev libomp-dev libgmp-dev`
1522
- MacOS: `libomp brew install gmp`
@@ -18,121 +25,169 @@
1825

1926
## Set up sequencer (WIP)
2027

21-
Run the following to enable the sequencer:
28+
Enable the sequencer by setting the following environment variable:
2229

2330
```sh
2431
CDK_ERIGON_SEQUENCER=1 ./build/bin/cdk-erigon <flags>
2532
```
2633

2734
### Special mode - L1 recovery
2835

29-
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).
36+
The sequencer supports a special recovery mode which allows it to continue the chain using data from the L1.
37+
38+
To enable this add the following flag:
39+
40+
```sh
41+
`zkevm.l1-sync-start-block: [first l1 block with sequencer data]`.
42+
```
43+
44+
!!! important
45+
Find the first block on the L1 from the sequencer contract that contains the `sequenceBatches` event.
46+
47+
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.
3048

31-
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.
49+
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.
50+
51+
!!! tip
52+
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`.
3253

3354
## Enable zkEVM APIs
3455

35-
In order to enable the `zkevm_ namespace`, add `zkevm` to the `http.api` flag (see the example config below??).
56+
In order to enable the `zkevm_ namespace`, add `zkevm` to the [`http.api`](#configurations) flag.
3657

3758
### Supported functions
3859

39-
`zkevm_batchNumber`
40-
`zkevm_batchNumberByBlockNumber`
41-
`zkevm_consolidatedBlockNumber`
42-
`zkevm_isBlockConsolidated`
43-
`zkevm_verifiedBatchNumber`
44-
`zkevm_isBlockVirtualized`
45-
`zkevm_virtualBatchNumber`
46-
`zkevm_getFullBlockByHash`
47-
`zkevm_getFullBlockByNumber`
60+
- `zkevm_batchNumber`
61+
- `zkevm_batchNumberByBlockNumber`
62+
- `zkevm_consolidatedBlockNumber`
63+
- `zkevm_isBlockConsolidated`
64+
- `zkevm_verifiedBatchNumber`
65+
- `zkevm_isBlockVirtualized`
66+
- `zkevm_virtualBatchNumber`
67+
- `zkevm_getFullBlockByHash`
68+
- `zkevm_getFullBlockByNumber`
4869

4970
### Supported (remote)
5071

51-
`zkevm_getBatchByNumber`
72+
- `zkevm_getBatchByNumber`
5273

5374
### Not yet supported
5475

55-
`zkevm_getNativeBlockHashesInRange`
76+
- `zkevm_getNativeBlockHashesInRange`
5677

5778
### Deprecated
5879

59-
`zkevm_getBroadcastURI` - removed by zkEVM.
80+
- `zkevm_getBroadcastURI` - removed by zkEVM.
6081

6182
## Limitations/warnings
6283

63-
The golden poseidon hashing will be much faster on x86, so developers on Mac may experience slowness on Apple silicone
64-
Falling behind the network significantly will cause a SMT rebuild - which will take some time for longer chains
84+
- The golden poseidon hashing is much faster on x86, so developers using MacOS M1/M2 chips may experience slower processing.
85+
- Falling behind the network significantly causes an SMT rebuild which takes some time to complete on longer chains.
86+
87+
## Configuration files
88+
89+
- Config files are the easiest way to configure `cdk-erigon`.
90+
- 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).
91+
- Depending on your RPC provider, you may wish to alter `zkevm.rpc-ratelimit` in the yaml file.
92+
93+
## Running CDK Erigon
94+
95+
1. Build the node with the following command:
6596

66-
### Configuration files
97+
```sh
98+
make cdk-erigon
99+
```
67100

68-
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.
101+
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.
69102

70-
Depending on the RPC provider you are using, you may wish to alter zkevm.rpc-ratelimit.
103+
```sh
104+
run ./build/bin/cdk-erigon --config="./hermezconfig-{network}.yaml"
105+
```
71106

72-
## Running CDK-Erigon
73-
Build using make cdk-erigon
74-
Set up your config file (copy one of the examples found in the repository root directory, and edit as required)
75-
run ./build/bin/cdk-erigon --config="./hermezconfig-{network}.yaml" (complete the name of your config file as required)
76-
NB: --externalcl flag is removed in upstream erigon so beware of re-using commands/config
107+
!!! warn
108+
Be aware that the `--externalcl` flag is removed upstream in `cdk-erigon` so take care when reusing commands/configurations.
77109

78110
### Run modes
79-
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.
80111

81-
Docker (DockerHub)
82-
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.
112+
`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.
113+
114+
It can also run as a sequencer. To enable the sequencer, set the `CDK_ERIGON_SEQUENCER` environment variable to `1` and start the node.
115+
116+
`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.
117+
118+
### Docker (DockerHub)
119+
120+
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.
83121

84122
A datadir must be mounted to the container to persist the chain data between runs.
85123

86-
Example commands:
124+
#### Example `docker` commands
87125

88-
Mainnet
126+
##### Mainnet
127+
128+
```sh
89129
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
90-
Cardona
130+
```
131+
132+
##### Cardona
133+
134+
```sh
91135
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
92-
docker-compose example:
136+
```
93137

94-
Mainnet:
138+
#### Example `docker-compose` commands
139+
140+
##### Mainnet
141+
142+
```sh
95143
NETWORK=mainnet L1_RPC_URL=https://rpc.eth.gateway.fm docker-compose -f docker-compose-example.yml up -d
96-
Cardona:
144+
```
145+
146+
##### Cardona:
147+
148+
```sh
97149
NETWORK=cardona L1_RPC_URL=https://rpc.sepolia.org docker-compose -f docker-compose-example.yml up -d
98-
Config
99-
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.
100-
101-
For a full explanation of the config options, see below:
102-
103-
datadir: Path to your node's data directory.
104-
chain: Specifies the L2 network to connect with, e.g., hermez-mainnet. For dynamic configs this should always be in the format dynamic-{network}
105-
http: Enables HTTP RPC server (set to true).
106-
private.api.addr: Address for the private API, typically localhost:9091, change this to run multiple instances on the same machine
107-
zkevm.l2-chain-id: Chain ID for the L2 network, e.g., 1101.
108-
zkevm.l2-sequencer-rpc-url: URL for the L2 sequencer RPC.
109-
zkevm.l2-datastreamer-url: URL for the L2 data streamer.
110-
zkevm.l1-chain-id: Chain ID for the L1 network.
111-
zkevm.l1-rpc-url: L1 Ethereum RPC URL.
112-
zkevm.address-sequencer: The contract address for the sequencer
113-
zkevm.address-zkevm: The address for the zkevm contract
114-
zkevm.address-admin: The address for the admin contract
115-
zkevm.address-rollup: The address for the rollup contract
116-
zkevm.address-ger-manager: The address for the GER manager contract
117-
zkevm.rpc-ratelimit: Rate limit for RPC calls.
118-
zkevm.data-stream-port: Port for the data stream. This needs to be set to enable the datastream server
119-
zkevm.data-stream-host: The host for the data stream i.e. localhost. This must be set to enable the datastream server
120-
zkevm.datastream-version: Version of the data stream protocol.
121-
externalcl: External consensus layer flag.
122-
http.api: List of enabled HTTP API modules.
123-
Sequencer specific config:
124-
125-
zkevm.executor-urls: A csv list of the executor URLs. These will be used in a round robbin fashion by the sequencer
126-
zkevm.executor-strict: Defaulted to true, but can be set to false when running the sequencer without verifications (use with extreme caution)
127-
zkevm.witness-full: Defaulted to true. Controls whether the full or partial witness is used with the executor.
128-
zkevm.sequencer-initial-fork-id: The fork id to start the network with.
129-
Useful config entries:
130-
131-
zkevm.sync-limit: This will ensure the network only syncs to a given block height.
150+
```
151+
152+
## Configurations
153+
154+
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.
155+
156+
- `datadir`: Path to your node's data directory.
157+
- `chain`: Specifies the L2 network to connect with; e.g. `hermez-mainnet`. For dynamic configs this should always be in the format `dynamic-{network}`.
158+
- `http`: Enables HTTP RPC server (set to `true`).
159+
- `private.api.addr`: Address for the private API, typically `localhost:9091`. Change this to run multiple instances on the same machine.
160+
- `zkevm.l2-chain-id`: Chain ID for the L2 network; e.g. 1101.
161+
- `zkevm.l2-sequencer-rpc-url`: URL for the L2 sequencer RPC.
162+
- `zkevm.l2-datastreamer-url`: URL for the L2 data streamer.
163+
- `zkevm.l1-chain-id`: Chain ID for the L1 network.
164+
- `zkevm.l1-rpc-url`: L1 Ethereum RPC URL.
165+
- `zkevm.address-sequencer`: The contract address for the sequencer.
166+
- `zkevm.address-zkevm`: The address for the zkevm contract.
167+
- `zkevm.address-admin`: The address for the admin contract.
168+
- `zkevm.address-rollup`: The address for the rollup contract.
169+
- `zkevm.address-ger-manager`: The address for the GER manager contract.
170+
- `zkevm.rpc-ratelimit`: Rate limit for RPC calls.
171+
- `zkevm.data-stream-port`: Port for the data stream. This needs to be set to enable the datastream server.
172+
- `zkevm.data-stream-host`: The host for the data stream i.e. `localhost`. This must be set to enable the datastream server.
173+
- `zkevm.datastream-version`: Version of the data stream protocol.
174+
- `externalcl`: External consensus layer flag.
175+
- `http.api`: List of enabled HTTP API modules.
176+
177+
### Sequencer specific config
178+
179+
- `zkevm.executor-urls`: A csv list of the executor URLs. These are used in a round robbin fashion by the sequencer.
180+
- `zkevm.executor-strict`: Default is true but can be set to false when running the sequencer without verifications (_use with extreme caution_).
181+
- `zkevm.witness-full`: Default is true. Controls whether the full or partial witness is used with the executor.
182+
- `zkevm.sequencer-initial-fork-id`: The fork id to start the network with.
183+
184+
### Useful config entries
185+
186+
- `zkevm.sync-limit`: This ensures the network only syncs to a given block height.
132187
133188
## Networks
134189
135-
| Network Name | Chain ID | ForkID | Genesis File | RPC URL | Rootchain | Rollup Address |
190+
| Network name | Chain ID | ForkID | Genesis file | RPC URL | Rootchain | Rollup Address |
136191
|---------------|----------|--------|--------------|--------------------------------------------------|------------------|----------------------------------------------|
137192
| zkEVM Mainnet | 1101 | 9 | [Link](https://hackmd.io/bpmxb5QaSFafV0nB4i-KZA) | [Mainnet RPC](https://zkevm-rpc.com/) | Ethereum Mainnet | `0x5132A183E9F3CB7C848b0AAC5Ae0c4f0491B7aB2` |
138193
| zkEVM Cardona | 2442 | 9 | [Link](https://hackmd.io/Ug9pB613SvevJgnXRC4YJA) | [Cardona RPC](https://rpc.cardona.zkevm-rpc.com/) | Sepolia | `0x32d33D5137a7cFFb54c5Bf8371172bcEc5f310ff` |

0 commit comments

Comments
 (0)