Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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
LOGOS_BLOCKCHAIN_NODE_REV=abc123def456789
LOGOS_BLOCKCHAIN_BUNDLE_VERSION=v1

What it defines:

  • VERSION — Circuit assets release tag
  • LOGOS_BLOCKCHAIN_NODE_REV — Git revision of logos-blockchain-node to build/fetch
  • LOGOS_BLOCKCHAIN_BUNDLE_VERSION — Bundle schema version

Where it’s used:

  • scripts/run/run-examples.sh
  • scripts/build/build-bundle.sh
  • scripts/setup/setup-logos-blockchain-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>
  LOGOS_BLOCKCHAIN_NODE_REV=<logos-blockchain-node git revision>
  LOGOS_BLOCKCHAIN_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 logos-blockchain-node binaries.

scripts/run/run-examples.sh -t 60 -n 3 host

This automatically:

  • Clones/updates logos-blockchain-node checkout
  • Builds required binaries
  • Sets LOGOS_BLOCKCHAIN_NODE_BIN

Option 2: Manual Build

If you have a sibling logos-blockchain-node checkout:

cd ../logos-blockchain-node
cargo build --release --bin logos-blockchain-node 

# Set environment variables
export LOGOS_BLOCKCHAIN_NODE_BIN=$PWD/target/release/logos-blockchain-node

# 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 LOGOS_BLOCKCHAIN_NODE_BIN=$PWD/.tmp/logos-blockchain-node

Circuit Assets

Nodes require circuit assets for proof generation. The framework expects a directory containing the circuits, not a single file.

Asset Location

Default path: ~/.logos-blockchain-circuits

Container path (compose/k8s): /opt/circuits (set during image build)

Getting Assets

Option 1: Use helper script (recommended):

scripts/setup/setup-logos-blockchain-circuits.sh v0.3.1 ~/.logos-blockchain-circuits

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

scripts/run/run-examples.sh -t 60 -n 3 host

Override Path

Set LOGOS_BLOCKCHAIN_CIRCUITS to use a custom location:

LOGOS_BLOCKCHAIN_CIRCUITS=/custom/path/to/circuits \
cargo run -p runner-examples --bin local_runner

When Are Assets Needed?

RunnerWhen Required
Host (local)Always
ComposeDuring image build (baked into image)
K8sDuring image build

Error without assets:

Error: circuits directory not found (LOGOS_BLOCKCHAIN_CIRCUITS)

Platform Requirements

Host Runner (Local Processes)

Requires:

  • Rust nightly toolchain
  • Node binaries built
  • Circuit assets for proof generation
  • 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
  • Circuit assets baked into image
  • Docker Desktop (macOS) or Docker Engine (Linux)

Platform notes (macOS / Apple silicon):

  • Prefer LOGOS_BLOCKCHAIN_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
  • Circuit assets baked into image

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 LOGOS_BLOCKCHAIN_TESTNET_IMAGE.

Best for:

  • Production-like testing
  • Resource isolation
  • Large topologies

Quick Setup Check

Run this checklist before your first scenario:

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

# 2. Check circuit assets
ls -lh "${HOME}/.logos-blockchain-circuits"

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

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

# 5. For host runner: verify node binaries (if not using scripts)
$LOGOS_BLOCKCHAIN_NODE_BIN --version

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

# Host runner
scripts/run/run-examples.sh -t 60 -n 3 host

# Compose runner
scripts/run/run-examples.sh -t 60 -n 3 compose

# K8s runner
scripts/run/run-examples.sh -t 60 -n 3 k8s

These scripts:

  • Verify versions.env exists
  • Clone/build logos-blockchain-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: