### Example Geth and Lighthouse Participant Configuration

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/configuration.md

Configures a Geth execution client and a Lighthouse consensus client with specified logging levels and volume sizes. This setup is suitable for a single participant node.

```yaml
participants:
  - el_type: geth
    el_log_level: info
    el_volume_size: 100000
    cl_type: lighthouse
    cl_log_level: info
    cl_volume_size: 100000
    validator_count: 64
    count: 1
```

--------------------------------

### Disruptoor Configuration Example

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

Example configuration for the Disruptoor package, demonstrating how to set up network partitions and shaping rules. Ensure Kurtosis is using the Docker backend and supports privileged mode.

```yaml
participants: [1]
components: [cl]
scope: el_p2p
include_control: true
```

```yaml
participants: [1]
components: all
delay: 50ms
jitter: 10ms
direction: "inbound"
```

```yaml
participants: [1]
components: [vc]
scope: "some_explicit_scope"
```

```yaml
config:
  # Native Disruptoor configuration
  # Use either 'config' or 'partitions'/'shaping', not both.
```

--------------------------------

### Full Ethereum Network Configuration Example

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/configuration.md

A comprehensive example demonstrating the configuration of an Ethereum network with multiple clients, MEV integration, and additional services.

```yaml
participants:
  - el_type: geth
    el_log_level: info
    cl_type: lighthouse
    cl_log_level: info
    validator_count: 64
    count: 2
    
  - el_type: reth
    cl_type: prysm
    use_separate_vc: true
    vc_type: prysm
    validator_count: 32

network_params:
  network: kurtosis
  preset: mainnet
  seconds_per_slot: 12
  genesis_delay: 300
  deneb_fork_epoch: 0
  preregistered_validator_keys_mnemonic: "test test test test test test test test test test test junk"
  num_validator_keys_per_node: 64
  prefunded_accounts:
    "0x9b2055d370f73ec7d8a03e965129118794d1a6b6": {"balance": "1000ETH"}

mev_type: flashbots
mev_params:
  mev_relay_image: "ethpandaops/mev-boost-relay:main"
  mev_builder_image: "ethpandaops/reth-rbuilder:develop"

additional_services:
  - prometheus
  - grafana
  - dora
  - blockscout
  - assertoor

global_log_level: info
persistent: false
wait_for_finalization: false
```

--------------------------------

### Participant Struct Configuration Example

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/types.md

Example configuration for a Participant node, showing settings for blobber service, keymanager, and checkpoint sync.

```python
blobber_enabled=False,
                    # Enable blobber service
blobber_extra_params=[],                 # Blobber parameters
blobber_image="ethpandaops/blobber:latest",
keymanager_enabled=False,                # Enable keymanager
checkpoint_sync_enabled=False,           # Checkpoint sync on startup
skip_start=False,                        # Skip starting this node
)
```

--------------------------------

### Run Disruptoor Example

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

Launches a two-node network with Disruptoor and Dora, applying network conditions at startup. Requires Kurtosis CLI and engine to support privileged mode.

```bash
kurtosis run --enclave disruptoor-example . --args-file .github/tests/examples/disruptoor.yaml --privileged --verbosity detailed
```

--------------------------------

### Run Ethereum Package with Defaults

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/api-reference.md

Basic usage of the `run` function with default configurations. This is suitable for quick testing or standard network setups.

```starlark
run(plan)
```

--------------------------------

### Example Reth and Prysm Participant Configuration with Separate VC

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/configuration.md

Configures a Reth execution client and a Prysm consensus client, utilizing a separate Prysm validator client. This setup allows for distinct configuration of the validator component.

```yaml
participants:
  - el_type: reth
    el_log_level: debug
    cl_type: prysm
    use_separate_vc: true
    vc_type: prysm
    validator_count: 32
```

--------------------------------

### Custom Service Implementation Example

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/overview.md

Outlines the steps to add a new custom service to the package. This includes creating a launcher file, handling its addition in the main logic, and updating constants.

```starlark
src/<service_name>/<service_name>_launcher.star
- launch(plan, params, args) - Launch function
Add to `additional_services` handling in `main.star`
Update constants in `src/package_io/constants.star`
```

--------------------------------

### Main Entry Point Function: run()

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/overview.md

The `run` function in `main.star` orchestrates the entire Ethereum network setup process. It takes a Kurtosis plan and configuration arguments to parse input, generate genesis data, and launch various network components.

```starlark
def run(plan, args={}):
    # Parses and validates input arguments
    # Generates genesis data for EL and CL
    # Launches EL clients based on participant configurations
    # Launches CL clients and connects to EL
    # Launches validator clients (if configured)
    # Sets up MEV infrastructure (if enabled)
    # Deploys monitoring services (if enabled)
    # Deploys additional services (if enabled)
    # Waits for finalization (if enabled)
    pass
```

