Skip to content

Commit a087605

Browse files
kmurphypolygonkmurphypolygon
authored
Merge pull request 0xPolygon#739 from 0xPolygon/cdk/update-deployment
CDK: Updating local deployment guide
2 parents 7c78c53 + a29033d commit a087605

File tree

1 file changed

+77
-82
lines changed

1 file changed

+77
-82
lines changed

‎docs/cdk/getting-started/local-deployment.md‎

Lines changed: 77 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
comments: true
33
---
44

5-
This guide walks you through the process of setting up and deploying a layer 2 CDK blockchain on your local machine.
5+
This guide walks you through the process of setting up and deploying a layer 2 CDK blockchain stack on your local machine.
66

77
The [Polygon CDK Kurtosis package](https://github.com/0xPolygon/kurtosis-cdk/) allows you to easily customize and instantiate all the components of a CDK chain. It uses the [Kurtosis](https://docs.kurtosis.com/) tool to orchestrate the setup of the chain components in Docker containers, with logic defined in [Starlark](https://github.com/bazelbuild/starlark) scripts (a Python dialect) which define the step-by-step process of setting up the chain.
88

@@ -19,10 +19,10 @@ The [Polygon CDK Kurtosis package](https://github.com/0xPolygon/kurtosis-cdk/) a
1919

2020
### Software
2121

22-
- [Docker Engine](https://docs.docker.com/engine/) version 4.27 or higher.
22+
- [Docker Engine](https://docs.docker.com/engine/) - version 4.27 or higher for MacOS.
2323
- [Kurtosis CLI](https://docs.kurtosis.com/install/)
2424

25-
And for submitting transactions and interacting with the environment once set up:
25+
And, optionally, for submitting transactions and interacting with the environment once set up, we are using:
2626

2727
- [Foundry](https://book.getfoundry.sh/getting-started/installation)
2828
- [yq](https://github.com/mikefarah/yq)
@@ -48,20 +48,20 @@ The `main.star` file contains the step-by-step instructions for the deployment p
4848

4949
It defines the following steps for the deployment process:
5050

51-
| Step number | Deployment step | Relevant Starlark code | Enabled by default |
52-
| ----------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------ |
53-
| 1 | Deploy a local layer 1 devnet chain | [ethereum.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/ethereum.star) | True |
54-
| 2 | Deploy the zkEVM smart contracts on the L1 | [deploy_zkevm_contracts.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/deploy_zkevm_contracts.star) | True |
55-
| 3 | Deploy the zkEVM node and CDK peripheral databases | [databases.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/databases.star) | True |
56-
| 4 | Deploy the CDK central environment | [cdk_central_environment.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/cdk_central_environment.star) | True |
57-
| 5 | Deploy the bridge infrastructure | [cdk_bridge_infrastructure.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/cdk_bridge_infra.star) | True |
58-
| 6 | Deploy the permissionless node | [zkevm_permissionless_node.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/zkevm_permissionless_node.star) | False |
59-
| 7 | Deploy the observability stack | [observability.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/observability.star) | True |
60-
| 8 | Deploy the block explorer | [blockscout.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/blockscout.star) | False |
61-
| 9 | Apply a load test to the chain | [load_test.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/workload.star) | False |
62-
| 10 | Deploy [Blutgang](https://github.com/rainshowerLabs/blutgang) for load balancing & caching | [cdk_blutgang.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/cdk_blutgang.star) | False |
63-
64-
You can customize (or skip) any of these steps by modifying the logic in the respective files.
51+
| Step number | Deployments | Relevant Starlark code | Enabled by default |
52+
|-------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|--------------------|
53+
| 1 | Deploy a local layer 1 Ethereum chain | [ethereum.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/ethereum.star) | True |
54+
| 2 | Deploy the CDK smart contracts on the L1 | [deploy_zkevm_contracts.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/deploy_zkevm_contracts.star) | True |
55+
| 3 | Deploy the central environment, prover, and CDK erigon or zkEVM node databases | [databases.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/databases.star) | True |
56+
| 4 | Deploy the CDK central environment | [cdk_central_environment.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/cdk_central_environment.star) | True |
57+
| 5 | Deploy the CDK erigon package | [cdk_erigon.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/cdk_erigon.star) - included in step 4 deployment | True |
58+
| 6 | Deploy the bridge infrastructure | [cdk_bridge_infrastructure.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/cdk_bridge_infra.star) | True |
59+
| 7 | Deploy the AggLayer | [agglayer.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/agglayer.star) | True |
60+
| - | Input parser tool to help deployment stages | [input_parser.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/input_parser.star) - deployed immediately | n/a |
61+
| - | zkEVM pool manager tool | [zkevm_pool_manager.star](https://github.com/0xPolygon/kurtosis-cdk/blob/main/zkevm_pool_manager.star) - deployed with CDK erigon node | n/a |
62+
63+
64+
You can customize (or skip) any of the numbered steps by modifying the logic in the respective files.
6565

6666
#### 2. [`params.yml`](https://github.com/0xPolygon/kurtosis-cdk/blob/main/params.yml)
6767

@@ -73,97 +73,95 @@ You can modify each of these parameters to customize the chain to your specific
7373

7474
## Run the chain locally
7575

76-
First run the [kurtosis clean](https://docs.kurtosis.com/clean) to remove any existing Kurtosis environments:
77-
78-
```bash
79-
kurtosis clean --all
80-
```
76+
1. Run the [kurtosis clean](https://docs.kurtosis.com/clean) to remove any existing Kurtosis environments:
8177

82-
Then, in the `kurtosis-cdk` directory, use the [kurtosis run](https://docs.kurtosis.com/run) command to deploy the chain on your local machine by executing the `main.star` script provided with the `params.yml` configuration file:
78+
```bash
79+
kurtosis clean --all
80+
```
8381

84-
```bash
85-
kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always .
86-
```
82+
2. In the `kurtosis-cdk` directory, use the [kurtosis run](https://docs.kurtosis.com/run) command to deploy the chain on your local machine by executing the `main.star` script provided with the `params.yml` configuration file:
8783

88-
!!! info
84+
```bash
85+
kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always .
86+
```
8987

90-
- `--enclave cdk-v1` specifies the name of the [enclave](https://docs.kurtosis.com/advanced-concepts/enclaves/) (isolated environment) to use for the deployment process.
91-
- `--args-file params.yml` specifies the configuration file to use for the deployment process.
92-
- `--image-download always` specifies to always download the latest Docker images for the deployment process.
88+
- `enclave cdk-v1` specifies the name of the enclave, or isolated environment, to use for the deployment process.
89+
- `args-file params.yml` specifies the configuration file to use for the deployment process.
90+
- `image-download` specifies to always download the latest Docker images for the deployment process.
9391

94-
This command typically takes a while to complete and outputs the logs of each step in the deployment process for you to monitor the progress of the chain setup. Once the command is complete, you should see the following output:
92+
3. This command typically takes a while to complete and outputs the logs of each step in the deployment process for you to monitor the progress of the chain setup. Once the command is complete, you should see the following output:
9593

96-
```bash
97-
Starlark code successfully run. No output was returned.
94+
```bash
95+
Starlark code successfully run. No output was returned.
9896
99-
===============================================
100-
|| Created enclave: cdk-v1 ||
101-
===============================================
102-
Name: cdk-v1
103-
Status: RUNNING
97+
===============================================
98+
|| Created enclave: cdk-v1 ||
99+
===============================================
100+
Name: cdk-v1
101+
Status: RUNNING
104102
105-
========================================= Files Artifacts =========================================
103+
========================================= Files Artifacts =========================================
106104
107-
... List of files generated during the deployment process ...
105+
... List of files generated during the deployment process ...
108106
109-
========================================== User Services ==========================================
107+
========================================== User Services ==========================================
110108
111-
... List of services with "RUNNING" status - none should be "FAILED"! ...
109+
... List of services with "RUNNING" status - none should be "FAILED"! ...
112110
113-
```
111+
```
114112

115-
### Inspect the chain
113+
3. Inspect the chain
116114

117-
Run the following command to see the status of the enclave and the services running within it at any time.
115+
Run the following command to see the status of the enclave and the services running within it at any time.
118116

119-
```sh
120-
kurtosis enclave inspect cdk-v1
121-
```
117+
```sh
118+
kurtosis enclave inspect cdk-v1
119+
```
122120

123121
## Interacting with the chain
124122

125-
Now that your chain is running, you can explore and interact with each component!
123+
Now that your chain is running, you can explore and interact with each component.
126124

127125
Below are a few examples of how you can interact with the chain.
128126

129127
### Read/write operations
130128

131129
Let's do some read and write operations and test transactions on the L2 with Foundry.
132130
133-
1. Export the RPC URL of your L2 to an environment variable called `ETH_RPC_URL` with the following command:
134-
135-
```bash
136-
export ETH_RPC_URL="$(kurtosis port print cdk-v1 cdk-erigon-node-001 http-rpc)"
137-
```
138-
139-
2. Use `cast` to view information about the chain, such as the latest block number:
131+
1. Use `cast` to view information about the chain, such as the latest block number:
140132
141133
```bash
142134
cast block-number
143135
```
144136
145-
3. View the balance of an address, such as the pre-funded admin account:
137+
2. View the balance of an address, such as the pre-funded admin account:
146138
147139
```bash
148140
cast balance --ether 0xE34aaF64b29273B7D567FCFc40544c014EEe9970
149141
```
150142
151-
4. Send simple transactions to the chain, such as a transfer of some ETH:
143+
3. Send simple transactions to the chain, such as a transfer of some ETH:
152144
153145
```bash
154146
cast send --legacy --value 0.01ether 0x0000000000000000000000000000000000000000 --private-key "0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625"
155147
```
156148
157-
!!! info
158-
The `0xE34...9970` and `0x12d...c625` public-private key pair used in the above commands is the default admin account configured in `params.yml`.
149+
!!! info
150+
The `0xE34...9970` and `0x12d...c625` public-private key pair used in the above commands is the default admin account configured in `params.yml`.
159151
160152
### Load testing the chain
161153
162-
Use the [`polycli loadtest`](https://github.com/maticnetwork/polygon-cli/blob/main/doc/polycli_loadtest.md) command to send multiple transactions at once to the chain to test its performance:
154+
1. Export the RPC URL of your L2 to an environment variable called `ETH_RPC_URL` with the following command:
163155
164-
```bash
165-
polycli loadtest --rpc-url "$ETH_RPC_URL" --legacy --verbosity 700 --requests 500 --rate-limit 5 --mode t --private-key "0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625"
166-
```
156+
```bash
157+
export ETH_RPC_URL="$(kurtosis port print cdk-v1 cdk-erigon-node-001 http-rpc)"
158+
```
159+
160+
2. Use the [`polycli loadtest`](https://github.com/maticnetwork/polygon-cli/blob/main/doc/polycli_loadtest.md) command to send multiple transactions at once to the chain to test its performance:
161+
162+
```bash
163+
polycli loadtest --rpc-url "$ETH_RPC_URL" --legacy --verbosity 700 --requests 500 --rate-limit 5 --mode t --private-key "0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625"
164+
```
167165
168166
### Viewing transaction finality
169167
@@ -185,34 +183,27 @@ To open the bridge interface and bridge tokens across the L1 and L2, run the fol
185183
open $(kurtosis port print cdk-v1 zkevm-bridge-proxy-001 web-ui)
186184
```
187185
188-
!!! tip
189-
If the `open` command doesn't work, you can find the URL's in the Kurtosis output.
186+
## Additional services
190187
191-
### Viewing chain metrics
188+
There are a number of additional services you can add to the stack, including observability applications and other useful tools.
192189
193-
!!! warning
194-
- Observability defaults to false.
195-
- Turn on observability in the deployment by setting the `deploy_observability` parameter to `true` in `params.yml`.
196-
- Redeploy Kurtosis.
190+
See the current list of additional services in the [CDK kurtosis additional services documentation](https://github.com/0xPolygon/kurtosis-cdk/blob/main/docs/additional-services.md).
197191
198-
Once the observability function is activated, you can see information such as:
192+
To add an additional service, simply add the name of the service to the `params.yml` array. For example:
199193
200-
- How many transactions are being processed.
201-
- The amount of gas being used.
202-
- The time since a batch was last verified.
203-
- How many addresses have bridged.
194+
```yml
195+
args:
196+
additional_services:
197+
- blockscout
198+
- prometheus_grafana
199+
```
204200
205-
Open the Grafana dashboard by running the following command:
201+
To use the additional service, simply add the service to a kurtosis call. For example, to open the Grafana dashboard once set up in `params.yml`, run the following command:
206202
207203
```bash
208204
open $(kurtosis port print cdk-v1 grafana-001 dashboards)
209205
```
210206
211-
!!! tip
212-
If the `open` command doesn't work, you can find the URL's in the Kurtosis output.
213-
214-
From the hamburger menu, navigate to `Dashboards` and select the `Panoptichain` dashboard to view all of the metrics.
215-
216207
![Panoptichain Dashboard](../../img/cdk/grafana.png)
217208
218209
### Stopping the chain
@@ -227,6 +218,10 @@ kurtosis clean --all
227218
228219
While it is possible to run a CDK chain on your own, we strongly recommend getting in touch with the [Polygon team directly](https://share-eu1.hsforms.com/1aI6l7_bFTn-vWl0NIFVzDQc8xid), or one of our [implementation providers](https://ecosystem.polygon.technology/spn/cdk/) for production deployments.
229220
221+
## Advanced use cases
222+
223+
For a list of advanced use cases and documentation explaining how to set them up, please see the list in the [Kurtosis CDK stack repo](https://github.com/0xPolygon/kurtosis-cdk?tab=readme-ov-file#advanced-use-cases).
224+
230225
## Further reading
231226
232227
- For more information on CDK architecture, components, and how to customize your chain, refer to the [CDK architecture documentation](https://docs.polygon.technology/cdk/architecture/cdk-zkevm/).

0 commit comments

Comments
 (0)