@aztec/bb.js 0.0.1-alpha.7 → 0.0.1-commit.5daedc8

package/src/bb_backends/node/platform.ts

@@ -0,0 +1,151 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import { fileURLToPath } from 'url';
+
+function getCurrentDir() {
+  if (typeof __dirname !== 'undefined') {
+    return __dirname;
+  } else {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    return path.dirname(fileURLToPath(import.meta.url));
+  }
+}
+
+/**
+ * Find package root by climbing directory tree until package.json is found.
+ * @param startDir Starting directory to search from
+ * @returns Absolute path to package root, or null if not found
+ */
+export function findPackageRoot(): string | null {
+  let currentDir = getCurrentDir();
+  const root = path.parse(currentDir).root;
+
+  while (currentDir !== root) {
+    const packageJsonPath = path.join(currentDir, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      return currentDir;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+
+  return null;
+}
+
+/**
+ * Supported platform/architecture combinations.
+ */
+export type Platform = 'x86_64-linux' | 'x86_64-darwin' | 'aarch64-linux' | 'aarch64-darwin';
+
+/**
+ * Map from Platform to build directory name.
+ */
+const PLATFORM_TO_BUILD_DIR: Record<Platform, string> = {
+  'x86_64-linux': 'amd64-linux',
+  'x86_64-darwin': 'amd64-macos',
+  'aarch64-linux': 'arm64-linux',
+  'aarch64-darwin': 'arm64-macos',
+};
+
+/**
+ * Detect the current platform and architecture.
+ * @returns Platform identifier or null if unsupported
+ */
+export function detectPlatform(): Platform | null {
+  const arch = process.arch; // 'x64' | 'arm64' | ...
+  const platform = process.platform; // 'linux' | 'darwin' | 'win32' | ...
+
+  if (arch === 'x64' && platform === 'linux') {
+    return 'x86_64-linux';
+  }
+  if (arch === 'x64' && platform === 'darwin') {
+    return 'x86_64-darwin';
+  }
+  if (arch === 'arm64' && platform === 'linux') {
+    return 'aarch64-linux';
+  }
+  if (arch === 'arm64' && platform === 'darwin') {
+    return 'aarch64-darwin';
+  }
+
+  return null;
+}
+
+/**
+ * Find the bb binary for the native backend.
+ * @param customPath Optional custom path to bb binary (overrides automatic detection)
+ * @returns Absolute path to bb binary, or null if not found
+ *
+ * Search order:
+ * 1. If customPath is provided and exists, return it
+ * 2. Otherwise search in <package-root>/build/<platform>/bb
+ */
+export function findBbBinary(customPath?: string): string | null {
+  // Check custom path first if provided
+  if (customPath) {
+    if (fs.existsSync(customPath)) {
+      return path.resolve(customPath);
+    }
+    // Custom path provided but doesn't exist - return null
+    return null;
+  }
+
+  // Automatic detection
+  const platform = detectPlatform();
+  if (!platform) {
+    return null;
+  }
+
+  const buildDir = PLATFORM_TO_BUILD_DIR[platform];
+
+  // Get package root by climbing directory tree to find package.json
+  const packageRoot = findPackageRoot();
+
+  if (!packageRoot) {
+    return null;
+  }
+
+  // Check in build/<platform>/bb
+  const bbPath = path.join(packageRoot, 'build', buildDir, 'bb');
+
+  if (fs.existsSync(bbPath)) {
+    return bbPath;
+  }
+
+  return null;
+}
+
+export function findNapiBinary(customPath?: string): string | null {
+  // Check custom path first if provided
+  if (customPath) {
+    if (fs.existsSync(customPath)) {
+      return path.resolve(customPath);
+    }
+    // Custom path provided but doesn't exist - return null
+    return null;
+  }
+
+  // Automatic detection
+  const platform = detectPlatform();
+  if (!platform) {
+    return null;
+  }
+
+  const buildDir = PLATFORM_TO_BUILD_DIR[platform];
+
+  // Get package root by climbing directory tree to find package.json
+  const packageRoot = findPackageRoot();
+
+  if (!packageRoot) {
+    return null;
+  }
+
+  // Check in build/<platform>/nodejs_module.node
+  const bbPath = path.join(packageRoot, 'build', buildDir, 'nodejs_module.node');
+
+  if (fs.existsSync(bbPath)) {
+    return bbPath;
+  }
+
+  return null;
+}

package/src/bb_backends/wasm.ts

@@ -0,0 +1,102 @@
+import { BarretenbergWasmMain, BarretenbergWasmMainWorker } from '../barretenberg_wasm/barretenberg_wasm_main/index.js';
+import { fetchModuleAndThreads } from '../barretenberg_wasm/index.js';
+import { IMsgpackBackendSync, IMsgpackBackendAsync } from './interface.js';
+import { createMainWorker } from '../barretenberg_wasm/barretenberg_wasm_main/factory/node/index.js';
+import { getRemoteBarretenbergWasm } from '../barretenberg_wasm/helpers/index.js';
+import { proxy } from 'comlink';
+
+/**
+ * Synchronous WASM backend that wraps BarretenbergWasmMain.
+ * Encapsulates all WASM initialization and memory management.
+ */
+export class BarretenbergWasmSyncBackend implements IMsgpackBackendSync {
+  private constructor(private wasm: BarretenbergWasmMain) {}
+
+  /**
+   * Create and initialize a synchronous WASM backend.
+   * @param wasmPath Optional path to WASM files
+   * @param logger Optional logging function
+   */
+  static async new(wasmPath?: string, logger?: (msg: string) => void): Promise<BarretenbergWasmSyncBackend> {
+    const wasm = new BarretenbergWasmMain();
+    const { module, threads } = await fetchModuleAndThreads(1, wasmPath, logger);
+    await wasm.init(module, threads, logger);
+    return new BarretenbergWasmSyncBackend(wasm);
+  }
+
+  call(inputBuffer: Uint8Array): Uint8Array {
+    return this.wasm.cbindCall('bbapi', inputBuffer);
+  }
+
+  destroy(): void {
+    // BarretenbergWasmMain has async destroy, but for sync API we call it without awaiting
+    // This is consistent with the synchronous semantics expected by the caller
+    void this.wasm.destroy();
+  }
+}
+
+/**
+ * Asynchronous WASM backend that supports both direct WASM and worker-based modes.
+ *
+ * Worker mode (default): Runs WASM on a worker thread to avoid blocking the main thread. Used in browsers.
+ * Direct mode: Runs WASM directly on the calling thread. Used by node.js for better performance.
+ */
+export class BarretenbergWasmAsyncBackend implements IMsgpackBackendAsync {
+  private constructor(
+    private wasm: BarretenbergWasmMain | BarretenbergWasmMainWorker,
+    private worker?: any,
+  ) {}
+
+  /**
+   * Create and initialize an asynchronous WASM backend.
+   * @param options.threads Number of threads (defaults to hardware max, up to 32 for parallel proving)
+   * @param options.wasmPath Optional path to WASM files
+   * @param options.logger Optional logging function
+   * @param options.memory Optional initial and maximum memory configuration
+   * @param options.useWorker Run on worker thread (default: true for browser safety)
+   */
+  static async new(
+    options: {
+      threads?: number;
+      wasmPath?: string;
+      logger?: (msg: string) => void;
+      memory?: { initial?: number; maximum?: number };
+      useWorker?: boolean;
+    } = {},
+  ): Promise<BarretenbergWasmAsyncBackend> {
+    // Default to worker mode for browser safety
+    const useWorker = options.useWorker ?? true;
+
+    if (useWorker) {
+      // Worker-based mode: runs on worker thread (browser-safe)
+      const worker = await createMainWorker();
+      const wasm = getRemoteBarretenbergWasm<BarretenbergWasmMainWorker>(worker);
+      const { module, threads } = await fetchModuleAndThreads(options.threads, options.wasmPath, options.logger);
+      await wasm.init(
+        module,
+        threads,
+        proxy(options.logger ?? (() => {})),
+        options.memory?.initial,
+        options.memory?.maximum,
+      );
+      return new BarretenbergWasmAsyncBackend(wasm, worker);
+    } else {
+      // Direct mode: runs on calling thread (faster but blocks thread)
+      const wasm = new BarretenbergWasmMain();
+      const { module, threads } = await fetchModuleAndThreads(options.threads, options.wasmPath, options.logger);
+      await wasm.init(module, threads, options.logger, options.memory?.initial, options.memory?.maximum);
+      return new BarretenbergWasmAsyncBackend(wasm);
+    }
+  }
+
+  async call(inputBuffer: Uint8Array): Promise<Uint8Array> {
+    return this.wasm.cbindCall('bbapi', inputBuffer);
+  }
+
+  async destroy(): Promise<void> {
+    await this.wasm.destroy();
+    if (this.worker) {
+      await this.worker.terminate();
+    }
+  }
+}

package/src/bbapi/exception_handling.test.ts

@@ -0,0 +1,54 @@
+import { BarretenbergWasmSyncBackend } from '../bb_backends/wasm.js';
+import { SyncApi } from '../cbind/generated/sync.js';
+import { BBApiException } from '../bbapi_exception.js';
+
+describe('BBApi Exception Handling from bb.js', () => {
+  let backend: BarretenbergWasmSyncBackend;
+  let api: SyncApi;
+
+  beforeAll(async () => {
+    backend = await BarretenbergWasmSyncBackend.new();
+    api = new SyncApi(backend);
+  }, 60000);
+
+  afterAll(() => {
+    backend.destroy();
+  });
+
+  it('should catch CRS initialization exceptions from WASM', () => {
+    // Create an SrsInitSrs command with invalid data that will cause an exception in C++
+    // We pass buffers that are too small, which will cause validation to fail
+    const invalidCommand = {
+      numPoints: 100, // Request 100 points (requires 6400 bytes)
+      pointsBuf: new Uint8Array(10), // Only 10 bytes - will cause exception
+      g2Point: new Uint8Array(10), // Only 10 bytes (needs 128) - will cause exception
+    };
+
+    // In WASM builds, throw_or_abort calls abort directly which throws a generic Error
+    // In native builds with exceptions, our try-catch in bbapi converts it to ErrorResponse
+    // This test verifies that errors are catchable from bb.js (even if as generic Error in WASM)
+    expect(() => {
+      api.srsInitSrs(invalidCommand);
+    }).toThrow();
+  });
+
+  it('should return error message from caught exception', () => {
+    const invalidCommand = {
+      numPoints: 100,
+      pointsBuf: new Uint8Array(10),
+      g2Point: new Uint8Array(10),
+    };
+
+    try {
+      api.srsInitSrs(invalidCommand);
+      fail('Expected exception to be thrown');
+    } catch (error) {
+      // Error is catchable and contains a useful message
+      expect(error).toBeInstanceOf(Error);
+      expect((error as Error).message).toBeTruthy();
+      expect((error as Error).message.length).toBeGreaterThan(0);
+      expect((error as Error).message).toContain('g1_identity');
+      console.log('Successfully caught exception from bb.js with message:', (error as Error).message);
+    }
+  });
+});

package/src/bbapi_exception.ts

@@ -0,0 +1,13 @@
+/**
+ * Exception thrown when barretenberg API operations fail
+ */
+export class BBApiException extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'BBApiException';
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, BBApiException);
+    }
+  }
+}

