@aztec/bb.js 0.0.1-alpha.7 → 0.0.1-commit.21caa21

package/src/bb_backends/browser/index.ts

@@ -0,0 +1,50 @@
+import { BarretenbergWasmSyncBackend, BarretenbergWasmAsyncBackend } from '../wasm.js';
+import { Barretenberg, BarretenbergSync } from '../../barretenberg/index.js';
+import { BackendOptions, BackendType } from '../index.js';
+
+/**
+ * Create backend of specific type (no fallback)
+ */
+export async function createAsyncBackend(
+  type: BackendType,
+  options: BackendOptions,
+  logger: (msg: string) => void,
+): Promise<Barretenberg> {
+  switch (type) {
+    case BackendType.Wasm:
+    case BackendType.WasmWorker: {
+      const useWorker = type === BackendType.WasmWorker;
+      logger(`Using WASM backend (worker: ${useWorker})`);
+      const wasm = await BarretenbergWasmAsyncBackend.new({
+        threads: options.threads,
+        wasmPath: options.wasmPath,
+        logger,
+        memory: options.memory,
+        useWorker,
+      });
+      return new Barretenberg(wasm, options);
+    }
+
+    default:
+      throw new Error(`Unknown backend type: ${type}`);
+  }
+}
+
+/**
+ * Create backend of specific type (no fallback)
+ */
+export async function createSyncBackend(
+  type: BackendType,
+  options: BackendOptions,
+  logger: (msg: string) => void,
+): Promise<BarretenbergSync> {
+  switch (type) {
+    case BackendType.Wasm:
+      logger('Using WASM backend');
+      const wasm = await BarretenbergWasmSyncBackend.new(options.wasmPath, logger);
+      return new BarretenbergSync(wasm);
+
+    default:
+      throw new Error(`Backend ${type} not supported for BarretenbergSync`);
+  }
+}

package/src/bb_backends/browser/platform.ts

@@ -0,0 +1,11 @@
+export function findPackageRoot(): string | null {
+  throw new Error('Not implemented in browser environment.');
+}
+
+export function findBbBinary(customPath?: string): string | null {
+  throw new Error('Not implemented in browser environment.');
+}
+
+export function findNapiBinary(customPath?: string): string | null {
+  throw new Error('Not implemented in browser environment.');
+}

package/src/bb_backends/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Backend types for Barretenberg
+ */
+export enum BackendType {
+  /** WASM direct execution (no worker) */
+  Wasm = 'Wasm',
+  /** WASM with worker threads */
+  WasmWorker = 'WasmWorker',
+  /** Native via Unix domain socket (async only) */
+  NativeUnixSocket = 'NativeUnixSocket',
+  /** Native via shared memory */
+  NativeSharedMemory = 'NativeSharedMemory',
+}
+
+export type BackendOptions = {
+  /** @description Number of threads to run the backend worker on */
+  threads?: number;
+
+  /** @description Initial and Maximum memory to be alloted to the backend worker */
+  memory?: { initial?: number; maximum?: number };
+
+  /** @description Path to download CRS files */
+  crsPath?: string;
+
+  /** @description Path to download WASM files */
+  wasmPath?: string;
+
+  /** @description Custom path to bb binary for native backend (overrides automatic detection) */
+  bbPath?: string;
+
+  /**
+   * @description Logging function
+   * Warning: Attaching a logger can prevent nodejs from exiting without explicitly destroying the backend.
+   */
+  logger?: (msg: string) => void;
+
+  /**
+   * @description Maximum concurrent clients for shared memory IPC server (default: 1)
+   * Only applies to NativeSharedMemory backend
+   */
+  maxClients?: number;
+
+  /**
+   * @description Specify exact backend to use
+   * - If unset: tries backends in default order with fallback
+   * - If set: must succeed with specified backend or throw error (no fallback)
+   *
+   * Barretenberg (async) supports: all types
+   * BarretenbergSync supports: Wasm, NativeSharedMem only
+   */
+  backend?: BackendType;
+};

package/src/bb_backends/interface.ts

