A Kurtosis package that deploys a private, portable, and modular Polygon CDK devnet.
To get started you’ll need to install Kurtosis.
You will also need a few other tools. Run this script to check you have the required versions.
curl -s https://raw.githubusercontent.com/0xPolygon/kurtosis-cdk/main/scripts/tool_check.sh | bash
Once that’s good and installed on your system, you can cd
into this directory and run:
kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always .
This command will take a few minutes but will basically run an entire CDK deployment locally. Assuming everything worked, you can do a few things to quickly play around with your test CDK. The steps below will assume you have the Foundry toolchain installed.
Let’s just do a simple RPC call. First you’ll need to figure out which port Kurtosis is using for RPC. You can get a generall feel for the entire network layout by running:
kurtosis enclave inspect cdk-v1
That output is quite useful might might also be a little
overwhelming. If we want to simply see the port mapping within the
cdk-v1
enclave for the zkevm-node-rpc
service and the
trusted-rpc
port, we can run this command.
kurtosis port print cdk-v1 zkevm-node-rpc-001 http-rpc
For the sake of this document, I’m going to map that value to an environment variable.
export ETH_RPC_URL="$(kurtosis port print cdk-v1 zkevm-node-rpc-001 http-rpc)"
That is the same environment variable that cast
uses, so now I
should be able to run this command.
cast block-number
By default, the CDK is configured in test mode which means there is
some pre-funded value in the admin account with address
0xE34aaF64b29273B7D567FCFc40544c014EEe9970
.
cast balance --ether 0xE34aaF64b29273B7D567FCFc40544c014EEe9970
Okay let’s send some transactions…
cast send --legacy --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 --value 0.01ether 0x0000000000000000000000000000000000000000
Okay let’s… send even more transactions.
polycli loadtest --requests 500 --legacy --rpc-url $ETH_RPC_URL --verbosity 700 --rate-limit 5 --mode t --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625
polycli loadtest --requests 500 --legacy --rpc-url $ETH_RPC_URL --verbosity 700 --rate-limit 10 --mode t --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625
polycli loadtest --requests 500 --legacy --rpc-url $ETH_RPC_URL --verbosity 700 --rate-limit 10 --mode 2 --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625
polycli loadtest --requests 500 --legacy --rpc-url $ETH_RPC_URL --verbosity 700 --rate-limit 3 --mode uniswapv3 --private-key 0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625
cast nonce 0xE34aaF64b29273B7D567FCFc40544c014EEe9970
Pretty often we’ll want to check the output from the service. We can grab some logs:
kurtosis service logs cdk-v1 zkevm-agglayer-001
In other cases, if we see an error we might want to get a shell in the container to be able to poke around.
kurtosis service shell cdk-v1 zkevm-node-sequencer-001
One of the most common ways to check the status of the system is to make sure that batches are going through the normal progression of trusted, virtual, and verified:
cast rpc zkevm_batchNumber
cast rpc zkevm_virtualBatchNumber
cast rpc zkevm_verifiedBatchNumber
When everything is done, you might want to clean up with this command which stopps everything and deletes it.
kurtosis clean -a
In addition to the core stack, you can also attach and synchronize a
permissionless node. Of course, you’ll need the CDK stack running from
the previous commands. Assuming that has run and correctly created a
network, you’ll need to pull the genesis file artifact out and add it
to your permissionless_node
kurtosis package.
rm -r /tmp/zkevm
kurtosis files download cdk-v1 genesis /tmp
cp /tmp/genesis.json templates/permissionless-node/genesis.json
Now that we have the right genesis file, we can add a permissionless
node to the cdk-v1
enclave:
kurtosis run --enclave cdk-v1 --args-file params.yml --main-file zkevm_permissionless_node.star .
You can use the permissionless package to sync data from a production network as well. First you’ll need to get the genesis file and it should be populated already with the CDK fields like:
rollupCreationBlockNumber
rollupManagerCreationBlockNumber
L1Config.chainId
L1Config.polygonZkEVMGlobalExitRootAddress
L1Config.polygonRollupManagerAddress
L1Config.polTokenAddress
L1Config.polygonZkEVMAddress
If you’re unsure how to populate these fields please check out how it’s done within run-constract-setup.sh. When you have the genesis file ready, drop it into ./templates/permissionless-node/genesis.json.
In addition to the genesis setup, we’ll also need to tweak a parameter in ./params.yml:
l1_rpc_url
will most likely need to be changed to be your actual L1 network. Most likely Sepolia or mainnet
There are other parameters that might seem like they should be
changed, e.g. l1_chain_id
, but those aren’t actually used for the
permisionless setup. The most important thing is just to update the
RPC URL.
Once you’ve done that, you should be good to go and you can start synchronizing with ths command:
kurtosis run --enclave cdk-v1 --args-file params.yml --main-file zkevm_permissionless_node.star .
kurtosis-cdk
deploys Prometheus, Grafana, and Panoptichain to help observe the
network. This is enabled by default, but can be turned off by setting the
deploy_observability
to false
in the params.yml
.
Upon successful deployment of the CDK, you will encounter an output similar to the following:
66a0a1fbb82f grafana-001 dashboards: 3000/tcp -> http://127.0.0.1:49701 RUNNING
3048924295f9 panoptichain-001 prometheus: 9090/tcp -> http://127.0.0.1:49651 RUNNING
df5a52b990f2 prometheus-001 http: 9090/tcp -> http://127.0.0.1:49678 RUNNING
To view the dashboards, go to the Grafana endpoint with the /dashboards
path.
You can also click the hamburger menu in the top left, and go to Dashboards.
There are two predefined dashboards here to help you understand the health of
the CDK at a glance.
- The Panoptichain dashboard displays the metrics that are collected from the Panoptichain service. This dashboard focuses on on-chain metrics such as blocks, transactions, and smart contract calls.
- The Services dashboard captures the metrics being emitted by the individual services in the CDK, and metrics pertaining to process health.
To ensure that a service is properly emitting metrics, you can view all the
Prometheus targets and their state by navigating to the Prometheus endpoint with
the /targets
path.
Are you looking to run our Kurtosis CDK package on macOS? You are in the right place!
Running Docker on macOS differs slightly from Docker on Linux. One key distinction is that Docker on macOS doesn’t directly expose container networks to the host system. Consequently, accessing containers via their private IPs isn’t possible by default.
This is a problem because our Kurtosis package requires this functionality to run smoothly… But don’t worry! We have a solution that will transform your Mac so that it works like magic!
Step 1: Set up docker-mac-net-connect to address this precise issue.
To begin, install `docker-mac-net-connect`.
brew install chipmk/tap/docker-mac-net-connect
Next, start the service and configure it to launch on boot.
sudo brew services start chipmk/tap/docker-mac-net-connect
Step 2: Uninstall your current Docker Engine version.
/Applications/Docker.app/Contents/MacOS/uninstall
Step 3: Install the latest Docker Engine version.
Ensure to install version 4.27 or higher. This version is necessary for running the zkEVM Prover on macOS.
Step 4: Check that you can access containers using their private IPs.
Start a dummy `nginx` container.
docker run --rm --name nginx -d nginx
Access the container using its private IP.
curl -m 1 -I $(docker inspect nginx --format '{{.NetworkSettings.IPAddress}}')
You should receive a response similar to the following.
HTTP/1.1 200 OK
Server: nginx/1.25.4
Date: Mon, 08 Apr 2024 08:11:30 GMT
Content-Type: text/html
Content-Length: 615
Last-Modified: Wed, 14 Feb 2024 16:03:00 GMT
Connection: keep-alive
ETag: "65cce434-267"
Accept-Ranges: bytes
With these steps completed, your macOS environment is now ready to seamlessly run our Kurtosis CDK package. Happy coding!
Rather than executing the deployment process as a monolithic operation, you can break it down into stages and run each stage separately.
You can enable a stage by setting the boolean value to true and disable it by setting it to false. By default, all stages will be executed.
Currently, the deployment process includes the following stages:
- Deploy Local L1
- Deploy ZkEVM Contracts on L1
- Deploy ZkEVM Node and CDK Peripheral Databases
- Deploy CDK Central/Trusted Environment
- Deploy CDK/Bridge Infrastructure
- Deploy Permissionless Node
Here’s an example of how you can specify the stages to run through. In order to run this you’ll need yq installed.
# Disable all deployment steps.
yq -Yi '.deploy_l1 = false' params.yml
yq -Yi '.deploy_zkevm_contracts_on_l1 = false' params.yml
yq -Yi '.deploy_databases = false' params.yml
yq -Yi '.deploy_cdk_central_environment = false' params.yml
yq -Yi '.deploy_cdk_bridge_infra = false' params.yml
yq -Yi '.deploy_zkevm_permissionless_node = false' params.yml
# Deploy L1
yq -Yi '.deploy_l1 = true' params.yml
kurtosis run --enclave cdk-v1 --args-file params.yml .
yq -Yi '.deploy_l1 = false' params.yml # reset
# Perform additional tasks...
# Deploy ZkEVM Contracts on L1
yq -Yi '.deploy_zkevm_contracts_on_l1 = true' params.yml
kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always .
yq -Yi '.deploy_zkevm_contracts_on_l1 = false' params.yml # reset
# Perform additional tasks...
# Deploy ZkEVM Node and CDK Peripheral Databases
yq -Yi '.deploy_databases = true' params.yml
kurtosis run --enclave cdk-v1 --args-file params.yml .
yq -Yi '.deploy_databases = false' params.yml # reset
# Perform additional tasks...
# Deploy CDK Central Environment
yq -Yi '.deploy_cdk_central_environment = true' params.yml
kurtosis run --enclave cdk-v1 --args-file params.yml .
yq -Yi '.deploy_cdk_central_environment = false' params.yml # reset
# Perform additional tasks...
# Deploy CDK Bridge Infrastructure
yq -Yi '.deploy_cdk_bridge_infra = true' params.yml
kurtosis run --enclave cdk-v1 --args-file params.yml .
yq -Yi '.deploy_cdk_bridge_infra = false' params.yml # reset
# Perform additional tasks...
# Deploy ZkEVM Permissionless Node
yq -Yi '.deploy_zkevm_permissionless_node = true' params.yml
kurtosis run --enclave cdk-v1 --args-file params.yml .
yq -Yi '.deploy_zkevm_permissionless_node = false' params.yml # reset
We manually build zkevm contracts images to make the deployment of the Kurtosis package as fast as possible.
Indeed, most of the deployment time is spent downloading npm dependencies and compiling the zkevm contracts.
We maintain a list of images at leovct/zkevm-contracts for fork ids 6, 7, 8 and 9.
If you wish to use a custom image, you can build your own using the Dockerfile. All you need to modify is the zkevm_contracts_image field in params.yml.
You can follow the steps and manually build and push the different zkevm contract images to your preferred registry, or you can simply trigger this workflow.
docker login
docker buildx create --name container --driver=docker-container
./docs/zkevm-contracts-images-builder.sh $USER
Copyright (c) 2024 PT Services DMCC
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
The SPDX license identifier for this project is MIT OR Apache-2.0
.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.