{"id":18953141,"url":"https://github.com/0xpolygon/kurtosis-cdk","last_synced_at":"2026-03-29T16:30:18.336Z","repository":{"id":228632740,"uuid":"771194308","full_name":"0xPolygon/kurtosis-cdk","owner":"0xPolygon","description":"A Kurtosis package that deploys a private, portable, and modular Polygon CDK devnet","archived":false,"fork":false,"pushed_at":"2025-02-12T21:44:13.000Z","size":22125,"stargazers_count":57,"open_issues_count":7,"forks_count":100,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-02-13T08:08:31.172Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.polygon.technology/cdk","language":"Starlark","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xPolygon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-12T21:24:49.000Z","updated_at":"2025-02-12T18:01:35.000Z","dependencies_parsed_at":"2024-03-25T04:24:31.104Z","dependency_job_id":"107d858c-00dd-4b68-bd7f-303931289495","html_url":"https://github.com/0xPolygon/kurtosis-cdk","commit_stats":null,"previous_names":["0xpolygon/kurtosis-cdk"],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xPolygon%2Fkurtosis-cdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xPolygon%2Fkurtosis-cdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xPolygon%2Fkurtosis-cdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xPolygon%2Fkurtosis-cdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xPolygon","download_url":"https://codeload.github.com/0xPolygon/kurtosis-cdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239952598,"owners_count":19723922,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T13:36:43.014Z","updated_at":"2026-03-29T16:30:18.290Z","avatar_url":"https://github.com/0xPolygon.png","language":"Starlark","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Polygon CDK Kurtosis Package\n\nA [Kurtosis](https://github.com/kurtosis-tech/kurtosis) package that deploys a private, portable, and modular [Polygon CDK](https://docs.polygon.technology/cdk/) devnet over [Docker](https://www.docker.com/) or [Kubernetes](https://kubernetes.io/).\n\nSpecifically, this package will deploy:\n\n1. A local L1 chain, fully customizable with multi-client support, using the [ethereum-package](https://github.com/ethpandaops/ethereum-package).\n2. A local L2 chain, using the [Polygon Chain Development Kit](https://docs.polygon.technology/cdk/) (CDK), with customizable components such as sequencer, sequence sender, aggregator, rpc, prover, dac, etc. It will first deploy the [Polygon zkEVM smart contracts](https://github.com/0xPolygonHermez/zkevm-contracts) on the L1 chain before deploying the different components.\n3. The [zkEVM bridge](https://github.com/0xPolygonHermez/zkevm-bridge-service) infrastructure to facilitate asset bridging between the L1 and L2 chains, and vice-versa.\n4. The [Agglayer](https://github.com/agglayer/agglayer-go), 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.\n5. [Additional services](docs/additional-services.md) such as transaction spammer, monitoring tools, permissionless nodes etc.\n\n\u003e 🚨 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](https://polygon.technology/interest-form) or [talk to an Implementation Partner (IP)](https://ecosystem.polygon.technology/spn/cdk/).\n\n## Table of Contents\n\n- [Getting Started](#getting-started)\n- [Supported Configurations](#supported-configurations)\n- [Advanced Use Cases](#advanced-use-cases)\n- [FAQ](#faq)\n- [Contact](#contact)\n- [License](#license)\n- [Contribution](#contribution)\n\n\n## Supported Configurations\n\nThe package is flexible and supports various configurations for deploying and testing the Polygon CDK stack.\n\nYou can take a look at this [table](CDK_VERSION_MATRIX.MD) to see which versions of the CDK are meant to work together, broken by fork identifier.\n\nThe 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.\n\n\u003e The team is actively working on enabling the use cases that are currently not possible.\n\n| Stack                                 | Sequencer                                                   | Sequence Sender / Aggregator                                                                                                                                | Supported by Kurtosis?                                                                                   |\n| ------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |\n| New CDK stack                         | [cdk-erigon](https://github.com/0xPolygonHermez/cdk-erigon) | [cdk-node](https://github.com/0xPolygon/cdk)                                                                                                                | ✅                                                                                                       |\n| New sequencer with new zkevm stack    | [cdk-erigon](https://github.com/0xPolygonHermez/cdk-erigon) | [zkevm-sequence-sender](https://github.com/0xPolygonHermez/zkevm-sequence-sender) + [zkevm-aggregator](https://github.com/0xPolygonHermez/zkevm-aggregator) | ❌ (WIP) - Check the [kurtosis-cdk-erigon](https://github.com/xavier-romero/kurtosis-cdk-erigon) package |\n| New sequencer with legacy zkevm stack | [cdk-erigon](https://github.com/0xPolygonHermez/cdk-erigon) | [zkevm-node](https://github.com/0xPolygonHermez/zkevm-node)                                                                                                 | ❌ (WIP)                                                                                                 |\n| Legacy sequencer with new cdk stack   | [zkevm-node](https://github.com/0xPolygonHermez/zkevm-node) | [cdk-node](https://github.com/0xPolygon/cdk)                                                                                                                | ❌ (WIP)                                                                                                 |\n| Legacy sequencer with new zkevm stack | [zkevm-node](https://github.com/0xPolygonHermez/zkevm-node) | [zkevm-sequence-sender](https://github.com/0xPolygonHermez/zkevm-sequence-sender) + [zkevm-aggregator](https://github.com/0xPolygonHermez/zkevm-aggregator) | ❌ (WIP)                                                                                                 |\n| Legacy zkevm stack                    | [zkevm-node](https://github.com/0xPolygonHermez/zkevm-node) | [zkevm-node](https://github.com/0xPolygonHermez/zkevm-node)                                                                                                 | ✅                                                                                                       |\n\nTo understand how to configure Kurtosis for these use cases, refer to the [documentation](.github/tests/README.md) and review the test files located in the `.github/tests/` directory.\n\n## Getting Started\n\n### Prerequisites\n\nTo begin, you will need to install [Docker](https://docs.docker.com/get-docker/) (\u003e= [v4.27.0](https://docs.docker.com/desktop/release-notes/#4270) for Mac users) and [Kurtosis](https://docs.kurtosis.com/install/).\n\n- If you notice some services, such as the `zkevm-stateless-executor` or `zkevm-prover`, consistently having the status of `STOPPED`, try increasing the Docker memory allocation.\n\nIf you intend to interact with and debug the stack, you may also want to consider a few additional optional tools such as:\n\n- [jq](https://github.com/jqlang/jq)\n- [yq](https://pypi.org/project/yq/) (v3)\n- [cast](https://book.getfoundry.sh/getting-started/installation)\n- [polycli](https://github.com/0xPolygon/polygon-cli)\n\n### Deploy\n\nOnce 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.\n\n```bash\nkurtosis run --enclave cdk github.com/0xPolygon/kurtosis-cdk\n```\n\nThe default deployment includes [cdk-erigon](https://github.com/0xPolygonHermez/cdk-erigon) as the sequencer, and [cdk-node](https://github.com/0xPolygon/cdk) 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](./input_parser.star).\n\nTo make customizations to the CDK environment, clone this repo, make any desired configuration changes, and then run:\n\n```bash\n# Delete all stop and clean all currently running enclaves\nkurtosis clean --all\n\n# Run this command from the root of the repository to start the network\nkurtosis run --enclave cdk .\n```\n\n![CDK Erigon Architecture Diagram](./docs/architecture-diagram/cdk-erigon-architecture-diagram.png)\n\n### Interact\n\nLet's do a simple L2 RPC test call.\n\nFirst, 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:\n\n```bash\nkurtosis enclave inspect cdk\n```\n\nThat output, while quite useful, might also be a little overwhelming. Let's store the RPC URL in an environment variable.\n\n\u003e You may need to adjust the various commands slightly if you deployed the legacy [zkevm-node](https://github.com/0xPolygonHermez/zkevm-node) as the sequencer. You should target the `zkevm-node-rpc-001` service instead of `cdk-erigon-rpc-001`.\n\n```bash\nexport ETH_RPC_URL=\"$(kurtosis port print cdk cdk-erigon-rpc-001 rpc)\"\n```\n\nThat 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](https://book.getfoundry.sh/getting-started/installation) installed.\n\n```bash\ncast block-number\n```\n\nBy default, the CDK is configured in `test` mode, which means there is some pre-funded value in the admin account with address `0xE34aaF64b29273B7D567FCFc40544c014EEe9970`.\n\n```bash\ncast balance --ether 0xE34aaF64b29273B7D567FCFc40544c014EEe9970\n```\n\nOkay, let’s send some transactions...\n\n```bash\nprivate_key=\"0x12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625\"\ncast send --legacy --private-key \"$private_key\" --value 0.01ether 0x0000000000000000000000000000000000000000\n```\n\nOkay, let’s send even more transactions... Note that this step will assume you have [polygon-cli](https://github.com/maticnetwork/polygon-cli) installed.\n\n```bash\npolycli loadtest --rpc-url \"$ETH_RPC_URL\" --legacy --private-key \"$private_key\" --verbosity 700 --requests 50000 --rate-limit 50 --concurrency 5 --mode t\npolycli loadtest --rpc-url \"$ETH_RPC_URL\" --legacy --private-key \"$private_key\" --verbosity 700 --requests 500 --rate-limit 10 --mode 2\npolycli loadtest --rpc-url \"$ETH_RPC_URL\" --legacy --private-key \"$private_key\" --verbosity 700 --requests 500 --rate-limit 3  --mode uniswapv3\n```\n\nPretty often, you will want to check the output from the service. Here is how you can grab some logs:\n\n```bash\nkurtosis service logs cdk agglayer --follow\n```\n\nIn other cases, if you see an error, you might want to get a shell in the service to be able to poke around.\n\n```bash\nkurtosis service shell cdk contracts-001\njq . /opt/zkevm/combined.json\n```\n\nOne 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](https://docs.polygon.technology/cdk/concepts/transaction-finality/):\n\n```bash\ncast rpc zkevm_batchNumber\ncast rpc zkevm_virtualBatchNumber\ncast rpc zkevm_verifiedBatchNumber\n```\n\nIf the number of verified batches is increasing, then it means the system works properly.\n\nTo access the `zkevm-bridge` user interface, open this URL in your web browser.\n\n```bash\nopen \"$(kurtosis port print cdk zkevm-bridge-proxy-001 web-ui)\"\n```\n\nWhen everything is done, you might want to clean up with this command which stops the local devnet and deletes it.\n\n```bash\nkurtosis clean --all\n```\n\nFor more information about the CDK stack, visit the [Polygon Knowledge Layer](https://docs.polygon.technology/cdk/).\n\n## Advanced Use Cases\n\nThis section features documentation specifically designed for advanced users, outlining complex operations and techniques.\n\n- How to use CDK [ACL](docs/acl-allowlists-blocklists.md).\n- How to deploy [additional services](docs/additional-services.md) alongside the CDK stack, such as transaction spammer, monitoring tools, permissionless nodes etc.\n- How to [attach multiple CDK chains to the AggLayer](docs/attach-multiple-cdks.md).\n- How to use the different [data availability modes](docs/data-availability-modes.md).\n- How to [deploy the stack to an external L1](docs/deploy-using-sepolia.org) such as Sepolia.\n- How to [deploy contracts with the deterministic deployment proxy](docs/deterministic-deployment-proxy.md).\n- How to [edit the zkevm contracts](docs/edit-contracts.md).\n- How to [perform an environment migration](docs/environment-migration.org) with clean copies of the databases.\n- How to [iterate and debug quickly](docs/fast-iteration-cycle.md) with Kurtosis.\n- How to use zkevm contracts [fork 12](docs/fork12.md).\n- How to [integrate a third-party data availability committee](docs/integrate-da.md) (DAC).\n- How to [migrate from fork 7 to fork 9](docs/migrate/forkid-7-to-9.md).\n- How to [upgrade forks for isolated CDK chains](docs/migrate/upgrade.md).\n- How to use a [native token](docs/native-token/native-token.md).\n- How to [play with the network](docs/network-ops.org) to introduce latencies.\n- How to [set up a permissionless zkevm node](docs/permissionless-zkevm-node.md).\n- How to [resequence batches with the cdk-erigon sequencer](docs/resequence-sequencer/resequence-sequencer.md).\n- How to [run a debugger](docs/running-a-debugger/running-a-debugger.org).\n- How to [assign static ports](docs/static-ports/static-ports.md) to Kurtosis services.\n- How to work with the [timelock](docs/timelock.org).\n- How to [trigger a reorg](docs/trigger-a-reorg/trigger-a-reorg.md).\n- How to [perform a trustless recovery the DAC and L1](docs/trustless-recovery-from-dac-l1.md).\n\n## FAQ\n\n### Q: What are the different ways to deploy this package?\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClick to expand\u003c/b\u003e\u003c/summary\u003e\n\n1. Deploy the package without cloning the repository.\n\n```bash\nkurtosis run --enclave cdk github.com/0xPolygon/kurtosis-cdk\nkurtosis run --enclave cdk github.com/0xPolygon/kurtosis-cdk@main\nkurtosis run --enclave cdk github.com/0xPolygon/kurtosis-cdk@v0.2.15\n```\n\n2. Deploy the package with the default parameters.\n\n```bash\nkurtosis run --enclave cdk .\n```\n\n3. Deploy with the default parameters and specify on-the-fly custom arguments.\n\n```bash\nkurtosis run --enclave cdk . '{\"deployment_stages\": {\"deploy_l1\": false}}'\n```\n\n4. Deploy with a configuration file.\n\nCheck the [tests](.github/tests/) folder for sample configuration files.\n\n```bash\nkurtosis run --enclave cdk --args-file params.yml .\n```\n\n5. Do not deploy with a configuration file and specify on-the-fly custom arguments.\n\n🚨 Avoid using this method, as Kurtosis is unable to merge parameters from two different sources (the parameters file and on-the-fly arguments).\n\nThe parameters file will not be used, and only the on-the-fly arguments will be considered.\n\n```bash\nkurtosis run --enclave cdk --args-file params.yml . '{\"args\": {\"agglayer_image\": \"ghcr.io/agglayer/agglayer:latest\"}}'\n# similar to: kurtosis run --enclave cdk . '{\"args\": {\"agglayer_image\": \"ghcr.io/agglayer/agglayer:latest\"}}'\n```\n\n\u003c/details\u003e\n\n### Q: How do I deploy the package to Kubernetes?\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClick to expand\u003c/b\u003e\u003c/summary\u003e\n\nBy default your Kurtosis cluster should be `docker`. You can check this using the following command:\n\n```bash\nkurtosis cluster get\n```\n\nYou can also list the available clusters.\n\n```bash\nkurtosis cluster ls\n```\n\nIf you take a look at your Kurtosis configuration, it should be similar to this:\n\n```yaml\nconfig-version: 2\nshould-send-metrics: true\nkurtosis-clusters:\n  docker:\n    type: \"docker\"\n```\n\nLet's say you've deployed a local [minikube](https://minikube.sigs.k8s.io/docs/) cluster. It would work the same for any type of Kubernetes cluster.\n\nEdit the Kurtosis configuration file.\n\n```bash\nvi \"$(kurtosis config path)\"\n```\n\nUnder `kurtosis-clusters`, you should add another entry for your local Kubernetes cluster.\n\n```yaml\nkurtosis-clusters:\n  minikube: # give it the name you want\n    type: \"kubernetes\"\n    config:\n      kubernetes-cluster-name: \"local-01\" # should be the same as your cluster name\n      storage-class: \"standard\"\n      enclave-size-in-megabytes: 10\n```\n\nThen point Kurtosis to the local Kubernetes cluster.\n\n```bash\nkurtosis cluster set minikube\n```\n\nDeploy the package to Kubernetes.\n\n```bash\nkurtosis run --enclave cdk .\n```\n\nIf you want to revert back to Docker, simply use:\n\n```bash\nkurtosis cluster set docker\n```\n\n\u003c/details\u003e\n\n### Q: I'm trying to deploy the package and Kurtosis is complaining, what should I do?\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClick to expand\u003c/b\u003e\u003c/summary\u003e\n\nOccasionally, Kurtosis deployments may run indefinitely. Typically, deployments should complete within 10 to 15 minutes. If you experience longer deployment times or if it seems stuck, check the Docker engine's memory limit and set it to 16GB if possible. If this does not resolve the issue, please refer to the troubleshooting steps provided.\n\n\u003e 🚨 If you're deploying the package on a mac, you may face an issue when trying to pull the [zkevm-prover](https://github.com/0xPolygonHermez/zkevm-prover) image! Kurtosis will complain by saying `Error response from daemon: no matching manifest for linux/arm64/v8 in the manifest list entries: no match for platform in manifest: not found`. Indeed, the image is meant to be used on `linux/amd64` architectures, which is a bit different from m1 macs architectures, `linux/arm64/v8`.\n\u003e\n\u003e A work-around is to pull the image by specifying the `linux/amd64` architecture before deploying the package.\n\u003e\n\u003e ```bash\n\u003e docker pull --platform linux/amd64 hermeznetwork/zkevm-prover:\u003ctag\u003e\n\u003e kurtosis run ...\n\u003e ```\n\n1. Make sure the issue is related to Kurtosis itself. If you made any changes to the package, most common issues are misconfigurations of services, file artefacts, ports, etc.\n\n2. Remove the Kurtosis enclaves.\n\nNote: By specifying the `--all` flag, Kurtosis will also remove running enclaves.\n\n```bash\nkurtosis clean --all\n```\n\n3. Restart the Kurtosis engine.\n\n```bash\nkurtosis engine restart\n```\n\n4. Restart the Docker daemon.\n\n\u003c/details\u003e\n\n### Q: How do I debug in Kurtosis?\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClick to expand\u003c/b\u003e\u003c/summary\u003e\n\nKurtosis is just a thin wrapper on top of Docker so you can use all the `docker`commands you want.\n\nOn top of that, here are some useful commands.\n\n1. View the state of the enclave (services and endpoints).\n\n```bash\nkurtosis enclave inspect cdk\n```\n\n2. Follow the logs of a service.\n\nNote: If you want to see all the logs of a service, you can specify the `--all` flag.\n\n```bash\nkurtosis service logs cdk cdk-erigon-sequencer-001 --follow\n```\n\n3. Execute a command inside a service.\n\n```bash\nkurtosis service exec cdk contracts-001 'cat /opt/zkevm/combined.json' | tail -n +2 | jq\n```\n\n4. Get a shell inside a service.\n\n```bash\nkurtosis service shell cdk cdk-erigon-sequencer-001\n```\n\n5. Stop or start a service.\n\n```bash\nkurtosis service stop cdk cdk-erigon-sequencer-001\nkurtosis service start cdk cdk-erigon-sequencer-001\n```\n\n6. Get a specific endpoint.\n\n```bash\nkurtosis port print cdk cdk-erigon-node-001 http-rpc\n```\n\n7. Inspect a file artifact.\n\n```bash\nkurtosis files inspect cdk cdk-erigon-node-config-artifact-sequencer config.yaml\n```\n\n8. Download a file artifact.\n\n```bash\nkurtosis files download cdk cdk-erigon-node-config-artifact\n```\n\n\u003c/details\u003e\n\n### Q: How to lint Starlark code?\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClick to expand\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nkurtosis lint --format .\n```\n\n\u003c/details\u003e\n\n### Q: How do I do x, y, z in Kurtosis?\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClick to expand\u003c/b\u003e\u003c/summary\u003e\n\nHead to the Kurtosis [documentation](https://docs.kurtosis.com/).\n\nYou can also take a look at the [Starlark language specification](https://github.com/bazelbuild/starlark/blob/master/spec.md) to know if certain operations are supported.\n\n\u003c/details\u003e\n\n## Contact\n\n- For technical issues, join our [Discord](https://discord.gg/0xpolygonrnd).\n- For documentation issues, raise an issue on the published live doc at [our main repo](https://github.com/0xPolygon/polygon-docs).\n\n## License\n\nCopyright (c) 2024 PT Services DMCC\n\nLicensed under either:\n\n- Apache License, Version 2.0, ([LICENSE-APACHE](./LICENSE-APACHE) or \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e), or\n- MIT license ([LICENSE-MIT](./LICENSE-MIT) or \u003chttp://opensource.org/licenses/MIT\u003e)\n\nas your option.\n\nThe SPDX license identifier for this project is `MIT` OR `Apache-2.0`.\n\n## Contribution\n\nUnless 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xpolygon%2Fkurtosis-cdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xpolygon%2Fkurtosis-cdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xpolygon%2Fkurtosis-cdk/lists"}