Skip to content

Local deployment guide

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

The Polygon CDK Kurtosis package allows you to easily customize and instantiate all the components of a CDK chain. It uses the Kurtosis tool to orchestrate the setup of the chain components in Docker containers, with logic defined in Starlark scripts (a Python dialect) which define the step-by-step process of setting up the chain.

Tip

Check out the Polygon Kurtosis docs for more documentation on this stack and how to use it, and if you need to raise an issue or have a question for the team.

Prerequisites

Hardware

  • Linux-based OS (or WSL).
  • Minimum 8GB RAM/2-core CPU.
  • AMD64 architecture.

Software

And for submitting transactions and interacting with the environment once set up:

Set up the Kurtosis environment

Clone the repository

git clone https://github.com/0xPolygon/kurtosis-cdk.git
cd kurtosis-cdk

Check your environment

Run the tool_check.sh script to confirm you have all the prerequisite software.

Tip

You may need to make the script executable: chmod +x scripts/tool_check.sh

./scripts/tool_check.sh

If everything is installed correctly, you should see the following output:

Checking that you have the necessary tools to deploy the Kurtosis CDK package...
✅ kurtosis is installed, meets the requirement (=0.89).
✅ docker is installed, meets the requirement (>=24.7).

You might as well need the following tools to interact with the environment...
✅ jq is installed.
✅ yq is installed, meets the requirement (>=3.2).
✅ cast is installed.
✅ polycli is installed.

🎉 You are ready to go!

Understanding the deployment steps

There are two configuration files which help you understand what happens during a deployment.

1. main.star

The main.star file contains the step-by-step instructions for the deployment process. It orchestrates the setup of all the components in sequential order and pulls in any necessary logic from other files.

It defines the following steps for the deployment process:

Step number Deployment step Relevant Starlark code Enabled by default
1 Deploy a local layer 1 devnet chain ethereum.star True
2 Deploy the zkEVM smart contracts on the L1 deploy_zkevm_contracts.star True
3 Deploy the zkEVM node and CDK peripheral databases databases.star True
4 Deploy the CDK central environment cdk_central_environment.star True
5 Deploy the bridge infrastructure cdk_bridge_infrastructure.star True
6 Deploy the permissionless node zkevm_permissionless_node.star False
7 Deploy the observability stack observability.star True
8 Deploy the block explorer blockscout.star False
9 Apply a load test to the chain load_test.star False
10 Deploy Blutgang for load balancing & caching cdk_blutgang.star False

You can customize (or skip) any of these steps by modifying the logic in the respective files.

2. params.yml

The params.yml file defines the parameters of the chain and the deployment process.

It includes configurations for simple parameters such as the chain ID and more complex configurations such as the gas token smart contract address.

You can modify each of these parameters to customize the chain to your specific needs.

Run the chain locally

First run the kurtosis clean to remove any existing Kurtosis environments:

kurtosis clean --all

Then, in the kurtosis-cdk directory, use the kurtosis run command to deploy the chain on your local machine by executing the main.star script provided with the params.yml configuration file:

kurtosis run --enclave cdk-v1 --args-file params.yml --image-download always .

Info

  • --enclave cdk-v1 specifies the name of the enclave (isolated environment) to use for the deployment process.
  • --args-file params.yml specifies the configuration file to use for the deployment process.
  • --image-download always specifies to always download the latest Docker images for the deployment process.

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:

Starlark code successfully run. No output was returned.

===============================================
||          Created enclave: cdk-v1          ||
===============================================
Name:            cdk-v1
Status:          RUNNING

========================================= Files Artifacts =========================================

... List of files generated during the deployment process ...

========================================== User Services ==========================================

... List of services with "RUNNING" status - none should be "FAILED"! ...

Inspect the chain

Run the following command to see the status of the enclave and the services running within it at any time.

kurtosis enclave inspect cdk-v1

Interacting with the chain

Now that your chain is running, you can explore and interact with each component!

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

Read/write operations

Let’s do some read and write operations and test transactions on the L2 with Foundry.

  1. Export the RPC URL of your L2 to an environment variable called ETH_RPC_URL with the following command:

    export ETH_RPC_URL="$(kurtosis port print cdk-v1 cdk-erigon-node-001 http-rpc)"

  2. Use cast to view information about the chain, such as the latest block number:

    cast block-number

  3. View the balance of an address, such as the pre-funded admin account:

    cast balance --ether 0xE34aaF64b29273B7D567FCFc40544c014EEe9970

  4. Send simple transactions to the chain, such as a transfer of some ETH:

    cast send --legacy --value 0.01ether 0x0000000000000000000000000000000000000000 --private-key "0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625"

Info

The 0xE34...9970 and 0x12d...c625 public-private key pair used in the above commands is the default admin account configured in params.yml.

Load testing the chain

Use the polycli loadtest command to send multiple transactions at once to the chain to test its performance:

polycli loadtest --rpc-url "$ETH_RPC_URL" --legacy --verbosity 700 --requests 500 --rate-limit 5 --mode t --private-key "0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625"

Viewing transaction finality

A common way to check the status of the system is by ensuring that batches are sent and verified on the L1 chain.

Use cast to view the progression of batches from trusted, virtual, and verified states:

cast rpc zkevm_batchNumber          # Latest batch number on the L2
cast rpc zkevm_virtualBatchNumber   # Latest batch received on the L1
cast rpc zkevm_verifiedBatchNumber  # Latest batch verified or "proven" on the L1

Opening the bridge UI

To open the bridge interface and bridge tokens across the L1 and L2, run the following command:

open $(kurtosis port print cdk-v1 zkevm-bridge-proxy-001 web-ui)

Tip

If the open command doesn’t work, you can find the URL’s in the Kurtosis output.

Viewing chain metrics

Warning

  • Observability defaults to false.
  • Turn on observability in the deployment by setting the deploy_observability parameter to true in params.yml.
  • Redeploy Kurtosis.

Once the observability function is activated, you can see information such as:

  • How many transactions are being processed.
  • The amount of gas being used.
  • The time since a batch was last verified.
  • How many addresses have bridged.

Open the Grafana dashboard by running the following command:

open $(kurtosis port print cdk-v1 grafana-001 dashboards)

Tip

If the open command doesn’t work, you can find the URL’s in the Kurtosis output.

From the hamburger menu, navigate to Dashboards and select the Panoptichain dashboard to view all of the metrics.

Panoptichain Dashboard

Stopping the chain

If you want to stop the chain and remove all the containers, run the following command:

kurtosis clean --all

Going to production

While it is possible to run a CDK chain on your own, we strongly recommend getting in touch with the Polygon team directly, or one of our implementation providers for production deployments.

Further reading

  • For more information on CDK architecture, components, and how to customize your chain, refer to the CDK architecture documentation.
  • For detailed how to’s, including how to create a native token, check out our how to guides.
  • For detailed conceptual information on zero-knowledge stacks, check out our concepts documentation.

Comments