Rapidly Testing New Polygon CDK Releases with Kurtosis

·

Introduction

The Polygon Chain Development Kit (CDK) provides a robust framework for launching customized zero-knowledge Layer 2 (L2) blockchains. For developers looking to test new versions of the CDK stack quickly and efficiently, the Kurtosis package offers a streamlined solution. This platform utilizes containerized environments to spin up temporary, private networks that include all necessary components.

Kurtosis employs Starlark, a Python-like scripting language, to define the entire setup process. This enables developers to instantiate fully functional CDK chains with customizable elements like sequencers, aggregators, and data availability committees. The entire stack runs in isolated Docker containers, making it ideal for testing and development without affecting live environments.

What the Kurtosis Package Deploys

When you initiate the Kurtosis package for Polygon CDK, it deploys a comprehensive local development environment. This setup includes several key components that work together to simulate a real-world blockchain network.

Local L1 Chain: The foundation is a local Ethereum-compatible Layer 1 chain deployed using the ethereum-package. This component is fully customizable and supports multiple client implementations, providing a realistic base layer for your L2 operations.

Local L2 Chain: At the heart of the setup is the Polygon CDK-based L2 chain. This includes all essential components such as the sequencer, sequence sender, aggregator, RPC nodes, prover, and data availability committee. The L2 chain deployment follows a specific sequence: it first deploys the necessary zkEVM smart contracts on the L1 chain before initializing the other components.

Bridge Infrastructure: To facilitate asset movement between layers, the package includes the zkEVM bridge service. This component handles the secure transfer of assets from L1 to L2 and vice versa, implementing the necessary cryptographic guarantees for trustless operations.

AggLayer Protocol: This emerging interoperability protocol enables trustless cross-chain token transfers and message passing between different L2 chains. It uses zero-knowledge proofs to ensure security while allowing for complex operations across multiple chains.

Additional Services: The package also includes various utility services such as transaction spam generators for load testing, monitoring tools for observing network performance, and permissionless nodes for enhanced decentralization.

Understanding Version Compatibility

The Polygon CDK ecosystem comprises multiple interconnected modules that must maintain version compatibility to function correctly. The Kurtosis package manages these dependencies through a system of Fork IDs, each representing a specific combination of component versions.

For instance, Fork ID 12 uses CDK Erigon version v2.1.2, zkEVM Prover v8.0.0-RC14, and zkEVM Contracts v8.0.0-rc.4. This careful versioning ensures that all components work together seamlessly, preventing compatibility issues that could disrupt testing and development.

When starting with the Kurtosis package, it's recommended to begin with the default Fork ID (typically the most recent stable version) unless you have specific requirements for testing older or newer component combinations.

Setting Up Your Testing Environment

Before deploying your test network, you need to prepare your development environment with several essential tools.

Docker: Since Kurtosis operates using containerized services, you must have Docker installed and running on your system. This provides the underlying containerization technology that enables isolated, reproducible environments.

Kurtosis CLI: The command-line interface for Kurtosis allows you to interact with the platform, start environments, and manage services. Installation typically involves adding the Kurtosis package repository and installing the CLI tool.

Development Utilities: Several additional tools enhance your testing capabilities:

Most of these tools can be installed through package managers or by following the installation instructions provided in their respective repositories.

Deployment Process

Once your environment is prepared, deploying a test network involves a straightforward process. Begin by cloning the kurtosis-cdk repository from the official GitHub repository. This contains all the necessary configuration files and scripts.

Before initiating the deployment, it's recommended to start with a clean environment by running the Kurtosis clean command with the all flag. This ensures no conflicting services are running from previous sessions.

Adjusting system limits may be necessary for optimal performance. The ulimit command can increase the number of open file descriptors, which is particularly important when running multiple blockchain components simultaneously.

The actual deployment is initiated with the kurtosis run command, specifying the enclave name (typically "cdk") and the path to the configuration directory. This command reads the Starlark scripts and begins the process of pulling Docker images, configuring services, and starting the entire stack.

By default, the deployment includes CDK Erigon as the sequencer, along with CDK node components handling sequence sending and aggregation. You can verify the specific versions and configurations by examining the input_parser.star file in the repository.

Network Inspection and Management

After deployment, you can inspect the running environment to understand its structure and component relationships. The kurtosis enclave inspect command provides a detailed overview of all running services, their statuses, and how they're connected.

This inspection reveals the network topology, showing how different components communicate and which ports they expose for external interaction. Understanding this layout is crucial for debugging and customizing your test environment.

Interacting with Your L2 Chain

Once your test network is running, you can begin interacting with it through various interfaces. The primary method is via JSON-RPC calls to the L2 chain's RPC endpoint.

First, set the ETH_RPC_URL environment variable to point to your running CDK Erigon RPC service. You can obtain this URL using the kurtosis port print command, which displays the accessible ports for your services.

Basic chain interaction can be tested using the cast tool from the Foundry suite. Checking the current block number verifies that your chain is producing blocks and that the RPC connection is working correctly.