--------------------------------

### Custom Devnet Configuration Example

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/genesis-and-network-setup.md

An example YAML configuration for creating a custom private devnet (Kurtosis) with specific network parameters, including genesis settings and prefunded accounts.

```yaml
network_params:
  network: kurtosis
  preset: mainnet
  network_id: "1337"
  genesis_gaslimit: 30000000
  seconds_per_slot: 12
  genesis_delay: 300
  preregistered_validator_count: 64
  num_validator_keys_per_node: 64
  preregistered_validator_keys_mnemonic: "test test test test test test test test test test test junk"
  
  # Enable Deneb at genesis
  deneb_fork_epoch: 0
  
  # Electra disabled
  electra_fork_epoch: 18446744073709551615
  
  # Prefund test accounts
  prefunded_accounts:
    "0x9b2055d370f73ec7d8a03e965129118794d1a6b6": {"balance": "1000ETH"}
    "0x70997970C51812e339D9B73b0245601f271b76b0": {"balance": "500ETH"}
```

--------------------------------

### Starlark Control Flow Examples

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/utilities-and-modules.md

Provides examples of common Starlark control flow structures including if-elif-else, for loops, and list comprehensions.

```starlark
if condition:
    # statements
elif other_condition:
    # statements
else:
    # statements

for item in collection:
    # statements

result = [func(x) for x in collection]  # List comprehension
```

--------------------------------

### Custom EL/CL Client Registration Example

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/overview.md

Shows the required file structure and functions to implement when adding a new custom execution or consensus layer client. This involves creating specific launcher files and registering them.

```starlark
src/<el|cl>/<client_name>/<client_name>_launcher.star
- new_<client_name>_launcher(el_cl_data, jwt_file) - Factory
- launch(plan, launcher_config, args) - Launch function
- get_<client_name>_context() - Context extraction
```

--------------------------------

### Example Network Parameters

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/configuration.md

Defines core network parameters such as network name, preset, slot duration, genesis delay, and fork epochs. Includes settings for validator keys and pre-funded accounts.

```yaml
network_params:
  network: kurtosis
  preset: mainnet
  seconds_per_slot: 12
  genesis_delay: 300
  deneb_fork_epoch: 0
  electra_fork_epoch: 18446744073709551615
  preregistered_validator_keys_mnemonic: "test mnemonic words here"
  num_validator_keys_per_node: 64
  prefunded_accounts:
    "0x9b2055d370f73ec7d8a03e965129118794d1a6b6": {"balance": "1000ETH"}
```

--------------------------------

### Run Ethereum Package with Default Configuration

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

This command runs the Ethereum package with its default settings. Ensure Docker is running and the Kurtosis CLI is installed.

```bash
kurtosis run --enclave my-testnet github.com/ethpandaops/ethereum-package
```

--------------------------------

### Get Default Tempo Parameters

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/utilities-and-modules.md

Returns the default configuration for a Tempo service, specifying resource limits and image.

```starlark
struct(
    min_cpu="100m",
    max_cpu="1000m",
    min_mem="512Mb",
    max_mem="1Gb",
    image="grafana/tempo:latest",
)
```

--------------------------------

### Launcher Factory Pattern Example

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/client-reference.md

Illustrates the common Launcher Factory pattern used across different client launchers. This pattern defines a function to create launcher configurations.

```starlark
def new_<client>_launcher(config_args):
    return struct(
        # Launcher configuration
        image=...,
        config_files={},
        # etc.
    )
```

--------------------------------

### Run Ethereum Network with Mock MEV

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

Configure the network to use mock-builder and mev-boost for testing purposes by setting 'mev_type': 'mock'. This setup is suitable when a full MEV infrastructure is not required.

```json
{"mev_type": "mock"}
```

--------------------------------

### Launch Consensus Layer Client

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/api-reference.md

Example of launching a Consensus Layer (CL) client. This function requires various parameters including network parameters, authentication files, and context from other services.

```starlark
cl_context = cl_launcher.launch(
    plan,
    network_params,
    el_cl_data,
    jwt_file,
    keymanager_file,
    args_with_right_defaults,
    all_el_contexts,
    global_node_selectors,
    global_tolerations,
    persistent,
    tempo_otlp_grpc_url,
    otel_otlp_grpc_url,
    otel_otlp_http_traces_url,
    num_participants,
    validator_data,
    prysm_password_relative_filepath,
    prysm_password_artifact_uuid,
    global_other_index,
    extra_files_artifacts,
    backend,
)
```

--------------------------------

### Get Default Blockscout Parameters

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/utilities-and-modules.md

Returns the default configuration for a Blockscout service, including image references and environment settings.

```starlark
struct(
    image="blockscout/blockscout:latest",
    verif_image="blockscout/smart-contract-verifier:latest",
    frontend_image="blockscout/frontend:latest",
    env={},
)
```