@@ -0,0 +1,35 @@
+/**
+ * Generic interface for msgpack backend implementations.
+ * Both WASM and native binary backends implement this interface.
+ */
+export interface IMsgpackBackend {
+  /**
+   * Execute a msgpack command and return the msgpack response.
+   * @param inputBuffer The msgpack-encoded input buffer
+   * @returns The msgpack-encoded response buffer (sync or async)
+   */
+  call(inputBuffer: Uint8Array): Uint8Array | Promise<Uint8Array>;
+
+  /**
+   * Clean up resources.
+   */
+  destroy(): void | Promise<void>;
+}
+
+/**
+ * Synchronous variant of IMsgpackBackend.
+ * Used by BarretenbergSync and SyncApi.
+ */
+export interface IMsgpackBackendSync extends IMsgpackBackend {
+  call(inputBuffer: Uint8Array): Uint8Array;
+  destroy(): void;
+}
+
+/**
+ * Asynchronous variant of IMsgpackBackend.
+ * Used by Barretenberg and AsyncApi.
+ */
+export interface IMsgpackBackendAsync extends IMsgpackBackend {
+  call(inputBuffer: Uint8Array): Promise<Uint8Array>;
+  destroy(): Promise<void>;
+}

package/src/bb_backends/node/index.ts

@@ -0,0 +1,102 @@
+import { BarretenbergNativeSocketAsyncBackend } from './native_socket.js';
+import { BarretenbergWasmSyncBackend, BarretenbergWasmAsyncBackend } from '../wasm.js';
+import { BarretenbergNativeShmSyncBackend } from './native_shm.js';
+import { BarretenbergNativeShmAsyncBackend } from './native_shm_async.js';
+import { findBbBinary, findNapiBinary } from './platform.js';
+import { Barretenberg, BarretenbergSync } from '../../barretenberg/index.js';
+import { BackendOptions, BackendType } from '../index.js';
+
+/**
+ * Create backend of specific type (no fallback)
+ */
+export async function createAsyncBackend(
+  type: BackendType,
+  options: BackendOptions,
+  logger: (msg: string) => void,
+): Promise<Barretenberg> {
+  options = {
+    ...options,
+    wasmPath: options.wasmPath ?? process.env.BB_WASM_PATH,
+  };
+
+  switch (type) {
+    case BackendType.NativeUnixSocket: {
+      const bbPath = findBbBinary(options.bbPath);
+      if (!bbPath) {
+        throw new Error('Native backend requires bb binary.');
+      }
+      logger(`Using native Unix socket backend: ${bbPath}`);
+      const socket = new BarretenbergNativeSocketAsyncBackend(bbPath, options.threads, options.logger);
+      return new Barretenberg(socket, options);
+    }
+
+    case BackendType.NativeSharedMemory: {
+      const bbPath = findBbBinary(options.bbPath);
+      if (!bbPath) {
+        throw new Error('Native backend requires bb binary.');
+      }
+      const napiPath = findNapiBinary();
+      if (!napiPath) {
+        throw new Error('Native async backend requires napi client stub.');
+      }
+      logger(`Using native shared memory async backend: ${bbPath}`);
+      const asyncBackend = await BarretenbergNativeShmAsyncBackend.new(bbPath, options.threads, options.logger);
+      return new Barretenberg(asyncBackend, options);
+    }
+
+    case BackendType.Wasm:
+    case BackendType.WasmWorker: {
+      const useWorker = type === BackendType.WasmWorker;
+      logger(`Using WASM backend (worker: ${useWorker})`);
+      const wasm = await BarretenbergWasmAsyncBackend.new({
+        threads: options.threads,
+        wasmPath: options.wasmPath,
+        logger: options.logger,
+        memory: options.memory,
+        useWorker,
+      });
+      return new Barretenberg(wasm, options);
+    }
+
+    default:
+      throw new Error(`Unknown backend type: ${type}`);
+  }
+}
+
+/**
+ * Create backend of specific type (no fallback)
+ */
+export async function createSyncBackend(
+  type: BackendType,
+  options: BackendOptions,
+  logger: (msg: string) => void,
+): Promise<BarretenbergSync> {
+  options = {
+    ...options,
+    wasmPath: options.wasmPath ?? process.env.BB_WASM_PATH,
+  };
+
+  switch (type) {
+    case BackendType.NativeSharedMemory: {
+      const bbPath = findBbBinary(options.bbPath);
+      if (!bbPath) {
+        throw new Error('Native backend requires bb binary.');
+      }
+      const napiPath = findNapiBinary();
+      if (!napiPath) {
+        throw new Error('Native sync backend requires napi client stub.');
+      }
+      logger(`Using native shared memory backend: ${bbPath}`);
+      const shm = await BarretenbergNativeShmSyncBackend.new(bbPath, options.threads, options.logger);
+      return new BarretenbergSync(shm);
+    }
+
+    case BackendType.Wasm:
+      logger('Using WASM backend');
+      const wasm = await BarretenbergWasmSyncBackend.new(options.wasmPath, logger);
+      return new BarretenbergSync(wasm);
+
+    default:
+      throw new Error(`Backend ${type} not supported for BarretenbergSync`);
+  }
+}