The CDK test environment comes preconfigured with a test mode that includes a pre-funded administrator account. You can check the balance of this account to confirm that the initial state setup completed successfully.

Transaction Testing

For more advanced testing, you can send transactions to your L2 chain. The test environment includes a known private key for the pre-funded account, allowing you to sign and send transactions without additional account setup.

A simple value transfer transaction can test basic functionality. Sending ETH to the zero address (a common test pattern) verifies that transaction processing, gas calculation, and block inclusion are working correctly.

The transaction response provides detailed information including transaction hash, block number, gas usage, and status. A status of 1 indicates successful execution, while any other value suggests an error occurred.

Load Testing Scenarios

For comprehensive testing, especially when evaluating new CDK versions, load testing provides valuable performance insights. The polygon-cli tools include a loadtest command that can generate significant transaction volume.

Different testing modes exercise various aspects of the system:

Adjusting parameters like request count, rate limit, and concurrency allows you to simulate different network conditions and usage patterns. Monitoring system behavior under load helps identify potential bottlenecks or issues before deployment to production environments.

Monitoring and Logs

During testing, monitoring service logs provides crucial insights into system behavior and helps identify issues. The kurtosis service logs command allows you to tail logs from specific services in real-time.

Following the AggLayer logs shows cross-chain operations and interoperability features. The bridge service logs reveal asset transfer activities between L1 and L2. The sequencer and RPC logs display transaction processing and block production details.

For deeper investigation, you can access shells within running service containers. This allows you to examine configuration files, check service status, and run diagnostic commands directly within the container environment.

System Health Checks

Regular health checks ensure your test network is operating correctly. Several specific JSON-RPC methods provide insight into the zkEVM batch processing system:

If these numbers are increasing steadily, it indicates that the proving system is working correctly and batches are being processed, proven, and verified in sequence. Stagnant numbers may indicate a problem with the prover or aggregator services.

User Interface Access

Some components, like the zkEVM bridge, include web-based user interfaces. You can access these interfaces by using the kurtosis port print command to get the appropriate URL and opening it in your browser.

These interfaces provide visual representations of bridge operations, allowing you to monitor asset transfers, check transaction statuses, and interact with the bridge without using command-line tools.

Cleaning Up

After completing your testing, properly cleaning up the environment ensures system resources are freed and prevents conflicts with future deployments. The kurtosis clean command with the all flag removes all running services and associated containers.

This cleanup is particularly important when testing different Fork IDs or component versions, as it ensures a fresh start for each test scenario.

Frequently Asked Questions

What is the primary advantage of using Kurtosis for Polygon CDK testing?
Kurtosis provides a containerized, isolated environment that can be quickly spun up and torn down. This allows for testing multiple configurations and versions without conflicts. The platform's declarative approach using Starlark scripts ensures reproducible environments, making it ideal for development and quality assurance workflows.

How does the Fork ID system affect my testing?
Each Fork ID represents a specific combination of component versions that are known to work together. When testing new CDK releases, you would typically use the Fork ID corresponding to that release. This system ensures version compatibility across all stack components, preventing subtle bugs that can occur when mixing incompatible versions.

Can I customize the components deployed by the Kurtosis package?
Yes, the Starlark scripts that define the deployment are customizable. You can modify parameters, change component versions, or even add entirely new services to the deployment. However, for standard testing of new CDK releases, using the predefined configurations is recommended unless you have specific customization needs.

What should I do if my deployment fails or services won't start?
First, check the service logs using the kurtosis service logs command. Common issues include port conflicts, insufficient system resources, or network connectivity problems preventing Docker image downloads. Ensure all prerequisites are properly installed and that your system meets the minimum resource requirements.

How can I simulate real-world conditions in my test environment?
Beyond basic load testing, you can deploy complex smart contracts, simulate user interactions patterns, and even connect multiple test environments to simulate multi-chain scenarios. The Explore more strategies for advanced testing approaches that can help identify potential issues before mainnet deployment.

What's the difference between the various load testing modes?
Each load testing mode exercises different parts of the system. Basic transaction testing focuses on core transaction processing. Mode 2 tests more complex transaction patterns, while Uniswap V3 mode simulates the intensive computation and storage patterns typical of DeFi applications. Using a combination of these modes provides comprehensive coverage of potential real-world usage scenarios.

Conclusion

Testing new versions of Polygon CDK using Kurtosis provides an efficient, isolated environment for validating functionality, performance, and compatibility. The containerized approach ensures consistency across testing scenarios while the comprehensive component coverage allows for full-stack validation. By following the deployment and testing processes outlined, developers can confidently evaluate new CDK releases before committing to production deployments.

The combination of automated deployment, detailed logging, and comprehensive testing tools makes this approach particularly valuable for teams maintaining production CDK-based chains. Regular testing of new releases helps identify potential issues early, ensuring smooth upgrades and maintaining network reliability.