--------------------------------

### Participants Matrix Configuration

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

Define combinations of EL, CL, and VC clients for participant setup. Each client type can accept standard participant parameters.

```yaml
participants_matrix: {}
  # el:
  #   - el_type: geth
  #   - el_type: besu
  # cl:
  #   - cl_type: prysm
  #   - cl_type: lighthouse
  # vc:
  #   - vc_type: prysm
  #   - vc_type: lighthouse
```

--------------------------------

### Full Monitoring Setup Configuration

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/README.md

Enables a comprehensive suite of monitoring and exploration services, including Prometheus, Grafana, Tempo, Dora, Blockscout, and Assertoor. Configure retention policies for Prometheus.

```yaml
additional_services:
  - prometheus
  - grafana
  - tempo
  - dora
  - blockscout
  - assertoor

prometheus_params:
  storage_tsdb_retention_time: "30d"

grafana_params:
  additional_dashboards: []

```

--------------------------------

### Example MEV Configuration

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/configuration.md

Configures MEV (Maximal Extractable Value) settings, specifying the MEV type and relay/builder image details. Use this to integrate with MEV services.

```yaml
mev_type: flashbots
mev_params:
  mev_relay_image: "ethpandaops/mev-boost-relay:main"
  mev_builder_image: "ethpandaops/reth-rbuilder:develop"
  run_multiple_relays: false
```

--------------------------------

### Lighthouse Launcher Functions

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/client-reference.md

Defines the available functions for launching the Lighthouse consensus client. These functions are used to configure and start the client.

```starlark
def new_lighthouse_launcher(el_cl_data, jwt_file)
def launch(plan, launcher, args)
def get_lighthouse_context(service_name, ip_addr, port)
def get_beacon_config(config)
def get_blobber_config(config)
```

--------------------------------

### Basic Network Setup Configuration

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/README.md

Defines parameters for a basic Kurtosis network with specified execution and consensus clients, validator count, and network settings. Use this for simple testnet deployments.

```yaml
# network_params.yaml
participants:
  - el_type: geth
    cl_type: lighthouse
    validator_count: 64

network_params:
  network: kurtosis
  preset: mainnet
  seconds_per_slot: 12
  genesis_delay: 300
  preregistered_validator_keys_mnemonic: "test test test test test test test test test test test junk"
  num_validator_keys_per_node: 64

additional_services:
  - prometheus
  - grafana

global_log_level: info

```

--------------------------------

### 3-Node Ethereum Network with Mock MEV

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

Sets up a 3-node Ethereum network using various EL/CL client combinations in 'mock' MEV mode. This is useful for testing MEV-boost without a full relay setup.

```yaml
participants:
  - el_type: geth
    el_image: ''
    cl_type: lighthouse
    cl_image: ''
    count: 2
  - el_type: nethermind
    el_image: ''
    cl_type: teku
    cl_image: ''
    count: 1
  - el_type: besu
    el_image: ''
    cl_type: prysm
    cl_image: ''
    count: 2
mev_type: mock
```

--------------------------------

### run(plan, args)

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/api-reference.md

The main entry point function for the Ethereum Package. Launches an arbitrarily complex Ethereum testnet based on provided configuration.

```APIDOC
## run(plan, args)

### Description
The main entry point function for the Ethereum Package. Launches an arbitrarily complex Ethereum testnet based on provided configuration.

### Signature
```starlark
def run(plan, args={})
```

### Parameters
#### Path Parameters
- **plan** (plan object) - Required - Kurtosis plan object for orchestrating services
- **args** (dict) - Optional - Configuration dictionary following the network_params.yaml schema

### Request Example
```starlark
# Basic usage with defaults
run(plan)

