Annotated Tree

Directory structure with key paths annotated:

logos-blockchain-testing/
├─ testing-framework/           # Core library crates
│  ├─ configs/                  # Node config builders, topology generation, tracing/logging config
│  ├─ core/                     # Scenario model (ScenarioBuilder), runtime (Runner, Deployer), topology, node spawning
│  ├─ workflows/                # Workloads (transactions, DA, chaos), expectations (liveness), builder DSL extensions
│  ├─ runners/                  # Deployment backends
│  │  ├─ local/                 # LocalDeployer (spawns local processes)
│  │  ├─ compose/               # ComposeDeployer (Docker Compose + Prometheus)
│  │  └─ k8s/                   # K8sDeployer (Kubernetes Helm)
│  └─ assets/                   # Docker/K8s stack assets
│     └─ stack/
│        ├─ kzgrs_test_params/  # KZG circuit parameters directory
│        │  └─ kzgrs_test_params  # Actual proving key file (note repeated name)
│        ├─ monitoring/         # Prometheus config
│        ├─ scripts/            # Container entrypoints
│        └─ cfgsync.yaml        # Config sync server template
│
├─ examples/                    # PRIMARY ENTRY POINT: runnable binaries
│  └─ src/bin/
│     ├─ local_runner.rs        # Host processes demo (LocalDeployer)
│     ├─ compose_runner.rs      # Docker Compose demo (ComposeDeployer)
│     └─ k8s_runner.rs          # Kubernetes demo (K8sDeployer)
│
├─ scripts/                     # Helper utilities
│  ├─ run-examples.sh           # Convenience script (handles setup + runs examples)
│  ├─ build-bundle.sh           # Build prebuilt binaries+circuits bundle
│  ├─ setup-circuits-stack.sh  # Fetch KZG parameters (Linux + host)
│  └─ setup-nomos-circuits.sh  # Legacy circuit fetcher
│
└─ book/                        # This documentation (mdBook)

Key Directories Explained

testing-framework/

Core library crates providing the testing API.

testing-framework/assets/stack/

Docker/K8s deployment assets:

• kzgrs_test_params/kzgrs_test_params: Circuit parameters file (note repeated name; override via NOMOS_KZGRS_PARAMS_PATH)
• monitoring/: Prometheus config
• scripts/: Container entrypoints

scripts/

Convenience utilities:

• run-examples.sh: All-in-one script for host/compose/k8s modes (recommended)
• build-bundle.sh: Create prebuilt binaries+circuits bundle for compose/k8s
• build_test_image.sh: Build the compose/k8s Docker image (bakes in assets)
• setup-circuits-stack.sh: Fetch KZG parameters for both Linux and host
• cfgsync.yaml: Configuration sync server template

examples/ (Start Here!)

Runnable binaries demonstrating framework usage:

• local_runner.rs — Local processes
• compose_runner.rs — Docker Compose (requires NOMOS_TESTNET_IMAGE built)
• k8s_runner.rs — Kubernetes (requires cluster + image)

Run with: POL_PROOF_DEV_MODE=true cargo run -p runner-examples --bin <name>

All runners require POL_PROOF_DEV_MODE=true to avoid expensive proof generation.

scripts/

Helper utilities:

• setup-nomos-circuits.sh: Fetch KZG parameters from releases

Observability

Compose runner includes:

• Prometheus at http://localhost:9090 (metrics scraping)
• Node metrics exposed per validator/executor
• Access in expectations: ctx.telemetry().prometheus().map(|p| p.base_url())

Logging controlled by:

• NOMOS_LOG_DIR — Write per-node log files
• NOMOS_LOG_LEVEL — Global log level (error/warn/info/debug/trace)
• NOMOS_LOG_FILTER — Target-specific filtering (e.g., cryptarchia=trace,nomos_da_sampling=debug)
• NOMOS_TESTS_TRACING — Enable file logging for local runner

See Logging & Observability for details.

Navigation Guide

For detailed guidance, see Internal Crate Reference.