build.zig

const std = @import("std");
const builtin = @import("builtin");
const Builder = std.Build;

const zkvmTarget = struct {
    name: []const u8,
    set_pie: bool = false,
    triplet: []const u8,
    cpu_features: []const u8,
};

const zkvm_targets: []const zkvmTarget = &.{
    .{ .name = "risc0", .triplet = "riscv32-freestanding-none", .cpu_features = "generic_rv32" },
    .{ .name = "sp1", .triplet = "riscv32-freestanding-none", .cpu_features = "generic_rv32" },
    .{ .name = "zisk", .set_pie = true, .triplet = "riscv64-freestanding-none", .cpu_features = "generic_rv64" },
    .{ .name = "openvm", .triplet = "riscv32-freestanding-none", .cpu_features = "generic_rv32" },
    .{ .name = "ziren", .triplet = "mipsel-freestanding-none", .cpu_features = "mips32r2" },
};

const ProverChoice = enum { dummy, risc0, openvm, all };

fn setTestRunLabel(b: *Builder, run_step: *std.Build.Step.Run, name: []const u8) void {
    run_step.step.name = b.fmt("test {s}", .{name});
}

fn setTestRunLabelFromCompile(b: *Builder, run_step: *std.Build.Step.Run, compile_step: *std.Build.Step.Compile) void {
    const source_name = if (compile_step.root_module.root_source_file) |root_source|
        root_source.getDisplayName()
    else
        compile_step.step.name;
    setTestRunLabel(b, run_step, source_name);
}

fn defaultSimpleTestRunner(b: *Builder) std.Build.Step.Compile.TestRunner {
    const test_runner_path = b.graph.zig_lib_directory.join(b.allocator, &.{ "compiler", "test_runner.zig" }) catch @panic("OOM");
    return .{
        .path = .{ .cwd_relative = test_runner_path },
        .mode = .simple,
    };
}

// Add the glue libs to a compile target.
//
// Every per-prover Rust crate is funnelled through a single `zeam-glue`
// `staticlib` shim so that Rust's allocator shim
// (`__rust_alloc`, `__rust_dealloc`, `__rust_realloc`, `__rust_alloc_zeroed`)
// is emitted exactly once. When multiple Rust staticlibs were linked together
// directly, `ld64` on macOS rejected the duplicate strong definitions and the
// `build-all-provers` job broke on any fresh (cache-miss) rebuild.
fn addRustGlueLib(b: *Builder, comp: *Builder.Step.Compile, target: Builder.ResolvedTarget, prover: ProverChoice) void {
    const glue_path = switch (prover) {
        // `.dummy` uses the dedicated multisig-only Cargo profile (ThinLTO,
        // codegen-units=1) to give the leanMultisig prover the same level of
        // cross-crate inlining that single-prover builds already get.
        .dummy => "rust/target/multisig-release/libzeam_glue.a",
        .all => "rust/target/release/libzeam_glue.a",
        .risc0 => "rust/target/risc0-release/libzeam_glue.a",
        .openvm => "rust/target/openvm-release/libzeam_glue.a",
    };
    comp.root_module.addObjectFile(b.path(glue_path));
    comp.root_module.link_libc = true;
    comp.root_module.linkSystemLibrary("unwind", .{});
    if (target.result.os.tag == .macos) {
        comp.root_module.linkFramework("CoreFoundation", .{});
        comp.root_module.linkFramework("SystemConfiguration", .{});
        comp.root_module.linkFramework("Security", .{});
    }
}