# With custom configuration
args = {
    "participants": [
        {
            "el_type": "geth",
            "cl_type": "lighthouse"
        }
    ],
    "network_params": {
        "network": "kurtosis",
        "preregistered_validator_keys_mnemonic": "test mnemonic here"
    }
}
run(plan, args)
```

### Response
#### Success Response
None

### Description
The `run()` function orchestrates the complete setup of an Ethereum network by:
1. Parsing and validating input configuration through `input_parser.input_parser()`
2. Generating genesis data for EL and CL using the Ethereum genesis generator
3. Launching execution layer (EL) clients (Geth, Reth, Erigon, Nethermind, Besu, etc.)
4. Launching consensus layer (CL) clients (Lighthouse, Prysm, Teku, Lodestar, Nimbus, Grandine)
5. Launching validator clients if separate from CL
6. Setting up optional monitoring (Prometheus, Grafana, Tempo)
7. Configuring MEV infrastructure if enabled (MEV-Boost, relays, builders)
8. Deploying additional services (transaction spammer, block explorers, etc.)

**Supported Networks:**
- `kurtosis` - Private devnet with controlled genesis
- `mainnet` - Ethereum mainnet (checkpoint sync)
- `sepolia` - Sepolia testnet (checkpoint sync)
- `hoodi` - Hoodi testnet (checkpoint sync)
- `ephemery` - Ephemery testnet
- `shadowfork` networks (e.g., `mainnet-shadowfork`)

**Execution Layer (EL) Clients:**
- `geth` - Go Ethereum
- `reth` - Rust Ethereum
- `erigon` - Erigon
- `nethermind` - Nethermind
- `besu` - Hyperledger Besu
- `ethereumjs` - EthereumJS
- `nimbus` - Nimbus-eth1
- `ethrex` - ethrex

**Consensus Layer (CL) Clients:**
- `lighthouse` - Lighthouse
- `prysm` - Prysm
- `teku` - Teku
- `lodestar` - Lodestar
- `nimbus` - Nimbus-eth2
- `grandine` - Grandine
- `caplin` - Caplin (Geth CL)
- `consensoor` - Consensoor

**Validator Client (VC) Types:**
- `lighthouse` - Lighthouse
- `prysm` - Prysm
- `teku` - Teku
- `lodestar` - Lodestar
- `nimbus` - Nimbus
- `grandine` - Grandine
- `vero` - Vero
- `consensoor` - Consensoor
```

--------------------------------

### Network Launcher Function Signature

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/utilities-and-modules.md

Illustrates the function signature pattern for getting a network handler by its name.

```starlark
def get_network_from_name(network_name)
    # Returns network type handler for the named network
```

--------------------------------

### Get Processed Node Selectors

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/utilities-and-modules.md

Processes and returns node selectors for service scheduling. Accepts a dictionary of node labels.

```starlark
selectors = get_node_selectors({"node-type": "compute"})
```

--------------------------------

### Run Ethereum Package with Custom Configuration

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

This command runs the Ethereum package using a custom configuration file. The `--args-file` flag specifies the path to your YAML configuration file.

```bash
kurtosis run --enclave my-testnet github.com/ethpandaops/ethereum-package --args-file network_params.yaml
```

--------------------------------

### Get Processed Tolerations

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/utilities-and-modules.md

Processes and returns Kubernetes tolerations for service deployment. Accepts a list of global toleration objects.

```starlark
tolerations = get_tolerations(participant.tolerations)
```

--------------------------------

### Get Default Grafana Parameters

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/utilities-and-modules.md

Returns the default configuration for a Grafana service, including resource limits, image, and dashboard settings.

```starlark
struct(
    additional_dashboards=[],
    min_cpu="100m",
    max_cpu="1000m",
    min_mem="512Mb",
    max_mem="1Gb",
    image="grafana/grafana:latest",
)
```

--------------------------------

### Add Service with Configuration

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/utilities-and-modules.md

Illustrates adding a service to the plan with its configuration, including image, ports, files, and environment variables.

```starlark
service = plan.add_service(
    name="service-0",
    config=ServiceConfig(
        image=image_name,
        ports={"http": PortSpec(number=8080)},
        files={"/config": config_artifact},
        env_vars={"KEY": "value"},
    ),
)
```

--------------------------------

### Get Default Prometheus Parameters

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/utilities-and-modules.md

Returns the default configuration for a Prometheus service, specifying storage retention, resource limits, and image.

```starlark
struct(
    storage_tsdb_retention_time="30d",
    storage_tsdb_retention_size="10GB",
    min_cpu="500m",
    max_cpu="2000m",
    min_mem="1Gb",
    max_mem="4Gb",
    image="prom/prometheus:latest",
)
```

--------------------------------

### Ethereum Package Data Flow

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/overview.md

This snippet illustrates the sequence of operations from initial configuration input to a fully launched Ethereum network, including parsing, genesis generation, and client launches.

```text
1. Configuration Input (YAML/JSON)
   ↓
2. input_parser.star - Parse and validate
   ↓
3. Network launcher selection (kurtosis, public, shadowfork, etc.)
   ↓
4. Genesis generation
   ├─ EL genesis (chain config)
   └─ CL genesis (beacon state)
   ↓
5. Launch sequence
   ├─ EL clients (execution layer)
   ├─ CL clients (consensus layer)
   ├─ VC clients (validator clients)
   ├─ MEV infrastructure (optional)
   └─ Additional services (optional)
   ↓
6. Network ready for testing
```

--------------------------------

### Execution Layer Launcher

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/service-launchers.md

Launches EL clients (Geth, Reth, Erigon, etc.) by generating service configurations, mounting genesis and JWT files, and setting up network parameters, metrics, and port publishing.