package/src/bb_backends/node/native_pipe.ts

@@ -0,0 +1,127 @@
+import { spawn, ChildProcess } from 'child_process';
+import * as fs from 'fs';
+import { IMsgpackBackendSync, IMsgpackBackendAsync } from '../interface.js';
+
+/**
+ * Asynchronous native backend that communicates with bb binary via stdin/stdout.
+ * Uses event-based I/O with a state machine to handle partial reads.
+ *
+ * Protocol:
+ * - Request: 4-byte little-endian length + msgpack buffer
+ * - Response: 4-byte little-endian length + msgpack buffer
+ */
+export class BarretenbergNativePipeAsyncBackend implements IMsgpackBackendAsync {
+  private process: ChildProcess;
+  private pendingResolve: ((data: Uint8Array) => void) | null = null;
+  private pendingReject: ((error: Error) => void) | null = null;
+
+  // State machine for reading responses
+  private readingLength: boolean = true;
+  private lengthBuffer: Buffer = Buffer.alloc(4);
+  private lengthBytesRead: number = 0;
+  private responseLength: number = 0;
+  private responseBuffer: Buffer | null = null;
+  private responseBytesRead: number = 0;
+
+  constructor(bbBinaryPath: string) {
+    this.process = spawn(bbBinaryPath, ['msgpack', 'run'], {
+      stdio: ['pipe', 'pipe', 'inherit'],
+    });
+
+    this.process.stdout!.on('data', (chunk: Buffer) => {
+      this.handleData(chunk);
+    });
+
+    this.process.on('error', err => {
+      if (this.pendingReject) {
+        this.pendingReject(new Error(`Native backend process error: ${err.message}`));
+        this.pendingReject = null;
+        this.pendingResolve = null;
+      }
+    });
+
+    this.process.on('exit', (code, signal) => {
+      if (this.pendingReject) {
+        if (code !== null && code !== 0) {
+          this.pendingReject(new Error(`Native backend process exited with code ${code}`));
+        } else if (signal) {
+          if (signal != 'SIGTERM') {
+            this.pendingReject(new Error(`Native backend process killed with signal ${signal}`));
+          }
+        } else {
+          this.pendingReject(new Error('Native backend process exited unexpectedly'));
+        }
+        this.pendingReject = null;
+        this.pendingResolve = null;
+      }
+    });
+  }
+
+  private handleData(chunk: Buffer): void {
+    let offset = 0;
+
+    while (offset < chunk.length) {
+      if (this.readingLength) {
+        // Reading 4-byte length prefix
+        const bytesToCopy = Math.min(4 - this.lengthBytesRead, chunk.length - offset);
+        chunk.copy(this.lengthBuffer, this.lengthBytesRead, offset, offset + bytesToCopy);
+        this.lengthBytesRead += bytesToCopy;
+        offset += bytesToCopy;
+
+        if (this.lengthBytesRead === 4) {
+          // Length is complete, switch to reading data
+          this.responseLength = this.lengthBuffer.readUInt32LE(0);
+          this.responseBuffer = Buffer.alloc(this.responseLength);
+          this.responseBytesRead = 0;
+          this.readingLength = false;
+        }
+      } else {
+        // Reading response data
+        const bytesToCopy = Math.min(this.responseLength - this.responseBytesRead, chunk.length - offset);
+        chunk.copy(this.responseBuffer!, this.responseBytesRead, offset, offset + bytesToCopy);
+        this.responseBytesRead += bytesToCopy;
+        offset += bytesToCopy;
+
+        if (this.responseBytesRead === this.responseLength) {
+          // Response is complete
+          if (this.pendingResolve) {
+            this.pendingResolve(new Uint8Array(this.responseBuffer!));
+            this.pendingResolve = null;
+            this.pendingReject = null;
+          }
+
+          // Reset state for next message
+          this.readingLength = true;
+          this.lengthBytesRead = 0;
+          this.responseLength = 0;
+          this.responseBuffer = null;
+          this.responseBytesRead = 0;
+        }
+      }
+    }
+  }
+
+  async call(inputBuffer: Uint8Array): Promise<Uint8Array> {
+    if (this.pendingResolve) {
+      throw new Error('Cannot call while another call is pending (no pipelining supported)');
+    }
+
+    return new Promise((resolve, reject) => {
+      this.pendingResolve = resolve;
+      this.pendingReject = reject;
+
+      // Write request: 4-byte little-endian length + msgpack data
+      const lengthBuf = Buffer.alloc(4);
+      lengthBuf.writeUInt32LE(inputBuffer.length, 0);
+      this.process.stdin!.write(lengthBuf);
+      this.process.stdin!.write(inputBuffer);
+    });
+  }
+
+  async destroy(): Promise<void> {
+    this.process.kill();
+    return new Promise(resolve => {
+      this.process.once('exit', () => resolve());
+    });
+  }
+}

