janbajecdev / kurtosis-cdk

Polygon CDK Kurtosis Package

A Kurtosis package that deploys a private, portable, and modular Polygon CDK devnet.

Table of Contents

• For Users
  • Deploy the CDK Stack
  • Set Up a Permissionless Node
  • Observability
  • Troubleshooting: Mac Users
• For Developers
  • Break Down the Deployment Into Stages
  • ZkEVM Contracts Caching Solution
• License
• Contribution

For Users

Deploy the CDK stack

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

Set Up a Permissionless Node

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 .

Remote Permissionless Testing

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 .

Observability

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.

1. 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.
2. 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.

Troubleshooting for Mac Users

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!

For Developers

Break Down the Deployment Into Stages

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:

1. Deploy Local L1
2. Deploy ZkEVM Contracts on L1
3. Deploy ZkEVM Node and CDK Peripheral Databases
4. Deploy CDK Central/Trusted Environment
5. Deploy CDK/Bridge Infrastructure
6. 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

ZkEVM Contracts Caching Solution

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

License

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.

Contribution

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.