@aztec/bb-prover 0.0.1-commit.e558bd1c → 0.0.1-commit.e57c76e

package/src/bb/bb_js_backend.ts

@@ -0,0 +1,435 @@
+import { type AvmStat, type BackendOptions, BackendType, Barretenberg } from '@aztec/bb.js';
+import type { LogFn, Logger } from '@aztec/foundation/log';
+import { FifoMemoryQueue } from '@aztec/foundation/queue';
+import { Timer } from '@aztec/foundation/timer';
+
+import type { UltraHonkFlavor } from '../honk.js';
+
+/**
+ * Maps UltraHonkFlavor to the bb.js ProofSystemSettings.
+ * All server-side proofs use disableZk: true.
+ */
+function getProofSettings(flavor: UltraHonkFlavor) {
+  const base = { disableZk: true, optimizedSolidityVerifier: false };
+  switch (flavor) {
+    case 'ultra_honk':
+      return { ...base, oracleHashType: 'poseidon2' as const, ipaAccumulation: false };
+    case 'ultra_keccak_honk':
+      return { ...base, oracleHashType: 'keccak' as const, ipaAccumulation: false };
+    case 'ultra_starknet_honk':
+      return { ...base, oracleHashType: 'starknet' as const, ipaAccumulation: false };
+    case 'ultra_rollup_honk':
+      return { ...base, oracleHashType: 'poseidon2' as const, ipaAccumulation: true };
+  }
+}
+
+/** Result of a successful proof generation via bb.js. */
+export type BBJsProofResult = {
+  /** Proof fields as 32-byte Uint8Arrays. */
+  proofFields: Uint8Array[];
+  /** Public input fields as 32-byte Uint8Arrays. */
+  publicInputFields: Uint8Array[];
+  /** Duration of the proving operation in ms. */
+  durationMs: number;
+};
+
+/** Public API surface of a bb.js instance, used by the factory and debug wrapper. */
+export interface BBJsApi {
+  generateProof(
+    circuitName: string,
+    bytecode: Uint8Array,
+    verificationKey: Uint8Array,
+    witness: Uint8Array,
+    flavor: UltraHonkFlavor,
+  ): Promise<BBJsProofResult>;
+  verifyProof(
+    proofFields: Uint8Array[],
+    verificationKey: Uint8Array,
+    publicInputFields: Uint8Array[],
+    flavor: UltraHonkFlavor,
+  ): Promise<{ verified: boolean; durationMs: number }>;
+  verifyChonkProof(
+    fieldsWithPublicInputs: Uint8Array[],
+    verificationKey: Uint8Array,
+  ): Promise<{ verified: boolean; durationMs: number }>;
+  computeGateCount(
+    circuitName: string,
+    bytecode: Uint8Array,
+    flavor: UltraHonkFlavor | 'mega_honk',
+  ): Promise<{ circuitSize: number; durationMs: number }>;
+  generateContract(verificationKey: Uint8Array): Promise<{ solidityCode: string; durationMs: number }>;
+  /** Generate an AVM proof from serialized inputs. Callers should call verifyAvmProof separately. */
+  generateAvmProof(inputs: Uint8Array): Promise<{ proof: Uint8Array[]; stats: AvmStat[]; durationMs: number }>;
+  /** Verify an AVM proof against serialized public inputs. */
+  verifyAvmProof(proof: Uint8Array[], publicInputs: Uint8Array): Promise<{ verified: boolean; durationMs: number }>;
+  /** Check the AVM circuit from serialized inputs. Returns pass/fail and per-stage timings. */
+  checkAvmCircuit(inputs: Uint8Array): Promise<{ passed: boolean; stats: AvmStat[]; durationMs: number }>;
+  destroy(): Promise<void>;
+}
+
+/**
+ * Thin wrapper around a single Barretenberg instance.
+ * Each instance spawns its own bb process via the NativeUnixSocket backend.
+ */
+export class BBJsInstance implements BBJsApi {
+  private constructor(private api: Barretenberg) {}
+
+  /** Creates a new Barretenberg instance connected to a fresh bb process. */
+  static async create(bbPath: string, logger?: LogFn, threads?: number): Promise<BBJsInstance> {
+    const options: BackendOptions = {
+      bbPath,
+      backend: BackendType.NativeUnixSocket,
+      logger,
+    };
+    if (threads !== undefined) {
+      options.threads = threads;
+    }
+    const api = await Barretenberg.new(options);
+    return new BBJsInstance(api);
+  }
+
+  /**
+   * Generate an UltraHonk proof for a circuit.
+   * @param circuitName - Identifier for the circuit (used by bb internally).
+   * @param bytecode - Uncompressed ACIR bytecode.
+   * @param verificationKey - The circuit's verification key bytes.
+   * @param witness - Uncompressed witness bytes.
+   * @param flavor - The UltraHonk flavor to use.
+   */
+  async generateProof(
+    circuitName: string,
+    bytecode: Uint8Array,
+    verificationKey: Uint8Array,
+    witness: Uint8Array,
+    flavor: UltraHonkFlavor,
+  ): Promise<BBJsProofResult> {
+    const timer = new Timer();
+    const result = await this.api.circuitProve({
+      circuit: {
+        name: circuitName,
+        bytecode,
+        verificationKey,
+      },
+      witness,
+      settings: getProofSettings(flavor),
+    });
+    return {
+      proofFields: result.proof,
+      publicInputFields: result.publicInputs,
+      durationMs: timer.ms(),
+    };
+  }
+
+  /**
+   * Verify an UltraHonk proof.
+   * @param proofFields - Proof fields as 32-byte Uint8Arrays.
+   * @param verificationKey - The VK bytes.
+   * @param publicInputFields - Public input fields as 32-byte Uint8Arrays.
+   * @param flavor - The UltraHonk flavor.
+   * @returns Whether the proof is valid.
+   */
+  async verifyProof(
+    proofFields: Uint8Array[],
+    verificationKey: Uint8Array,
+    publicInputFields: Uint8Array[],
+    flavor: UltraHonkFlavor,
+  ): Promise<{ verified: boolean; durationMs: number }> {
+    const timer = new Timer();
+    const result = await this.api.circuitVerify({
+      verificationKey,
+      publicInputs: publicInputFields,
+      proof: proofFields,
+      settings: getProofSettings(flavor),
+    });
+    return { verified: result.verified, durationMs: timer.ms() };
+  }
+
+  /**
+   * Compute circuit gate count / circuit size.
+   * @param circuitName - Identifier for the circuit.
+   * @param bytecode - Uncompressed ACIR bytecode.
+   * @param flavor - 'mega_honk' for chonk circuits, or an UltraHonk flavor.
+   * @returns The dyadic circuit size (next power of 2 of gate count).
+   */
+  async computeGateCount(
+    circuitName: string,
+    bytecode: Uint8Array,
+    flavor: UltraHonkFlavor | 'mega_honk',
+  ): Promise<{ circuitSize: number; durationMs: number }> {
+    const timer = new Timer();
+    if (flavor === 'mega_honk') {
+      const result = await this.api.chonkStats({
+        circuit: { name: circuitName, bytecode },
+        includeGatesPerOpcode: false,
+      });
+      return { circuitSize: result.circuitSize, durationMs: timer.ms() };
+    }
+    const result = await this.api.circuitStats({
+      circuit: { name: circuitName, bytecode, verificationKey: new Uint8Array(0) },
+      includeGatesPerOpcode: false,
+      settings: getProofSettings(flavor),
+    });
+    return { circuitSize: result.numGatesDyadic, durationMs: timer.ms() };
+  }
+
+  /**
+   * Generate a Solidity verifier contract from a verification key.
+   * @param verificationKey - The VK bytes.
+   * @returns The Solidity source code.
+   */
+  async generateContract(verificationKey: Uint8Array): Promise<{ solidityCode: string; durationMs: number }> {
+    const timer = new Timer();
+    const result = await this.api.circuitWriteSolidityVerifier({
+      verificationKey,
+      settings: {
+        ipaAccumulation: false,
+        oracleHashType: 'poseidon2',
+        disableZk: true,
+        optimizedSolidityVerifier: false,
+      },
+    });
+    return { solidityCode: result.solidityCode, durationMs: timer.ms() };
+  }
+
+  /**
+   * Verify a Chonk (IVC) proof passed as flat field elements (with public inputs prepended).
+   * The split into structured sub-proofs happens server-side in `ChonkProof::from_field_elements`,
+   * so this layer doesn't need to know per-component sub-proof sizes.
+   * @param fieldsWithPublicInputs - Flat proof fields as 32-byte Uint8Arrays (public inputs prepended).
+   * @param verificationKey - The VK bytes.
+   */
+  async verifyChonkProof(
+    fieldsWithPublicInputs: Uint8Array[],
+    verificationKey: Uint8Array,
+  ): Promise<{ verified: boolean; durationMs: number }> {
+    const timer = new Timer();
+    const result = await this.api.chonkVerifyFromFields({ proof: fieldsWithPublicInputs, vk: verificationKey });
+    return { verified: result.valid, durationMs: timer.ms() };
+  }
+
+  /** Generate an AVM proof from serialized inputs. */
+  async generateAvmProof(inputs: Uint8Array): Promise<{ proof: Uint8Array[]; stats: AvmStat[]; durationMs: number }> {
+    const timer = new Timer();
+    const result = await this.api.avmProve({ inputs });
+    return { proof: result.proof, stats: result.stats, durationMs: timer.ms() };
+  }
+
+  /** Verify an AVM proof against serialized public inputs. */
+  async verifyAvmProof(
+    proof: Uint8Array[],
+    publicInputs: Uint8Array,
+  ): Promise<{ verified: boolean; durationMs: number }> {
+    const timer = new Timer();
+    const result = await this.api.avmVerify({ proof, publicInputs });
+    return { verified: result.verified, durationMs: timer.ms() };
+  }
+
+  /** Check the AVM circuit from serialized inputs. */
+  async checkAvmCircuit(inputs: Uint8Array): Promise<{ passed: boolean; stats: AvmStat[]; durationMs: number }> {
+    const timer = new Timer();
+    const result = await this.api.avmCheckCircuit({ inputs });
+    return { passed: result.passed, stats: result.stats, durationMs: timer.ms() };
+  }
+
+  /** Destroy this instance and kill the underlying bb process. */
+  async destroy(): Promise<void> {
+    await this.api.destroy();
+  }
+}
+
+/** Options for {@link BBJsFactory}. */
+export interface BBJsFactoryOptions {
+  /**
+   * Number of long-lived bb processes to keep in the pool.
+   * If omitted, every `getInstance()` call spawns a fresh bb that is destroyed on dispose.
+   */
+  poolSize?: number;
+  logger?: Logger;
+  threads?: number;
+  debugDir?: string;
+}
+
+/**
+ * Manages bb.js instance lifecycle. By default every `getInstance()` call spawns a fresh
+ * bb process that is destroyed when the borrow is disposed. Pass `poolSize` to keep a fixed
+ * set of long-lived bb processes that are reused across calls — useful when the per-call
+ * bb startup cost dominates the workload (e.g. high-rate IVC verification).
+ *
+ * Idiomatic usage:
+ * ```
+ * await using inst = await factory.getInstance();
+ * await inst.someMethod(...);
+ * // disposed automatically when `inst` goes out of scope
+ * ```
+ */
+export class BBJsFactory {
+  private readonly poolSize?: number;
+  private readonly logger?: Logger;
+  private readonly threads?: number;
+  private readonly debugDir?: string;
+
+  /** Available pooled instances when poolSize is set; otherwise undefined. */
+  private pool?: FifoMemoryQueue<BBJsApi>;
+  /** Lazily-resolved on first `getInstance()` call to prevent racing pool initialization. */
+  private initPromise?: Promise<void>;
+  private destroyed = false;
+
+  constructor(
+    private bbPath: string,
+    options: BBJsFactoryOptions = {},
+  ) {
+    this.poolSize = options.poolSize;
+    this.logger = options.logger;
+    this.threads = options.threads;
+    this.debugDir = options.debugDir;
+    if (this.poolSize !== undefined && this.poolSize < 1) {
+      throw new Error(`BBJsFactory poolSize must be >= 1, got ${this.poolSize}`);
+    }
+  }
+
+  /**
+   * Acquire a bb instance. The returned object implements `BBJsApi` and `AsyncDisposable`.
+   * With no pool: spawns a fresh bb that is destroyed on dispose. With a pool: borrows from
+   * the pool and returns to it on dispose.
+   */
+  async getInstance(): Promise<BBJsApi & AsyncDisposable> {
+    if (this.destroyed) {
+      throw new Error('BBJsFactory has been destroyed');
+    }
+    if (this.poolSize === undefined) {
+      // No pool: fresh-per-call, dispose destroys.
+      const instance = await this.createInstance();
+      return this.makeOwned(instance);
+    }
+    if (!this.initPromise) {
+      this.initPromise = this.initPool();
+    }
+    await this.initPromise;
+    const pool = this.pool;
+    if (!pool) {
+      throw new Error('BBJsFactory has been destroyed');
+    }
+    const instance = await pool.get();
+    if (!instance) {
+      throw new Error('BBJsFactory was destroyed while waiting for an instance');
+    }
+    return this.makeBorrowed(instance);
+  }
+
+  /**
+   * Tear down all pooled instances. Idempotent. No-op when no pool is configured (fresh-per-call
+   * instances are destroyed by their own dispose callbacks). Instances currently held by an
+   * in-flight pooled borrow are destroyed by their dispose callback when released.
+   */
+  async destroy(): Promise<void> {
+    if (this.destroyed) {
+      return;
+    }
+    this.destroyed = true;
+    const pool = this.pool;
+    this.pool = undefined;
+    if (!pool) {
+      return;
+    }
+    const idle: BBJsApi[] = [];
+    while (pool.length() > 0) {
+      const item = pool.getImmediate();
+      if (item) {
+        idle.push(item);
+      }
+    }
+    pool.cancel();
+    // Aggregate teardown failures so a single bb child that fails to shut down doesn't mask others.
+    const results = await Promise.allSettled(idle.map(item => item.destroy()));
+    const errors = results.filter((r): r is PromiseRejectedResult => r.status === 'rejected').map(r => r.reason);
+    if (errors.length > 0) {
+      throw new AggregateError(errors, `BBJsFactory.destroy: ${errors.length} bb instance(s) failed to shut down`);
+    }
+  }
+
+  private async initPool(): Promise<void> {
+    // Use allSettled so that if any createInstance() rejects we can destroy the rest instead of
+    // leaking bb child processes whose creation succeeded.
+    const results = await Promise.allSettled(Array.from({ length: this.poolSize! }, () => this.createInstance()));
+    const items: BBJsApi[] = [];
+    const errors: unknown[] = [];
+    for (const result of results) {
+      if (result.status === 'fulfilled') {
+        items.push(result.value);
+      } else {
+        errors.push(result.reason);
+      }
+    }
+    if (errors.length > 0 || this.destroyed) {
+      // Either creation failed or destroy() raced ahead — clean up everything we successfully spawned.
+      await Promise.all(items.map(item => item.destroy()));
+      if (errors.length > 0) {
+        throw errors[0];
+      }
+      return;
+    }
+    const pool = new FifoMemoryQueue<BBJsApi>();
+    for (const item of items) {
+      pool.put(item);
+    }
+    this.pool = pool;
+  }
+
+  private async createInstance(): Promise<BBJsApi> {
+    const logFn = this.logger ? (msg: string) => this.logger!.verbose(`bb.js - ${msg}`) : undefined;
+    const raw = await BBJsInstance.create(this.bbPath, logFn, this.threads);
+    return this.maybeWrapDebug(raw);
+  }
+
+  /** Wrap the instance in a debug wrapper if debugDir is configured. */
+  private async maybeWrapDebug(instance: BBJsInstance): Promise<BBJsApi> {
+    if (this.debugDir && this.logger) {
+      const { DebugBBJsInstance } = await import('./bb_js_debug.js');
+      return new DebugBBJsInstance(instance, this.debugDir, this.bbPath, this.logger);
+    }
+    return instance;
+  }
+
+  /**
+   * Wrap a fresh instance with an `AsyncDisposable` that destroys it on dispose. Used when no
+   * pool is configured. Destroy errors are propagated so that a teardown failure (e.g. a bb child
+   * that didn't shut down cleanly) surfaces instead of being silently swallowed.
+   */
+  private makeOwned(instance: BBJsApi): BBJsApi & AsyncDisposable {
+    return this.makeDisposable(instance, () => instance.destroy());
+  }
+
+  /**
+   * Wrap a pooled instance with an `AsyncDisposable` that returns it to the pool (or destroys it
+   * if the factory was destroyed in the meantime). Destroy errors are propagated.
+   */
+  private makeBorrowed(instance: BBJsApi): BBJsApi & AsyncDisposable {
+    return this.makeDisposable(instance, async () => {
+      const pool = this.pool;
+      if (pool && !this.destroyed) {
+        pool.put(instance);
+      } else {
+        await instance.destroy();
+      }
+    });
+  }
+
+  private makeDisposable(instance: BBJsApi, onDispose: () => void | Promise<void>): BBJsApi & AsyncDisposable {
+    let disposed = false;
+    const dispose = async (): Promise<void> => {
+      if (disposed) {
+        return;
+      }
+      disposed = true;
+      await onDispose();
+    };
+    return new Proxy(instance as BBJsApi & AsyncDisposable, {
+      get(target, prop, receiver) {
+        if (prop === Symbol.asyncDispose) {
+          return dispose;
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+  }
+}

package/src/bb/bb_js_debug.ts

@@ -0,0 +1,227 @@
+import type { AvmStat } from '@aztec/bb.js';
+import type { Logger } from '@aztec/foundation/log';
+
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { gzipSync } from 'zlib';
+
+import type { UltraHonkFlavor } from '../honk.js';
+import type { BBJsApi, BBJsProofResult } from './bb_js_backend.js';
+
+/**
+ * Maps UltraHonk flavors to the CLI flags used by the bb binary.
+ * The CLI always uses `--scheme ultra_honk`; flavors are expressed via
+ * `--oracle_hash` and `--ipa_accumulation`.
+ */
+function getCliFlags(flavor: UltraHonkFlavor): string {
+  const base = '--scheme ultra_honk --disable_zk';
+  switch (flavor) {
+    case 'ultra_honk':
+      return `${base} --oracle_hash poseidon2`;
+    case 'ultra_keccak_honk':
+      return `${base} --oracle_hash keccak`;
+    case 'ultra_starknet_honk':
+      return `${base} --oracle_hash starknet`;
+    case 'ultra_rollup_honk':
+      return `${base} --oracle_hash poseidon2 --ipa_accumulation`;
+  }
+}
+
+/** Concatenate an array of 32-byte field elements into a single buffer. */
+function concatFields(fields: Uint8Array[]): Buffer {
+  const totalLen = fields.reduce((sum, f) => sum + f.length, 0);
+  const buf = Buffer.alloc(totalLen);
+  let offset = 0;
+  for (const f of fields) {
+    buf.set(f, offset);
+    offset += f.length;
+  }
+  return buf;
+}
+
+/**
+ * Wraps a BBJsApi instance to write debug files and log equivalent CLI commands.
+ * Activated when BB_DEBUG_OUTPUT_DIR is set. Each operation writes its inputs
+ * and outputs to a numbered subdirectory, enabling offline reproduction.
+ */
+export class DebugBBJsInstance implements BBJsApi {
+  private counter = 0;
+
+  constructor(
+    private inner: BBJsApi,
+    private debugDir: string,
+    private bbPath: string,
+    private logger: Logger,
+  ) {}
+
+  private nextDir(prefix: string): string {
+    this.counter++;
+    const padded = String(this.counter).padStart(3, '0');
+    return path.join(this.debugDir, `${prefix}-${padded}`);
+  }
+
+  /** Write a command string to both the logger and a command.sh file in the given directory. */
+  private async logCommand(dir: string, command: string): Promise<void> {
+    this.logger.info(`Executing BB with: ${command}`);
+    await fs.writeFile(path.join(dir, 'command.sh'), `#!/bin/bash\n${command}\n`, { mode: 0o755 });
+  }
+
+  async generateProof(
+    circuitName: string,
+    bytecode: Uint8Array,
+    verificationKey: Uint8Array,
+    witness: Uint8Array,
+    flavor: UltraHonkFlavor,
+  ): Promise<BBJsProofResult> {
+    const dir = this.nextDir(circuitName);
+    await fs.mkdir(dir, { recursive: true });
+
+    const bytecodePath = path.join(dir, `${circuitName}-bytecode.gz`);
+    const vkPath = path.join(dir, `${circuitName}-vk`);
+    const witnessPath = path.join(dir, 'partial-witness.gz');
+
+    await Promise.all([
+      fs.writeFile(bytecodePath, gzipSync(bytecode)),
+      fs.writeFile(vkPath, verificationKey),
+      fs.writeFile(witnessPath, gzipSync(witness)),
+    ]);
+
+    const flags = getCliFlags(flavor);
+    await this.logCommand(
+      dir,
+      `${this.bbPath} prove ${flags} -o ${dir} -b ${bytecodePath} -k ${vkPath} -w ${witnessPath}`,
+    );
+
+    const result = await this.inner.generateProof(circuitName, bytecode, verificationKey, witness, flavor);
+
+    const proofBuf = concatFields(result.proofFields);
+    const publicInputsBuf = concatFields(result.publicInputFields);
+    await Promise.all([
+      fs.writeFile(path.join(dir, 'proof'), proofBuf),
+      fs.writeFile(path.join(dir, 'public_inputs'), publicInputsBuf),
+    ]);
+
+    return result;
+  }
+
+  async verifyProof(
+    proofFields: Uint8Array[],
+    verificationKey: Uint8Array,
+    publicInputFields: Uint8Array[],
+    flavor: UltraHonkFlavor,
+  ): Promise<{ verified: boolean; durationMs: number }> {
+    const dir = this.nextDir(`verify-${flavor}`);
+    await fs.mkdir(dir, { recursive: true });
+
+    const proofPath = path.join(dir, 'proof');
+    const vkPath = path.join(dir, 'vk');
+    const publicInputsPath = path.join(dir, 'public_inputs');
+
+    const proofBuf = concatFields(proofFields);
+    const publicInputsBuf = concatFields(publicInputFields);
+    await Promise.all([
+      fs.writeFile(proofPath, proofBuf),
+      fs.writeFile(vkPath, verificationKey),
+      fs.writeFile(publicInputsPath, publicInputsBuf),
+    ]);
+
+    const flags = getCliFlags(flavor);
+    await this.logCommand(dir, `${this.bbPath} verify ${flags} -p ${proofPath} -k ${vkPath} -i ${publicInputsPath}`);
+
+    return this.inner.verifyProof(proofFields, verificationKey, publicInputFields, flavor);
+  }
+
+  async verifyChonkProof(
+    fieldsWithPublicInputs: Uint8Array[],
+    verificationKey: Uint8Array,
+  ): Promise<{ verified: boolean; durationMs: number }> {
+    const dir = this.nextDir('verify-chonk');
+    await fs.mkdir(dir, { recursive: true });
+
+    const proofPath = path.join(dir, 'proof');
+    const vkPath = path.join(dir, 'vk');
+
+    const proofBuf = concatFields(fieldsWithPublicInputs);
+    await Promise.all([fs.writeFile(proofPath, proofBuf), fs.writeFile(vkPath, verificationKey)]);
+
+    await this.logCommand(dir, `${this.bbPath} verify --scheme chonk -p ${proofPath} -k ${vkPath} -v`);
+
+    return this.inner.verifyChonkProof(fieldsWithPublicInputs, verificationKey);
+  }
+
+  async computeGateCount(
+    circuitName: string,
+    bytecode: Uint8Array,
+    flavor: UltraHonkFlavor | 'mega_honk',
+  ): Promise<{ circuitSize: number; durationMs: number }> {
+    const dir = this.nextDir(`gates-${circuitName}`);
+    await fs.mkdir(dir, { recursive: true });
+
+    const bytecodePath = path.join(dir, `${circuitName}-bytecode.gz`);
+    await fs.writeFile(bytecodePath, gzipSync(bytecode));
+
+    if (flavor === 'mega_honk') {
+      await this.logCommand(dir, `${this.bbPath} gates --scheme chonk -b ${bytecodePath}`);
+    } else {
+      const flags = getCliFlags(flavor);
+      await this.logCommand(dir, `${this.bbPath} gates ${flags} -b ${bytecodePath}`);
+    }
+
+    return this.inner.computeGateCount(circuitName, bytecode, flavor);
+  }
+
+  async generateAvmProof(inputs: Uint8Array): Promise<{ proof: Uint8Array[]; stats: AvmStat[]; durationMs: number }> {
+    const dir = this.nextDir('avm-prove');
+    await fs.mkdir(dir, { recursive: true });
+
+    const inputsPath = path.join(dir, 'avm_inputs.bin');
+    await fs.writeFile(inputsPath, inputs);
+
+    await this.logCommand(dir, `${this.bbPath} avm_prove --avm-inputs ${inputsPath} -o ${dir}`);
+
+    const result = await this.inner.generateAvmProof(inputs);
+
+    const proofBuf = concatFields(result.proof);
+    await fs.writeFile(path.join(dir, 'proof'), proofBuf);
+
+    return result;
+  }
+
+  async verifyAvmProof(
+    proof: Uint8Array[],
+    publicInputs: Uint8Array,
+  ): Promise<{ verified: boolean; durationMs: number }> {
+    const dir = this.nextDir('avm-verify');
+    await fs.mkdir(dir, { recursive: true });
+
+    const proofPath = path.join(dir, 'proof');
+    const publicInputsPath = path.join(dir, 'avm_public_inputs.bin');
+
+    const proofBuf = concatFields(proof);
+    await Promise.all([fs.writeFile(proofPath, proofBuf), fs.writeFile(publicInputsPath, publicInputs)]);
+
+    await this.logCommand(dir, `${this.bbPath} avm_verify -p ${proofPath} --avm-public-inputs ${publicInputsPath}`);
+
+    return this.inner.verifyAvmProof(proof, publicInputs);
+  }
+
+  async checkAvmCircuit(inputs: Uint8Array): Promise<{ passed: boolean; stats: AvmStat[]; durationMs: number }> {
+    const dir = this.nextDir('avm-check-circuit');
+    await fs.mkdir(dir, { recursive: true });
+
+    const inputsPath = path.join(dir, 'avm_inputs.bin');
+    await fs.writeFile(inputsPath, inputs);
+
+    await this.logCommand(dir, `${this.bbPath} avm_check_circuit --avm-inputs ${inputsPath}`);
+
+    return this.inner.checkAvmCircuit(inputs);
+  }
+
+  generateContract(verificationKey: Uint8Array): Promise<{ solidityCode: string; durationMs: number }> {
+    return this.inner.generateContract(verificationKey);
+  }
+
+  destroy(): Promise<void> {
+    return this.inner.destroy();
+  }
+}

package/src/bb/file_names.ts

@@ -0,0 +1,6 @@
+// File-naming conventions used by `bb` CLI output directories. Retained for consumers that still
+// read/write proofs to disk alongside bb-prover's in-memory bb.js flows.
+
+export const VK_FILENAME = 'vk';
+export const PROOF_FILENAME = 'proof';
+export const PUBLIC_INPUTS_FILENAME = 'public_inputs';

package/src/config.ts

@@ -3,8 +3,24 @@ export interface BBConfig {
   bbWorkingDirectory: string;
   /** Whether to skip tmp dir cleanup for debugging purposes */
   bbSkipCleanup: boolean;
+  /**
+   * Number of long-lived bb processes pooled by the RPC verifier (BBCircuitVerifier).
+   * Also caps concurrent verifications via the wrapping QueuedIVCVerifier.
+   */
   numConcurrentIVCVerifiers: number;
+  /** Thread count for the RPC IVC verifier. */
   bbIVCConcurrency: number;
+  /**
+   * Upper bound on proofs per batch for the peer chonk batch verifier.
+   * Proofs are verified immediately as they arrive — this only caps how many
+   * can accumulate while a batch is already being processed.
+   * Default 16: at 4 cores, a full batch of 16 verifies in ~245ms wall time.
+   */
+  bbChonkVerifyMaxBatch: number;
+  /** Thread count for the peer batch verifier parallel reduce. Default 6 to leave cores for the rest of the node. */
+  bbChonkVerifyConcurrency: number;
+  /** When set, bb.js operations write input/output files and log equivalent CLI commands to this directory. */
+  bbDebugOutputDir?: string;
 }
 
 export interface ACVMConfig {