```APIDOC
## Execution Layer Launcher

### Module: `src/el/el_launcher.star`

### Main Function: `launch`

```starlark
def launch(
    plan,
    network_params,
    el_cl_data,
    jwt_file,
    args_with_right_defaults,
    global_node_selectors,
    global_tolerations,
    persistent,
    otel_otlp_grpc_url,
    otel_otlp_http_traces_url,
    num_participants,
    global_other_index,
    extra_files_artifacts,
    backend,
    binary_artifacts={},
)
```

### Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| plan | plan object | Kurtosis plan for service orchestration |
| network_params | struct | Network parameters (chain ID, gas limit, forks, etc.) |
| el_cl_data | struct | EL/CL genesis data from generator |
| jwt_file | artifact | JWT secret file for EL-CL communication |
| args_with_right_defaults | struct | Parsed input arguments with defaults |
| global_node_selectors | dict | Kubernetes node selectors |
| global_tolerations | list | Kubernetes tolerations |
| persistent | bool | Whether to use persistent storage |
| otel_otlp_grpc_url | string | OpenTelemetry gRPC URL (optional) |
| otel_otlp_http_traces_url | string | OpenTelemetry HTTP traces URL (optional) |
| num_participants | number | Total number of participants |
| global_other_index | number | Global service index |
| extra_files_artifacts | dict | Extra files to mount |
| backend | string | Cluster backend (docker or kubernetes) |
| binary_artifacts | dict | Injected EL binaries (optional) |

### Returns:

List of `el_context` structs with:
- `service_name` - Service name in Kurtosis (e.g., "el-node-0")
- `ip_addr` - Internal IP address
- `port` - RPC port number
- `rpc_http_port` - HTTP RPC port
- `ws_port` - WebSocket port
- `engine_rpc_port_num` - Engine API RPC port
- `engine_ws_port_num` - Engine API WebSocket port
- `metrics_port_num` - Prometheus metrics port

### Description:

Launches EL clients based on participant configurations. For each participant, creates a service with the specified EL client (Geth, Reth, Erigon, etc.) connected to the network via genesis data. The launcher:

1. Generates service configurations for each EL client
2. Mounts genesis data and JWT files
3. Configures network parameters (network ID, gas limit, forks)
4. Sets up prometheus metrics
5. Handles port publishing
6. Manages persistent storage

### Supported Clients:
- `geth` - Go Ethereum
- `reth` - Rust Ethereum  
- `erigon` - Erigon
- `nethermind` - Nethermind
- `besu` - Hyperledger Besu
- `ethereumjs` - EthereumJS
- `nimbus` - Nimbus-eth1
- `ethrex` - ethrex

### Source File:
`src/el/el_launcher.star`
```

--------------------------------

### Get Standardized Network Name

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/utilities-and-modules.md

Standardizes various network name formats into a canonical string. Handles mainnet, sepolia, and shadowforks.

```starlark
net_name = get_network_name("mainnet-shadowfork")  # Returns "mainnet"
```

--------------------------------

### Service Launcher Pattern

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/overview.md

Illustrates the common pattern for launching services within the package. This pattern involves creating a launcher and then executing it with a plan and configuration.

```starlark
launcher.new_<service>_launcher(args) → config
launcher.launch(plan, config, args) → context
```

--------------------------------

### Get Public IP Address

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/utilities-and-modules.md

Retrieves the public IP address for service deployment. Requires plan, tolerations, and node selectors as input.

```starlark
public_ip = get_public_ip(plan, tolerations, selectors)
```

--------------------------------

### Consensus Layer Launcher

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/service-launchers.md

Launches CL clients (Lighthouse, Prysm, Teku, etc.) by generating beacon chain genesis, configuring consensus parameters, mounting validator keystores, and establishing EL connections.

```APIDOC
## Consensus Layer Launcher

### Module: `src/cl/cl_launcher.star`

### Main Function: `launch`

```starlark
def launch(
    plan,
    network_params,
    el_cl_data,
    jwt_file,
    keymanager_file,
    args_with_right_defaults,
    all_el_contexts,
    global_node_selectors,
    global_tolerations,
    persistent,
    tempo_otlp_grpc_url,
    otel_otlp_grpc_url,
    otel_otlp_http_traces_url,
    num_participants,
    validator_data,
    prysm_password_relative_filepath,
    prysm_password_artifact_uuid,
    global_other_index,
    extra_files_artifacts,
    backend,
    bootnodoor_enr=None,
    binary_artifacts={},
)
```

### Key Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| el_cl_data | struct | Genesis data for beacon chain |
| jwt_file | artifact | JWT secret for EL-CL communication |
| keymanager_file | artifact | Keymanager configuration |
| all_el_contexts | list | List of EL contexts for engine API connection |
| validator_data | struct | Validator keystores and metadata |
| tempo_otlp_grpc_url | string | Tempo tracing URL |
| bootnodoor_enr | string | Optional bootnode ENR override |

### Returns:

List of `cl_context` structs with:
- `service_name` - Service name (e.g., "cl-node-0")
- `ip_addr` - Internal IP address
- `http_port` - HTTP port for REST API
- `grpc_port` - gRPC port
- `metrics_port_num` - Prometheus metrics port

### Description:

Launches CL clients with the following steps:

1. Generates beacon chain genesis from EL/CL data
2. Configures consensus parameters (fork epochs, validator count, etc.)
3. Mounts validator keystores (if separate VC)
4. Establishes EL connection via engine API
5. Configures P2P networking
6. Sets up metrics collection

### Supported Clients:
- `lighthouse` - Lighthouse (Rust)
- `prysm` - Prysm (Go)
- `teku` - Teku (Java)
- `lodestar` - Lodestar (JavaScript)
- `nimbus` - Nimbus-eth2 (Nim)
- `grandine` - Grandine (Rust)
- `caplin` - Caplin (Geth CL)
- `consensoor` - Consensoor

### Source File:
`src/cl/cl_launcher.star`
```

