cli.cpp

Go to the documentation of this file.

 
#include "barretenberg/api/api_acir.hpp"
#include "barretenberg/api/api_avm.hpp"
#include "barretenberg/api/api_chonk.hpp"
#include "barretenberg/api/api_msgpack.hpp"
#include "barretenberg/api/api_ultra_honk.hpp"
#include "barretenberg/api/aztec_process.hpp"
#include "barretenberg/api/file_io.hpp"
#include "barretenberg/bb/cli11_formatter.hpp"
#include "barretenberg/bb/curve_constants.hpp"
#include "barretenberg/bbapi/bbapi.hpp"
#include "barretenberg/bbapi/bbapi_ultra_honk.hpp"
#include "barretenberg/bbapi/c_bind.hpp"
#include "barretenberg/common/assert.hpp"
#include "barretenberg/common/bb_bench.hpp"
#include "barretenberg/common/get_bytecode.hpp"
#include "barretenberg/common/memory_profile.hpp"
#include "barretenberg/common/thread.hpp"
#include "barretenberg/common/version.hpp"
#include "barretenberg/dsl/acir_format/serde/index.hpp"
#include "barretenberg/srs/factories/native_crs_factory.hpp"
#include "barretenberg/srs/global_crs.hpp"
#include "barretenberg/vm2/api_avm.hpp"
#include <atomic>
#include <fstream>
#include <iostream>
#include <mutex>
 
