A Kurtosis package that deploys a private, portable, and modular Polygon CDK devnet over Docker or Kubernetes.
Specifically, this package will deploy:
- A local L1 chain, fully customizable with multi-client support, using the ethereum-package.
- A local L2 chain, using the Polygon Chain Development Kit (CDK), with customizable components such as sequencer, sequence sender, aggregator, rpc, prover, dac, etc. It will first deploy the Polygon zkEVM smart contracts on the L1 chain before deploying the different components.
- The zkEVM bridge infrastructure to facilitate asset bridging between the L1 and L2 chains, and vice-versa.
- The Agglayer, an in-development interoperability protocol, that allows for trustless cross-chain token transfers and message-passing, as well as more complex operations between L2 chains, secured by zk proofs.
- Additional services such as transaction spammer, monitoring tools, permissionless nodes etc.
🚨 This package is currently designed as a development tool for testing configurations and scenarios within the Polygon CDK stack. It is not recommended for long-running or production environments such as testnets or mainnet. If you need help, you can reach out to the Polygon team or talk to an Implementation Partner (IP).
The package is flexible and supports various configurations for deploying and testing the Polygon CDK stack. The table provided illustrates the different combinations of sequencers and sequence sender/aggregator components that can be used, along with their current support status in Kurtosis.
The team is actively working on enabling the use cases that are currently not possible.
| Stack | Sequencer | Sequence Sender / Aggregator | Supported by Kurtosis? |
|---|---|---|---|
| New CDK stack | cdk-erigon | cdk-node | ✅ |
| New sequencer with new zkevm stack | cdk-erigon | zkevm-sequence-sender + zkevm-aggregator | ❌ (WIP) - Check the kurtosis-cdk-erigon package |
| New sequencer with legacy zkevm stack | cdk-erigon | zkevm-node | ❌ (WIP) |
| Legacy sequencer with new cdk stack | zkevm-node | cdk-node | ❌ (WIP) |
| Legacy sequencer with new zkevm stack | zkevm-node | zkevm-sequence-sender + zkevm-aggregator | ❌ (WIP) |
| Legacy zkevm stack | zkevm-node | zkevm-node | ✅ |
To understand how to configure Kurtosis for these use cases, refer to the documentation and review the test files located in the .github/tests/ directory.
To begin, you will need to install Docker (>= v4.27.0 for Mac users) and Kurtosis.
If you intend to interact with and debug the stack, you may also want to consider a few additional optional tools such as:
Once that is good and installed on your system, you can run the following command to deploy the complete CDK stack locally. This process typically takes around eight to ten minutes.
kurtosis run --enclave cdk github.com/0xPolygon/kurtosis-cdkThe default deployment includes cdk-erigon as the sequencer, and cdk-node functioning as the sequence sender and aggregator. You can verify the default versions of these components and the default fork ID by reviewing input_parser.star. You can check the default versions of the deployed components and the default fork ID by looking at input_parser.star.
To make customizations to the CDK environment, clone this repo, make any desired configuration changes, and then run:
# Delete all stop and clean all currently running enclaves
kurtosis clean --all
# Run this command from the root of the repository to start the network
kurtosis run --enclave cdk .
Let's do a simple L2 RPC test call.
First, you will need to figure out which port Kurtosis is using for the RPC. You can get a general feel for the entire network layout by running the following command:
kurtosis enclave inspect cdkThat output, while quite useful, might also be a little overwhelming. Let's store the RPC URL in an environment variable.
You may need to adjust the various commands slightly if you deployed the legacy zkevm-node as the sequencer. You should target the
zkevm-node-rpc-001service instead ofcdk-erigon-node-001.
export ETH_RPC_URL="$(kurtosis port print cdk cdk-erigon-node-001 rpc)"That is the same environment variable that cast uses, so you should now be able to run this command. Note that the steps below will assume you have the Foundry toolchain installed.
cast block-numberBy 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 0xE34aaF64b29273B7D567FCFc40544c014EEe9970Okay, let’s send some transactions...
private_key="0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625"
cast send --legacy --private-key "$private_key" --value 0.01ether 0x0000000000000000000000000000000000000000Okay, let’s send even more transactions... Note that this step will assume you have polygon-cli installed.
polycli loadtest --rpc-url "$ETH_RPC_URL" --legacy --private-key "$private_key" --verbosity 700 --requests 50000 --rate-limit 50 --concurrency 5 --mode t
polycli loadtest --rpc-url "$ETH_RPC_URL" --legacy --private-key "$private_key" --verbosity 700 --requests 500 --rate-limit 10 --mode 2
polycli loadtest --rpc-url "$ETH_RPC_URL" --legacy --private-key "$private_key" --verbosity 700 --requests 500 --rate-limit 3 --mode uniswapv3Pretty often, you will want to check the output from the service. Here is how you can grab some logs:
kurtosis service logs cdk agglayer --followIn other cases, if you see an error, you might want to get a shell in the service to be able to poke around.
kurtosis service shell cdk contracts-001
jq . /opt/zkevm/combined.jsonOne 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_verifiedBatchNumberIf the number of verified batches is increasing, then it means the system works properly.
To access the zkevm-bridge user interface, open this URL in your web browser.
open "$(kurtosis port print cdk zkevm-bridge-proxy-001 web-ui)"When everything is done, you might want to clean up with this command which stops the local devnet and deletes it.
kurtosis clean --allFor more information about the CDK stack, visit the Polygon Knowledge Layer.
This section features documentation specifically designed for advanced users, outlining complex operations and techniques.
- How to deploy additional services alongside the CDK stack, such as transaction spammer, monitoring tools, permissionless nodes etc.
- How to attach multiple CDK chains to the AggLayer.
- How to use CDK ACL.
- How to use the different data availability modes.
- How to deploy the stack to an external L1 such as Sepolia.
- How to edit the zkevm contracts.
- How to perform an environment migration with clean copies of the databases.
- How to iterate and debug quickly with Kurtosis.
- How to use zkevm contracts fork 12.
- How to integrate a third-party data availability committee (DAC).
- How to migrate from fork 7 to fork 9.
- How to upgrade forks for isolated CDK chains.
- How to use a native token.
- How to play with the network to introduce latencies.
- How to set up a permissionless zkevm node.
- How to run a debugger.
- How to work with the timelock.
- How to trigger a reorg.
- For technical issues, join our Discord.
- For documentation issues, raise an issue on the published live doc at our main repo.
Copyright (c) 2024 PT Services DMCC
Licensed under either:
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0), or
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
as 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.
