logos-blockchain/logos-blockchain-testing
1
0
Fork 0
mirror of https://github.com/logos-blockchain/logos-blockchain-testing.git synced 2026-01-02 13:23:13 +00:00
Code Issues Packages Projects Releases Wiki Activity
logos-blockchain-testing/docs/environment-variables.html
andrussal b44a96f392 Publish book
2025-12-20 09:51:51 +01:00

550 lines
39 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE HTML>
<html lang="en" class="light" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Environment Variables - Logos Blockchain Testing Framework Book</title>
<!-- Custom HTML head -->
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="favicon.svg">
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body class="sidebar-visible no-js">
<div id="body-container">
<!-- Provide site root to javascript -->
<script>
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('light')
html.classList.add(theme);
var body = document.querySelector('body');
body.classList.remove('no-js')
body.classList.add('js');
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
var body = document.querySelector('body');
var sidebar = null;
var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
body.classList.remove('sidebar-visible');
body.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded "><a href="project-context-primer.html"><strong aria-hidden="true">1.</strong> Project Context Primer</a></li><li class="chapter-item expanded "><a href="what-you-will-learn.html"><strong aria-hidden="true">2.</strong> What You Will Learn</a></li><li class="chapter-item expanded "><a href="quickstart.html"><strong aria-hidden="true">3.</strong> Quickstart</a></li><li class="chapter-item expanded "><a href="part-i.html"><strong aria-hidden="true">4.</strong> Part I — Foundations</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="introduction.html"><strong aria-hidden="true">4.1.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="architecture-overview.html"><strong aria-hidden="true">4.2.</strong> Architecture Overview</a></li><li class="chapter-item expanded "><a href="testing-philosophy.html"><strong aria-hidden="true">4.3.</strong> Testing Philosophy</a></li><li class="chapter-item expanded "><a href="scenario-lifecycle.html"><strong aria-hidden="true">4.4.</strong> Scenario Lifecycle</a></li><li class="chapter-item expanded "><a href="design-rationale.html"><strong aria-hidden="true">4.5.</strong> Design Rationale</a></li></ol></li><li class="chapter-item expanded "><a href="part-ii.html"><strong aria-hidden="true">5.</strong> Part II — User Guide</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="workspace-layout.html"><strong aria-hidden="true">5.1.</strong> Workspace Layout</a></li><li class="chapter-item expanded "><a href="annotated-tree.html"><strong aria-hidden="true">5.2.</strong> Annotated Tree</a></li><li class="chapter-item expanded "><a href="authoring-scenarios.html"><strong aria-hidden="true">5.3.</strong> Authoring Scenarios</a></li><li class="chapter-item expanded "><a href="workloads.html"><strong aria-hidden="true">5.4.</strong> Core Content: Workloads & Expectations</a></li><li class="chapter-item expanded "><a href="scenario-builder-ext-patterns.html"><strong aria-hidden="true">5.5.</strong> Core Content: ScenarioBuilderExt Patterns</a></li><li class="chapter-item expanded "><a href="best-practices.html"><strong aria-hidden="true">5.6.</strong> Best Practices</a></li><li class="chapter-item expanded "><a href="usage-patterns.html"><strong aria-hidden="true">5.7.</strong> Usage Patterns</a></li><li class="chapter-item expanded "><a href="examples.html"><strong aria-hidden="true">5.8.</strong> Examples</a></li><li class="chapter-item expanded "><a href="examples-advanced.html"><strong aria-hidden="true">5.9.</strong> Advanced & Artificial Examples</a></li><li class="chapter-item expanded "><a href="cucumber-bdd.html"><strong aria-hidden="true">5.10.</strong> Cucumber/BDD Interface</a></li><li class="chapter-item expanded "><a href="running-scenarios.html"><strong aria-hidden="true">5.11.</strong> Running Scenarios</a></li><li class="chapter-item expanded "><a href="runners.html"><strong aria-hidden="true">5.12.</strong> Runners</a></li><li class="chapter-item expanded "><a href="node-control.html"><strong aria-hidden="true">5.13.</strong> RunContext: BlockFeed & Node Control</a></li><li class="chapter-item expanded "><a href="chaos.html"><strong aria-hidden="true">5.14.</strong> Chaos Workloads</a></li><li class="chapter-item expanded "><a href="topology-chaos.html"><strong aria-hidden="true">5.15.</strong> Topology & Chaos Patterns</a></li></ol></li><li class="chapter-item expanded "><a href="part-iii.html"><strong aria-hidden="true">6.</strong> Part III — Developer Reference</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="scenario-model.html"><strong aria-hidden="true">6.1.</strong> Scenario Model (Developer Level)</a></li><li class="chapter-item expanded "><a href="api-levels.html"><strong aria-hidden="true">6.2.</strong> API Levels: Builder DSL vs. Direct</a></li><li class="chapter-item expanded "><a href="extending.html"><strong aria-hidden="true">6.3.</strong> Extending the Framework</a></li><li class="chapter-item expanded "><a href="custom-workload-example.html"><strong aria-hidden="true">6.4.</strong> Example: New Workload & Expectation (Rust)</a></li><li class="chapter-item expanded "><a href="internal-crate-reference.html"><strong aria-hidden="true">6.5.</strong> Internal Crate Reference</a></li></ol></li><li class="chapter-item expanded "><a href="part-iv.html"><strong aria-hidden="true">7.</strong> Part IV — Operations & Deployment</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="operations-overview.html"><strong aria-hidden="true">7.1.</strong> Overview</a></li><li class="chapter-item expanded "><a href="prerequisites.html"><strong aria-hidden="true">7.2.</strong> Prerequisites & Setup</a></li><li class="chapter-item expanded "><a href="running-examples.html"><strong aria-hidden="true">7.3.</strong> Running Examples</a></li><li class="chapter-item expanded "><a href="ci-integration.html"><strong aria-hidden="true">7.4.</strong> CI Integration</a></li><li class="chapter-item expanded "><a href="environment-variables.html" class="active"><strong aria-hidden="true">7.5.</strong> Environment Variables</a></li><li class="chapter-item expanded "><a href="logging-observability.html"><strong aria-hidden="true">7.6.</strong> Logging & Observability</a></li></ol></li><li class="chapter-item expanded "><a href="part-v.html"><strong aria-hidden="true">8.</strong> Part V — Appendix</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="dsl-cheat-sheet.html"><strong aria-hidden="true">8.1.</strong> Builder API Quick Reference</a></li><li class="chapter-item expanded "><a href="troubleshooting.html"><strong aria-hidden="true">8.2.</strong> Troubleshooting Scenarios</a></li><li class="chapter-item expanded "><a href="faq.html"><strong aria-hidden="true">8.3.</strong> FAQ</a></li><li class="chapter-item expanded "><a href="glossary.html"><strong aria-hidden="true">8.4.</strong> Glossary</a></li></ol></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<!-- Track and set sidebar scroll position -->
<script>
var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
sidebarScrollbox.addEventListener('click', function(e) {
if (e.target.tagName === 'A') {
sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
}
}, { passive: true });
var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
sessionStorage.removeItem('sidebar-scroll');
if (sidebarScrollTop) {
// preserve sidebar scroll position when navigating via links within sidebar
sidebarScrollbox.scrollTop = sidebarScrollTop;
} else {
// scroll sidebar to current active section when navigating via "next/previous chapter" buttons
var activeSection = document.querySelector('#sidebar .active');
if (activeSection) {
activeSection.scrollIntoView({ block: 'center' });
}
}
</script>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Logos Blockchain Testing Framework Book</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="environment-variables-reference"><a class="header" href="#environment-variables-reference">Environment Variables Reference</a></h1>
<p>Complete reference of environment variables used by the testing framework, organized by category.</p>
<h2 id="critical-variables"><a class="header" href="#critical-variables">Critical Variables</a></h2>
<p>These MUST be set for successful test runs:</p>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Required</th><th>Default</th><th>Effect</th></tr></thead><tbody>
<tr><td><code>POL_PROOF_DEV_MODE</code></td><td><strong>YES</strong></td><td>—</td><td><strong>REQUIRED for all runners</strong>. Set to <code>true</code> to use fast dev-mode proving instead of expensive Groth16. Without this, tests will hang/timeout.</td></tr>
</tbody></table>
</div>
<p><strong>Example:</strong></p>
<pre><code class="language-bash">export POL_PROOF_DEV_MODE=true
</code></pre>
<p>Or add to your shell profile (<code>~/.bashrc</code>, <code>~/.zshrc</code>):</p>
<pre><code class="language-bash"># Required for nomos-testing framework
export POL_PROOF_DEV_MODE=true
</code></pre>
<hr />
<h2 id="runner-selection--topology"><a class="header" href="#runner-selection--topology">Runner Selection &amp; Topology</a></h2>
<p>Control which runner to use and the test topology:</p>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Default</th><th>Effect</th></tr></thead><tbody>
<tr><td><code>NOMOS_DEMO_VALIDATORS</code></td><td>1</td><td>Number of validators (all runners)</td></tr>
<tr><td><code>NOMOS_DEMO_EXECUTORS</code></td><td>1</td><td>Number of executors (all runners)</td></tr>
<tr><td><code>NOMOS_DEMO_RUN_SECS</code></td><td>60</td><td>Run duration in seconds (all runners)</td></tr>
<tr><td><code>LOCAL_DEMO_VALIDATORS</code></td><td>—</td><td>Legacy: Number of validators (host runner only)</td></tr>
<tr><td><code>LOCAL_DEMO_EXECUTORS</code></td><td>—</td><td>Legacy: Number of executors (host runner only)</td></tr>
<tr><td><code>LOCAL_DEMO_RUN_SECS</code></td><td>—</td><td>Legacy: Run duration (host runner only)</td></tr>
<tr><td><code>COMPOSE_NODE_PAIRS</code></td><td>—</td><td>Compose-specific topology format: "validators×executors" (e.g., <code>3x2</code>)</td></tr>
</tbody></table>
</div>
<p><strong>Example:</strong></p>
<pre><code class="language-bash"># Run with 5 validators, 2 executors, for 120 seconds
NOMOS_DEMO_VALIDATORS=5 \
NOMOS_DEMO_EXECUTORS=2 \
NOMOS_DEMO_RUN_SECS=120 \
scripts/run/run-examples.sh -t 120 -v 5 -e 2 host
</code></pre>
<hr />
<h2 id="node-binaries-host-runner"><a class="header" href="#node-binaries-host-runner">Node Binaries (Host Runner)</a></h2>
<p>Required for host runner when not using helper scripts:</p>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Required</th><th>Default</th><th>Effect</th></tr></thead><tbody>
<tr><td><code>NOMOS_NODE_BIN</code></td><td>Yes (host)</td><td>—</td><td>Path to <code>nomos-node</code> binary</td></tr>
<tr><td><code>NOMOS_EXECUTOR_BIN</code></td><td>Yes (host)</td><td>—</td><td>Path to <code>nomos-executor</code> binary</td></tr>
<tr><td><code>NOMOS_NODE_PATH</code></td><td>No</td><td>—</td><td>Path to nomos-node git checkout (dev workflow)</td></tr>
</tbody></table>
</div>
<p><strong>Example:</strong></p>
<pre><code class="language-bash">export NOMOS_NODE_BIN=/path/to/nomos-node/target/release/nomos-node
export NOMOS_EXECUTOR_BIN=/path/to/nomos-node/target/release/nomos-executor
</code></pre>
<hr />
<h2 id="docker-images-compose--k8s"><a class="header" href="#docker-images-compose--k8s">Docker Images (Compose / K8s)</a></h2>
<p>Required for compose and k8s runners:</p>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Required</th><th>Default</th><th>Effect</th></tr></thead><tbody>
<tr><td><code>NOMOS_TESTNET_IMAGE</code></td><td>Yes (compose/k8s)</td><td><code>logos-blockchain-testing:local</code></td><td>Docker image tag for node containers</td></tr>
<tr><td><code>NOMOS_TESTNET_IMAGE_PULL_POLICY</code></td><td>No</td><td><code>IfNotPresent</code> (local) / <code>Always</code> (ECR)</td><td>K8s <code>imagePullPolicy</code> used by the runner</td></tr>
<tr><td><code>NOMOS_BINARIES_TAR</code></td><td>No</td><td>—</td><td>Path to prebuilt bundle (<code>.tar.gz</code>) for image build</td></tr>
<tr><td><code>NOMOS_SKIP_IMAGE_BUILD</code></td><td>No</td><td>0</td><td>Skip image rebuild (compose/k8s); assumes image already exists</td></tr>
<tr><td><code>NOMOS_FORCE_IMAGE_BUILD</code></td><td>No</td><td>0</td><td>Force rebuilding the image even when the script would normally skip it (e.g. non-local k8s)</td></tr>
</tbody></table>
</div>
<p><strong>Example:</strong></p>
<pre><code class="language-bash"># Using prebuilt bundle
export NOMOS_BINARIES_TAR=.tmp/nomos-binaries-linux-v0.3.1.tar.gz
export NOMOS_TESTNET_IMAGE=logos-blockchain-testing:local
scripts/build/build_test_image.sh
# Using pre-existing image (skip build)
export NOMOS_SKIP_IMAGE_BUILD=1
scripts/run/run-examples.sh -t 60 -v 3 -e 1 compose
</code></pre>
<hr />
<h2 id="circuit-assets-kzg-parameters"><a class="header" href="#circuit-assets-kzg-parameters">Circuit Assets (KZG Parameters)</a></h2>
<p>Circuit asset configuration for DA workloads:</p>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Default</th><th>Effect</th></tr></thead><tbody>
<tr><td><code>NOMOS_KZGRS_PARAMS_PATH</code></td><td><code>testing-framework/assets/stack/kzgrs_test_params/kzgrs_test_params</code></td><td>Path to KZG proving key file</td></tr>
<tr><td><code>NOMOS_KZG_DIR_REL</code></td><td><code>testing-framework/assets/stack/kzgrs_test_params</code></td><td>Directory containing KZG assets (relative to workspace root)</td></tr>
<tr><td><code>NOMOS_KZG_FILE</code></td><td><code>kzgrs_test_params</code></td><td>Filename of the proving key within <code>NOMOS_KZG_DIR_REL</code></td></tr>
<tr><td><code>NOMOS_KZG_CONTAINER_PATH</code></td><td><code>/kzgrs_test_params/kzgrs_test_params</code></td><td>File path where the node expects KZG params inside containers</td></tr>
<tr><td><code>NOMOS_KZG_MODE</code></td><td>Runner-specific</td><td>K8s only: <code>hostPath</code> (mount from host) or <code>inImage</code> (embed into image)</td></tr>
<tr><td><code>NOMOS_KZG_IN_IMAGE_PARAMS_PATH</code></td><td><code>/opt/nomos/kzg-params/kzgrs_test_params</code></td><td>K8s <code>inImage</code> mode: where the proving key is stored inside the image</td></tr>
<tr><td><code>VERSION</code></td><td>From <code>versions.env</code></td><td>Circuit release tag (used by helper scripts)</td></tr>
<tr><td><code>NOMOS_CIRCUITS</code></td><td>—</td><td>Directory containing fetched circuit bundles (set by <code>scripts/setup/setup-circuits-stack.sh</code>)</td></tr>
<tr><td><code>NOMOS_CIRCUITS_VERSION</code></td><td>—</td><td>Legacy alias for <code>VERSION</code> (supported by some build scripts)</td></tr>
<tr><td><code>NOMOS_CIRCUITS_PLATFORM</code></td><td>Auto-detected</td><td>Override circuits platform (e.g. <code>linux-x86_64</code>, <code>macos-aarch64</code>)</td></tr>
<tr><td><code>NOMOS_CIRCUITS_HOST_DIR_REL</code></td><td><code>.tmp/nomos-circuits-host</code></td><td>Output dir for host circuits bundle (relative to repo root)</td></tr>
<tr><td><code>NOMOS_CIRCUITS_LINUX_DIR_REL</code></td><td><code>.tmp/nomos-circuits-linux</code></td><td>Output dir for linux circuits bundle (relative to repo root)</td></tr>
<tr><td><code>NOMOS_CIRCUITS_NONINTERACTIVE</code></td><td>0</td><td>Set to <code>1</code> to overwrite outputs without prompting in setup scripts</td></tr>
<tr><td><code>NOMOS_CIRCUITS_REBUILD_RAPIDSNARK</code></td><td>0</td><td>Set to <code>1</code> to force rebuilding rapidsnark (host bundle only)</td></tr>
</tbody></table>
</div>
<p><strong>Example:</strong></p>
<pre><code class="language-bash"># Use custom circuit assets
NOMOS_KZGRS_PARAMS_PATH=/custom/path/to/kzgrs_test_params \
cargo run -p runner-examples --bin local_runner
</code></pre>
<hr />
<h2 id="node-logging"><a class="header" href="#node-logging">Node Logging</a></h2>
<p>Control node log output (not framework runner logs):</p>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Default</th><th>Effect</th></tr></thead><tbody>
<tr><td><code>NOMOS_LOG_LEVEL</code></td><td><code>info</code></td><td>Global log level: <code>error</code>, <code>warn</code>, <code>info</code>, <code>debug</code>, <code>trace</code></td></tr>
<tr><td><code>NOMOS_LOG_FILTER</code></td><td>—</td><td>Fine-grained module filtering (e.g., <code>cryptarchia=trace,nomos_da_sampling=debug</code>)</td></tr>
<tr><td><code>NOMOS_LOG_DIR</code></td><td>—</td><td>Host runner: directory for per-node log files (persistent). Compose/k8s: use <code>cfgsync.yaml</code> for file logging.</td></tr>
<tr><td><code>NOMOS_TESTS_KEEP_LOGS</code></td><td>0</td><td>Keep per-run temporary directories (useful for debugging/CI artifacts)</td></tr>
<tr><td><code>NOMOS_TESTS_TRACING</code></td><td>false</td><td>Enable debug tracing preset (combine with <code>NOMOS_LOG_DIR</code> unless external tracing backends configured)</td></tr>
</tbody></table>
</div>
<p><strong>Important:</strong> Node logging ignores <code>RUST_LOG</code>; use <code>NOMOS_LOG_LEVEL</code> and <code>NOMOS_LOG_FILTER</code> for node logs.</p>
<p><strong>Example:</strong></p>
<pre><code class="language-bash"># Debug logging to files
NOMOS_LOG_DIR=/tmp/test-logs \
NOMOS_LOG_LEVEL=debug \
NOMOS_LOG_FILTER="cryptarchia=trace,nomos_da_sampling=debug" \
POL_PROOF_DEV_MODE=true \
cargo run -p runner-examples --bin local_runner
# Inspect logs
ls /tmp/test-logs/
# nomos-node-0.2024-12-18T14-30-00.log
# nomos-node-1.2024-12-18T14-30-00.log
</code></pre>
<p><strong>Common filter targets:</strong></p>
<div class="table-wrapper"><table><thead><tr><th>Target Prefix</th><th>Subsystem</th></tr></thead><tbody>
<tr><td><code>cryptarchia</code></td><td>Consensus (Cryptarchia)</td></tr>
<tr><td><code>nomos_da_sampling</code></td><td>DA sampling service</td></tr>
<tr><td><code>nomos_da_dispersal</code></td><td>DA dispersal service</td></tr>
<tr><td><code>nomos_da_verifier</code></td><td>DA verification</td></tr>
<tr><td><code>nomos_blend</code></td><td>Mix network/privacy layer</td></tr>
<tr><td><code>chain_service</code></td><td>Chain service (node APIs/state)</td></tr>
<tr><td><code>chain_network</code></td><td>P2P networking</td></tr>
<tr><td><code>chain_leader</code></td><td>Leader election</td></tr>
</tbody></table>
</div>
<hr />
<h2 id="observability--metrics"><a class="header" href="#observability--metrics">Observability &amp; Metrics</a></h2>
<p>Optional observability integration:</p>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Default</th><th>Effect</th></tr></thead><tbody>
<tr><td><code>NOMOS_METRICS_QUERY_URL</code></td><td>—</td><td>Prometheus-compatible base URL for runner to query (e.g., <code>http://localhost:9090</code>)</td></tr>
<tr><td><code>NOMOS_METRICS_OTLP_INGEST_URL</code></td><td>—</td><td>Full OTLP HTTP ingest URL for node metrics export (e.g., <code>http://localhost:9090/api/v1/otlp/v1/metrics</code>)</td></tr>
<tr><td><code>NOMOS_GRAFANA_URL</code></td><td>—</td><td>Grafana base URL for printing/logging (e.g., <code>http://localhost:3000</code>)</td></tr>
<tr><td><code>NOMOS_OTLP_ENDPOINT</code></td><td>—</td><td>OTLP trace endpoint (optional)</td></tr>
<tr><td><code>NOMOS_OTLP_METRICS_ENDPOINT</code></td><td>—</td><td>OTLP metrics endpoint (optional)</td></tr>
</tbody></table>
</div>
<p><strong>Example:</strong></p>
<pre><code class="language-bash"># Enable Prometheus querying
export NOMOS_METRICS_QUERY_URL=http://localhost:9090
export NOMOS_METRICS_OTLP_INGEST_URL=http://localhost:9090/api/v1/otlp/v1/metrics
export NOMOS_GRAFANA_URL=http://localhost:3000
scripts/run/run-examples.sh -t 60 -v 3 -e 1 compose
</code></pre>
<hr />
<h2 id="compose-runner-specific"><a class="header" href="#compose-runner-specific">Compose Runner Specific</a></h2>
<p>Variables specific to Docker Compose deployment:</p>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Default</th><th>Effect</th></tr></thead><tbody>
<tr><td><code>COMPOSE_RUNNER_HOST</code></td><td><code>127.0.0.1</code></td><td>Host address for port mappings</td></tr>
<tr><td><code>COMPOSE_RUNNER_PRESERVE</code></td><td>0</td><td>Keep containers running after test (for debugging)</td></tr>
<tr><td><code>COMPOSE_RUNNER_HTTP_TIMEOUT_SECS</code></td><td>—</td><td>Override HTTP readiness timeout (seconds)</td></tr>
<tr><td><code>COMPOSE_RUNNER_HOST_GATEWAY</code></td><td><code>host.docker.internal:host-gateway</code></td><td>Controls <code>extra_hosts</code> entry injected into compose (set to <code>disable</code> to omit)</td></tr>
<tr><td><code>TESTNET_RUNNER_PRESERVE</code></td><td>—</td><td>Alias for <code>COMPOSE_RUNNER_PRESERVE</code></td></tr>
</tbody></table>
</div>
<p><strong>Example:</strong></p>
<pre><code class="language-bash"># Keep containers after test for debugging
COMPOSE_RUNNER_PRESERVE=1 \
scripts/run/run-examples.sh -t 60 -v 3 -e 1 compose
# Containers remain running
docker ps --filter "name=nomos-compose-"
docker logs &lt;container-id&gt;
</code></pre>
<hr />
<h2 id="k8s-runner-specific"><a class="header" href="#k8s-runner-specific">K8s Runner Specific</a></h2>
<p>Variables specific to Kubernetes deployment:</p>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Default</th><th>Effect</th></tr></thead><tbody>
<tr><td><code>K8S_RUNNER_NAMESPACE</code></td><td>Random UUID</td><td>Kubernetes namespace (pin for debugging)</td></tr>
<tr><td><code>K8S_RUNNER_RELEASE</code></td><td>Random UUID</td><td>Helm release name (pin for debugging)</td></tr>
<tr><td><code>K8S_RUNNER_NODE_HOST</code></td><td>—</td><td>NodePort host resolution for non-local clusters</td></tr>
<tr><td><code>K8S_RUNNER_DEBUG</code></td><td>0</td><td>Log Helm stdout/stderr for install commands</td></tr>
<tr><td><code>K8S_RUNNER_PRESERVE</code></td><td>0</td><td>Keep namespace/release after run (for debugging)</td></tr>
<tr><td><code>K8S_RUNNER_DEPLOYMENT_TIMEOUT_SECS</code></td><td>—</td><td>Override deployment readiness timeout</td></tr>
<tr><td><code>K8S_RUNNER_HTTP_TIMEOUT_SECS</code></td><td>—</td><td>Override HTTP readiness timeout (port-forwards)</td></tr>
<tr><td><code>K8S_RUNNER_HTTP_PROBE_TIMEOUT_SECS</code></td><td>—</td><td>Override HTTP readiness timeout (NodePort probes)</td></tr>
<tr><td><code>K8S_RUNNER_PROMETHEUS_HTTP_TIMEOUT_SECS</code></td><td>—</td><td>Override Prometheus readiness timeout</td></tr>
<tr><td><code>K8S_RUNNER_PROMETHEUS_HTTP_PROBE_TIMEOUT_SECS</code></td><td>—</td><td>Override Prometheus NodePort probe timeout</td></tr>
</tbody></table>
</div>
<p><strong>Example:</strong></p>
<pre><code class="language-bash"># Pin namespace for debugging
K8S_RUNNER_NAMESPACE=nomos-test-debug \
K8S_RUNNER_PRESERVE=1 \
K8S_RUNNER_DEBUG=1 \
scripts/run/run-examples.sh -t 60 -v 3 -e 1 k8s
# Inspect resources
kubectl get pods -n nomos-test-debug
kubectl logs -n nomos-test-debug -l nomos/logical-role=validator
</code></pre>
<hr />
<h2 id="platform--build-configuration"><a class="header" href="#platform--build-configuration">Platform &amp; Build Configuration</a></h2>
<p>Platform-specific build configuration:</p>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Default</th><th>Effect</th></tr></thead><tbody>
<tr><td><code>NOMOS_BUNDLE_DOCKER_PLATFORM</code></td><td>Host arch</td><td>Docker platform for bundle builds: <code>linux/arm64</code> or <code>linux/amd64</code> (macOS/Windows hosts)</td></tr>
<tr><td><code>NOMOS_BIN_PLATFORM</code></td><td>—</td><td>Legacy alias for <code>NOMOS_BUNDLE_DOCKER_PLATFORM</code></td></tr>
<tr><td><code>COMPOSE_CIRCUITS_PLATFORM</code></td><td>Host arch</td><td>Circuits platform for image builds: <code>linux-aarch64</code> or <code>linux-x86_64</code></td></tr>
<tr><td><code>NOMOS_EXTRA_FEATURES</code></td><td>—</td><td>Extra cargo features to enable when building bundles (used by <code>scripts/build/build-bundle.sh</code>)</td></tr>
</tbody></table>
</div>
<p><strong>macOS / Apple Silicon:</strong></p>
<pre><code class="language-bash"># Native performance (recommended for local testing)
export NOMOS_BUNDLE_DOCKER_PLATFORM=linux/arm64
# Or target amd64 (slower via emulation)
export NOMOS_BUNDLE_DOCKER_PLATFORM=linux/amd64
</code></pre>
<hr />
<h2 id="timeouts--performance"><a class="header" href="#timeouts--performance">Timeouts &amp; Performance</a></h2>
<p>Timeout and performance tuning:</p>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Default</th><th>Effect</th></tr></thead><tbody>
<tr><td><code>SLOW_TEST_ENV</code></td><td>false</td><td>Doubles built-in readiness timeouts (useful in CI / constrained laptops)</td></tr>
<tr><td><code>TESTNET_PRINT_ENDPOINTS</code></td><td>0</td><td>Print <code>TESTNET_ENDPOINTS</code> / <code>TESTNET_PPROF</code> lines during deploy (set automatically by <code>scripts/run/run-examples.sh</code>)</td></tr>
<tr><td><code>NOMOS_DISPERSAL_TIMEOUT_SECS</code></td><td>20</td><td>DA dispersal timeout (seconds)</td></tr>
<tr><td><code>NOMOS_RETRY_COOLDOWN_SECS</code></td><td>3</td><td>Cooldown between retries (seconds)</td></tr>
<tr><td><code>NOMOS_GRACE_PERIOD_SECS</code></td><td>1200</td><td>Grace period before enforcing strict time-based expectations (seconds)</td></tr>
<tr><td><code>NOMOS_PRUNE_DURATION_SECS</code></td><td>30</td><td>Prune step duration (seconds)</td></tr>
<tr><td><code>NOMOS_PRUNE_INTERVAL_SECS</code></td><td>5</td><td>Interval between prune cycles (seconds)</td></tr>
<tr><td><code>NOMOS_SHARE_DURATION_SECS</code></td><td>5</td><td>Share duration (seconds)</td></tr>
<tr><td><code>NOMOS_COMMITMENTS_WAIT_SECS</code></td><td>1</td><td>Commitments wait duration (seconds)</td></tr>
<tr><td><code>NOMOS_SDP_TRIGGER_DELAY_SECS</code></td><td>5</td><td>SDP trigger delay (seconds)</td></tr>
</tbody></table>
</div>
<p><strong>Example:</strong></p>
<pre><code class="language-bash"># Increase timeouts for slow environments
SLOW_TEST_ENV=true \
scripts/run/run-examples.sh -t 120 -v 5 -e 2 compose
</code></pre>
<hr />
<h2 id="node-configuration-advanced"><a class="header" href="#node-configuration-advanced">Node Configuration (Advanced)</a></h2>
<p>Node-level configuration passed through to nomos-node/nomos-executor:</p>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Default</th><th>Effect</th></tr></thead><tbody>
<tr><td><code>CONSENSUS_SLOT_TIME</code></td><td>—</td><td>Consensus slot time (seconds)</td></tr>
<tr><td><code>CONSENSUS_ACTIVE_SLOT_COEFF</code></td><td>—</td><td>Active slot coefficient (0.0-1.0)</td></tr>
<tr><td><code>NOMOS_USE_AUTONAT</code></td><td>Unset</td><td>If set, use AutoNAT instead of a static loopback address for libp2p NAT settings</td></tr>
<tr><td><code>NOMOS_CFGSYNC_PORT</code></td><td>4400</td><td>Port used for cfgsync service inside the stack</td></tr>
<tr><td><code>NOMOS_TIME_BACKEND</code></td><td><code>monotonic</code></td><td>Select time backend (used by compose/k8s stack scripts and deployers)</td></tr>
</tbody></table>
</div>
<p><strong>Example:</strong></p>
<pre><code class="language-bash"># Faster block production
CONSENSUS_SLOT_TIME=5 \
CONSENSUS_ACTIVE_SLOT_COEFF=0.9 \
POL_PROOF_DEV_MODE=true \
cargo run -p runner-examples --bin local_runner
</code></pre>
<hr />
<h2 id="framework-runner-logging-not-node-logs"><a class="header" href="#framework-runner-logging-not-node-logs">Framework Runner Logging (Not Node Logs)</a></h2>
<p>Control framework runner process logs (uses <code>RUST_LOG</code>, not <code>NOMOS_*</code>):</p>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Default</th><th>Effect</th></tr></thead><tbody>
<tr><td><code>RUST_LOG</code></td><td>—</td><td>Framework runner log level (e.g., <code>debug</code>, <code>info</code>)</td></tr>
<tr><td><code>RUST_BACKTRACE</code></td><td>—</td><td>Enable Rust backtraces on panic (<code>1</code> or <code>full</code>)</td></tr>
<tr><td><code>CARGO_TERM_COLOR</code></td><td>—</td><td>Cargo output color (<code>always</code>, <code>never</code>, <code>auto</code>)</td></tr>
</tbody></table>
</div>
<p><strong>Example:</strong></p>
<pre><code class="language-bash"># Debug framework runner (not nodes)
RUST_LOG=debug \
RUST_BACKTRACE=1 \
cargo run -p runner-examples --bin local_runner
</code></pre>
<hr />
<h2 id="helper-script-variables"><a class="header" href="#helper-script-variables">Helper Script Variables</a></h2>
<p>Variables used by helper scripts (<code>scripts/run/run-examples.sh</code>, etc.):</p>
<div class="table-wrapper"><table><thead><tr><th>Variable</th><th>Default</th><th>Effect</th></tr></thead><tbody>
<tr><td><code>NOMOS_NODE_REV</code></td><td>From <code>versions.env</code></td><td>nomos-node git revision to build/fetch</td></tr>
<tr><td><code>NOMOS_BUNDLE_VERSION</code></td><td>From <code>versions.env</code></td><td>Bundle schema version</td></tr>
<tr><td><code>NOMOS_IMAGE_SELECTION</code></td><td>—</td><td>Internal: image selection mode set by <code>run-examples.sh</code> (<code>local</code>/<code>ecr</code>/<code>auto</code>)</td></tr>
<tr><td><code>NOMOS_NODE_APPLY_PATCHES</code></td><td>1</td><td>Set to <code>0</code> to disable applying local patches when building bundles</td></tr>
<tr><td><code>NOMOS_NODE_PATCH_DIR</code></td><td><code>patches/nomos-node</code></td><td>Patch directory applied to nomos-node checkout during bundle builds</td></tr>
<tr><td><code>NOMOS_NODE_PATCH_LEVEL</code></td><td>—</td><td>Patch application level (<code>all</code> or an integer) for bundle builds</td></tr>
</tbody></table>
</div>
<hr />
<h2 id="quick-reference-examples"><a class="header" href="#quick-reference-examples">Quick Reference Examples</a></h2>
<h3 id="minimal-host-run"><a class="header" href="#minimal-host-run">Minimal Host Run</a></h3>
<pre><code class="language-bash">POL_PROOF_DEV_MODE=true \
scripts/run/run-examples.sh -t 60 -v 3 -e 1 host
</code></pre>
<h3 id="debug-logging-host"><a class="header" href="#debug-logging-host">Debug Logging (Host)</a></h3>
<pre><code class="language-bash">POL_PROOF_DEV_MODE=true \
NOMOS_LOG_DIR=/tmp/logs \
NOMOS_LOG_LEVEL=debug \
NOMOS_LOG_FILTER="cryptarchia=trace" \
scripts/run/run-examples.sh -t 60 -v 3 -e 1 host
</code></pre>
<h3 id="compose-with-observability"><a class="header" href="#compose-with-observability">Compose with Observability</a></h3>
<pre><code class="language-bash">POL_PROOF_DEV_MODE=true \
NOMOS_METRICS_QUERY_URL=http://localhost:9090 \
NOMOS_GRAFANA_URL=http://localhost:3000 \
scripts/run/run-examples.sh -t 60 -v 3 -e 1 compose
</code></pre>
<h3 id="k8s-with-debug"><a class="header" href="#k8s-with-debug">K8s with Debug</a></h3>
<pre><code class="language-bash">POL_PROOF_DEV_MODE=true \
K8S_RUNNER_NAMESPACE=nomos-debug \
K8S_RUNNER_DEBUG=1 \
K8S_RUNNER_PRESERVE=1 \
scripts/run/run-examples.sh -t 60 -v 3 -e 1 k8s
</code></pre>
<h3 id="ci-environment"><a class="header" href="#ci-environment">CI Environment</a></h3>
<pre><code class="language-yaml">env:
POL_PROOF_DEV_MODE: true
RUST_BACKTRACE: 1
NOMOS_TESTS_KEEP_LOGS: 1
</code></pre>
<hr />
<h2 id="see-also"><a class="header" href="#see-also">See Also</a></h2>
<ul>
<li><a href="prerequisites.html">Prerequisites &amp; Setup</a> — Required files and setup</li>
<li><a href="running-examples.html">Running Examples</a> — How to run scenarios</li>
<li><a href="logging-observability.html">Logging &amp; Observability</a> — Log collection details</li>
<li><a href="ci-integration.html">CI Integration</a> — CI-specific variables</li>
<li><a href="troubleshooting.html">Troubleshooting</a> — Common issues with variables</li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="ci-integration.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="logging-observability.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="ci-integration.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="logging-observability.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js"></script>
<script src="mark.min.js"></script>
<script src="searcher.js"></script>
<script src="clipboard.min.js"></script>
<script src="highlight.js"></script>
<script src="book.js"></script>
<!-- Custom JS scripts -->
<script src="theme/mermaid-init.js"></script>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink