Prerequisites & Setup

This page covers everything you need before running your first scenario.

Required Files

versions.env (Required)

All helper scripts require a versions.env file at the repository root:

VERSION=v0.3.1
NOMOS_NODE_REV=abc123def456789
NOMOS_BUNDLE_VERSION=v1

What it defines:

• VERSION — Circuit release tag for KZG parameters
• NOMOS_NODE_REV — Git revision of nomos-node to build/fetch
• NOMOS_BUNDLE_VERSION — Bundle schema version

Where it’s used:

• scripts/run/run-examples.sh
• scripts/build/build-bundle.sh
• scripts/setup/setup-nomos-circuits.sh
• CI workflows

Error if missing:

ERROR: versions.env not found at repository root
This file is required and should define:
  VERSION=<circuit release tag>
  NOMOS_NODE_REV=<nomos-node git revision>
  NOMOS_BUNDLE_VERSION=<bundle schema version>

Fix: Ensure you’re in the repository root. The file should already exist in the checked-out repo.

Node Binaries

Scenarios need compiled nomos-node and nomos-executor binaries.

Option 1: Use Helper Scripts (Recommended)

scripts/run/run-examples.sh -t 60 -v 3 -e 1 host

This automatically:

• Clones/updates nomos-node checkout
• Builds required binaries
• Sets NOMOS_NODE_BIN / NOMOS_EXECUTOR_BIN

Option 2: Manual Build

If you have a sibling nomos-node checkout:

cd ../nomos-node
cargo build --release --bin nomos-node --bin nomos-executor

# Set environment variables
export NOMOS_NODE_BIN=$PWD/target/release/nomos-node
export NOMOS_EXECUTOR_BIN=$PWD/target/release/nomos-executor

# Return to testing framework
cd ../nomos-testing

Option 3: Prebuilt Bundles (CI)

CI workflows use prebuilt artifacts:

- name: Download nomos binaries
  uses: actions/download-artifact@v3
  with:
    name: nomos-binaries-linux
    path: .tmp/

- name: Extract bundle
  run: |
    tar -xzf .tmp/nomos-binaries-linux-*.tar.gz -C .tmp/
    export NOMOS_NODE_BIN=$PWD/.tmp/nomos-node
    export NOMOS_EXECUTOR_BIN=$PWD/.tmp/nomos-executor

Circuit Assets (KZG Parameters)

Data Availability (DA) workloads require KZG cryptographic parameters.

Asset Location

Default path: testing-framework/assets/stack/kzgrs_test_params/kzgrs_test_params

Note: The directory kzgrs_test_params/ contains a file named kzgrs_test_params. This is the proving key file (~120MB).

Container path (compose/k8s): /kzgrs_test_params/kzgrs_test_params

Getting Assets

Option 1: Use helper script (recommended):

# Fetch circuits
scripts/setup/setup-nomos-circuits.sh v0.3.1 /tmp/nomos-circuits

# Copy to default location
mkdir -p testing-framework/assets/stack/kzgrs_test_params
cp -r /tmp/nomos-circuits/* testing-framework/assets/stack/kzgrs_test_params/

# Verify (should be ~120MB)
ls -lh testing-framework/assets/stack/kzgrs_test_params/kzgrs_test_params

Option 2: Let run-examples.sh handle it:

scripts/run/run-examples.sh -t 60 -v 3 -e 1 host

This automatically fetches and places assets.

Override Path

Set NOMOS_KZGRS_PARAMS_PATH to use a custom location:

NOMOS_KZGRS_PARAMS_PATH=/custom/path/to/kzgrs_test_params \
cargo run -p runner-examples --bin local_runner

When Are Assets Needed?

Error without assets:

Error: Custom { kind: NotFound, error: "Circuit file not found at: testing-framework/assets/stack/kzgrs_test_params/kzgrs_test_params" }

Platform Requirements

Host Runner (Local Processes)

Requires:

• Rust nightly toolchain
• Node binaries built
• KZG circuit assets (for DA workloads)
• Available ports (18080+, 3100+, etc.)

No Docker required.

Best for:

• Quick iteration
• Development
• Smoke tests

Compose Runner (Docker Compose)

Requires:

• Docker daemon running
• Docker image built: logos-blockchain-testing:local
• KZG assets baked into image
• Docker Desktop (macOS) or Docker Engine (Linux)

Platform notes (macOS / Apple silicon):

• Prefer NOMOS_BUNDLE_DOCKER_PLATFORM=linux/arm64 for native performance
• Use linux/amd64 only if targeting amd64 environments (slower via emulation)

Best for:

• Reproducible environments
• CI testing
• Chaos workloads (node control support)

K8s Runner (Kubernetes)

Requires:

• Kubernetes cluster (Docker Desktop K8s, minikube, kind, or remote)
• kubectl configured
• Docker image built and loaded/pushed
• KZG assets baked into image + mounted via hostPath

Local cluster setup:

# Docker Desktop: Enable Kubernetes in settings

# OR: Use kind
kind create cluster
kind load docker-image logos-blockchain-testing:local

# OR: Use minikube
minikube start
minikube image load logos-blockchain-testing:local

Remote cluster: Push image to registry and set NOMOS_TESTNET_IMAGE.

Best for:

• Production-like testing
• Resource isolation
• Large topologies

Critical Environment Variable

POL_PROOF_DEV_MODE=true is REQUIRED for ALL runners!

Without this, proof generation uses expensive Groth16 proving, causing:

• Tests “hang” for minutes
• CPU spikes to 100%
• Timeouts and failures

Always set:

POL_PROOF_DEV_MODE=true cargo run -p runner-examples --bin local_runner
POL_PROOF_DEV_MODE=true scripts/run/run-examples.sh -t 60 -v 3 -e 1 compose
# etc.

Or add to your shell profile:

# ~/.bashrc or ~/.zshrc
export POL_PROOF_DEV_MODE=true

Quick Setup Check

Run this checklist before your first scenario:

# 1. Verify versions.env exists
cat versions.env

# 2. Check circuit assets (for DA workloads)
ls -lh testing-framework/assets/stack/kzgrs_test_params/kzgrs_test_params

# 3. Verify POL_PROOF_DEV_MODE is set
echo $POL_PROOF_DEV_MODE  # Should print: true

# 4. For compose/k8s: verify Docker is running
docker ps

# 5. For compose/k8s: verify image exists
docker images | grep logos-blockchain-testing

# 6. For host runner: verify node binaries (if not using scripts)
$NOMOS_NODE_BIN --version
$NOMOS_EXECUTOR_BIN --version

Recommended: Use Helper Scripts

The easiest path is to let the helper scripts handle everything:

# Host runner
scripts/run/run-examples.sh -t 60 -v 3 -e 1 host

# Compose runner
scripts/run/run-examples.sh -t 60 -v 3 -e 1 compose

# K8s runner
scripts/run/run-examples.sh -t 60 -v 3 -e 1 k8s

These scripts:

• Verify versions.env exists
• Clone/build nomos-node if needed
• Fetch circuit assets if missing
• Build Docker images (compose/k8s)
• Load images into cluster (k8s)
• Run the scenario with proper environment

Next Steps:

• Running Examples — Learn how to run scenarios
• Environment Variables — Full variable reference
• Troubleshooting — Common issues and fixes