build.zig

const std = @import("std");

/// Selects the crypto accelerator implementation.
///   default — native host crypto (default.zig, dynamically linked C libs)
///   extern  — zkvm-standards extern ABI (extern_bridge.zig, zkvm_* symbols resolved at link by the consumer)
const CryptoBackend = enum {
    default,
    @"extern",
};

/// The set of modules produced by `buildModules`. The exposable ones are registered
/// via `addModule` (retrievable by dependents through `dep.module(name)`) when
/// `expose` is true; `accel_impl`, `executor_types`, `zkvm_io` and `zkvm_root` stay private.
const ModuleSet = struct {
    zesu_allocator: *std.Build.Module,
    primitives: *std.Build.Module,
    accelerators: *std.Build.Module,
    precompile_types: *std.Build.Module,
    bytecode: *std.Build.Module,
    state: *std.Build.Module,
    database: *std.Build.Module,
    context: *std.Build.Module,
    precompile: *std.Build.Module,
    interpreter: *std.Build.Module,
    handler: *std.Build.Module,
    input: *std.Build.Module,
    output: *std.Build.Module,
    hardfork: *std.Build.Module,
    rlp_decode: *std.Build.Module,
    mpt: *std.Build.Module,
    ssz_decode: *std.Build.Module,
    ssz_output: *std.Build.Module,
    db: *std.Build.Module,
    block_rlp_size: *std.Build.Module,
    executor: *std.Build.Module,
    runner: *std.Build.Module,
    zkvm_io: *std.Build.Module,
    /// Freestanding only, private (used by the in-repo rv64im-object build): the relocatable-object
    /// root that wires runner + extern IO + allocator and exports main().
    zkvm_root: ?*std.Build.Module,
};

/// What the zkVM a guest object is built for provides beyond the rv64im baseline. Every field
/// defaults to false: the portable guest, and every native build. Each one only selects code at
/// comptime; the zkVM project that links the object must provide what it enables.
pub const GuestFeatures = struct {
    /// Fixed-size copy accelerator, used by `primitives.dma`
    /// (currently: the ZisK DMA chip).
    dma: bool = false,
    /// Hardware-assisted JUMPDEST analysis
    /// (currently: the ZisK >= 1.3 `jump_dest` precompile, `csrs 0x81C`).
    jump_dest: bool = false,
    /// 256-bit MOD/ADDMOD/MULMOD, provided by the linking zkVM project as `*_mod256_c`
    /// functions in the guest (currently: libziskos).
    arith256_mod: bool = false,
};