package/src/benchmark/index.ts

@@ -0,0 +1,26 @@
+import * as fs from 'fs';
+export * from './timer.js';
+
+const bfd = (() => {
+  const bfdStr = process.env.BENCHMARK_FD;
+  const bfd = bfdStr ? parseInt(bfdStr) : -1;
+  if (bfd >= 0 && !fs.fstatSync(bfd)) {
+    throw new Error('fd is not open. Did you redirect in your shell?');
+  }
+  return bfd;
+})();
+
+export function writeBenchmark<T>(name: string, value: T, labels: Record<string, any> = {}) {
+  if (bfd === -1) {
+    return;
+  }
+  const data = {
+    timestamp: new Date().toISOString(),
+    name,
+    type: typeof value,
+    value,
+    ...labels,
+  };
+  const jsonl = JSON.stringify(data) + '\n';
+  fs.writeSync(bfd, jsonl);
+}

package/src/benchmark/timer.ts

@@ -0,0 +1,45 @@
+/**
+ * Timer class to measure time intervals in milliseconds and seconds.
+ * Upon instantiation, it stores the current timestamp as the starting point.
+ * The 'ms()' method returns the elapsed time in milliseconds,
+ * while the 's()' method returns the elapsed time in seconds.
+ *
+ * @example
+ * const timer = new Timer();
+ * setTimeout(() =\> \{
+ *   console.log(`Elapsed time: ${timer.ms()} ms`);
+ * \}, 1000);
+ */
+export class Timer {
+  private start: number;
+
+  constructor() {
+    this.start = performance.now();
+  }
+
+  public us() {
+    return this.ms() * 1000;
+  }
+
+  /**
+   * Returns the elapsed time in milliseconds since the Timer instance was created.
+   * Provides a simple and convenient way to measure the time duration between two events
+   * or monitor performance of specific code sections.
+   *
+   * @returns The elapsed time in milliseconds.
+   */
+  public ms() {
+    return performance.now() - this.start;
+  }
+
+  /**
+   * Returns the time elapsed since the Timer instance was created, in seconds.
+   * The value is calculated by subtracting the initial start time from the current time
+   * and dividing the result by 1000 to convert milliseconds to seconds.
+   *
+   * @returns The elapsed time in seconds.
+   */
+  public s() {
+    return this.ms() / 1000;
+  }
+}