namespace bb {
 
// TODO(https://github.com/AztecProtocol/barretenberg/issues/1257): Remove unused/seemingly unnecessary flags.
// TODO(https://github.com/AztecProtocol/barretenberg/issues/1258): Improve defaults.
 
// Helper function to recursively print active subcommands for CLI11 app debugging
void print_active_subcommands(const CLI::App& app, const std::string& prefix = "bb command: ")
{
    // get_subcommands() returns a vector of pointers to subcommands
    for (auto* subcmd : app.get_subcommands()) {
        // Check if this subcommand was activated (nonzero count)
        if (subcmd->count() > 0) {
            vinfo(prefix, subcmd->get_name());
            // Recursively print any subcommands of this subcommand
            print_active_subcommands(*subcmd, prefix + "  ");
        }
    }
}
 
// Recursive helper to find the deepest parsed subcommand.
CLI::App* find_deepest_subcommand(CLI::App* app)
{
    for (auto& sub : app->get_subcommands()) {
        if (sub->parsed()) {
            // Check recursively if this subcommand has a deeper parsed subcommand.
            if (CLI::App* deeper = find_deepest_subcommand(sub); deeper != nullptr) {
                return deeper;
            }
            return sub;
        }
    }
    return nullptr;
}
 
// Helper function to print options for a given subcommand.
void print_subcommand_options(const CLI::App* sub)
{
    for (const auto& opt : sub->get_options()) {
        if (opt->count() > 0) { // Only print options that were set.
            if (opt->results().size() > 1) {
                vinfo("  Warning: the following option is called more than once");
            }
            vinfo("  ", opt->get_name(), ": ", opt->results()[0]);
        }
    }
}
 
int parse_and_run_cli_command(int argc, char* argv[])
{
    std::string name = "Barretenberg\nYour favo(u)rite zkSNARK library written in C++, a perfectly good computer "
                       "programming language.";
 
    // Check AVM support at runtime via global boolean
    if (avm_enabled) {
        name += "\nAztec Virtual Machine (AVM): enabled";
    } else {
        name += "\nAztec Virtual Machine (AVM): disabled";
    }
#ifdef ENABLE_AVM_TRANSPILER
    name += "\nAVM Transpiler: enabled";
#else
    name += "\nAVM Transpiler: disabled";
#endif
#ifdef STARKNET_GARAGA_FLAVORS
    name += "\nStarknet Garaga Extensions: enabled";
#else
    name += "\nStarknet Garaga Extensions: disabled";
#endif
    CLI::App app{ name };
    argv = app.ensure_utf8(argv);
    app.formatter(std::make_shared<Formatter>());
 
    // If no arguments are provided, print help and exit.
    if (argc == 1) {
        std::cout << app.help() << std::endl;
        return 0;
    }
 
    // prevent two or more subcommands being executed
    app.require_subcommand(0, 1);
 
    API::Flags flags{};
    // Some paths, with defaults, that may or may not be set by commands
    std::filesystem::path bytecode_path{ "./target/program.json" };
    std::filesystem::path witness_path{ "./target/witness.gz" };
    std::filesystem::path ivc_inputs_path{ "./ivc-inputs.msgpack" };
    std::filesystem::path output_path{
        "./out"
    }; // sometimes a directory where things will be written, sometimes the path of a file to be written
    std::filesystem::path public_inputs_path{ "./target/public_inputs" };
    std::filesystem::path proof_path{ "./target/proof" };
    std::filesystem::path vk_path{ "./target/vk" };
    flags.scheme = "";
    flags.oracle_hash_type = "poseidon2";
    flags.crs_path = srs::bb_crs_path();
    flags.include_gates_per_opcode = false;
 
    /***************************************************************************************************************
     * Flag: --help-extended (detected early to set group visibility)
     ***************************************************************************************************************/
    // Check if --help-extended was passed before parsing (since we need to modify group visibility before CLI setup)
    bool show_extended_help = false;
    for (int i = 1; i < argc; ++i) {
        if (std::string(argv[i]) == "--help-extended") {
            show_extended_help = true;
            break;
        }
    }
    // Group names - empty string hides the group from help, non-empty shows it
    const std::string advanced_group = show_extended_help ? "Advanced Options (Aztec/Power Users)" : "";
    const std::string aztec_internal_group = show_extended_help ? "Aztec Internal Commands" : "";
 
    const auto add_output_path_option = [&](CLI::App* subcommand, auto& _output_path) {
        return subcommand->add_option("--output_path, -o",
                                      _output_path,
                                      "Directory to write files or path of file to write, depending on subcommand.");
    };
 
    // Helper to add --help-extended to subcommands (for help consistency)
    const auto add_help_extended_flag = [&](CLI::App* subcommand) {
        subcommand->add_flag("--help-extended", "Show all options including advanced ones.");
    };
 
    /***************************************************************************************************************
     * Subcommand: Adders for options that we will create for more than one subcommand
     ***************************************************************************************************************/
 
    const auto add_ipa_accumulation_flag = [&](CLI::App* subcommand) {
        return subcommand
            ->add_flag("--ipa_accumulation",
                       flags.ipa_accumulation,
                       "Accumulate/Aggregate IPA (Inner Product Argument) claims")
            ->group(advanced_group);
    };
 
    const auto add_scheme_option = [&](CLI::App* subcommand) {
        return subcommand
            ->add_option(
                "--scheme, -s",
                flags.scheme,
                "The type of proof to be constructed. This can specify a proving system, an accumulation scheme, or a "
                "particular type of circuit to be constructed and proven for some implicit scheme.")
            ->envname("BB_SCHEME")
            ->default_val("ultra_honk")
            ->check(CLI::IsMember({ "chonk", "avm", "ultra_honk" }).name("is_member"))
            ->group(advanced_group);
    };
 
    const auto add_crs_path_option = [&](CLI::App* subcommand) {
        return subcommand
            ->add_option("--crs_path, -c",
                         flags.crs_path,
                         "Path CRS directory. Missing CRS files will be retrieved from the internet.")
            ->check(CLI::ExistingDirectory)
            ->group(advanced_group);
    };
 
    const auto add_oracle_hash_option = [&](CLI::App* subcommand) {
        return subcommand
            ->add_option(
                "--oracle_hash",
                flags.oracle_hash_type,
                "The hash function used by the prover as random oracle standing in for a verifier's challenge "
                "generation. Poseidon2 is to be used for proofs that are intended to be verified inside of a "
                "circuit. Keccak is optimized for verification in an Ethereum smart contract, where Keccak "
                "has a privileged position due to the existence of an EVM precompile. Starknet is optimized "
                "for verification in a Starknet smart contract, which can be generated using the Garaga library. "
                "Prefer using --verifier_target instead.")
            ->check(CLI::IsMember({ "poseidon2", "keccak", "starknet" }).name("is_member"))
            ->group(advanced_group);
    };
 
    const auto add_verifier_target_option = [&](CLI::App* subcommand) {
        return subcommand
            ->add_option("--verifier_target, -t",
                         flags.verifier_target,
                         "Target verification environment. Determines hash function and ZK settings.\n"
                         "\n"
                         "Options:\n"
                         "  evm                  Ethereum/Solidity (keccak, ZK)\n"
                         "  evm-no-zk            Ethereum/Solidity without ZK\n"
                         "  noir-recursive       Noir circuits (poseidon2, ZK)\n"
                         "  noir-recursive-no-zk Noir circuits without ZK\n"
                         "  noir-rollup          Rollup with IPA (poseidon2, ZK)\n"
                         "  noir-rollup-no-zk    Rollup without ZK\n"
                         "  starknet             Starknet via Garaga (ZK)\n"
                         "  starknet-no-zk       Starknet without ZK")
            ->envname("BB_VERIFIER_TARGET")
            ->check(CLI::IsMember({ "evm",
                                    "evm-no-zk",
                                    "noir-recursive",
                                    "noir-recursive-no-zk",
                                    "noir-rollup",
                                    "noir-rollup-no-zk",
                                    "starknet",
                                    "starknet-no-zk" }));
    };
 
    const auto add_write_vk_flag = [&](CLI::App* subcommand) {
        return subcommand->add_flag("--write_vk", flags.write_vk, "Write the provided circuit's verification key");
    };
 
    const auto remove_zk_option = [&](CLI::App* subcommand) {
        return subcommand
            ->add_flag("--disable_zk",
                       flags.disable_zk,
                       "Use a non-zk version of --scheme. Prefer using --verifier_target *-no-zk variants instead.")
            ->group(advanced_group);
    };
 
    const auto add_bytecode_path_option = [&](CLI::App* subcommand) {
        subcommand->add_option("--bytecode_path, -b", bytecode_path, "Path to ACIR bytecode generated by Noir.")
            /* ->check(CLI::ExistingFile) OR stdin indicator - */;
    };
 
    const auto add_witness_path_option = [&](CLI::App* subcommand) {
        subcommand->add_option("--witness_path, -w", witness_path, "Path to partial witness generated by Noir.")
            /* ->check(CLI::ExistingFile) OR stdin indicator - */;
    };
 
    const auto add_ivc_inputs_path_options = [&](CLI::App* subcommand) {
        subcommand
            ->add_option(
                "--ivc_inputs_path", ivc_inputs_path, "For IVC, path to input stack with bytecode and witnesses.")
            ->group(advanced_group);
    };
 
    const auto add_public_inputs_path_option = [&](CLI::App* subcommand) {
        return subcommand->add_option(
            "--public_inputs_path, -i", public_inputs_path, "Path to public inputs.") /* ->check(CLI::ExistingFile) */;
    };
 
    const auto add_proof_path_option = [&](CLI::App* subcommand) {
        return subcommand->add_option(
            "--proof_path, -p", proof_path, "Path to a proof.") /* ->check(CLI::ExistingFile) */;
    };
 
    const auto add_vk_path_option = [&](CLI::App* subcommand) {
        return subcommand->add_option("--vk_path, -k", vk_path, "Path to a verification key.")
            /* ->check(CLI::ExistingFile) */;
    };
 
    const auto add_verbose_flag = [&](CLI::App* subcommand) {
        return subcommand->add_flag("--verbose, --verbose_logging, -v", flags.verbose, "Output all logs to stderr.")
            ->group(advanced_group);
    };
 
    const auto add_debug_flag = [&](CLI::App* subcommand) {
        return subcommand->add_flag("--debug_logging, -d", flags.debug, "Output debug logs to stderr.")
            ->group(advanced_group);
    };
 
    bool disable_asserts = false;
    const auto add_disable_asserts_flag = [&](CLI::App* subcommand) {
        return subcommand
            ->add_flag("--disable_asserts",
                       disable_asserts,
                       "Disable BB assertions (asserts become warnings). Not for production use.")
            ->group(advanced_group);
    };
 
    const auto add_include_gates_per_opcode_flag = [&](CLI::App* subcommand) {
        return subcommand->add_flag("--include_gates_per_opcode",
                                    flags.include_gates_per_opcode,
                                    "Include gates_per_opcode in the output of the gates command.");
    };
 
    const auto add_slow_low_memory_flag = [&](CLI::App* subcommand) {
        return subcommand
            ->add_flag("--slow_low_memory", flags.slow_low_memory, "Enable low memory mode (can be 2x slower or more).")
            ->group(advanced_group);
    };
 
    const auto add_storage_budget_option = [&](CLI::App* subcommand) {
        return subcommand
            ->add_option("--storage_budget",
                         flags.storage_budget,
                         "Storage budget for FileBackedMemory (e.g. '500m', '2g'). When exceeded, falls "
                         "back to RAM (requires --slow_low_memory).")
            ->group(advanced_group);
    };
 
    const auto add_vk_policy_option = [&](CLI::App* subcommand) {
        return subcommand
            ->add_option("--vk_policy",
                         flags.vk_policy,
                         "Policy for handling verification keys. 'default' uses the provided VK as-is, 'check' "
                         "verifies the provided VK matches the computed VK (throws error on mismatch), 'recompute' "
                         "always ignores the provided VK and treats it as nullptr, 'rewrite' checks the VK and "
                         "rewrites the input file with the correct VK if there's a mismatch (for check command).")
            ->check(CLI::IsMember({ "default", "check", "recompute", "rewrite" }).name("is_member"))
            ->group(advanced_group);
    };
 
    const auto add_use_zk_flavor_flag = [&](CLI::App* subcommand) {
        return subcommand
            ->add_flag("--use_zk_flavor",
                       flags.use_zk_flavor,
                       "Chonk-only: derive the VK against MegaZKFlavor rather than MegaFlavor. "
                       "Set this for the IVC hiding kernel (the only Chonk circuit proven as MegaZK).")
            ->group(advanced_group);
    };
 
    const auto add_optimized_solidity_verifier_flag = [&](CLI::App* subcommand) {
        return subcommand->add_flag(
            "--optimized", flags.optimized_solidity_verifier, "Use the optimized Solidity verifier.");
    };
 
    const auto add_output_format_option = [&](CLI::App* subcommand) {
        return subcommand
            ->add_option("--output_format",
                         flags.output_format,
                         "Output format for proofs and verification keys: 'binary' (default) or 'json'.\n"
                         "JSON format includes metadata like bb_version, scheme, and verifier_target.")
            ->check(CLI::IsMember({ "binary", "json" }).name("is_member"));
    };
 
    bool print_bench = false;
    const auto add_print_bench_flag = [&](CLI::App* subcommand) {
        return subcommand
            ->add_flag(
                "--print_bench", print_bench, "Pretty print op counts to standard error in a human-readable format.")
            ->group(advanced_group);
    };
 
    std::string bench_out;
    const auto add_bench_out_option = [&](CLI::App* subcommand) {
        return subcommand->add_option("--bench_out", bench_out, "Path to write the op counts in a json.")
            ->group(advanced_group);
    };
    std::string bench_out_hierarchical;
    const auto add_bench_out_hierarchical_option = [&](CLI::App* subcommand) {
        return subcommand
            ->add_option("--bench_out_hierarchical",
                         bench_out_hierarchical,
                         "Path to write the hierarchical benchmark data (op counts and timings with "
                         "parent-child relationships) as json.")
            ->group(advanced_group);
    };
    std::string memory_profile_out;
    const auto add_memory_profile_out_option = [&](CLI::App* subcommand) {
        return subcommand
            ->add_option("--memory_profile_out",
                         memory_profile_out,
                         "Path to write memory profile data (polynomial breakdown by category, RSS "
                         "checkpoints, CRS size) as json.")
            ->group(advanced_group);
    };
 
    std::string trace_out_perfetto;
    const auto add_trace_out_perfetto_option = [&](CLI::App* subcommand) {
        return subcommand
            ->add_option("--trace_out_perfetto",
                         trace_out_perfetto,
                         "Path to write a Chrome Trace Event Format JSON of every instrumented "
                         "BB_BENCH scope (per-call timeline). Drop the file into ui.perfetto.dev "
                         "or chrome://tracing.")
            ->group(advanced_group);
    };
    std::string trace_out_perfetto_aggregate;
    const auto add_trace_out_perfetto_aggregate_option = [&](CLI::App* subcommand) {
        return subcommand
            ->add_option("--trace_out_perfetto_aggregate",
                         trace_out_perfetto_aggregate,
                         "Path to write a synthesized Chrome Trace Event Format JSON derived from the "
                         "aggregate stats. Smaller than --trace_out_perfetto but lossy about individual "
                         "call timing.")
            ->group(advanced_group);
    };
 
    /***************************************************************************************************************
     * Top-level flags
     ***************************************************************************************************************/
    add_verbose_flag(&app);
    add_debug_flag(&app);
    add_crs_path_option(&app);
 
    /***************************************************************************************************************
     * Builtin flag: --version
     ***************************************************************************************************************/
    app.set_version_flag("--version", BB_VERSION, "Print the version string.");
 
    /***************************************************************************************************************
     * Flag: --help-extended (register with CLI11)
     ***************************************************************************************************************/
    app.add_flag("--help-extended", "Show all options including advanced and Aztec-specific commands.");
 
    /***************************************************************************************************************
     * Subcommand: acir_roundtrip
     ***************************************************************************************************************/
    std::filesystem::path acir_roundtrip_output_path;
    CLI::App* acir_roundtrip_cmd =
        app.add_subcommand("acir_roundtrip",
                           "[Internal testing] Deserialize an ACIR program from bytecode (msgpack), "
                           "re-serialize it back to msgpack, and write it to an output JSON file "
                           "in nargo-compatible format. Functional equivalence should then be verified "
                           "externally (e.g. by proving with the roundtripped bytecode).");
 
    acir_roundtrip_cmd->group(aztec_internal_group);
    add_bytecode_path_option(acir_roundtrip_cmd);
    acir_roundtrip_cmd
        ->add_option("--output_path,-o", acir_roundtrip_output_path, "Output path for the roundtripped bytecode JSON.")
        ->required();
 
    /***************************************************************************************************************
     * Subcommand: check
     ***************************************************************************************************************/
    CLI::App* check = app.add_subcommand(
        "check",
        "A debugging tool to quickly check whether a witness satisfies a circuit The "
        "function constructs the execution trace and iterates through it row by row, applying the "
        "polynomial relations defining the gate types. For Chonk, we check the VKs in the folding stack.");
 
    add_help_extended_flag(check);
    add_scheme_option(check);
    add_bytecode_path_option(check);
    add_witness_path_option(check);
    add_ivc_inputs_path_options(check);
    add_vk_policy_option(check);
    add_disable_asserts_flag(check);
 
    /***************************************************************************************************************
     * Subcommand: gates
     ***************************************************************************************************************/
    CLI::App* gates = app.add_subcommand("gates",
                                         "Construct a circuit from the given bytecode (in particular, expand black box "
                                         "functions) and return the gate count information.");
 
    add_help_extended_flag(gates);
    add_scheme_option(gates);
    add_verbose_flag(gates);
    add_bytecode_path_option(gates);
    add_include_gates_per_opcode_flag(gates);
    add_verifier_target_option(gates);
    add_oracle_hash_option(gates);
    add_ipa_accumulation_flag(gates);
 
    /***************************************************************************************************************
     * Subcommand: prove
     ***************************************************************************************************************/
    CLI::App* prove = app.add_subcommand("prove", "Generate a proof.");
 
    add_help_extended_flag(prove);
    add_scheme_option(prove);
    add_bytecode_path_option(prove);
    add_witness_path_option(prove);
    add_output_path_option(prove, output_path);
    add_ivc_inputs_path_options(prove);
    add_vk_path_option(prove);
    add_vk_policy_option(prove);
    add_verbose_flag(prove);
    add_debug_flag(prove);
    add_crs_path_option(prove);
    add_verifier_target_option(prove);
    add_oracle_hash_option(prove);
    add_write_vk_flag(prove);
    add_ipa_accumulation_flag(prove);
    remove_zk_option(prove);
    add_slow_low_memory_flag(prove);
    add_print_bench_flag(prove);
    add_bench_out_option(prove);
    add_bench_out_hierarchical_option(prove);
    add_memory_profile_out_option(prove);
    add_trace_out_perfetto_option(prove);
    add_trace_out_perfetto_aggregate_option(prove);
    add_storage_budget_option(prove);
    add_output_format_option(prove);
 
    prove->add_flag("--verify", "Verify the proof natively, resulting in a boolean output. Useful for testing.");
 
    /***************************************************************************************************************
     * Subcommand: write_vk
     ***************************************************************************************************************/
    CLI::App* write_vk =
        app.add_subcommand("write_vk",
                           "Write the verification key of a circuit. The circuit is constructed using "
                           "quickly generated but invalid witnesses (which must be supplied in Barretenberg in order "
                           "to expand ACIR black box opcodes), and no proof is constructed.");
 
    add_help_extended_flag(write_vk);
    add_scheme_option(write_vk);
    add_bytecode_path_option(write_vk);
    add_output_path_option(write_vk, output_path);
    add_ivc_inputs_path_options(write_vk);
 
    add_verbose_flag(write_vk);
    add_debug_flag(write_vk);
    add_crs_path_option(write_vk);
    add_verifier_target_option(write_vk);
    add_oracle_hash_option(write_vk);
    add_ipa_accumulation_flag(write_vk);
    remove_zk_option(write_vk);
    add_output_format_option(write_vk);
    add_use_zk_flavor_flag(write_vk);
 
    /***************************************************************************************************************
     * Subcommand: verify
     ***************************************************************************************************************/
    CLI::App* verify = app.add_subcommand("verify", "Verify a proof.");
 
    add_help_extended_flag(verify);
    add_public_inputs_path_option(verify);
    add_proof_path_option(verify);
    add_vk_path_option(verify);
 
    add_verbose_flag(verify);
    add_debug_flag(verify);
    add_scheme_option(verify);
    add_crs_path_option(verify);
    add_verifier_target_option(verify);
    add_oracle_hash_option(verify);
    remove_zk_option(verify);
    add_ipa_accumulation_flag(verify);
 
    /***************************************************************************************************************
     * Subcommand: batch_verify
     ***************************************************************************************************************/
    std::filesystem::path batch_verify_proofs_dir{ "./proofs" };
    CLI::App* batch_verify =
        app.add_subcommand("batch_verify", "Batch-verify multiple Chonk proofs with a single IPA SRS MSM.");
 
    add_help_extended_flag(batch_verify);
    add_scheme_option(batch_verify);
    batch_verify->add_option("--proofs_dir", batch_verify_proofs_dir, "Directory containing proof_N/vk_N pairs.");
    add_verbose_flag(batch_verify);
    add_debug_flag(batch_verify);
    add_crs_path_option(batch_verify);
 
    /***************************************************************************************************************
     * Subcommand: proof_stats
     ***************************************************************************************************************/
    CLI::App* proof_stats =
        app.add_subcommand("proof_stats", "Output proof statistics (compressed size, number of public inputs).");
 
    add_help_extended_flag(proof_stats);
    add_scheme_option(proof_stats);
    add_proof_path_option(proof_stats);
    add_output_path_option(proof_stats, output_path);
    add_verbose_flag(proof_stats);
 
    /***************************************************************************************************************
     * Subcommand: write_solidity_verifier
     ***************************************************************************************************************/
    CLI::App* write_solidity_verifier =
        app.add_subcommand("write_solidity_verifier",
                           "Write a Solidity smart contract suitable for verifying proofs of circuit "
                           "satisfiability for the circuit with verification key at vk_path. Not all "
                           "hash types are implemented due to efficiency concerns.");
 
    add_help_extended_flag(write_solidity_verifier);
    add_scheme_option(write_solidity_verifier);
    add_vk_path_option(write_solidity_verifier);
    add_output_path_option(write_solidity_verifier, output_path);
 
    add_verbose_flag(write_solidity_verifier);
    add_verifier_target_option(write_solidity_verifier);
    remove_zk_option(write_solidity_verifier);
    add_crs_path_option(write_solidity_verifier);
    add_optimized_solidity_verifier_flag(write_solidity_verifier);
 
    std::filesystem::path avm_inputs_path{ "./target/avm_inputs.bin" };
    const auto add_avm_inputs_option = [&](CLI::App* subcommand) {
        return subcommand->add_option("--avm-inputs", avm_inputs_path, "");
    };
    std::filesystem::path avm_public_inputs_path{ "./target/avm_public_inputs.bin" };
    const auto add_avm_public_inputs_option = [&](CLI::App* subcommand) {
        return subcommand->add_option("--avm-public-inputs", avm_public_inputs_path, "");
    };
 
    /***************************************************************************************************************
     * Subcommand: avm_simulate
     ***************************************************************************************************************/
    CLI::App* avm_simulate_command = app.add_subcommand("avm_simulate", "Simulate AVM execution.");
    avm_simulate_command->group(aztec_internal_group);
    add_verbose_flag(avm_simulate_command);
    add_debug_flag(avm_simulate_command);
    add_avm_inputs_option(avm_simulate_command);
 
    /***************************************************************************************************************
     * Subcommand: avm_prove
     ***************************************************************************************************************/
    CLI::App* avm_prove_command = app.add_subcommand("avm_prove", "Generate an AVM proof.");
    avm_prove_command->group(aztec_internal_group);
    add_verbose_flag(avm_prove_command);
    add_debug_flag(avm_prove_command);
    add_crs_path_option(avm_prove_command);
    std::filesystem::path avm_prove_output_path{ "./proofs" };
    add_output_path_option(avm_prove_command, avm_prove_output_path);
    add_avm_inputs_option(avm_prove_command);
 
    /***************************************************************************************************************
     * Subcommand: avm_write_vk
     ***************************************************************************************************************/
    CLI::App* avm_write_vk_command = app.add_subcommand("avm_write_vk", "Write AVM verification key.");
    avm_write_vk_command->group(aztec_internal_group);
    add_verbose_flag(avm_write_vk_command);
    add_debug_flag(avm_write_vk_command);
    add_crs_path_option(avm_write_vk_command);
    std::filesystem::path avm_write_vk_output_path{ "./keys" };
    add_output_path_option(avm_write_vk_command, avm_write_vk_output_path);
 
    /***************************************************************************************************************
     * Subcommand: avm_check_circuit
     ***************************************************************************************************************/
    CLI::App* avm_check_circuit_command = app.add_subcommand("avm_check_circuit", "Check AVM circuit satisfiability.");
    avm_check_circuit_command->group(aztec_internal_group);
    add_verbose_flag(avm_check_circuit_command);
    add_debug_flag(avm_check_circuit_command);
    add_crs_path_option(avm_check_circuit_command);
    add_avm_inputs_option(avm_check_circuit_command);
 
    /***************************************************************************************************************
     * Subcommand: avm_verify
     ***************************************************************************************************************/
    CLI::App* avm_verify_command = app.add_subcommand("avm_verify", "Verify an AVM proof.");
    avm_verify_command->group(aztec_internal_group);
    add_verbose_flag(avm_verify_command);
    add_debug_flag(avm_verify_command);
    add_crs_path_option(avm_verify_command);
    add_avm_public_inputs_option(avm_verify_command);
    add_proof_path_option(avm_verify_command);
 
    /***************************************************************************************************************
     * Subcommand: aztec_process_artifact
     ***************************************************************************************************************/
    CLI::App* aztec_process = app.add_subcommand(
        "aztec_process",
        "Process Aztec contract artifacts: transpile and generate verification keys for all private functions.\n"
        "If input is a directory (and no output specified), recursively processes all artifacts found in the "
        "directory.\n"
        "Multiple -i flags can be specified when no -o flag is present for parallel processing.");
    aztec_process->group(aztec_internal_group);
 
    std::vector<std::string> artifact_input_paths;
    std::string artifact_output_path;
    bool force_regenerate = false;
 
    aztec_process->add_option("-i,--input",
                              artifact_input_paths,
                              "Input artifact JSON path or directory to search (optional, defaults to current "
                              "directory). Can be specified multiple times when no -o flag is present.");
    aztec_process->add_option(
        "-o,--output",
        artifact_output_path,
        "Output artifact JSON path (optional, same as input if not specified). Cannot be used with multiple -i flags.");
    aztec_process->add_flag("-f,--force", force_regenerate, "Force regeneration of verification keys");
    add_verbose_flag(aztec_process);
    add_debug_flag(aztec_process);
 
    /***************************************************************************************************************
     * Subcommand: aztec_process cache_paths
     ***************************************************************************************************************/
    CLI::App* cache_paths_command =
        aztec_process->add_subcommand("cache_paths",
                                      "Output cache paths for verification keys in an artifact.\n"
                                      "Format: <hash>:<cache_path>:<function_name> (one per line).");
 
    std::string cache_paths_input;
    cache_paths_command->add_option("input", cache_paths_input, "Input artifact JSON path (required).")->required();
    add_verbose_flag(cache_paths_command);
    add_debug_flag(cache_paths_command);
 
    /***************************************************************************************************************
     * Subcommand: msgpack
     ***************************************************************************************************************/
    CLI::App* msgpack_command = app.add_subcommand("msgpack", "Msgpack API interface.");
 
    // Subcommand: msgpack schema
    CLI::App* msgpack_schema_command =
        msgpack_command->add_subcommand("schema", "Output a msgpack schema encoded as JSON to stdout.");
    add_verbose_flag(msgpack_schema_command);
 
    // Subcommand: msgpack curve_constants
    CLI::App* msgpack_curve_constants_command =
        msgpack_command->add_subcommand("curve_constants", "Output curve constants as msgpack to stdout.");
    add_verbose_flag(msgpack_curve_constants_command);
 
    // Subcommand: msgpack run
    CLI::App* msgpack_run_command =
        msgpack_command->add_subcommand("run", "Execute msgpack API commands from stdin or file.");
    add_verbose_flag(msgpack_run_command);
    std::string msgpack_input_file;
    msgpack_run_command->add_option(
        "-i,--input", msgpack_input_file, "Input file containing msgpack buffers (defaults to stdin)");
    size_t request_ring_size = 1024 * 1024; // 1MB default
    msgpack_run_command
        ->add_option(
            "--request-ring-size", request_ring_size, "Request ring buffer size for shared memory IPC (default: 1MB)")
        ->check(CLI::PositiveNumber);
    size_t response_ring_size = 1024 * 1024; // 1MB default
    msgpack_run_command
        ->add_option("--response-ring-size",
                     response_ring_size,
                     "Response ring buffer size for shared memory IPC (default: 1MB)")
        ->check(CLI::PositiveNumber);
    int max_clients = 1;
    msgpack_run_command
        ->add_option("--max-clients",
                     max_clients,
                     "Maximum concurrent clients for socket IPC servers (default: 1, only used for .sock files)")
        ->check(CLI::PositiveNumber);
 
    /***************************************************************************************************************
     * Build the CLI11 App
     ***************************************************************************************************************/
 
    CLI11_PARSE(app, argc, argv);
 
    // Handle --help-extended: print help and exit
    if (show_extended_help) {
        std::cout << app.help() << '\n';
        return 0;
    }
 
    // Apply verifier_target to derive oracle_hash_type, disable_zk, and ipa_accumulation
    // This only applies when verifier_target is explicitly set
    if (!flags.verifier_target.empty()) {
        // Check for conflicting flags - verifier_target should not be combined with low-level flags
        // We need to check the active subcommand for these options
        CLI::App* active_sub = find_deepest_subcommand(&app);
        if (active_sub != nullptr) {
            // Helper to safely get option count (returns 0 if option doesn't exist)
            auto get_option_count = [](CLI::App* sub, const std::string& name) -> size_t {
                try {
                    return sub->get_option(name)->count();
                } catch (const CLI::OptionNotFound&) {
                    return 0;
                }
            };
 
            if (get_option_count(active_sub, "--oracle_hash") > 0) {
                throw_or_abort("Cannot use --verifier_target with --oracle_hash. "
                               "The --verifier_target flag sets oracle_hash automatically.");
            }
            if (get_option_count(active_sub, "--disable_zk") > 0) {
                throw_or_abort("Cannot use --verifier_target with --disable_zk. "
                               "Use a '-no-zk' variant of --verifier_target instead (e.g., 'evm-no-zk').");
            }
            if (get_option_count(active_sub, "--ipa_accumulation") > 0) {
                throw_or_abort("Cannot use --verifier_target with --ipa_accumulation. "
                               "Use '--verifier_target noir-rollup' for IPA accumulation.");
            }
        }
 
        // Map verifier_target to underlying flags
        if (flags.verifier_target == "evm") {
            flags.oracle_hash_type = "keccak";
        } else if (flags.verifier_target == "evm-no-zk") {
            flags.oracle_hash_type = "keccak";
            flags.disable_zk = true;
        } else if (flags.verifier_target == "noir-recursive") {
            flags.oracle_hash_type = "poseidon2";
        } else if (flags.verifier_target == "noir-recursive-no-zk") {
            flags.oracle_hash_type = "poseidon2";
            flags.disable_zk = true;
        } else if (flags.verifier_target == "noir-rollup") {
            flags.oracle_hash_type = "poseidon2";
            flags.ipa_accumulation = true;
        } else if (flags.verifier_target == "noir-rollup-no-zk") {
            flags.oracle_hash_type = "poseidon2";
            flags.ipa_accumulation = true;
            flags.disable_zk = true;
        } else if (flags.verifier_target == "starknet") {
            flags.oracle_hash_type = "starknet";
        } else if (flags.verifier_target == "starknet-no-zk") {
            flags.oracle_hash_type = "starknet";
            flags.disable_zk = true;
        }
        vinfo("verifier_target '",
              flags.verifier_target,
              "' -> oracle_hash_type='",
              flags.oracle_hash_type,
              "', disable_zk=",
              flags.disable_zk,
              ", ipa_accumulation=",
              flags.ipa_accumulation);
    }
 
    // Immediately after parsing, we can init the global CRS factory. Note this does not yet read or download any
    // points; that is done on-demand.
    srs::init_net_crs_factory(flags.crs_path);
    if ((prove->parsed() || write_vk->parsed()) && output_path != "-") {
        // If writing to an output folder, make sure it exists.
        std::filesystem::create_directories(output_path);
    }
    if (flags.debug) {
        bb_log_level = LogLevel::DEBUG;
    } else if (flags.verbose) {
        bb_log_level = LogLevel::VERBOSE;
    }
    slow_low_memory = flags.slow_low_memory;
#if !defined(__wasm__) || defined(ENABLE_WASM_BENCH)
    if (!flags.storage_budget.empty()) {
        storage_budget = parse_size_string(flags.storage_budget);
    }
    if (!memory_profile_out.empty()) {
        bb::detail::use_memory_profile = true;
        vinfo("Memory profiling enabled via --memory_profile_out");
    }
    if (print_bench || !bench_out.empty() || !bench_out_hierarchical.empty() || !trace_out_perfetto.empty() ||
        !trace_out_perfetto_aggregate.empty()) {
        bb::detail::use_bb_bench = true;
        vinfo("BB_BENCH enabled via --print_bench / --bench_out / --trace_out_perfetto");
    }
    if (!trace_out_perfetto.empty()) {
        bb::detail::capture_per_call_events.store(true);
        vinfo("Per-call BB_BENCH event capture enabled via --trace_out_perfetto");
    }
#endif
 
    print_active_subcommands(app);
    info("Scheme is: ", flags.scheme, ", num threads: ", get_num_cpus());
    if (CLI::App* deepest = find_deepest_subcommand(&app)) {
        print_subcommand_options(deepest);
    }
 
    // TODO(AD): it is inflexible that Chonk shares an API command (prove) with UH this way. The base API class is a
    // poor fit. It would be better to have a separate handling for each scheme with subcommands to prove.
    const auto execute_non_prove_command = [&](API& api) {
        if (check->parsed()) {
            api.check(flags, bytecode_path, witness_path);
            return 0;
        }
        if (gates->parsed()) {
            api.gates(flags, bytecode_path);
            return 0;
        }
        if (write_vk->parsed()) {
            api.write_vk(flags, bytecode_path, output_path);
            return 0;
        }
        if (verify->parsed()) {
            const bool verified = api.verify(flags, public_inputs_path, proof_path, vk_path);
            vinfo("verified: ", verified);
            return verified ? 0 : 1;
        }
        if (write_solidity_verifier->parsed()) {
            // Validate that verifier_target is compatible with Solidity verifier
            if (!flags.verifier_target.empty() && flags.verifier_target != "evm" &&
                flags.verifier_target != "evm-no-zk") {
                throw_or_abort("write_solidity_verifier requires --verifier_target to be 'evm' or 'evm-no-zk', got '" +
                               flags.verifier_target + "'");
            }
            api.write_solidity_verifier(flags, output_path, vk_path);
            return 0;
        }
        auto subcommands = app.get_subcommands();
        const std::string message = std::string("No handler for subcommand ") + subcommands[0]->get_name();
        throw_or_abort(message);
        return 1;
    };
 
    try {
        // ACIR roundtrip (internal testing)
        if (acir_roundtrip_cmd->parsed()) {
            acir_roundtrip(bytecode_path, acir_roundtrip_output_path);
            return 0;
        }
 
        // MSGPACK
        if (msgpack_schema_command->parsed()) {
            std::cout << bbapi::get_msgpack_schema_as_json() << std::endl;
            return 0;
        }
        if (msgpack_curve_constants_command->parsed()) {
            write_curve_constants_msgpack_to_stdout();
            return 0;
        }
        if (msgpack_run_command->parsed()) {
            return execute_msgpack_run(msgpack_input_file, max_clients, request_ring_size, response_ring_size);
        }
        if (aztec_process->parsed()) {
#ifdef __wasm__
            throw_or_abort("Aztec artifact processing is not supported in WASM builds.");
#else
            // Handle cache_paths subcommand
            if (cache_paths_command->parsed()) {
                return get_cache_paths(cache_paths_input) ? 0 : 1;
            }
 
            // Check for invalid combination of multiple inputs with output path
            if (!artifact_output_path.empty() && artifact_input_paths.size() > 1) {
                throw_or_abort("Cannot specify --output when multiple --input flags are provided.");
            }
 
            // Default to current directory if no inputs specified
            if (artifact_input_paths.empty()) {
                artifact_input_paths.push_back(".");
            }
 
            // Handle multiple inputs (process in parallel)
            if (artifact_input_paths.size() > 1) {
                // Validate all inputs are files, not directories
                for (const auto& input : artifact_input_paths) {
                    if (std::filesystem::is_directory(input)) {
                        throw_or_abort("When using multiple --input flags, all inputs must be files, not directories.");
                    }
                }
 
                // Process all artifacts in parallel
                std::atomic<bool> all_success = true;
                std::vector<std::string> failures;
                std::mutex failures_mutex;
 
                parallel_for(artifact_input_paths.size(), [&](size_t i) {
                    const auto& input = artifact_input_paths[i];
                    if (!process_aztec_artifact(input, input, force_regenerate)) {
                        all_success = false;
                        std::lock_guard<std::mutex> lock(failures_mutex);
                        failures.push_back(input);
                    }
                });
 
                if (!all_success) {
                    info("Failed to process ", failures.size(), " artifact(s)");
                    return 1;
                }
                info("Successfully processed ", artifact_input_paths.size(), " artifact(s)");
                return 0;
            }
 
            // Single input case
            std::string input = artifact_input_paths[0];
 
            // Check if input is a directory
            if (std::filesystem::is_directory(input)) {
                // If output specified for directory input, that's an error
                if (!artifact_output_path.empty()) {
                    throw_or_abort(
                        "Cannot specify --output when input is a directory. Artifacts are updated in-place.");
                }
                // Recursively process all artifacts in directory
                return process_all_artifacts(input, force_regenerate) ? 0 : 1;
            }
 
            // Input is a file, process single artifact
            std::string output = artifact_output_path.empty() ? input : artifact_output_path;
            return process_aztec_artifact(input, output, force_regenerate) ? 0 : 1;
#endif
        }
        // AVM - functions will throw at runtime if not supported (via stub module)
        else if (avm_prove_command->parsed()) {
            // This outputs both files: proof and vk, under the given directory.
            avm_prove(avm_inputs_path, avm_prove_output_path);
        } else if (avm_check_circuit_command->parsed()) {
            avm_check_circuit(avm_inputs_path);
        } else if (avm_verify_command->parsed()) {
            return avm_verify(proof_path, avm_public_inputs_path) ? 0 : 1;
        } else if (avm_simulate_command->parsed()) {
            avm_simulate(avm_inputs_path);
        } else if (avm_write_vk_command->parsed()) {
            avm_write_verification_key(avm_write_vk_output_path);
        } else if (flags.scheme == "chonk") {
            ChonkAPI api;
            if (prove->parsed()) {
                if (!std::filesystem::exists(ivc_inputs_path)) {
                    throw_or_abort("The prove command for Chonk expect a valid file passed with --ivc_inputs_path "
                                   "<ivc-inputs.msgpack> (default ./ivc-inputs.msgpack)");
                }
                api.prove(flags, ivc_inputs_path, output_path);
#if !defined(__wasm__) || defined(ENABLE_WASM_BENCH)
                if (print_bench) {
                    vinfo("Printing BB_BENCH results...");
                    bb::detail::GLOBAL_BENCH_STATS.print_aggregate_counts_hierarchical(std::cout);
                    std::cout << std::flush;
                }
                if (!bench_out.empty()) {
                    std::ofstream file(bench_out);
                    bb::detail::GLOBAL_BENCH_STATS.print_aggregate_counts(file, 2);
                }
                if (!bench_out_hierarchical.empty()) {
                    std::ofstream file(bench_out_hierarchical);
                    bb::detail::GLOBAL_BENCH_STATS.serialize_aggregate_data_json(file);
                }
                if (!trace_out_perfetto.empty()) {
                    std::ofstream file(trace_out_perfetto);
                    bb::detail::GLOBAL_BENCH_STATS.serialize_trace_events_json(file);
                    vinfo("Perfetto per-call trace written to ", trace_out_perfetto);
                }
                if (!trace_out_perfetto_aggregate.empty()) {
                    std::ofstream file(trace_out_perfetto_aggregate);
                    bb::detail::GLOBAL_BENCH_STATS.serialize_aggregate_trace_json(file);
                    vinfo("Perfetto aggregate trace written to ", trace_out_perfetto_aggregate);
                }
#endif
                if (!memory_profile_out.empty()) {
                    std::ofstream file(memory_profile_out);
                    bb::detail::GLOBAL_MEMORY_PROFILE.serialize_json(file);
                    vinfo("Memory profile written to ", memory_profile_out);
                }
                return 0;
            }
            if (check->parsed()) {
                if (!std::filesystem::exists(ivc_inputs_path)) {
                    throw_or_abort("The check command for Chonk expect a valid file passed with --ivc_inputs_path "
                                   "<ivc-inputs.msgpack> (default ./ivc-inputs.msgpack)");
                }
                if (disable_asserts) {
                    BB_DISABLE_ASSERTS();
                    return api.check_precomputed_vks(flags, ivc_inputs_path) ? 0 : 1;
                }
                return api.check_precomputed_vks(flags, ivc_inputs_path) ? 0 : 1;
            }
            if (batch_verify->parsed()) {
                const bool verified = api.batch_verify(flags, batch_verify_proofs_dir);
                vinfo("batch verified: ", verified);
                return verified ? 0 : 1;
            }
            if (proof_stats->parsed()) {
                api.proof_stats(proof_path, output_path);
                return 0;
            }
            return execute_non_prove_command(api);
        } else if (flags.scheme == "ultra_honk") {
            UltraHonkAPI api;
            if (prove->parsed()) {
                api.prove(flags, bytecode_path, witness_path, vk_path, output_path);
#if !defined(__wasm__) || defined(ENABLE_WASM_BENCH)
                if (print_bench) {
                    bb::detail::GLOBAL_BENCH_STATS.print_aggregate_counts_hierarchical(std::cout);
                }
                if (!bench_out.empty()) {
                    std::ofstream file(bench_out);
                    bb::detail::GLOBAL_BENCH_STATS.print_aggregate_counts(file, 2);
                }
                if (!bench_out_hierarchical.empty()) {
                    std::ofstream file(bench_out_hierarchical);
                    bb::detail::GLOBAL_BENCH_STATS.serialize_aggregate_data_json(file);
                }
                if (!trace_out_perfetto.empty()) {
                    std::ofstream file(trace_out_perfetto);
                    bb::detail::GLOBAL_BENCH_STATS.serialize_trace_events_json(file);
                    vinfo("Perfetto per-call trace written to ", trace_out_perfetto);
                }
                if (!trace_out_perfetto_aggregate.empty()) {
                    std::ofstream file(trace_out_perfetto_aggregate);
                    bb::detail::GLOBAL_BENCH_STATS.serialize_aggregate_trace_json(file);
                    vinfo("Perfetto aggregate trace written to ", trace_out_perfetto_aggregate);
                }
#endif
                return 0;
            }
            return execute_non_prove_command(api);
        } else {
            throw_or_abort("No match for API command");
            return 1;
        }
    } catch (std::runtime_error const& err) {
#ifndef BB_NO_EXCEPTIONS
        std::cerr << err.what() << std::endl;
        return 1;
#endif
    }
    return 0;
}
} // namespace bb