# EPF6 - Week 9

## Overview

- Investigated how Simulation and assertions (e.g. `nodeAssertion`) can integrate with Kurtosis endpoints
- Confirmed with the team that the proposed advanced runner design identified is the preferrable approach for mapping Kurtosis services into CL/EL/VC roles
- Explored adapting `Simulation.initWithDefaults()` versus introducing a new `Simulation.initWithKurtosisConfig()`
- Worked on planning the `KurtosisSDKRunner` integration with Simulation and assertion framework
- Attended core dev call and shared updates

## Main points

- **Assertions input**: Assertions like [*nodeAssertion*](https://github.com/ChainSafe/lodestar/blob/91df6658d512c5bee0744a6baff8bf572e272f8a/packages/cli/test/sim/multiFork.test.ts#L108) require ready-to-use endpoints (e.g. *beacon API URLs*). Directly using a generic `Map<string, ServiceContext>` is insufficient, from `ServiceContext` to `NodeService`

Current types of KurtosisServiceMap:

    // Optional enrichment for nodes
    export type NodeRoles = {
      beacon?: boolean;
      validator?: boolean;
      execution?: boolean;
    };

    // Future extensible service wrapper
    export type NodeService = {
      id: string;
      serviceContext: ServiceContext;
      beaconApiUrl?: string;
      roles?: NodeRoles;
      metadata?: Record<string, any>;
    };

    // Map of all services (used by test runner and tracker)
    export type KurtosisServicesMap = Map<string, NodeService>;

- Advanced Runner solution: Crucible’s simulation code expects explicit knowledge of which services are CL/EL/VC, not just generic contexts

Example of potential mapping structure:

{
  beacons: {
    "cl-1-lodestar-geth": { serviceContext, beaconApiUrl: "http://localhost:64000" },
    "cl-2-lodestar-geth": { serviceContext, beaconApiUrl: "http://localhost:64001" }
  },
  validators: {
    "vc-1-geth-lodestar": { serviceContext, metricsUrl: "http://localhost:64010" }
  },
  execution: {
    "el-4-geth-lodestar": { serviceContext, rpcUrl: "http://localhost:8545" }
  }
}

- This confirms that **advanced-runner** integration with assertions is the **winning** approach

- Simulation integration:
Considering whether to tweak `Simulation.initWithDefaults()` or introduce a dedicated `Simulation.initWithKurtosisConfig()`

- Drafted a possible signature for `initWithKurtosisConfig()`:

static async initWithKurtosisConfig(
  {forkConfig, logsDir, id, trustedSetup}: SimulationInitOptions,
  kurtosisConfigPath: string // Path to .yml file
): Promise<Simulation>

- Initial implementation design includes:
- Instantiating `KurtosisSDKRunner` inside Simulation
- Loading YAML config via `loadKurtosisConfig()`
- Runner creates services and Simulation converts them into `NodePairs` for compatibility with existing tests and assertions

## Learnings & Outcomes

- `ServiceContext` alone is too generic — mapping to beacon/validator/execution clients is essential
- Confirmed that the `KurtosisSDKRunner` should expose higher-level structures (beacon/EL/VC maps) rather than raw service contexts
- First design of `Simulation.initWithKurtosisConfig()` shows a pathway to integrate YAML configs (`multiFork.yml`) into the test framework

## Week 10 TODOs

- Improve and validate the `initWithKurtosisConfig()` implementation in Simulation
- Initial implementation of **Simulation** and **Tracker** to consume `KurtosisSDKRunner` outputs
- Adapt `Simulation`, `SimulationTracker`, and related orchestration code to consume Kurtosis Runner outputs and correctly map Kurtosis services into beacon, validator, and execution clients
- Continue refining how [NodePairs](https://github.com/ChainSafe/lodestar/blob/91df6658d512c5bee0744a6baff8bf572e272f8a/packages/cli/test/utils/crucible/simulation.ts#L103) are derived from Kurtosis services and converted in `Simulation.ts`

### Useful resources checked
[NodePair function](https://github.com/ChainSafe/lodestar/blob/91df6658d512c5bee0744a6baff8bf572e272f8a/packages/cli/test/utils/crucible/simulation.ts#L103) structure