--------------------------------

### Erigon Launcher Functions

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/client-reference.md

Outlines the functions required to launch and configure Erigon execution clients. These functions facilitate the setup and management of Erigon nodes.

```starlark
def new_erigon_launcher(el_cl_data, jwt_file)
def launch(plan, launcher, args)
def get_erigon_context(service_name, ip_addr, port, engine_rpc_port)
```

--------------------------------

### Mock zkVM Backend Configuration

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

Configure a mock zkVM backend for testing. Customize simulated proving time, proof size, and failure simulation.

```yaml
- kind: mock
  proof_type: ethrex-zisk
  mock_proving_time: { kind: constant, ms: 5000 }
  mock_proof_size: 1024
```

```yaml
- kind: mock
  proof_type: reth-zisk
  mock_proving_time: { kind: random, min_ms: 2000, max_ms: 8000 }
```

```yaml
- kind: mock
  proof_type: reth-sp1
  mock_proving_time: { kind: linear, ms_per_mgas: 150 }
```

--------------------------------

### 2-Node Geth/Lighthouse Network with Optional Services

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

Sets up a 2-node Geth/Lighthouse network with optional monitoring and fuzzing services enabled. Includes Prometheus, Grafana, tx_fuzz, and EngineAPI snooper.

```yaml
participants:
  - el_type: geth
    cl_type: lighthouse
    count: 2
snooper_params:
  enabled: true
additional_services:
  - prometheus
  - grafana
  - tx_fuzz	hereum_metrics_exporter_enabled: true
```

--------------------------------

### Invoke AI Agent Skill with Claude Code

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

Example of invoking the kurtosis-ethereum AI agent skill using a natural language prompt in Claude Code.

```bash
# Claude Code
/kurtosis-ethereum spin up a 4-node devnet with geth+lighthouse and reth+prysm with assertoor stability checks
```

--------------------------------

### Access Service Shell in Kurtosis

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

Command to get shell access to a specific service within a Kurtosis testnet. Replace `$SERVICE_NAME` with the actual service name.

```bash
kurtosis service shell my-testnet $SERVICE_NAME
```

--------------------------------

### Port IDs Configuration

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/api-reference.md

Defines constants for various TCP and UDP port IDs used by services. These are essential for network communication setup and service discovery.

```starlark
TCP_DISCOVERY_PORT_ID = "tcp-discovery"
UDP_DISCOVERY_PORT_ID = "udp-discovery"
RPC_PORT_ID = "rpc"
HTTP_PORT_ID = "http"
METRICS_PORT_ID = "metrics"
ENGINE_RPC_PORT_ID = "engine-rpc"
VALIDATOR_HTTP_PORT_ID = "http-validator"
DEBUG_PORT_ID = "debug"
```

--------------------------------

### Launch Basic Network

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/README.md

Command to launch a Kurtosis network using a specified configuration file. Ensure the Ethereum package is cloned locally or available via its GitHub path.

```bash
kurtosis run --enclave my-network github.com/ethpandaops/ethereum-package --args-file network_params.yaml

```

--------------------------------

### Run Ethereum Network with Commit-Boost MEV

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

Enable infrastructure powered by commit-boost by setting 'mev_type': 'commit-boost'.

```json
{"mev_type": "commit-boost"}
```

--------------------------------

### MEV Parameters Configuration

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/types.md

Configure MEV builder, relay, MEV-Boost, and mock MEV settings. Includes options for image selection, extra arguments, and subsidies.

