How to Set Up a Local Ethereum Testnet with Kurtosis

Introduction

This guide provides a step-by-step process for creating a configurable local Ethereum testnet using Kurtosis. Designed for dApp developers, it enables you to deploy smart contracts and run tests against your decentralized applications (dApps) in a controlled environment before transitioning to live networks.

Key Objectives:

• Instantiate a local Ethereum testnet using Kurtosis and the ethereum-package.
• Connect a Hardhat development environment to compile, deploy, and test dApps.
• Customize network configurations, including node count and client pairings (EL/CL).

What is Kurtosis?

Kurtosis is a composable build system for multi-container environments, ideal for creating reproducible blockchain testnets. It supports dynamic setup logic and diverse client configurations (e.g., geth for Execution Layer and teku/lighthouse/lodestar for Consensus Layer). The Ethereum Foundation leverages Kurtosis for testing major upgrades like the Merge.

👉 Explore Kurtosis use cases

Prerequisites

Before proceeding, ensure you have:

1. Docker Engine installed and running.
2. Kurtosis CLI installed (latest version).
3. Node.js, yarn, and npx for dApp development.

Step 1: Instantiate a Local Ethereum Testnet

Run the following command to spin up a testnet:

kurtosis --enclave local-eth-testnet run github.com/ethpandaops/ethereum-package

Expected Output:

• An enclave named local-eth-testnet is created.
• File artifacts (e.g., genesis data, prefunded keys) and user services (EL/CL clients) are initialized.
• Services like geth (EL) and lighthouse (CL) start automatically.

Step 2: Connect Your dApp Development Environment

Clone and Set Up the Example dApp:

git clone https://github.com/kurtosis-tech/awesome-kurtosis.git && \
cd awesome-kurtosis/smart-contract-example && \
yarn

Configure Hardhat:

Update hardhat.config.ts to point to your local testnet’s RPC port (e.g., 8545):

localnet: {
  url: 'http://127.0.0.1:<YOUR_PORT>',
  accounts: [/* prefunded test keys */],
},

Verify connectivity:

npx hardhat balances --network localnet

Step 3: Deploy and Test Your dApp

1. Compile and Deploy:

   npx hardhat compile
   npx hardhat run scripts/deploy.ts --network localnet

2. Run Tests:

   npx hardhat test --network localnet

Step 4: Customize Network Configurations

Modify the eth-network-params.yaml to create a heterogeneous network:

{
  "participants": [
    { "el_client_type": "geth", "cl_client_type": "lighthouse" },
    { "el_client_type": "geth", "cl_client_type": "lodestar" },
    { "el_client_type": "geth", "cl_client_type": "teku" }
  ],
  "network_params": { /* ... */ }
}

Redeploy with updated params:

kurtosis clean -a && \
kurtosis run --enclave local-eth-testnet github.com/ethpandaops/ethereum-package --args-file ~/eth-network-params.yaml

👉 Advanced network configurations

FAQ

Why use Kurtosis over other testnet tools?

Kurtosis offers greater flexibility in client pairings and network configurations, making it suitable for testing diverse scenarios.

How do I troubleshoot RPC connection issues?

Ensure the el-client-* service ports match your Hardhat configuration. Use kurtosis enclave inspect to verify running services.

Can I add more nodes later?

Yes! Edit the params file and rerun the Kurtosis command. Existing enclaves must be cleaned first (kurtosis clean -a).

Conclusion

You’ve successfully:

1. Created a local Ethereum testnet.
2. Deployed and tested a dApp.
3. Scaled the network to 3 nodes with varied clients.

For further learning, explore the Kurtosis quickstart or join the Discord community.