/// Create (and optionally expose) zesu's whole module graph for a single target.
///
/// Two independent axes select implementations, one per caller-supplied parameter:
///   accel_impl = crypto_backend == extern ? extern_bridge.zig : default.zig
///   zkvm_io    = guest                    ? extern_io.zig     : io/interface.zig
/// `guest` is true only for the rv64im-object build
///
/// The allocator root is supplied by the caller (`allocator.zig` settable singleton for the
/// exposed graph; `alt_fl_alloc.zig` for the standalone rv64im object).
fn buildModules(
    b: *std.Build,
    target: std.Build.ResolvedTarget,
    optimize: std.builtin.OptimizeMode,
    expose: bool,
    alloc_root: std.Build.LazyPath,
    crypto_prefix: []const u8,
    crypto_backend: CryptoBackend,
    guest: bool,
    features: GuestFeatures,
) ModuleSet {
    const use_extern = crypto_backend == .@"extern";

    const mkmod = struct {
        fn f(bb: *std.Build, exp: bool, name: []const u8, opts: std.Build.Module.CreateOptions) *std.Build.Module {
            return if (exp) bb.addModule(name, opts) else bb.createModule(opts);
        }
    }.f;

    // ── Foundation ────────────────────────────────────────────────────────────
    const zesu_allocator = mkmod(b, expose, "zesu_allocator", .{
        .root_source_file = alloc_root,
        .target = target,
        .optimize = optimize,
    });

    const primitives_opts = b.addOptions();
    primitives_opts.addOption(bool, "has_dma", features.dma);
    primitives_opts.addOption(bool, "has_jump_dest", features.jump_dest);
    primitives_opts.addOption(bool, "has_arith256_mod", features.arith256_mod);

    const primitives = mkmod(b, expose, "primitives", .{
        .root_source_file = b.path("src/evm/primitives/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    primitives.addOptions("build_options", primitives_opts);

    // accel_impl is a private leaf: native crypto (default.zig) or the zkvm-standards extern
    // bridge (extern_bridge.zig, whose zkvm_* symbols the host resolves at link).
    const accel_impl = b.createModule(.{
        .root_source_file = b.path(if (use_extern) "src/crypto/extern_bridge.zig" else "src/crypto/default.zig"),
        .target = target,
        .optimize = optimize,
    });
    if (!use_extern) {
        accel_impl.addImport("zesu_allocator", zesu_allocator);
        // default.zig @cImports system crypto headers (e.g. secp256k1.h). C include paths are
        // per-module and don't cross the dependency boundary, so set it on the accel_impl module
        // itself — that way dependents (and our own apps/tests) resolve the @cImport without each
        // consumer re-adding an include path to a module they can't see. `crypto_prefix` is the
        // caller-provided prefix (overridable via -Dcrypto-prefix; see build()).
        accel_impl.addIncludePath(.{ .cwd_relative = b.fmt("{s}/include", .{crypto_prefix}) });
    }

    const accelerators = mkmod(b, expose, "accelerators", .{
        .root_source_file = b.path("src/crypto/accelerators.zig"),
        .target = target,
        .optimize = optimize,
    });
    accelerators.addImport("accel_impl", accel_impl);
    // For primitives.mix64 — the keccak memo indexes on the same non-uniform key
    // material as the address maps and needs the identical mixer, so both share one.
    accelerators.addImport("primitives", primitives);

    const precompile_types = mkmod(b, expose, "precompile_types", .{
        .root_source_file = b.path("src/evm/precompile/types.zig"),
        .target = target,
        .optimize = optimize,
    });

    // ── EVM ───────────────────────────────────────────────────────────────────
    const bytecode = mkmod(b, expose, "bytecode", .{
        .root_source_file = b.path("src/evm/bytecode/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    bytecode.addImport("primitives", primitives);
    bytecode.addImport("zesu_allocator", zesu_allocator);
    bytecode.addImport("accelerators", accelerators);

    const state = mkmod(b, expose, "state", .{
        .root_source_file = b.path("src/evm/state/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    state.addImport("primitives", primitives);
    state.addImport("bytecode", bytecode);
    state.addImport("zesu_allocator", zesu_allocator);

    const database = mkmod(b, expose, "database", .{
        .root_source_file = b.path("src/evm/database/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    database.addImport("primitives", primitives);
    database.addImport("state", state);
    database.addImport("bytecode", bytecode);

    const context = mkmod(b, expose, "context", .{
        .root_source_file = b.path("src/evm/context/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    context.addImport("primitives", primitives);
    context.addImport("bytecode", bytecode);
    context.addImport("state", state);
    context.addImport("database", database);
    context.addImport("zesu_allocator", zesu_allocator);

    const precompile = mkmod(b, expose, "precompile", .{
        .root_source_file = b.path("src/evm/precompile/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    precompile.addImport("primitives", primitives);
    precompile.addImport("zesu_allocator", zesu_allocator);
    precompile.addImport("precompile_types", precompile_types);
    precompile.addImport("accelerators", accelerators);

    const interpreter = mkmod(b, expose, "interpreter", .{
        .root_source_file = b.path("src/evm/interpreter/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    interpreter.addImport("primitives", primitives);
    interpreter.addImport("bytecode", bytecode);
    interpreter.addImport("context", context);
    interpreter.addImport("database", database);
    interpreter.addImport("state", state);
    interpreter.addImport("precompile", precompile);
    interpreter.addImport("zesu_allocator", zesu_allocator);
    interpreter.addImport("accelerators", accelerators);

    const handler = mkmod(b, expose, "handler", .{
        .root_source_file = b.path("src/evm/handler/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    handler.addImport("primitives", primitives);
    handler.addImport("bytecode", bytecode);
    handler.addImport("state", state);
    handler.addImport("database", database);
    handler.addImport("interpreter", interpreter);
    handler.addImport("context", context);
    handler.addImport("precompile", precompile);
    handler.addImport("zesu_allocator", zesu_allocator);

    // ── Stateless base ──────────────────────────────────────────────────────
    const input = mkmod(b, expose, "input", .{
        .root_source_file = b.path("src/stateless/input.zig"),
        .target = target,
        .optimize = optimize,
    });
    input.addImport("primitives", primitives);

    const output = mkmod(b, expose, "output", .{
        .root_source_file = b.path("src/stateless/output.zig"),
        .target = target,
        .optimize = optimize,
    });
    output.addImport("primitives", primitives);

    const hardfork = mkmod(b, expose, "hardfork", .{
        .root_source_file = b.path("src/stateless/hardfork.zig"),
        .target = target,
        .optimize = optimize,
    });
    hardfork.addImport("primitives", primitives);

    const rlp_decode = mkmod(b, expose, "rlp_decode", .{
        .root_source_file = b.path("src/stateless/rlp_decode.zig"),
        .target = target,
        .optimize = optimize,
    });
    rlp_decode.addImport("primitives", primitives);
    rlp_decode.addImport("input", input);

    const mpt = mkmod(b, expose, "mpt", .{
        .root_source_file = b.path("src/stateless/mpt/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    mpt.addImport("primitives", primitives);
    mpt.addImport("input", input);
    mpt.addImport("accelerators", accelerators);

    // Deferred: rlp_decode needs mpt (created above).
    rlp_decode.addImport("mpt", mpt);

    const ssz_decode = mkmod(b, expose, "ssz_decode", .{
        .root_source_file = b.path("src/stateless/stateless/ssz.zig"),
        .target = target,
        .optimize = optimize,
    });
    ssz_decode.addImport("input", input);
    ssz_decode.addImport("rlp_decode", rlp_decode);
    ssz_decode.addImport("hardfork", hardfork);

    const ssz_output = mkmod(b, expose, "ssz_output", .{
        .root_source_file = b.path("src/stateless/stateless/ssz_output.zig"),
        .target = target,
        .optimize = optimize,
    });
    ssz_output.addImport("input", input);
    ssz_output.addImport("accelerators", accelerators);
    ssz_output.addImport("primitives", primitives);
    ssz_output.addImport("hardfork", hardfork);

    // executor_types: shared type definitions — private (not a consumer entry point).
    const executor_types = b.createModule(.{
        .root_source_file = b.path("src/stateless/executor/types.zig"),
        .target = target,
        .optimize = optimize,
    });

    const db = mkmod(b, expose, "db", .{
        .root_source_file = b.path("src/stateless/db/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    db.addImport("primitives", primitives);
    db.addImport("state", state);
    db.addImport("bytecode", bytecode);
    db.addImport("mpt", mpt);
    db.addImport("executor_types", executor_types);
    db.addImport("input", input); // tests.zig builds StateWitness values

    const block_rlp_size = mkmod(b, expose, "block_rlp_size", .{
        .root_source_file = b.path("src/stateless/executor/block_rlp_size.zig"),
        .target = target,
        .optimize = optimize,
    });
    block_rlp_size.addImport("primitives", primitives);
    block_rlp_size.addImport("input", input);

    const executor = mkmod(b, expose, "executor", .{
        .root_source_file = b.path("src/stateless/executor/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    executor.addImport("executor_types", executor_types);
    executor.addImport("block_rlp_size", block_rlp_size);
    executor.addImport("zesu_allocator", zesu_allocator);
    executor.addImport("primitives", primitives);
    executor.addImport("input", input);
    executor.addImport("output", output);
    executor.addImport("mpt", mpt);
    executor.addImport("rlp_decode", rlp_decode);
    executor.addImport("hardfork", hardfork);
    executor.addImport("db", db);
    executor.addImport("context", context);
    executor.addImport("state", state);
    executor.addImport("bytecode", bytecode);
    executor.addImport("database", database);
    executor.addImport("handler", handler);
    executor.addImport("interpreter", interpreter);
    executor.addImport("precompile", precompile);
    executor.addImport("accelerators", accelerators);

    // zkvm_io is private: native stdin/env (io/interface.zig) or the extern C-ABI refs
    // (zkvm/extern_io.zig) the zkVM host resolves at link. Selected by the `guest` parameter
    const zkvm_io = b.createModule(.{
        .root_source_file = b.path(if (guest) "src/zkvm/extern_io.zig" else "src/io/interface.zig"),
        .target = target,
        .optimize = optimize,
    });

    const runner = mkmod(b, expose, "runner", .{
        .root_source_file = b.path("src/stateless/stateless/run.zig"),
        .target = target,
        .optimize = optimize,
    });
    runner.addImport("executor", executor);
    runner.addImport("ssz_decode", ssz_decode);
    runner.addImport("ssz_output", ssz_output);
    runner.addImport("zkvm_io", zkvm_io);

    var zkvm_root: ?*std.Build.Module = null;
    if (guest) {
        // zkvm_root stays PRIVATE (never addModule'd). It wires the full turnkey object
        // (runner + extern IO + allocator) and exports main(). It must NOT be exposed: the
        // exposed graph roots `zesu_allocator` on the settable singleton, and a consumer
        // building this as an object gets no chance to call set() before main() runs (get()
        // would panic on a freestanding default). The turnkey object is instead produced by the
        // `rv64im-object` step (which wires the bump allocator over ZKVM_HEAP_POS/TOP) and
        // published as zesu.rv64im.o. Module consumers import the leaf modules and call set().
        const root = b.createModule(.{
            .root_source_file = b.path("src/zkvm/root.zig"),
            .target = target,
            .optimize = optimize,
        });
        root.addImport("runner", runner);
        root.addImport("zkvm_io", zkvm_io);
        root.addImport("zesu_allocator", zesu_allocator);
        zkvm_root = root;
    }

    return .{
        .zesu_allocator = zesu_allocator,
        .primitives = primitives,
        .accelerators = accelerators,
        .precompile_types = precompile_types,
        .bytecode = bytecode,
        .state = state,
        .database = database,
        .context = context,
        .precompile = precompile,
        .interpreter = interpreter,
        .handler = handler,
        .input = input,
        .output = output,
        .hardfork = hardfork,
        .rlp_decode = rlp_decode,
        .mpt = mpt,
        .ssz_decode = ssz_decode,
        .ssz_output = ssz_output,
        .db = db,
        .block_rlp_size = block_rlp_size,
        .executor = executor,
        .runner = runner,
        .zkvm_io = zkvm_io,
        .zkvm_root = zkvm_root,
    };
}

/// Link libc and, for the default backend, native crypto C libraries onto a host exe/test.
fn addCryptoLibraries(
    step: *std.Build.Step.Compile,
    crypto_backend: CryptoBackend,
    inc: []const u8,
    blst: []const u8,
    mcl: []const u8,
    linux: bool,
) void {
    step.root_module.linkSystemLibrary("c", .{});
    if (crypto_backend == .@"extern") return;

    step.root_module.addIncludePath(.{ .cwd_relative = inc });
    step.root_module.linkSystemLibrary("m", .{});
    step.root_module.linkSystemLibrary("secp256k1", .{});
    step.root_module.linkSystemLibrary("ssl", .{});
    step.root_module.linkSystemLibrary("crypto", .{});
    step.root_module.addObjectFile(.{ .cwd_relative = blst });
    if (linux) {
        // mcl: link dynamically on Linux to avoid unresolved libstdc++ refs embedded in the .a.
        step.root_module.addLibraryPath(.{ .cwd_relative = "/usr/local/lib" });
        step.root_module.linkSystemLibrary("mcl", .{});
    } else {
        step.root_module.addObjectFile(.{ .cwd_relative = mcl });
        step.root_module.link_libcpp = true;
    }
}

fn addRunStep(
    bb: *std.Build,
    name: []const u8,
    desc: []const u8,
    exe: *std.Build.Step.Compile,
    fixed_args: []const []const u8,
) void {
    const step = bb.step(name, desc);
    const cmd = bb.addRunArtifact(exe);
    cmd.step.dependOn(bb.getInstallStep());
    cmd.addArgs(fixed_args);
    if (bb.args) |args| cmd.addArgs(args);
    step.dependOn(&cmd.step);
}

/// tests-zkevm-benchmark ships one tarball per gas value, so fetch and run one tier at a time:
///   zig build zkevm-benchmark -Dbench-gas=60M
fn addZkevmBenchmarkSteps(b: *std.Build, runner: *std.Build.Step.Compile) void {
    const version = "tests-zkevm-benchmark@v21.0.5";
    const gas = b.option([]const u8, "bench-gas", "zkevm benchmark gas tier: 30M, 60M, 100M, 150M or 200M (default 30M)") orelse "30M";
    const fetch = b.step("fetch-zkevm-benchmark-fixtures", "Download one " ++ version ++ " gas tier (-Dbench-gas)");
    const run = b.step("zkevm-benchmark", "Run one " ++ version ++ " gas tier (-Dbench-gas)");

    const tier = for ([_]u32{ 30, 60, 100, 150, 200 }) |g| {
        if (std.mem.eql(u8, gas, b.fmt("{d}M", .{g}))) break b.fmt("{d:0>4}M", .{g});
    } else {
        const fail = b.addFail(b.fmt("-Dbench-gas={s}: expected 30M, 60M, 100M, 150M or 200M", .{gas}));
        fetch.dependOn(&fail.step);
        run.dependOn(&fail.step);
        return;
    };

    const dir = b.fmt("spec-tests/fixtures/zkevm-benchmark/{s}", .{tier});
    const download = b.addSystemCommand(&.{
        "sh", "-c",
        b.fmt("marker={[dir]s}/.fixtures-{[version]s} && " ++
            "[ -f \"$marker\" ] && echo 'Fixtures already up to date.' && exit 0; " ++
            "echo 'Downloading {[version]s} {[tier]s} fixtures...' && " ++
            "rm -rf {[dir]s} && mkdir -p {[dir]s} && " ++
            "curl -fL \"https://github.com/ethereum/execution-specs/releases/download/{[encoded]s}/fixtures_zkevm-benchmark_{[tier]s}.tar.gz\" " ++
            "| tar xz --strip-components=1 -C {[dir]s}/ && " ++
            "touch \"$marker\"", .{
            .dir = dir,
            .version = version,
            .encoded = "tests-zkevm-benchmark%40v21.0.5",
            .tier = tier,
        }),
    });
    fetch.dependOn(&download.step);

    const cmd = b.addRunArtifact(runner);
    cmd.step.dependOn(b.getInstallStep());
    cmd.step.dependOn(&download.step);
    cmd.addArgs(&.{ "--fixtures", b.fmt("{s}/blockchain_tests", .{dir}) });
    if (b.args) |args| cmd.addArgs(args);
    run.dependOn(&cmd.step);
}

/// Build the relocatable guest object (zkvm-standards ABI: IO, crypto, heap and logging left as
/// unresolved externs) for a caller-supplied freestanding riscv64 `target`.
///
/// This is zesu's public build API for zkVM projects: a dependent (e.g. zesu-zkvm) imports this
/// build.zig, passes the same resolved target it uses for its own host object, and links the
/// returned object. The target's ISA extensions are the caller's; `GuestFeatures` only names the
/// zkVM capabilities zesu may compile in, and each is off unless the caller enables it.
///
/// `b` must be zesu's own builder (`dep.builder` from `b.dependency("zesu", .{})`), because the
/// module graph resolves its sources relative to it. `features` names the zkVM-specific
/// capabilities to compile in (all off by default).
pub fn addGuestObject(
    b: *std.Build,
    target: std.Build.ResolvedTarget,
    optimize: std.builtin.OptimizeMode,
    features: GuestFeatures,
) *std.Build.Step.Compile {
    // The extern crypto backend ignores crypto_prefix (it only locates native libraries).
    const obj_mods = buildModules(b, target, optimize, false, b.path("src/zkvm/alt_fl_alloc.zig"), "", .@"extern", true, features);

    const obj = b.addObject(.{
        .name = "zesu",
        .root_module = obj_mods.zkvm_root.?,
    });
    obj.root_module.code_model = .medium;
    obj.root_module.omit_frame_pointer = true;
    return obj;
}

/// Build a relocatable rv64im ELF guest object on the freestanding riscv64 baseline plus
/// `extra_features`, and wire an install step named `step_name` that publishes it to
/// `install_name` under zig-out. Backs the published `rv64im-object` (and, for now,
/// `zisk-object`) release artifacts.
fn addRv64imObjectStep(
    b: *std.Build,
    optimize: std.builtin.OptimizeMode,
    extra_features: []const std.Target.riscv.Feature,
    step_name: []const u8,
    step_desc: []const u8,
    install_name: []const u8,
    features: GuestFeatures,
) void {
    const rv64im_target = b.resolveTargetQuery(.{
        .cpu_arch = .riscv64,
        .cpu_model = .{ .explicit = &std.Target.riscv.cpu.baseline_rv64 },
        .cpu_features_add = std.Target.riscv.featureSet(extra_features),
        .cpu_features_sub = std.Target.riscv.featureSet(&.{ .a, .c, .zca, .zcb, .d, .f, .zicsr, .zaamo, .zalrsc }),
        .os_tag = .freestanding,
        .abi = .none,
    });

    const rv64_obj = addGuestObject(b, rv64im_target, optimize, features);

    const obj_step = b.step(step_name, step_desc);
    const install_obj = b.addInstallFile(rv64_obj.getEmittedBin(), install_name);
    obj_step.dependOn(&install_obj.step);
}

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const crypto_backend = b.option(
        CryptoBackend,
        "crypto-backend",
        "Crypto accelerator backend: selects the crypto implementation (default: default)",
    ) orelse CryptoBackend.default;
    // default.zig @cImports system crypto headers and needs libc; neither exists on a
    // freestanding target, so this combination can never build. Fail fast with an actionable
    // message rather than a bare "header not found" three @cImports deep.
    if (target.result.os.tag == .freestanding and crypto_backend == .default)
        std.debug.panic("freestanding targets require -Dcrypto-backend=extern (no libc/system crypto headers available)", .{});

    // ── Platform detection ────────────────────────────────────────────────────
    const is_linux = b.graph.host.result.os.tag == .linux;
    // Native crypto dependency prefix. Defaults per OS (Homebrew on macOS, /usr/local on Linux),
    // overridable for non-default setups (e.g. Intel-mac /usr/local) without patching the build.
    const crypto_prefix: []const u8 = b.option(
        []const u8,
        "crypto-prefix",
        "Native crypto dependency prefix (default: /opt/homebrew on macOS, /usr/local on Linux)",
    ) orelse (if (is_linux) "/usr/local" else "/opt/homebrew");
    const crypto_include = b.fmt("{s}/include", .{crypto_prefix});
    // HACK: unlike secp256k1/OpenSSL (resolved via linkSystemLibrary → pkg-config/system search),
    // mcl and blst ship no pkg-config metadata, so the linker can't locate them on its own —
    // addCryptoLibraries hands it the static archives by explicit path. We presume both live under
    // `<crypto_prefix>/lib` (libblst.a, libmcl.a). Assuming they share one directory is itself a bit
    // of a hack
    const libblst_path = b.fmt("{s}/lib/libblst.a", .{crypto_prefix});
    const libmcl_path = b.fmt("{s}/lib/libmcl.a", .{crypto_prefix});

    // ── Module graph (exposed via addModule; backend selected by option) ──────
    const mods = buildModules(b, target, optimize, true, b.path("src/evm/allocator.zig"), crypto_prefix, crypto_backend, false, .{});
    const block_rlp_size_test_step = b.step("test-block-rlp-size", "Run block RLP size unit tests");
    const block_rlp_size_test = b.addTest(.{ .root_module = mods.block_rlp_size });
    const run_block_rlp_size_test = b.addRunArtifact(block_rlp_size_test);
    block_rlp_size_test_step.dependOn(&run_block_rlp_size_test.step);

    // ── Host artifacts ────────────────────────────────────────────────────────
    //
    // extern backend: compile the stateless binary as a relocatable object so a
    // consumer (e.g. Linea with CTT) can link the unresolved zkvm_* crypto symbols
    // against their own static library. All other tooling is omitted — it cannot
    // be linked without a symbol provider.
    //
    // default backend: build the fully-linked zesu binary plus all supporting
    // tools and unit tests.
    const host_io = b.createModule(.{
        .root_source_file = b.path("src/io/interface.zig"),
        .target = target,
        .optimize = optimize,
    });
    if (crypto_backend == .@"extern") {
        const stateless_obj = b.addObject(.{
            .name = "zesu",
            .root_module = b.createModule(.{
                .root_source_file = b.path("src/stateless/stateless/main.zig"),
                .target = target,
                .optimize = optimize,
            }),
        });
        stateless_obj.root_module.addImport("rlp_decode", mods.rlp_decode);
        stateless_obj.root_module.addImport("input", mods.input);
        stateless_obj.root_module.addImport("mpt", mods.mpt);
        stateless_obj.root_module.addImport("executor", mods.executor);
        stateless_obj.root_module.addImport("zesu_allocator", mods.zesu_allocator);
        stateless_obj.root_module.addImport("zkvm_io", host_io);
        stateless_obj.root_module.addImport("ssz_decode", mods.ssz_decode);
        stateless_obj.root_module.addImport("accelerators", mods.accelerators);
        stateless_obj.root_module.addImport("primitives", mods.primitives);
        stateless_obj.root_module.addImport("hardfork", mods.hardfork);
        // Distinct path from rv64im-object's zig-out/lib/zesu.o (the guest ELF) — they must
        // never collide if both steps are invoked against the same zig-out.
        b.getInstallStep().dependOn(&b.addInstallFile(stateless_obj.getEmittedBin(), "lib/zesu-host.o").step);
    } else {
        // ── zesu binary ───────────────────────────────────────────────────────
        const stateless_exe = b.addExecutable(.{
            .name = "zesu",
            .root_module = b.createModule(.{
                .root_source_file = b.path("src/stateless/stateless/main.zig"),
                .target = target,
                .optimize = optimize,
            }),
        });
        stateless_exe.root_module.addImport("rlp_decode", mods.rlp_decode);
        stateless_exe.root_module.addImport("input", mods.input);
        stateless_exe.root_module.addImport("mpt", mods.mpt);
        stateless_exe.root_module.addImport("executor", mods.executor);
        stateless_exe.root_module.addImport("zesu_allocator", mods.zesu_allocator);
        stateless_exe.root_module.addImport("zkvm_io", host_io);
        stateless_exe.root_module.addImport("ssz_decode", mods.ssz_decode);
        stateless_exe.root_module.addImport("accelerators", mods.accelerators);
        stateless_exe.root_module.addImport("primitives", mods.primitives);
        stateless_exe.root_module.addImport("hardfork", mods.hardfork);
        addCryptoLibraries(stateless_exe, crypto_backend, crypto_include, libblst_path, libmcl_path, is_linux);
        b.installArtifact(stateless_exe);
        addRunStep(b, "run", "Run the zesu app", stateless_exe, &.{});

        // ── t8n: Ethereum State Transition Tool ───────────────────────────────
        const t8n_input_module = b.createModule(.{
            .root_source_file = b.path("tools/t8n/input.zig"),
            .target = target,
            .optimize = optimize,
        });
        t8n_input_module.addImport("executor", mods.executor);

        const t8n_exe = b.addExecutable(.{
            .name = "t8n",
            .root_module = b.createModule(.{
                .root_source_file = b.path("tools/t8n/main.zig"),
                .target = target,
                .optimize = optimize,
            }),
        });
        t8n_exe.root_module.addImport("executor", mods.executor);
        t8n_exe.root_module.addImport("hardfork", mods.hardfork);
        addCryptoLibraries(t8n_exe, crypto_backend, crypto_include, libblst_path, libmcl_path, is_linux);
        b.installArtifact(t8n_exe);
        addRunStep(b, "t8n", "Run the t8n state transition tool", t8n_exe, &.{});

        // ── spec-test-runner ──────────────────────────────────────────────────
        const spec_test_exe = b.addExecutable(.{
            .name = "spec-test-runner",
            .root_module = b.createModule(.{
                .root_source_file = b.path("tools/spec_test/main.zig"),
                .target = target,
                .optimize = optimize,
            }),
        });
        spec_test_exe.root_module.addImport("t8n_input", t8n_input_module);
        spec_test_exe.root_module.addImport("executor", mods.executor);
        spec_test_exe.root_module.addImport("hardfork", mods.hardfork);
        addCryptoLibraries(spec_test_exe, crypto_backend, crypto_include, libblst_path, libmcl_path, is_linux);
        b.installArtifact(spec_test_exe);
        addRunStep(b, "state-tests", "Run execution-spec-tests state fixtures", spec_test_exe, &.{});

        // ── blockchain-test-runner ────────────────────────────────────────────
        const blockchain_runner_module = b.createModule(.{
            .root_source_file = b.path("tools/blockchain_test/runner.zig"),
            .target = target,
            .optimize = optimize,
        });
        blockchain_runner_module.addImport("primitives", mods.primitives);
        blockchain_runner_module.addImport("executor", mods.executor);
        blockchain_runner_module.addImport("mpt", mods.mpt);
        blockchain_runner_module.addImport("hardfork", mods.hardfork);

        const bc_test_exe = b.addExecutable(.{
            .name = "blockchain-test-runner",
            .root_module = b.createModule(.{
                .root_source_file = b.path("tools/blockchain_test/main.zig"),
                .target = target,
                .optimize = optimize,
            }),
        });
        bc_test_exe.root_module.addImport("runner", blockchain_runner_module);
        addCryptoLibraries(bc_test_exe, crypto_backend, crypto_include, libblst_path, libmcl_path, is_linux);
        b.installArtifact(bc_test_exe);
        addRunStep(b, "blockchain-tests", "Run Ethereum blockchain test fixtures", bc_test_exe, &.{});

        // ── zkevm-blockchain-test-runner ──────────────────────────────────────
        const zkevm_test_exe = b.addExecutable(.{
            .name = "zkevm-blockchain-test-runner",
            .root_module = b.createModule(.{
                .root_source_file = b.path("tools/zkevm_test/main.zig"),
                .target = target,
                .optimize = optimize,
            }),
        });
        zkevm_test_exe.root_module.addImport("ssz_decode", mods.ssz_decode);
        zkevm_test_exe.root_module.addImport("ssz_output", mods.ssz_output);
        zkevm_test_exe.root_module.addImport("executor", mods.executor);
        addCryptoLibraries(zkevm_test_exe, crypto_backend, crypto_include, libblst_path, libmcl_path, is_linux);
        b.installArtifact(zkevm_test_exe);
        addRunStep(b, "zkevm-tests", "Run zkevm blockchain test fixtures", zkevm_test_exe, &.{ "--fixtures", "spec-tests/fixtures/zkevm/blockchain_tests" });
        addZkevmBenchmarkSteps(b, zkevm_test_exe);

        // ── transaction-test-runner ───────────────────────────────────────────
        const tx_test_exe = b.addExecutable(.{
            .name = "transaction-test-runner",
            .root_module = b.createModule(.{
                .root_source_file = b.path("tools/transaction_test/main.zig"),
                .target = target,
                .optimize = optimize,
            }),
        });
        tx_test_exe.root_module.addImport("executor", mods.executor);
        tx_test_exe.root_module.addImport("handler", mods.handler);
        tx_test_exe.root_module.addImport("context", mods.context);
        tx_test_exe.root_module.addImport("hardfork", mods.hardfork);
        tx_test_exe.root_module.addImport("primitives", mods.primitives);
        addCryptoLibraries(tx_test_exe, crypto_backend, crypto_include, libblst_path, libmcl_path, is_linux);
        b.installArtifact(tx_test_exe);
        addRunStep(b, "transaction-tests", "Run Ethereum transaction test fixtures", tx_test_exe, &.{ "--fixtures", "spec-tests/fixtures/transaction_tests" });

        // ── hive-rlp: Hive consume-rlp execution client ───────────────────────
        const hive_exe = b.addExecutable(.{
            .name = "hive-rlp",
            .root_module = b.createModule(.{
                .root_source_file = b.path("tools/hive/main.zig"),
                .target = target,
                .optimize = optimize,
            }),
        });
        hive_exe.root_module.addImport("primitives", mods.primitives);
        hive_exe.root_module.addImport("executor", mods.executor);
        hive_exe.root_module.addImport("hardfork", mods.hardfork);
        hive_exe.root_module.addImport("mpt", mods.mpt);
        addCryptoLibraries(hive_exe, crypto_backend, crypto_include, libblst_path, libmcl_path, is_linux);
        b.installArtifact(hive_exe);
        b.step("hive-rlp", "Build and install the Hive consume-rlp client").dependOn(b.getInstallStep());

        // ── Tests ─────────────────────────────────────────────────────────────
        const test_step = b.step("test", "Run all unit tests");
        test_step.dependOn(&run_block_rlp_size_test.step);

        for ([_]struct { m: *std.Build.Module, name: []const u8 }{
            .{ .m = mods.precompile, .name = "precompile" },
            .{ .m = mods.interpreter, .name = "interpreter" },
            .{ .m = mods.handler, .name = "handler" },
            .{ .m = mods.context, .name = "context" },
            .{ .m = mods.bytecode, .name = "bytecode" },
            .{ .m = mods.mpt, .name = "mpt" },
            .{ .m = mods.db, .name = "db" },
            .{ .m = mods.rlp_decode, .name = "rlp_decode" },
            .{ .m = mods.executor, .name = "executor" },
            .{ .m = mods.hardfork, .name = "hardfork" },
        }) |t| {
            const tst = b.addTest(.{ .root_module = t.m });
            _ = t.name;
            addCryptoLibraries(tst, crypto_backend, crypto_include, libblst_path, libmcl_path, is_linux);
            const run_tst = b.addRunArtifact(tst);
            test_step.dependOn(&run_tst.step);
        }
    }

    // ── rv64im relocatable object(s) ──────────────────────────────────────────
    //
    // Produces a relocatable rv64im ELF with all EVM and stateless execution logic
    // compiled in, but IO, crypto accelerators, heap and logging left as unresolved
    // extern references per zkvm-standards. Built from a private graph wired with the
    // bump allocator (over ZKVM_HEAP_POS/TOP) so the standalone object needs no set() call.
    //
    // `rv64im-object` targets the zkvm-standards baseline (M + Zicclsm + unaligned scalar
    // mem) shared across zkVM backends. `zisk-object` is the same graph on the same base
    // ISA, plus the Zbb and Zbs bit-manipulation extensions that ZisK's transpiler and cost
    // model support natively (see PRs #117, #119) — bitmanip instructions ZisK implements
    // as single ops but other zkVM backends may not, so they stay off the shared default
    // and are opt-in via this separate target instead of widening every consumer's ISA.
    //
    // Build with: zig build rv64im-object | zig build zisk-object
    // Verify undefined refs: llvm-nm zig-out/lib/<name> | grep ' U '
    addRv64imObjectStep(b, optimize, &.{ .m, .zicclsm, .unaligned_scalar_mem }, "rv64im-object", "Build relocatable rv64im ELF object (zesu.o)", "lib/zesu.o", .{});
    addRv64imObjectStep(b, optimize, &.{ .m, .zicclsm, .unaligned_scalar_mem, .zbb, .zbs }, "zisk-object", "Build relocatable rv64im+Zbb+Zbs ELF object for the ZisK guest (zesu-zisk.o)", "lib/zesu-zisk.o", .{ .dma = true });

    // ── Fixture fetch steps ───────────────────────────────────────────────────
    const spec_test_version = "tests@v21.0.1";
    const fetch_fixtures_step = b.step("fetch-fixtures", "Download execution-specs " ++ spec_test_version ++ " fixtures");
    fetch_fixtures_step.dependOn(&b.addSystemCommand(&.{
        "sh", "-c",
        "marker=spec-tests/.fixtures-" ++ spec_test_version ++ " && " ++
            "[ -f \"$marker\" ] && echo 'Fixtures already up to date.' && exit 0; " ++
            "echo 'Downloading execution-specs " ++ spec_test_version ++ " fixtures...' && " ++
            "rm -rf spec-tests/fixtures && mkdir -p spec-tests/fixtures && " ++
            "encoded=$(printf '%s' '" ++ spec_test_version ++ "' | sed 's/@/%40/g') && " ++
            "curl -fL \"https://github.com/ethereum/execution-specs/releases/download/${encoded}/fixtures.tar.gz\" " ++
            "| tar xz --strip-components=1 -C spec-tests/fixtures/ && " ++
            "touch \"$marker\" && " ++
            "echo 'Done. Fixtures extracted to spec-tests/fixtures/'",
    }).step);

    const zkevm_version = "tests-zkevm@v21.0.6";
    const fetch_zkevm_step = b.step("fetch-zkevm-fixtures", "Download " ++ zkevm_version ++ " execution-specs fixtures");
    fetch_zkevm_step.dependOn(&b.addSystemCommand(&.{
        "sh", "-c",
        "rm -rf spec-tests/fixtures/zkevm && " ++
            "mkdir -p spec-tests/fixtures/zkevm && " ++
            "echo 'Downloading " ++ zkevm_version ++ " fixtures...' && " ++
            "encoded=$(printf '%s' '" ++ zkevm_version ++ "' | sed 's/@/%40/g') && " ++
            "curl -fL \"https://github.com/ethereum/execution-specs/releases/download/${encoded}/fixtures_zkevm.tar.gz\" " ++
            "| tar xz --strip-components=1 -C spec-tests/fixtures/zkevm/ && " ++
            "echo 'Done. Fixtures extracted to spec-tests/fixtures/zkevm/'",
    }).step);

    // ── r2-stateless: execute latest R2 devnet batch natively ─────────────────
    // The catalog URL is defined here (single source of truth) and baked into
    // the tool as its default; the tool still accepts a runtime --catalog override.
    if (crypto_backend == .default) {
        const r2_catalog_url = "https://pub-afa6b160acfb4919bda1d0e2a00b5b77.r2.dev/testnets/sepolia";
        const r2_options = b.addOptions();
        r2_options.addOption([]const u8, "catalog_url", r2_catalog_url);

        const r2_exe = b.addExecutable(.{
            .name = "r2-stateless",
            .root_module = b.createModule(.{
                .root_source_file = b.path("tools/r2_stateless/main.zig"),
                .target = target,
                .optimize = optimize,
            }),
        });
        r2_exe.root_module.addImport("ssz_decode", mods.ssz_decode);
        r2_exe.root_module.addImport("ssz_output", mods.ssz_output);
        r2_exe.root_module.addImport("executor", mods.executor);
        r2_exe.root_module.addOptions("build_options", r2_options);
        addCryptoLibraries(r2_exe, crypto_backend, crypto_include, libblst_path, libmcl_path, is_linux);
        b.installArtifact(r2_exe);
        addRunStep(b, "r2-stateless", "Fetch and execute the latest R2 devnet batch", r2_exe, &.{});
    }
}