package/src/bin/index.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { findBbBinary } from '../bb_backends/node/platform.js';
+import { spawnSync } from 'node:child_process';
+
+const bin = findBbBinary();
+
+if (!bin) {
+  console.error('Could not find bb binary. Please ensure it is built and accessible.');
+  process.exit(1);
+}
+
+const result = spawnSync(bin, process.argv.slice(2), { stdio: 'inherit' });
+
+process.exit(result.status ?? 1);

package/src/cbind/README.md

@@ -0,0 +1 @@
+Derives bindings from the reported msgpack schema from bb.

package/src/cbind/generate.ts

@@ -0,0 +1,182 @@
+/**
+ * Generate TypeScript bindings from msgpack schema
+ */
+
+import { writeFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { fileURLToPath } from 'url';
+import { unpack } from 'msgpackr';
+import {
+  createSharedTypesCompiler,
+  createSyncApiCompiler,
+  createAsyncApiCompiler,
+  type SchemaCompiler,
+} from './schema_compiler.js';
+
+const execAsync = promisify(exec);
+
+interface GeneratorConfig {
+  name: string;
+  outputFile: string;
+  createCompiler: () => SchemaCompiler;
+}
+
+const GENERATORS: GeneratorConfig[] = [
+  {
+    name: 'Shared types',
+    outputFile: 'generated/api_types.ts',
+    createCompiler: createSharedTypesCompiler,
+  },
+  {
+    name: 'Sync API',
+    outputFile: 'generated/sync.ts',
+    createCompiler: createSyncApiCompiler,
+  },
+  {
+    name: 'Async API',
+    outputFile: 'generated/async.ts',
+    createCompiler: createAsyncApiCompiler,
+  },
+];
+
+// @ts-ignore
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+async function generate() {
+  const bbBuildPath = process.env.BB_BINARY_PATH || join(__dirname, '../../../cpp/build/bin/bb');
+
+  // Get schema from bb
+  console.log('Fetching msgpack schema from bb...');
+  const { stdout } = await execAsync(`${bbBuildPath} msgpack schema`);
+  const schema = JSON.parse(stdout.trim());
+
+  if (!schema.commands || !schema.responses) {
+    throw new Error('Invalid schema: missing commands or responses');
+  }
+
+  console.log('Generating TypeScript bindings...\n');
+
+  // Ensure output directory exists
+  const outputDir = join(__dirname, 'generated');
+  mkdirSync(outputDir, { recursive: true });
+
+  // Generate each output file
+  for (const config of GENERATORS) {
+    const compiler = config.createCompiler();
+    compiler.processApiSchema(schema.commands, schema.responses);
+
+    const outputPath = join(__dirname, config.outputFile);
+    const content = compiler.compile();
+    writeFileSync(outputPath, content);
+
+    console.log(`✓ ${config.name}: ${outputPath}`);
+  }
+
+  // Generate curve constants
+  console.log('\nGenerating curve constants...');
+  await generateCurveConstants(bbBuildPath, outputDir);
+
+  console.log('\nGeneration complete!');
+}
+
+async function generateCurveConstants(bbBuildPath: string, outputDir: string) {
+  // Get curve constants from bb as msgpack binary
+  const { stdout: constantsBuffer } = await execAsync(`${bbBuildPath} msgpack curve_constants`, {
+    encoding: 'buffer',
+    maxBuffer: 10 * 1024 * 1024, // 10MB buffer
+  });
+
+  // Decode msgpack
+  const constants = unpack(constantsBuffer as Buffer);
+
+  // Helper to convert Uint8Array to hex string
+  const toHex = (bytes: Uint8Array) => '0x' + Buffer.from(bytes).toString('hex');
+
+  // Helper to convert Uint8Array to bigint (big-endian)
+  const toBigInt = (bytes: Uint8Array) => {
+    let result = 0n;
+    for (const byte of bytes) {
+      result = (result << 8n) | BigInt(byte);
+    }
+    return result;
+  };
+
+  // Helper to serialize point coordinate (handles both Uint8Array and array of Uint8Array for field2)
+  const serializeCoordinate = (coord: Uint8Array | Uint8Array[]) => {
+    if (Array.isArray(coord)) {
+      // For field2 (like BN254 G2), we have array of two Uint8Arrays
+      return `[${coord.map(c => `new Uint8Array([${Array.from(c).join(', ')}])`).join(', ')}]`;
+    } else {
+      // For regular fields, single Uint8Array
+      return `new Uint8Array([${Array.from(coord).join(', ')}])`;
+    }
+  };
+
+  // Generate TypeScript file
+  const content = `/**
+ * Curve constants generated from barretenberg native binary.
+ * DO NOT EDIT - This file is auto-generated by generate.ts
+ */
+
+/**
+ * BN254 curve constants
+ */
+export const BN254_FR_MODULUS = ${toBigInt(constants.bn254_fr_modulus)}n;
+export const BN254_FQ_MODULUS = ${toBigInt(constants.bn254_fq_modulus)}n;
+
+export const BN254_G1_GENERATOR = {
+  x: ${serializeCoordinate(constants.bn254_g1_generator.x)},
+  y: ${serializeCoordinate(constants.bn254_g1_generator.y)},
+} as const;
+
+export const BN254_G2_GENERATOR = {
+  x: ${serializeCoordinate(constants.bn254_g2_generator.x)},
+  y: ${serializeCoordinate(constants.bn254_g2_generator.y)},
+} as const;
+
+/**
+ * Grumpkin curve constants
+ */
+export const GRUMPKIN_FR_MODULUS = ${toBigInt(constants.grumpkin_fr_modulus)}n;
+export const GRUMPKIN_FQ_MODULUS = ${toBigInt(constants.grumpkin_fq_modulus)}n;
+
+export const GRUMPKIN_G1_GENERATOR = {
+  x: ${serializeCoordinate(constants.grumpkin_g1_generator.x)},
+  y: ${serializeCoordinate(constants.grumpkin_g1_generator.y)},
+} as const;
+
+/**
+ * Secp256k1 curve constants
+ */
+export const SECP256K1_FR_MODULUS = ${toBigInt(constants.secp256k1_fr_modulus)}n;
+export const SECP256K1_FQ_MODULUS = ${toBigInt(constants.secp256k1_fq_modulus)}n;
+
+export const SECP256K1_G1_GENERATOR = {
+  x: ${serializeCoordinate(constants.secp256k1_g1_generator.x)},
+  y: ${serializeCoordinate(constants.secp256k1_g1_generator.y)},
+} as const;
+
+/**
+ * Secp256r1 curve constants
+ */
+export const SECP256R1_FR_MODULUS = ${toBigInt(constants.secp256r1_fr_modulus)}n;
+export const SECP256R1_FQ_MODULUS = ${toBigInt(constants.secp256r1_fq_modulus)}n;
+
+export const SECP256R1_G1_GENERATOR = {
+  x: ${serializeCoordinate(constants.secp256r1_g1_generator.x)},
+  y: ${serializeCoordinate(constants.secp256r1_g1_generator.y)},
+} as const;
+`;
+
+  const outputPath = join(outputDir, 'curve_constants.ts');
+  writeFileSync(outputPath, content);
+  console.log(`✓ Curve constants: ${outputPath}`);
+}
+
+// Run the generator
+generate().catch(error => {
+  console.error('Generation failed:', error);
+  process.exit(1);
+});