package/src/bb_backends/node/native_shm.ts

@@ -0,0 +1,195 @@
+import { createRequire } from 'module';
+import { spawn, ChildProcess } from 'child_process';
+import { openSync, closeSync } from 'fs';
+import { IMsgpackBackendSync } from '../interface.js';
+import { findNapiBinary, findPackageRoot } from './platform.js';
+
+// Import the NAPI module
+// The addon is built to the nodejs_module directory
+const addonPath = findNapiBinary();
+// Try loading, but don't throw if it doesn't exist (will be caught in constructor)
+let addon: any = null;
+try {
+  if (addonPath) {
+    const require = createRequire(findPackageRoot()!);
+    addon = require(addonPath);
+  }
+} catch (err) {
+  // Addon not built yet or not available
+  addon = null;
+}
+
+let instanceCounter = 0;
+
+/**
+ * Synchronous shared memory backend that communicates with bb binary via shared memory.
+ * Uses NAPI module to interface with shared memory IPC.
+ *
+ * Architecture: bb acts as the SERVER, TypeScript is the CLIENT
+ * - bb creates the shared memory region
+ * - TypeScript connects via NAPI wrapper
+ *
+ * Protocol:
+ * - Handled internally by IpcClient (no manual length prefixes needed)
+ */
+export class BarretenbergNativeShmSyncBackend implements IMsgpackBackendSync {
+  private process: ChildProcess;
+  private client: any; // NAPI MsgpackClient instance
+  private logFd?: number; // File descriptor for logs
+
+  private constructor(process: ChildProcess, client: any, logFd?: number) {
+    this.process = process;
+    this.client = client;
+    this.logFd = logFd;
+  }
+
+  /**
+   * Create and initialize a shared memory backend.
+   * @param bbBinaryPath Path to bb binary
+   * @param threads Optional number of threads
+   */
+  static async new(
+    bbBinaryPath: string,
+    threads?: number,
+    logger?: (msg: string) => void,
+  ): Promise<BarretenbergNativeShmSyncBackend> {
+    if (!addon || !addon.MsgpackClient) {
+      throw new Error('Shared memory NAPI not available.');
+    }
+
+    // Create a unique shared memory name
+    const shmName = `bb-sync-${process.pid}-${instanceCounter++}`;
+
+    // If threads not set use 1 thread. We're not expected to do long lived work on sync backends.
+    const hwc = threads ? threads.toString() : '1';
+    const env = { ...process.env, HARDWARE_CONCURRENCY: hwc };
+
+    // Set up file logging if logger is provided.
+    // Direct file redirection bypasses Node event loop - logs are written even if process hangs.
+    let logFd: number | undefined;
+    let logPath: string | undefined;
+    if (logger) {
+      logPath = `/tmp/${shmName}.log`;
+      logFd = openSync(logPath, 'w');
+      logger(`BB process logs redirected to: ${logPath}`);
+    }
+
+    // Spawn bb process with shared memory mode (SPSC-only, no max-clients needed)
+    const args = ['msgpack', 'run', '--input', `${shmName}.shm`, '--request-ring-size', `${1024 * 1024 * 4}`];
+    const bbProcess = spawn(bbBinaryPath, args, {
+      stdio: ['ignore', logFd ?? 'ignore', logFd ?? 'ignore'],
+      env,
+    });
+
+    // Disconnect from event loop so process can exit without waiting for bb
+    // The bb process has parent death monitoring (prctl on Linux, kqueue on macOS)
+    // so it will automatically exit when Node.js exits
+    bbProcess.unref();
+
+    // Track if process has exited
+    let processExited = false;
+    let exitError: Error | null = null;
+
+    bbProcess.on('error', err => {
+      processExited = true;
+      exitError = new Error(`Native backend process error: ${err.message}`);
+    });
+
+    bbProcess.on('exit', (code, signal) => {
+      processExited = true;
+      if (code !== null && code !== 0) {
+        exitError = new Error(`Native backend process exited with code ${code}`);
+      } else if (signal && signal !== 'SIGTERM') {
+        exitError = new Error(`Native backend process killed with signal ${signal}`);
+      }
+    });
+
+    // Wait for bb to create shared memory
+    // Retry connection every 100ms for up to 3 seconds
+    const retryInterval = 100; // ms
+    const timeout = 3000; // ms
+    const maxAttempts = Math.floor(timeout / retryInterval);
+    let client: any = null;
+
+    try {
+      for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        // Check if bb process has exited before attempting connection
+        if (processExited) {
+          throw exitError || new Error('Native backend process exited unexpectedly during startup');
+        }
+
+        // Wait before attempting connection (except first attempt)
+        if (attempt > 0) {
+          await new Promise(resolve => setTimeout(resolve, retryInterval));
+        }
+
+        try {
+          // Create NAPI client (SPSC-only, no max_clients needed)
+          client = new addon.MsgpackClient(shmName);
+          break; // Success!
+        } catch (err: any) {
+          // Connection failed, will retry
+          if (attempt === maxAttempts - 1) {
+            // Last attempt failed - check one more time if process exited
+            if (processExited && exitError) {
+              throw exitError;
+            }
+            throw new Error(`Failed to connect to shared memory after ${timeout}ms: ${err.message}`);
+          }
+        }
+      }
+
+      if (!client) {
+        throw new Error('Failed to create client connection');
+      }
+
+      return new BarretenbergNativeShmSyncBackend(bbProcess, client, logFd);
+    } finally {
+      // If we failed to connect, ensure the process is killed and log file closed
+      // kill() returns false if process already exited, but doesn't throw
+      if (!client) {
+        bbProcess.kill('SIGKILL');
+        if (logFd !== undefined) {
+          try {
+            closeSync(logFd);
+          } catch (e) {
+            // Ignore errors during cleanup
+          }
+        }
+      }
+    }
+  }
+
+  call(inputBuffer: Uint8Array): Uint8Array {
+    try {
+      const responseBuffer = this.client.call(Buffer.from(inputBuffer));
+      return new Uint8Array(responseBuffer);
+    } catch (err: any) {
+      throw new Error(`Shared memory call failed: ${err.message}`);
+    }
+  }
+
+  private cleanup(): void {
+    if (this.client) {
+      try {
+        this.client.close();
+      } catch (e) {
+        // Ignore errors during cleanup
+      }
+    }
+    if (this.logFd !== undefined) {
+      try {
+        closeSync(this.logFd);
+      } catch (e) {
+        // Ignore errors during cleanup
+      }
+    }
+  }
+
+  destroy(): void {
+    this.cleanup();
+    this.process.kill('SIGTERM');
+    // Remove process event listeners to prevent hanging
+    this.process.removeAllListeners();
+  }
+}