pub fn build(b: *Builder) !void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});
    const simple_test_runner = defaultSimpleTestRunner(b);

    // Get git commit hash as version
    const git_version = b.option([]const u8, "git_version", "Git commit hash for version") orelse "unknown";

    // Get prover choice (default to dummy)
    const prover_option = b.option([]const u8, "prover", "Choose prover: dummy, risc0, openvm, or all (default: dummy)") orelse "dummy";
    const prover = std.meta.stringToEnum(ProverChoice, prover_option) orelse .dummy;

    // Drop the jemalloc global allocator and use the system allocator. Needed
    // for the Shadow network simulator: its preload shim re-enters malloc during
    // its own first-syscall init while jemalloc holds its non-recursive init
    // lock, which self-deadlocks (shadow/shadow#3763).
    const no_jemalloc = b.option(bool, "no-jemalloc", "Disable the jemalloc global allocator (use the system allocator). Required under the Shadow simulator, whose shim deadlocks with jemalloc's init.") orelse false;

    const build_rust_lib_steps = build_rust_project(b, "rust", prover, no_jemalloc);

    // LTO option (disabled by default for faster builds)
    const enable_lto = b.option(bool, "lto", "Enable Link Time Optimization (slower builds, smaller binaries)") orelse false;

    // ThreadSanitizer for the `zeam` cli exe (debug data-race hunting, e.g. node3 sync).
    const enable_tsan = b.option(bool, "tsan", "Build the zeam cli with ThreadSanitizer") orelse false;

    // add ssz
    const ssz = b.dependency("ssz", .{
        .target = target,
        .optimize = optimize,
    }).module("ssz.zig");
    const simargs = b.dependency("zigcli", .{
        .target = target,
        .optimize = optimize,
    }).module("zigcli");
    const xev = b.dependency("xev", .{
        .target = target,
        .optimize = optimize,
    }).module("xev");
    const metrics = b.dependency("metrics", .{
        .target = target,
        .optimize = optimize,
    }).module("metrics");

    const datetime = b.dependency("datetime", .{
        .target = target,
        .optimize = optimize,
    }).module("datetime");

    const enr_dep = b.dependency("zig_enr", .{
        .target = target,
        .optimize = optimize,
    });
    const enr = enr_dep.module("zig-enr");

    const multiformats = enr_dep.builder.dependency("zmultiformats", .{
        .target = target,
        .optimize = optimize,
    }).module("multiformats-zig");

    const multiaddr_mod = enr_dep.builder.dependency("multiaddr", .{
        .target = target,
        .optimize = optimize,
    }).module("multiaddr");

    const yaml = b.dependency("zig_yaml", .{
        .target = target,
        .optimize = optimize,
    }).module("yaml");

    // add rocksdb
    const rocksdb = b.dependency("rocksdb", .{
        .target = target,
        .optimize = optimize,
    }).module("bindings");

    // add lmdb (external dep: github.com/blockblaz/lmdb-zig)
    const lmdb = b.dependency("lmdb", .{
        .target = target,
        .optimize = optimize,
    }).module("lmdb");

    // add snappyz
    const snappyz = b.dependency("zig_snappy", .{
        .target = target,
        .optimize = optimize,
    }).module("snappyz");

    const snappyframesz_dep = b.dependency("snappyframesz", .{
        .target = target,
        .optimize = optimize,
    });
    const snappyframesz = snappyframesz_dep.module("snappyframesz.zig");

    // Create build options early so modules can use them
    const build_options = b.addOptions();
    build_options.addOption([]const u8, "version", git_version);
    build_options.addOption([]const u8, "prover", @tagName(prover));
    build_options.addOption(bool, "has_risc0", prover == .risc0 or prover == .all);
    build_options.addOption(bool, "has_openvm", prover == .openvm or prover == .all);
    // Optional parallel ethp2p RS-broadcast transport (off by default). When
    // false the adapter selector picks a stub and `zig_ethp2p` is never
    // imported, so the default binary is unchanged.
    const ethp2p_enabled = b.option(bool, "ethp2p", "Compile in the experimental ethp2p parallel RS-broadcast transport (default: false)") orelse false;
    build_options.addOption(bool, "ethp2p", ethp2p_enabled);
    // Absolute path to test-keys for pre-generated validator keys
    build_options.addOption([]const u8, "test_keys_path", b.pathFromRoot("test-keys/hash-sig-keys"));
    // Optional slot-time override, for tests/sims that need a wider slot than the preset's.
    const seconds_per_slot_override = b.option(u64, "seconds-per-slot", "Override SECONDS_PER_SLOT (test/sim only; default = preset 4s)");
    build_options.addOption(?u64, "seconds_per_slot_override", seconds_per_slot_override);
    const build_options_module = build_options.createModule();

    // add zeam-utils
    const zeam_utils = b.addModule("@zeam/utils", .{
        .target = target,
        .optimize = optimize,
        .root_source_file = b.path("pkgs/utils/src/lib.zig"),
    });
    zeam_utils.addImport("datetime", datetime);
    zeam_utils.addImport("yaml", yaml);
    zeam_utils.addImport("ssz", ssz);
    zeam_utils.addImport("build_options", build_options_module);
    // add zeam-params
    const zeam_params = b.addModule("@zeam/params", .{
        .target = target,
        .optimize = optimize,
        .root_source_file = b.path("pkgs/params/src/lib.zig"),
    });
    zeam_params.addImport("build_options", build_options_module);

    // add zeam-metrics (core metrics definitions)
    const zeam_metrics = b.addModule("@zeam/metrics", .{
        .root_source_file = b.path("pkgs/metrics/src/lib.zig"),
        .target = target,
        .optimize = optimize,
    });
    zeam_metrics.addImport("metrics", metrics);

    // add zeam-thread-pool (work-stealing thread pool, zero dependencies)
    const thread_pool_dep = b.dependency("thread_pool", .{
        .target = target,
        .optimize = optimize,
    });
    const zeam_thread_pool = thread_pool_dep.module("thread-pool");

    // add zeam-xmss
    const zeam_xmss = b.addModule("@zeam/xmss", .{
        .root_source_file = b.path("pkgs/xmss/src/lib.zig"),
        .target = target,
        .optimize = optimize,
    });
    zeam_xmss.link_libc = true; // shadow_cost reads env via libc getenv
    zeam_xmss.addImport("ssz", ssz);
    zeam_xmss.addImport("@zeam/metrics", zeam_metrics);
    zeam_xmss.addImport("@zeam/utils", zeam_utils);

    // add zeam-types
    const zeam_types = b.addModule("@zeam/types", .{
        .root_source_file = b.path("pkgs/types/src/lib.zig"),
        .target = target,
        .optimize = optimize,
    });
    zeam_types.addImport("ssz", ssz);
    zeam_types.addImport("@zeam/params", zeam_params);
    zeam_types.addImport("@zeam/utils", zeam_utils);
    zeam_types.addImport("@zeam/metrics", zeam_metrics);
    zeam_types.addImport("@zeam/xmss", zeam_xmss);
    zeam_types.addImport("@zeam/thread-pool", zeam_thread_pool);

    // add zeam-types
    const zeam_configs = b.addModule("@zeam/configs", .{
        .root_source_file = b.path("pkgs/configs/src/lib.zig"),
        .target = target,
        .optimize = optimize,
    });
    zeam_configs.addImport("@zeam/utils", zeam_utils);
    zeam_configs.addImport("@zeam/types", zeam_types);
    zeam_configs.addImport("@zeam/params", zeam_params);
    zeam_configs.addImport("yaml", yaml);

    // add zeam-api (HTTP serving and events)
    const zeam_api = b.addModule("@zeam/api", .{
        .root_source_file = b.path("pkgs/api/src/lib.zig"),
        .target = target,
        .optimize = optimize,
    });
    zeam_api.addImport("@zeam/metrics", zeam_metrics);
    zeam_api.addImport("@zeam/types", zeam_types);
    zeam_api.addImport("@zeam/utils", zeam_utils);

    // add zeam-key-manager
    const zeam_key_manager = b.addModule("@zeam/key-manager", .{
        .root_source_file = b.path("pkgs/key-manager/src/lib.zig"),
        .target = target,
        .optimize = optimize,
    });
    zeam_key_manager.addImport("build_options", build_options_module);
    zeam_key_manager.addImport("@zeam/xmss", zeam_xmss);
    zeam_key_manager.addImport("@zeam/types", zeam_types);
    zeam_key_manager.addImport("@zeam/utils", zeam_utils);
    zeam_key_manager.addImport("@zeam/metrics", zeam_metrics);
    zeam_key_manager.addImport("ssz", ssz);

    // add zeam-state-transition
    const zeam_state_transition = b.addModule("@zeam/state-transition", .{
        .root_source_file = b.path("pkgs/state-transition/src/lib.zig"),
        .target = target,
        .optimize = optimize,
    });
    zeam_state_transition.addImport("@zeam/utils", zeam_utils);
    zeam_state_transition.addImport("@zeam/params", zeam_params);
    zeam_state_transition.addImport("@zeam/types", zeam_types);
    zeam_state_transition.addImport("ssz", ssz);
    zeam_state_transition.addImport("@zeam/api", zeam_api);
    zeam_state_transition.addImport("@zeam/xmss", zeam_xmss);
    zeam_state_transition.addImport("@zeam/key-manager", zeam_key_manager);
    zeam_state_transition.addImport("@zeam/metrics", zeam_metrics);
    // Used only by the host-side benchmark test; zkVM builds instantiate their own
    // state-transition module further below without this import.
    zeam_state_transition.addImport("@zeam/thread-pool", zeam_thread_pool);

    // add state proving manager
    const zeam_state_proving_manager = b.addModule("@zeam/state-proving-manager", .{
        .root_source_file = b.path("pkgs/state-proving-manager/src/manager.zig"),
        .target = target,
        .optimize = optimize,
    });
    zeam_state_proving_manager.addImport("@zeam/types", zeam_types);
    zeam_state_proving_manager.addImport("@zeam/utils", zeam_utils);
    zeam_state_proving_manager.addImport("@zeam/state-transition", zeam_state_transition);
    zeam_state_proving_manager.addImport("ssz", ssz);
    zeam_state_proving_manager.addImport("build_options", build_options_module);

    const st_module = b.createModule(.{
        .root_source_file = b.path("pkgs/state-transition/src/lib.zig"),
        .target = target,
        .optimize = optimize,
    });
    const st_lib = b.addLibrary(.{
        .name = "zeam-state-transition",
        .root_module = st_module,
        .linkage = .static,
    });
    b.installArtifact(st_lib);

    // add zeam-database
    const zeam_database = b.addModule("@zeam/database", .{
        .target = target,
        .optimize = optimize,
        .root_source_file = b.path("pkgs/database/src/lib.zig"),
    });
    zeam_database.addImport("rocksdb", rocksdb);
    zeam_database.addImport("lmdb", lmdb);
    zeam_database.addImport("ssz", ssz);
    zeam_database.addImport("@zeam/utils", zeam_utils);
    zeam_database.addImport("@zeam/types", zeam_types);

    // add network
    const zeam_network = b.addModule("@zeam/network", .{
        .target = target,
        .optimize = optimize,
        .root_source_file = b.path("pkgs/network/src/lib.zig"),
    });
    zeam_network.addImport("@zeam/types", zeam_types);
    zeam_network.addImport("@zeam/utils", zeam_utils);
    zeam_network.addImport("@zeam/params", zeam_params);
    zeam_network.addImport("xev", xev);
    zeam_network.addImport("ssz", ssz);
    zeam_network.addImport("multiformats", multiformats);
    zeam_network.addImport("multiaddr", multiaddr_mod);
    zeam_network.addImport("snappyframesz", snappyframesz);
    zeam_network.addImport("snappyz", snappyz);
    zeam_network.addImport("@zeam/metrics", zeam_metrics);

    // zig-libp2p — pure-Zig libp2p stack. The legacy `ethlibp2p.zig`
    // / `rust/libp2p-glue/` path was deleted; this is the only libp2p
    // implementation now. `ethlibp2p.zig` consumes it via
    // `@import("zig_libp2p")`.
    const zig_libp2p_dep = b.dependency("zig_libp2p", .{
        .target = target,
        .optimize = optimize,
    });
    zeam_network.addImport("zig_libp2p", zig_libp2p_dep.module("zig_libp2p"));

    // Optional ethp2p RS-broadcast transport. Only realize (fetch + import)
    // the lazy `zig_ethp2p` dependency under `-Dethp2p=true`; otherwise the
    // adapter selector compiles a stub that never imports it. (`build_options`
    // is imported into `zeam_network` just below.)
    if (ethp2p_enabled) {
        if (b.lazyDependency("zig_ethp2p", .{ .target = target, .optimize = optimize })) |dep| {
            zeam_network.addImport("zig_ethp2p", dep.module("zig_ethp2p"));
        }
    }

    // The publish-side forensic log line in v2 includes the build git SHA
    // so receivers across the fleet can correlate
    // broken-byte receipts back to the exact producer binary.
    zeam_network.addImport("build_options", build_options_module);

    // add beam node
    const zeam_beam_node = b.addModule("@zeam/node", .{
        .target = target,
        .optimize = optimize,
        .root_source_file = b.path("pkgs/node/src/lib.zig"),
    });
    zeam_beam_node.addImport("xev", xev);
    zeam_beam_node.addImport("ssz", ssz);
    zeam_beam_node.addImport("@zeam/utils", zeam_utils);
    zeam_beam_node.addImport("@zeam/params", zeam_params);
    zeam_beam_node.addImport("@zeam/types", zeam_types);
    zeam_beam_node.addImport("@zeam/configs", zeam_configs);
    zeam_beam_node.addImport("@zeam/state-transition", zeam_state_transition);
    zeam_beam_node.addImport("@zeam/network", zeam_network);
    zeam_beam_node.addImport("@zeam/database", zeam_database);
    zeam_beam_node.addImport("@zeam/metrics", zeam_metrics);
    zeam_beam_node.addImport("@zeam/api", zeam_api);
    zeam_beam_node.addImport("@zeam/key-manager", zeam_key_manager);
    zeam_beam_node.addImport("@zeam/xmss", zeam_xmss);
    zeam_beam_node.addImport("@zeam/thread-pool", zeam_thread_pool);

    const zeam_spectests = b.addModule("zeam_spectests", .{
        .target = target,
        .optimize = optimize,
        .root_source_file = b.path("pkgs/spectest/src/lib.zig"),
    });
    zeam_spectests.addImport("@zeam/utils", zeam_utils);
    zeam_spectests.addImport("@zeam/types", zeam_types);
    zeam_spectests.addImport("@zeam/configs", zeam_configs);
    zeam_spectests.addImport("@zeam/params", zeam_params);
    zeam_spectests.addImport("@zeam/key-manager", zeam_key_manager);
    zeam_spectests.addImport("ssz", ssz);
    zeam_spectests.addImport("build_options", build_options_module);
    zeam_spectests.addImport("@zeam/state-transition", zeam_state_transition);
    zeam_spectests.addImport("@zeam/node", zeam_beam_node);
    zeam_spectests.addImport("@zeam/xmss", zeam_xmss);
    zeam_spectests.addImport("@zeam/network", zeam_network);
    zeam_spectests.addImport("snappyz", snappyz);
    zeam_spectests.addImport("snappyframesz", snappyframesz);

    // ThreadSanitizer: instrument the Zig modules involved in the multi-threaded
    // beam runtime (chain-worker / libxev / rust-bridge thread interplay) so a
    // data race in the node-3 sync path is reported with both stacks.
    if (enable_tsan) {
        for ([_]*std.Build.Module{
            zeam_utils,
            zeam_params,
            zeam_metrics,
            zeam_types,
            zeam_configs,
            zeam_database,
            zeam_state_transition,
            zeam_network,
            zeam_beam_node,
            zeam_api,
            zeam_key_manager,
            zeam_xmss,
        }) |m| m.sanitize_thread = true;
    }

    // Add the cli executable
    const cli_exe = b.addExecutable(.{
        .name = "zeam",
        .root_module = b.createModule(.{
            .root_source_file = b.path("pkgs/cli/src/main.zig"),
            .target = target,
            .optimize = optimize,
            .sanitize_thread = if (enable_tsan) true else null,
        }),
    });

    // Enable LTO if requested and on Linux (disabled by default for faster builds)
    // Always disabled on macOS due to linker issues with Rust static libraries
    // (LTO requires LLD but macOS uses its own linker by default)
    if (enable_lto and target.result.os.tag == .linux) {
        cli_exe.lto = .full;
    }

    // addimport to root module is even required afer declaring it in mod
    cli_exe.root_module.addImport("ssz", ssz);
    cli_exe.root_module.addImport("build_options", build_options_module);
    cli_exe.root_module.addImport("simargs", simargs);
    cli_exe.root_module.addImport("xev", xev);
    cli_exe.root_module.addImport("@zeam/database", zeam_database);
    cli_exe.root_module.addImport("@zeam/utils", zeam_utils);
    cli_exe.root_module.addImport("@zeam/params", zeam_params);
    cli_exe.root_module.addImport("@zeam/types", zeam_types);
    cli_exe.root_module.addImport("@zeam/configs", zeam_configs);
    cli_exe.root_module.addImport("@zeam/metrics", zeam_metrics);
    cli_exe.root_module.addImport("@zeam/state-transition", zeam_state_transition);
    cli_exe.root_module.addImport("@zeam/state-proving-manager", zeam_state_proving_manager);
    cli_exe.root_module.addImport("@zeam/network", zeam_network);
    cli_exe.root_module.addImport("@zeam/node", zeam_beam_node);
    cli_exe.root_module.addImport("@zeam/api", zeam_api);
    cli_exe.root_module.addImport("@zeam/xmss", zeam_xmss);
    cli_exe.root_module.addImport("@zeam/thread-pool", zeam_thread_pool);
    cli_exe.root_module.addImport("metrics", metrics);
    cli_exe.root_module.addImport("multiformats", multiformats);
    cli_exe.root_module.addImport("multiaddr", multiaddr_mod);
    cli_exe.root_module.addImport("enr", enr);
    cli_exe.root_module.addImport("yaml", yaml);
    cli_exe.root_module.addImport("@zeam/key-manager", zeam_key_manager);

    cli_exe.step.dependOn(&build_rust_lib_steps.step);
    addRustGlueLib(b, cli_exe, target, prover);
    cli_exe.root_module.link_libc = true; // for rust static libs to link
    cli_exe.root_module.link_libcpp = true; // for rocksdb C++ library to link
    cli_exe.root_module.linkSystemLibrary("unwind", .{}); // to be able to display rust backtraces

    b.installArtifact(cli_exe);

    try build_zkvm_targets(b, &cli_exe.step, target, build_options_module);

    const run_prover = b.addRunArtifact(cli_exe);
    const prover_step = b.step("run", "Run cli executable");
    prover_step.dependOn(&run_prover.step);
    if (b.args) |args| {
        run_prover.addArgs(args);
    } else {
        run_prover.addArgs(&[_][]const u8{"prove"});
        run_prover.addArgs(&[_][]const u8{ "-d", b.fmt("{s}/bin", .{b.install_path}) });
    }

    const tools_step = b.step("tools", "Build zeam tools");

    const tools_cli_exe = b.addExecutable(.{
        .name = "zeam-tools",
        .root_module = b.createModule(.{
            .target = target,
            .optimize = optimize,
            .root_source_file = b.path("pkgs/tools/src/main.zig"),
        }),
    });
    tools_cli_exe.root_module.addImport("enr", enr);
    tools_cli_exe.root_module.addImport("build_options", build_options_module);
    tools_cli_exe.root_module.addImport("simargs", simargs);
    tools_cli_exe.root_module.addImport("@zeam/xmss", zeam_xmss);
    tools_cli_exe.root_module.addImport("@zeam/types", zeam_types);
    tools_cli_exe.step.dependOn(&build_rust_lib_steps.step);
    addRustGlueLib(b, tools_cli_exe, target, prover);

    const install_tools_cli = b.addInstallArtifact(tools_cli_exe, .{});
    tools_step.dependOn(&install_tools_cli.step);

    const all_step = b.step("all", "Build all executables and tools");
    all_step.dependOn(&cli_exe.step);
    all_step.dependOn(tools_step);

    const test_step = b.step("test", "Run zeam core tests");

    // ---------------------------------------------------------------
    // Single-node ingestion stress harness.
    //
    // Run with `zig build stress` (or `zig build stress -Doptimize=Debug`).
    // Configurable via env vars:
    //   ZEAM_STRESS_DURATION_SECS  default 1800 (30 min, the full merge-gate run)
    //   ZEAM_STRESS_NUM_BLOCKS     default 6
    //   ZEAM_STRESS_GOSSIP_THREADS default 3
    //   ZEAM_STRESS_RPC_THREADS    default 4
    //   ZEAM_STRESS_ATTN_THREADS   default 2
    //   ZEAM_STRESS_BORROW_THREADS default 2
    //   ZEAM_STRESS_CACHE_THREADS  default 1
    //   ZEAM_STRESS_WATCHDOG_SECS  default 60
    // ---------------------------------------------------------------
    const stress_exe = b.addExecutable(.{
        .name = "zeam-stress",
        .root_module = b.createModule(.{
            .root_source_file = b.path("pkgs/node/src/stress.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });
    stress_exe.root_module.addImport("xev", xev);
    stress_exe.root_module.addImport("ssz", ssz);
    stress_exe.root_module.addImport("@zeam/utils", zeam_utils);
    stress_exe.root_module.addImport("@zeam/params", zeam_params);
    stress_exe.root_module.addImport("@zeam/types", zeam_types);
    stress_exe.root_module.addImport("@zeam/configs", zeam_configs);
    stress_exe.root_module.addImport("@zeam/state-transition", zeam_state_transition);
    stress_exe.root_module.addImport("@zeam/network", zeam_network);
    stress_exe.root_module.addImport("@zeam/database", zeam_database);
    stress_exe.root_module.addImport("@zeam/metrics", zeam_metrics);
    stress_exe.root_module.addImport("@zeam/api", zeam_api);
    stress_exe.root_module.addImport("@zeam/key-manager", zeam_key_manager);
    stress_exe.root_module.addImport("@zeam/xmss", zeam_xmss);
    stress_exe.root_module.addImport("@zeam/thread-pool", zeam_thread_pool);
    addRustGlueLib(b, stress_exe, target, prover);
    stress_exe.step.dependOn(&build_rust_lib_steps.step);
    const run_stress = b.addRunArtifact(stress_exe);
    if (b.args) |args| run_stress.addArgs(args);
    const stress_step = b.step("stress", "Run single-node ingestion stress harness");
    stress_step.dependOn(&run_stress.step);

    // -----------------------------------------------------------------
    // `stress-quick`: short-form stress harness wired into `zig build
    // test`. The full 30-min run is operator-driven; this 30s run is
    // what CI executes on every change so the ingestion merge gate
    // actually has automated enforcement, rather than relying on a
    // manual attestation. The quick run uses the same code paths as the
    // full run and will fail CI on:
    //   * any `MissingPreState` (states-map race),
    //   * any unexpected `chain.onBlock` error in gossip-flood,
    //   * any `recordFatal` from coherence checks (BlockCache,
    //     borrow-reader, watchdog),
    //   * worker error counters non-zero in the summary epilogue.
    // 30s is long enough for several thousand ops on each worker
    // without putting the test job over budget.
    //
    // Override knobs are intentionally NOT wired here — CI exercises
    // the same defaults a developer sees with `zig build stress-quick`,
    // which is the point.
    const run_stress_quick = b.addRunArtifact(stress_exe);
    run_stress_quick.setEnvironmentVariable("ZEAM_STRESS_DURATION_SECS", "30");
    run_stress_quick.setEnvironmentVariable("ZEAM_STRESS_WATCHDOG_SECS", "15");
    const stress_quick_step = b.step("stress-quick", "Run a 30s stress harness (CI gate)");
    stress_quick_step.dependOn(&run_stress_quick.step);
    test_step.dependOn(&run_stress_quick.step);

    const run_stress_locks_quick = b.addRunArtifact(stress_exe);
    run_stress_locks_quick.setEnvironmentVariable("ZEAM_STRESS_DURATION_SECS", "30");
    run_stress_locks_quick.setEnvironmentVariable("ZEAM_STRESS_WATCHDOG_SECS", "15");
    run_stress_locks_quick.setEnvironmentVariable("ZEAM_STRESS_SKIP_VERIFY", "1");
    const stress_locks_quick_step = b.step("stress-locks-quick", "Run a 30s stress harness without XMSS verification (CI gate, slice b)");
    stress_locks_quick_step.dependOn(&run_stress_locks_quick.step);
    test_step.dependOn(&run_stress_locks_quick.step);

    // -----------------------------------------------------------------
    // `stress-saturation` and `stress-quick-saturation`: chain-worker
    // queue saturation harness.
    //
    // The full `stress-saturation` step is operator-driven (~30s
    // default). The quick variant is wired into `zig build test` so
    // CI catches:
    //   * Producer-side accounting drift (attempts != ok+qfull+err).
    //   * Backpressure regression (queue never fills — either the
    //     producers are too slow or the queue capacity got bumped
    //     without a corresponding bump to producer count).
    //   * Worker-drain regression (queue fills but never drains —
    //     classic worker-thread deadlock).
    //   * Any unexpected `submitBlock` / `submitGossipAttestation`
    //     error tag (today only `QueueClosed` and
    //     `ChainWorkerDisabled` are non-`QueueFull`).
    //
    // Both steps reuse the same `stress_exe` artifact — the harness
    // dispatches on `ZEAM_STRESS_MODE=saturation` set here.
    const run_stress_saturation = b.addRunArtifact(stress_exe);
    run_stress_saturation.setEnvironmentVariable("ZEAM_STRESS_MODE", "saturation");
    if (b.args) |args| run_stress_saturation.addArgs(args);
    const stress_saturation_step = b.step(
        "stress-saturation",
        "Run the chain-worker queue saturation harness",
    );
    stress_saturation_step.dependOn(&run_stress_saturation.step);

    const run_stress_quick_saturation = b.addRunArtifact(stress_exe);
    run_stress_quick_saturation.setEnvironmentVariable("ZEAM_STRESS_MODE", "saturation");
    // macOS CI runners are often noisy; attestation submits can keep up with the
    // default producer count so the attn queue never hits QueueFull (FATAL in
    // stress.zig). Extra attn producers + a slightly longer window make the
    // gate reliable without changing the operator stress-saturation defaults.
    run_stress_quick_saturation.setEnvironmentVariable("ZEAM_STRESS_DURATION_SECS", "15");
    run_stress_quick_saturation.setEnvironmentVariable("ZEAM_STRESS_WATCHDOG_SECS", "25");
    run_stress_quick_saturation.setEnvironmentVariable("ZEAM_STRESS_SAT_ATTN_PRODUCERS", "16");
    const stress_quick_saturation_step = b.step(
        "stress-quick-saturation",
        "Run a 15s chain-worker queue saturation harness (CI gate)",
    );
    stress_quick_saturation_step.dependOn(&run_stress_quick_saturation.step);
    test_step.dependOn(&run_stress_quick_saturation.step);

    // CLI integration tests (separate target) - always create this test target
    const cli_integration_tests = b.addTest(.{
        .root_module = b.createModule(.{
            .root_source_file = b.path("pkgs/cli/test/integration.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });
    cli_integration_tests.test_runner = simple_test_runner;

    const integration_build_options = b.addOptions();
    cli_integration_tests.step.dependOn(&cli_exe.step);
    integration_build_options.addOptionPath("cli_exe_path", cli_exe.getEmittedBin());
    const integration_build_options_module = integration_build_options.createModule();
    cli_integration_tests.root_module.addImport("build_options", integration_build_options_module);
    cli_integration_tests.root_module.addImport("@zeam/utils", zeam_utils);
    // params: lets the harness scale its timeouts by the slot time.
    cli_integration_tests.root_module.addImport("@zeam/params", zeam_params);

    // Add CLI constants module to integration tests
    const cli_constants = b.addModule("cli_constants", .{
        .root_source_file = b.path("pkgs/cli/src/constants.zig"),
        .target = target,
        .optimize = optimize,
    });
    cli_integration_tests.root_module.addImport("cli_constants", cli_constants);

    // Add error handler module to integration tests
    const error_handler_module = b.addModule("error_handler", .{
        .root_source_file = b.path("pkgs/cli/src/error_handler.zig"),
        .target = target,
        .optimize = optimize,
    });
    cli_integration_tests.root_module.addImport("error_handler", error_handler_module);

    const types_tests = b.addTest(.{
        .root_module = zeam_types,
    });
    types_tests.test_runner = simple_test_runner;
    types_tests.root_module.addImport("ssz", ssz);
    types_tests.root_module.addImport("@zeam/key-manager", zeam_key_manager);
    types_tests.step.dependOn(&build_rust_lib_steps.step);
    addRustGlueLib(b, types_tests, target, prover);
    const run_types_test = b.addRunArtifact(types_tests);
    setTestRunLabelFromCompile(b, run_types_test, types_tests);
    test_step.dependOn(&run_types_test.step);

    // Lock the gauge↑scrape contract for `lean_gossip_mesh_peers` (and the
    // append-only behaviour of the `registerScrapeRefresher` registry) in
    // code so doc-only audits cannot regress it silently.
    const metrics_tests = b.addTest(.{
        .root_module = zeam_metrics,
    });
    metrics_tests.test_runner = simple_test_runner;
    metrics_tests.root_module.addImport("metrics", metrics);
    const run_metrics_tests = b.addRunArtifact(metrics_tests);
    setTestRunLabelFromCompile(b, run_metrics_tests, metrics_tests);
    test_step.dependOn(&run_metrics_tests.step);

    const transition_tests = b.addTest(.{
        .root_module = zeam_state_transition,
    });
    transition_tests.test_runner = simple_test_runner;
    // TODO(gballet) typing modules each time is quite tedious, hopefully
    // this will no longer be necessary in later versions of zig.
    transition_tests.root_module.addImport("@zeam/types", zeam_types);
    transition_tests.root_module.addImport("@zeam/params", zeam_params);
    transition_tests.root_module.addImport("@zeam/metrics", zeam_metrics);
    transition_tests.root_module.addImport("ssz", ssz);
    const run_transition_test = b.addRunArtifact(transition_tests);
    setTestRunLabelFromCompile(b, run_transition_test, transition_tests);
    test_step.dependOn(&run_transition_test.step);

    const manager_tests = b.addTest(.{
        .root_module = zeam_state_proving_manager,
    });
    manager_tests.test_runner = simple_test_runner;
    manager_tests.root_module.addImport("@zeam/types", zeam_types);
    addRustGlueLib(b, manager_tests, target, prover);
    const run_manager_test = b.addRunArtifact(manager_tests);
    setTestRunLabelFromCompile(b, run_manager_test, manager_tests);
    test_step.dependOn(&run_manager_test.step);

    const node_tests = b.addTest(.{
        .root_module = zeam_beam_node,
    });
    node_tests.test_runner = simple_test_runner;
    addRustGlueLib(b, node_tests, target, prover);
    const run_node_test = b.addRunArtifact(node_tests);
    setTestRunLabelFromCompile(b, run_node_test, node_tests);
    test_step.dependOn(&run_node_test.step);

    // Build shadow_cost as its own module for focused pure-function tests. This
    // gives it independent globals from the copy imported through @zeam/xmss.
    const zeam_shadow_cost = b.createModule(.{
        .root_source_file = b.path("pkgs/xmss/src/shadow_cost.zig"),
        .target = target,
        .optimize = optimize,
    });
    zeam_shadow_cost.link_libc = true; // shadow_cost reads env via libc getenv
    const shadow_cost_tests = b.addTest(.{
        .root_module = zeam_shadow_cost,
    });
    const run_shadow_cost_test = b.addRunArtifact(shadow_cost_tests);
    setTestRunLabelFromCompile(b, run_shadow_cost_test, shadow_cost_tests);
    test_step.dependOn(&run_shadow_cost_test.step);
    const shadow_cost_test_step = b.step("test-shadow-cost", "Run shadow sim-cost unit tests");
    shadow_cost_test_step.dependOn(&run_shadow_cost_test.step);

    const cli_tests = b.addTest(.{
        .root_module = cli_exe.root_module,
    });
    cli_tests.test_runner = simple_test_runner;
    cli_tests.step.dependOn(&cli_exe.step);
    cli_tests.step.dependOn(&build_rust_lib_steps.step);
    addRustGlueLib(b, cli_tests, target, prover);
    const run_cli_test = b.addRunArtifact(cli_tests);
    setTestRunLabelFromCompile(b, run_cli_test, cli_tests);
    test_step.dependOn(&run_cli_test.step);

    const params_tests = b.addTest(.{
        .root_module = zeam_params,
    });
    params_tests.test_runner = simple_test_runner;
    const run_params_tests = b.addRunArtifact(params_tests);
    setTestRunLabelFromCompile(b, run_params_tests, params_tests);
    test_step.dependOn(&run_params_tests.step);

    const network_tests = b.addTest(.{
        .root_module = zeam_network,
    });
    network_tests.test_runner = simple_test_runner;
    network_tests.root_module.addImport("@zeam/types", zeam_types);
    network_tests.root_module.addImport("xev", xev);
    network_tests.root_module.addImport("ssz", ssz);
    addRustGlueLib(b, network_tests, target, prover);
    const run_network_tests = b.addRunArtifact(network_tests);
    setTestRunLabelFromCompile(b, run_network_tests, network_tests);
    test_step.dependOn(&run_network_tests.step);

    const configs_tests = b.addTest(.{
        .root_module = zeam_configs,
    });
    configs_tests.test_runner = simple_test_runner;
    configs_tests.root_module.addImport("@zeam/utils", zeam_utils);
    configs_tests.root_module.addImport("@zeam/types", zeam_types);
    configs_tests.root_module.addImport("@zeam/params", zeam_params);
    configs_tests.root_module.addImport("yaml", yaml);
    configs_tests.step.dependOn(&build_rust_lib_steps.step);
    addRustGlueLib(b, configs_tests, target, prover);
    const run_configs_tests = b.addRunArtifact(configs_tests);
    setTestRunLabelFromCompile(b, run_configs_tests, configs_tests);
    test_step.dependOn(&run_configs_tests.step);

    const utils_tests = b.addTest(.{
        .root_module = zeam_utils,
    });
    utils_tests.test_runner = simple_test_runner;
    const run_utils_tests = b.addRunArtifact(utils_tests);
    setTestRunLabelFromCompile(b, run_utils_tests, utils_tests);
    test_step.dependOn(&run_utils_tests.step);

    const database_tests = b.addTest(.{
        .root_module = zeam_database,
    });
    database_tests.test_runner = simple_test_runner;
    database_tests.step.dependOn(&build_rust_lib_steps.step);
    addRustGlueLib(b, database_tests, target, prover);
    const run_database_tests = b.addRunArtifact(database_tests);
    setTestRunLabelFromCompile(b, run_database_tests, database_tests);
    test_step.dependOn(&run_database_tests.step);

    const api_tests = b.addTest(.{
        .root_module = zeam_api,
    });
    api_tests.test_runner = simple_test_runner;
    api_tests.step.dependOn(&build_rust_lib_steps.step);
    addRustGlueLib(b, api_tests, target, prover);
    const run_api_tests = b.addRunArtifact(api_tests);
    setTestRunLabelFromCompile(b, run_api_tests, api_tests);
    test_step.dependOn(&run_api_tests.step);

    const xmss_tests = b.addTest(.{
        .root_module = zeam_xmss,
    });
    xmss_tests.test_runner = simple_test_runner;

    // xmss_tests.step.dependOn(&networking_build.step);
    xmss_tests.step.dependOn(&build_rust_lib_steps.step);
    addRustGlueLib(b, xmss_tests, target, prover);
    const run_xmss_tests = b.addRunArtifact(xmss_tests);
    setTestRunLabelFromCompile(b, run_xmss_tests, xmss_tests);
    test_step.dependOn(&run_xmss_tests.step);

    const spectests = b.addTest(.{
        .root_module = zeam_spectests,
    });
    spectests.test_runner = simple_test_runner;
    spectests.root_module.addImport("@zeam/utils", zeam_utils);
    spectests.root_module.addImport("@zeam/types", zeam_types);
    spectests.root_module.addImport("@zeam/configs", zeam_configs);
    spectests.root_module.addImport("@zeam/metrics", zeam_metrics);
    spectests.root_module.addImport("@zeam/state-transition", zeam_state_transition);
    spectests.root_module.addImport("@zeam/network", zeam_network);
    spectests.root_module.addImport("snappyz", snappyz);
    spectests.root_module.addImport("snappyframesz", snappyframesz);
    spectests.root_module.addImport("ssz", ssz);

    manager_tests.step.dependOn(&build_rust_lib_steps.step);

    network_tests.step.dependOn(&build_rust_lib_steps.step);
    node_tests.step.dependOn(&build_rust_lib_steps.step);
    transition_tests.step.dependOn(&build_rust_lib_steps.step);
    addRustGlueLib(b, transition_tests, target, prover);

    const tools_test_step = b.step("test-tools", "Run zeam tools tests");
    const tools_cli_tests = b.addTest(.{
        .root_module = tools_cli_exe.root_module,
    });
    tools_cli_tests.test_runner = simple_test_runner;
    tools_cli_tests.root_module.addImport("enr", enr);
    tools_cli_tests.root_module.addImport("@zeam/xmss", zeam_xmss);
    tools_cli_tests.root_module.addImport("@zeam/types", zeam_types);
    tools_cli_tests.step.dependOn(&build_rust_lib_steps.step);
    addRustGlueLib(b, tools_cli_tests, target, prover);
    const run_tools_cli_test = b.addRunArtifact(tools_cli_tests);
    setTestRunLabelFromCompile(b, run_tools_cli_test, tools_cli_tests);
    tools_test_step.dependOn(&run_tools_cli_test.step);

    test_step.dependOn(tools_test_step);

    // Create simtest step that runs only integration tests
    const simtests = b.step("simtest", "Run integration tests");
    const run_cli_integration_test = b.addRunArtifact(cli_integration_tests);
    setTestRunLabelFromCompile(b, run_cli_integration_test, cli_integration_tests);
    simtests.dependOn(&run_cli_integration_test.step);

    // Create spectest step that runs spec tests
    const spectest_generate_exe = b.addExecutable(.{
        .name = "spectest-generate",
        .root_module = b.createModule(.{
            .root_source_file = b.path("pkgs/spectest/src/generator.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });
    const run_spectest_generate = b.addRunArtifact(spectest_generate_exe);
    const spectest_generate_step = b.step("spectest:generate", "Regenerate spectest fixtures");
    spectest_generate_step.dependOn(&run_spectest_generate.step);

    // The test-binary compile reads the generated spectest index
    // (gitignored, regenerated by the generator step). Without this edge
    // the compile and the generator race when zig fans out parallel build
    // steps — the compile sometimes reads a stale or half-written index
    // and fails with "file contents changed during update" or
    // "FileNotFound". Pinning compile-after-generate makes
    // `zig build spectest` idempotent across re-invocations.
    spectests.step.dependOn(&run_spectest_generate.step);

    const run_spectests_after_generate = b.addRunArtifact(spectests);
    run_spectests_after_generate.step.dependOn(&run_spectest_generate.step);
    const run_spectests = b.addRunArtifact(spectests);

    const spectests_step = b.step("spectest", "Regenerate and run spec tests");
    spectests_step.dependOn(&run_spectests_after_generate.step);

    try setSpectestArgsAndEnv(b, run_spectest_generate, run_spectests, run_spectests_after_generate);

    const spectest_run_step = b.step("spectest:run", "Run previously generated spectests");
    spectest_run_step.dependOn(&run_spectests.step);
}

fn setSpectestArgsAndEnv(
    b: *Builder,
    run_spectest_generate: *std.Build.Step.Run,
    run_spectests: *std.Build.Step.Run,
    run_spectests_after_generate: *std.Build.Step.Run,
) !void {
    if (b.args) |args| {
        var generator_args_builder: std.ArrayList([]const u8) = .empty;
        defer generator_args_builder.deinit(b.allocator);

        var skip_expected_errors = false;

        for (args) |arg| {
            if (std.mem.startsWith(u8, arg, "--skip-expected-error-fixtures")) {
                const suffix = arg["--skip-expected-error-fixtures".len..];
                if (suffix.len == 0) {
                    skip_expected_errors = true;
                    continue;
                }

                if (suffix[0] == '=') {
                    const value = suffix[1..];
                    if (std.ascii.eqlIgnoreCase(value, "true")) {
                        skip_expected_errors = true;
                    }
                    continue;
                }

                // fallthrough to treat as a normal argument if the suffix does not
                // match the supported forms.
            }

            try generator_args_builder.append(b.allocator, arg);
        }

        if (generator_args_builder.items.len != 0) {
            const generator_args = try generator_args_builder.toOwnedSlice(b.allocator);
            run_spectest_generate.addArgs(generator_args);
        }

        if (skip_expected_errors) {
            run_spectests.setEnvironmentVariable("ZEAM_SPECTEST_SKIP_EXPECTED_ERRORS", "true");
            run_spectests_after_generate.setEnvironmentVariable("ZEAM_SPECTEST_SKIP_EXPECTED_ERRORS", "true");
        }
    }
}

fn build_rust_project(b: *Builder, path: []const u8, prover: ProverChoice, no_jemalloc: bool) *Builder.Step.Run {
    // Every Rust glue crate is routed through the `zeam-glue` staticlib shim;
    // feature flags control which per-prover rlibs get linked in. See the
    // comment on `addRustGlueLib`.
    //
    // We invoke `rustup run nightly cargo …` rather than `cargo +nightly`.
    // Both reach the same toolchain on a properly-installed rustup, but
    // the `+nightly` selector requires `cargo` on PATH to be rustup's
    // proxy shim (i.e. `~/.cargo/bin/cargo`). On the GitHub-Actions
    // `macos-latest` runner image that path is the `rustup-init`
    // installer, which doesn't recognise the `+toolchain` syntax and
    // exits with `error: unexpected argument '+nightly' found`. Going
    // through `rustup run` resolves the toolchain inside rustup itself
    // (`rustup` IS the proxy on every supported install), so we don't
    // depend on `cargo` being a particular flavour of binary.
    //
    // Local-dev requirement: rustup must be installed. Standalone
    // Cargo (e.g. Homebrew-only) won't satisfy `rustup run nightly`
    // any more than it satisfied the previous `cargo +nightly` shape.
    // jemalloc is the global allocator only for the multisig/default build (the
    // lib.rs cfg excludes the zkVM provers, which ship their own). Enable its
    // cargo feature here, unless -Dno-jemalloc was passed (e.g. for the Shadow
    // simulator, where jemalloc deadlocks the shim — system allocator instead).
    const multisig_features = if (no_jemalloc) "hashsig,multisig" else "hashsig,multisig,jemalloc";
    const cargo_build = switch (prover) {
        .dummy => b.addSystemCommand(&.{
            "rustup",    "run",                   "nightly",          "cargo",
            "-C",        path,                    "-Z",               "unstable-options",
            "build",     "--profile",             "multisig-release", "-p",
            "zeam-glue", "--no-default-features", "--features",       multisig_features,
        }),
        .risc0 => b.addSystemCommand(&.{
            "rustup",    "run",                   "nightly",       "cargo",
            "-C",        path,                    "-Z",            "unstable-options",
            "build",     "--profile",             "risc0-release", "-p",
            "zeam-glue", "--no-default-features", "--features",    "hashsig,multisig,risc0",
        }),
        .openvm => b.addSystemCommand(&.{
            "rustup",    "run",                   "nightly",        "cargo",
            "-C",        path,                    "-Z",             "unstable-options",
            "build",     "--profile",             "openvm-release", "-p",
            "zeam-glue", "--no-default-features", "--features",     "hashsig,multisig,openvm",
        }),
        .all => b.addSystemCommand(&.{
            "rustup",                "run",        "nightly",                       "cargo",
            "-C",                    path,         "-Z",                            "unstable-options",
            "build",                 "--release",  "-p",                            "zeam-glue",
            "--no-default-features", "--features", "hashsig,multisig,risc0,openvm",
        }),
    };

    // leanMultisig's backend crate uses compile-time #[cfg(target_feature)] for SIMD
    // (AVX2/AVX512 on x86_64, NEON on aarch64). On x86_64, we set the Rust target-cpu
    // so the compiler enables the appropriate feature flags.
    //
    // The default is x86-64-v3 (AVX2, no AVX-512) because enabling AVX-512 via
    // target-cpu=native has triggered hard-to-diagnose runtime faults in the deeper
    // Rust dependency graph on AVX-512-capable CPUs (LLVM codegen issues, clobber-list
    // bugs, and kernel/microcode XSAVE quirks). Capping at AVX2 produces portable and
    // reliable binaries across all x86_64 Linux hosts. Users who want machine-specific
    // performance can opt in with -Drust-target-cpu=native (or x86-64-v4 for AVX-512).
    //
    // We skip this on aarch64 because ring 0.17 fails its compile-time feature
    // assertions when target-cpu=native is set on aarch64-apple-darwin.
    //
    // We set RUSTFLAGS directly (not CARGO_ENCODED_RUSTFLAGS) because Cargo ignores
    // CARGO_ENCODED_RUSTFLAGS when RUSTFLAGS is already set in the environment — which
    // happens in CI via actions-rust-lang/setup-rust-toolchain setting RUSTFLAGS=-Dwarnings.
    if (builtin.cpu.arch == .x86_64) {
        const rust_target_cpu = b.option([]const u8, "rust-target-cpu", "Target CPU for Rust libs (default: x86-64-v3 for portable AVX2 builds; use 'native' or 'x86-64-v4' to opt into AVX-512)") orelse "x86-64-v3";
        const flags = b.fmt("-Ctarget-cpu={s} -Dwarnings", .{rust_target_cpu});
        cargo_build.setEnvironmentVariable("RUSTFLAGS", flags);
    }

    return cargo_build;
}

fn build_zkvm_targets(
    b: *Builder,
    main_exe: *Builder.Step,
    host_target: std.Build.ResolvedTarget,
    build_options_module: *std.Build.Module,
) !void {
    // zkvm targets (riscv32-freestanding-none) require ReleaseFast; ReleaseSafe
    // triggers "invalid operand for inline asm constraint 'i'" in LLVM on riscv32.
    const optimize = .ReleaseFast;

    for (zkvm_targets) |zkvm_target| {
        const target_query = try std.Build.parseTargetQuery(.{ .arch_os_abi = zkvm_target.triplet, .cpu_features = zkvm_target.cpu_features });
        const target = b.resolveTargetQuery(target_query);

        // add ssz
        const ssz = b.dependency("ssz", .{
            .target = target,
            .optimize = optimize,
        }).module("ssz.zig");

        // add metrics
        const metrics = b.dependency("metrics", .{
            .target = target,
            .optimize = optimize,
        }).module("metrics");

        // add zeam-params
        const zeam_params = b.addModule("@zeam/params", .{
            .target = target,
            .optimize = optimize,
            .root_source_file = b.path("pkgs/params/src/lib.zig"),
        });

        // add zeam-utils
        const zeam_utils = b.addModule("@zeam/utils", .{
            .target = target,
            .optimize = optimize,
            .root_source_file = b.path("pkgs/utils/src/lib.zig"),
        });
        zeam_utils.addImport("ssz", ssz);
        zeam_utils.addImport("build_options", build_options_module);
        // add zeam-metrics (core metrics definitions for ZKVM)
        const zeam_metrics = b.addModule("@zeam/metrics", .{
            .target = target,
            .optimize = optimize,
            .root_source_file = b.path("pkgs/metrics/src/lib.zig"),
        });
        zeam_metrics.addImport("metrics", metrics);

        // add zeam-types
        const zeam_types = b.addModule("@zeam/types", .{
            .target = target,
            .optimize = optimize,
            .root_source_file = b.path("pkgs/types/src/lib.zig"),
        });
        zeam_types.addImport("ssz", ssz);
        zeam_types.addImport("@zeam/params", zeam_params);
        zeam_types.addImport("@zeam/utils", zeam_utils);
        zeam_types.addImport("@zeam/metrics", zeam_metrics);

        const zkvm_module = b.addModule("zkvm", .{
            .optimize = optimize,
            .target = target,
            .root_source_file = b.path(b.fmt("pkgs/state-transition-runtime/src/{s}/lib.zig", .{zkvm_target.name})),
        });
        zeam_utils.addImport("zkvm", zkvm_module);

        // add state transition, create a new module for each zkvm since
        // that module depends on the zkvm module.
        const zeam_state_transition = b.addModule("@zeam/state-transition", .{
            .root_source_file = b.path("pkgs/state-transition/src/lib.zig"),
            .target = target,
            .optimize = optimize,
        });
        zeam_state_transition.addImport("@zeam/utils", zeam_utils);
        zeam_state_transition.addImport("@zeam/params", zeam_params);
        zeam_state_transition.addImport("@zeam/types", zeam_types);
        zeam_state_transition.addImport("ssz", ssz);
        zeam_state_transition.addImport("@zeam/metrics", zeam_metrics);
        zeam_state_transition.addImport("zkvm", zkvm_module);

        // target has to be riscv5 runtime provable/verifiable on zkVMs
        var exec_name: [256]u8 = undefined;
        var exe = b.addExecutable(.{
            .name = try std.fmt.bufPrint(&exec_name, "zeam-stf-{s}", .{zkvm_target.name}),
            .root_module = b.createModule(.{
                .root_source_file = b.path("pkgs/state-transition-runtime/src/main.zig"),
                .target = target,
                .optimize = optimize,
                .strip = true, // Strip debug info to avoid RISC-V relocation overflow
            }),
        });
        // addimport to root module is even required afer declaring it in mod
        exe.root_module.addImport("ssz", ssz);
        exe.root_module.addImport("@zeam/utils", zeam_utils);
        exe.root_module.addImport("@zeam/params", zeam_params);
        exe.root_module.addImport("@zeam/types", zeam_types);
        exe.root_module.addImport("@zeam/metrics", zeam_metrics);
        exe.root_module.addImport("@zeam/state-transition", zeam_state_transition);
        exe.root_module.addImport("zkvm", zkvm_module);
        exe.root_module.addAssemblyFile(b.path(b.fmt("pkgs/state-transition-runtime/src/{s}/start.s", .{zkvm_target.name})));
        if (zkvm_target.set_pie) {
            exe.pie = true;
        }
        exe.setLinkerScript(b.path(b.fmt("pkgs/state-transition-runtime/src/{s}/{s}.ld", .{ zkvm_target.name, zkvm_target.name })));
        main_exe.dependOn(&b.addInstallArtifact(exe, .{}).step);

        // in case of risc0, use an external tool to format the executable
        // the way the executor expects it.
        if (std.mem.eql(u8, zkvm_target.name, "risc0")) {
            const risc0_postbuild_gen = b.addExecutable(.{
                .name = "risc0ospkg",
                .root_module = b.createModule(.{
                    .root_source_file = b.path("build/risc0.zig"),
                    .target = host_target,
                    .optimize = .ReleaseFast,
                }),
            });
            const run_risc0_postbuild_gen_step = b.addRunArtifact(risc0_postbuild_gen);
            run_risc0_postbuild_gen_step.addFileArg(exe.getEmittedBin());
            const install_generated = b.addInstallBinFile(try exe.getEmittedBinDirectory().join(b.allocator, "risc0_runtime.elf"), "risc0_runtime.elf");
            install_generated.step.dependOn(&run_risc0_postbuild_gen_step.step);
            main_exe.dependOn(&install_generated.step);
        }
    }
}