```starlark
struct(
    # Builder Configuration
    mev_builder_image="ethpandaops/reth-rbuilder:develop",
    mev_builder_cl_image="sigp/lighthouse:latest",
    mev_builder_extra_data="",               # Extra data for builder
    mev_builder_subsidy=0,                   # ETH subsidy for builder
    mev_builder_extra_args=[],               # Additional builder parameters
    mev_builder_cl_extra_params=[],          # Additional CL params for builder
    
    # Relay Configuration
    mev_relay_image="ethpandaops/mev-boost-relay:main",
    mev_relay_api_extra_args=[],             # Extra relay API arguments
    mev_relay_api_extra_env_vars={},
    mev_relay_housekeeper_extra_args=[],     # Extra housekeeper arguments
    mev_relay_housekeeper_extra_env_vars={},
    mev_relay_website_extra_args=[],         # Extra website arguments
    mev_relay_website_extra_env_vars={},
    
    # MEV-Boost Configuration
    mev_boost_image="ethpandaops/mev-boost:develop",
    mev_boost_args=[],                       # Extra MEV-Boost arguments
    
    # Mock MEV Configuration
    mock_mev_image="ethpandaops/rustic-builder:main",
    
    # Helix Relay Configuration
    helix_relay_image="ghcr.io/gattaca-com/helix-relay:main",
    
    # Commit-Boost Configuration
    commit_boost_config="",                  # Commit-Boost TOML config
    
    # Monitoring & Debugging
    launch_adminer=False,                    # Launch adminer database UI
    run_multiple_relays=False,               # Run multiple relays
    
    # Builder Prometheus Config
    mev_builder_prometheus_config=struct(
        scrape_interval="30s",
        labels={},
    ),
)
```

--------------------------------

### Prysm Launcher Functions

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/client-reference.md

Defines the available functions for launching the Prysm consensus client. These functions are used to configure and start the client, including OpenTelemetry tracing support.

```starlark
def new_prysm_launcher(el_cl_data, jwt_file, otel_otlp_http_traces_url)
def launch(plan, launcher, args)
def get_prysm_context(service_name, ip_addr, port)
```

--------------------------------

### Configuration Hierarchy

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/README.md

Illustrates the flow of configuration processing from input YAML/JSON through parsing, network type selection, genesis generation, and service launching.

```text
Input Configuration (YAML/JSON)
    ↓
Parse & Validate (input_parser)
    ↓
Network Type Selection (network_launcher)
    ↓
Genesis Generation
    ↓
Service Launchers (EL, CL, VC, MEV, etc.)
    ↓
Complete Network

```

--------------------------------

### Default Consensus Layer Client Images

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/overview.md

Lists the default Docker images for various consensus layer clients. These are used when deploying a full Ethereum node setup.

```plaintext
lighthouse: sigp/lighthouse:latest
teku: consensys/teku:latest
prysm: offchainlabs/prysm-beacon-chain:stable
lodestar: chainsafe/lodestar:latest
nimbus: statusim/nimbus-eth2:multiarch-latest
grandine: sifrai/grandine:stable
caplin: ethpandaops/caplin:main
consensoor: ethpandaops/consensoor:main
```

--------------------------------

### Multi-Client Network Configuration

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/README.md

Sets up a network with multiple distinct client combinations for EL, CL, and VC. Useful for testing interoperability between different client stacks.

```yaml
participants:
  - el_type: geth
    cl_type: lighthouse
    validator_count: 32

  - el_type: reth
    cl_type: prysm
    validator_count: 32
    use_separate_vc: true

  - el_type: nethermind
    cl_type: teku
    validator_count: 32

network_params:
  network: kurtosis
  preset: mainnet

```

--------------------------------

### Download Execution Layer Genesis Data

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

Specific example of downloading the Execution Layer genesis data using the Kurtosis CLI. Saves the data to the specified output directory.

```bash
kurtosis files download my-testnet el-genesis-data ~/Downloads
```

--------------------------------

### ZKBoost Service Parameters

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/types.md

Configure ZKBoost service, including image, instances, ZKVMs, and environment variables. Use for ZK-related operations.

```starlark
struct(
    image="ghcr.io/eth-act/zkboost/zkboost:latest",
    instances=[],                            # ZK instance configurations
    zkvms=[],                                # ZK VM configurations
    env={},
)
```

--------------------------------

### Launch Function Pattern

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/client-reference.md

Defines a standard pattern for launching services, including creating service configurations and adding them to a plan. Returns a struct with service context information.

```starlark
def launch(plan, launcher_config, service_args):
    # Create service configuration
    service_config = ServiceConfig(
        image=launcher_config.image,
        ports=...,
        files=...,
        # etc.
    )
    
    # Add service to plan
    service = plan.add_service(
        name=service_name,
        config=service_config
    )
    
    # Return context with service information
    return struct(
        service_name=service_name,
        ip_addr=service.ip_address,
        port=service.ports["http"],
        # etc.
    )
```

--------------------------------

### Invoke AI Agent Skill with Codex

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

Example of invoking the kurtosis-ethereum AI agent skill using a natural language prompt with Codex. The skill is implicitly invoked or via /skills.

```bash
# Codex — the skill is invoked implicitly or via /skills
spin up a 4-node devnet with geth+lighthouse and reth+prysm with assertoor stability checks
```

--------------------------------

### Deposit Data Structure for Genesis

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/genesis-and-network-setup.md

Example structure for deposit data, used for external deposit contract deployment. Includes fields like pubkey, withdrawal credentials, amount, and signature.

```json
[
  {
    "pubkey": "0x...",
    "withdrawal_credentials": "0x...",
    "amount": 32,
    "signature": "0x...",
    "deposit_message_root": "0x...",
    "deposit_data_root": "0x..."
  }
]
```

--------------------------------

### sanity_check(plan, input_args)

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/utilities-and-modules.md

Performs a pre-launch validation of the entire configuration.

```APIDOC
## sanity_check(plan, input_args)

### Description
Performs a comprehensive pre-launch validation of the entire network configuration. This function checks for client compatibility, network configuration correctness, storage setup, Kubernetes settings, MEV parameters, and fork configuration. It ensures that all components are compatible and correctly configured before launching the network.

### Parameters
#### Path Parameters
- **plan** (object) - Required - The network plan object.
- **input_args** (object) - Required - The input arguments for the sanity check.

### Checks Performed
1. **Client Compatibility**: Validates EL, CL, and VC types, and their supported combinations.
2. **Network Configuration**: Ensures network name, ID, mnemonic (for kurtosis), and slot timing are consistent and valid.
3. **Storage Configuration**: Checks archive mode compatibility, volume sizes, and persistent storage requirements.
4. **Kubernetes Configuration**: Validates tolerations, node selectors, and resource requests.
5. **MEV Configuration**: Verifies MEV type, relay configuration, and builder parameters.
6. **Fork Configuration**: Ensures fork epochs are ordered, and presets are compatible and correctly timed.

### Failure Handling
- Terminates with a descriptive error message using the Starlark `fail()` function.
- Prevents the launch of an invalid network.
```

--------------------------------

### Service Context Structure

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/service-launchers.md

All launchers return context structures with common fields, including service name, IP address, and various ports.

```starlark
struct(
    service_name="service-0",              # Service name in Kurtosis
    ip_addr="172.16.0.2",                  # Internal IP address
    port=8545,                             # Main service port
    metrics_port_num=6060,                 # Optional: Prometheus metrics port
    http_port=3610,                        # Optional: HTTP port
    grpc_port=4000,                        # Optional: gRPC port
)
```

--------------------------------

### Launch Tempo Service

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/service-launchers.md

Launches Tempo, a distributed tracing backend for collecting, storing, and querying traces. Integrates with Grafana and requires Tempo parameters and global configurations.

```starlark
def launch(
    plan,
    tempo_params,
    global_node_selectors,
    global_tolerations,
    persistent,
    global_other_index,
)
```

--------------------------------

### Run Ethereum Package with Custom Configuration

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/api-reference.md

Advanced usage of the `run` function, allowing for custom network participants and parameters. Use this to define specific execution and consensus clients, or to set network-level configurations like mnemonics.

```starlark
args = {
    "participants": [
        {
            "el_type": "geth",
            "cl_type": "lighthouse"
        }
    ],
    "network_params": {
        "network": "kurtosis",
        "preregistered_validator_keys_mnemonic": "test mnemonic here"
    }
}
run(plan, args)
```

--------------------------------

### Apply Default Input Arguments

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/utilities-and-modules.md

Applies default values to input configuration for network parameters, services, resources, and logs. Ensures a complete configuration structure.

```starlark
default_input_args(input_args)
```

--------------------------------

### Consensus Layer Genesis Output Structure

Source: https://github.com/ethpandaops/ethereum-package/blob/main/_autodocs/genesis-and-network-setup.md

Example Starlark structure for Consensus Layer genesis data. Key fields include genesis time, validator root, fork version, and keystores.

```starlark
struct(
  genesis_time = <unix timestamp>,
  genesis_validators_root = "0x...",
  genesis_fork_version = "0x10000038",
  # Validator keys and state
  per_node_keystores = {
    # Keystores organized by node
  },
)
```

--------------------------------

### zkboost Instance Configuration

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

Configure individual zkboost instances, each monitoring an EL participant. Specify the Kurtosis service name and the index of the EL participant to connect to.

```yaml
instances:
  - name: zkboost
    el_participant_index: 0
```

--------------------------------

### Run Ethereum Network with Flashbots MEV

Source: https://github.com/ethpandaops/ethereum-package/blob/main/README.md

Use this command to spin up a network of Ethereum nodes with an external block-building network using Flashbot's mev-boost protocol. Ensure Kurtosis is installed and configured.

```bash
kurtosis run github.com/ethpandaops/ethereum-package '{"mev_type": "flashbots"}'
```