@aztec/bb.js 0.0.1-alpha.7 → 0.0.1-commit.0208eb9

package/src/barretenberg_wasm/fetch_code/browser/index.ts

@@ -0,0 +1,34 @@
+import pako from 'pako';
+
+// Annoyingly the wasm declares if it's memory is shared or not. So now we need two wasms if we want to be
+// able to fallback on "non shared memory" situations.
+export async function fetchCode(multithreaded: boolean, wasmPath?: string) {
+  let url: string;
+  if (wasmPath) {
+    const suffix = multithreaded ? '-threads' : '';
+    const filePath = wasmPath.split('/').slice(0, -1).join('/');
+    const fileNameWithExtensions = wasmPath.split('/').pop();
+    const [fileName, ...extensions] = fileNameWithExtensions!.split('.');
+    url = `${filePath}/${fileName}${suffix}.${extensions.join('.')}`;
+  } else {
+    url = multithreaded
+      ? (await import('./barretenberg-threads.js')).default
+      : (await import('./barretenberg.js')).default;
+  }
+  const res = await fetch(url);
+  // Default bb wasm is compressed, but user could point it to a non-compressed version
+  const maybeCompressedData = await res.arrayBuffer();
+  const buffer = new Uint8Array(maybeCompressedData);
+  const isGzip =
+    // Check magic number
+    buffer[0] === 0x1f &&
+    buffer[1] === 0x8b &&
+    // Check compression method:
+    buffer[2] === 0x08;
+  if (isGzip) {
+    const decompressedData = pako.ungzip(buffer);
+    return decompressedData.buffer as unknown as Uint8Array<ArrayBuffer>;
+  } else {
+    return buffer;
+  }
+}

package/src/barretenberg_wasm/fetch_code/index.ts

@@ -0,0 +1 @@
+export * from './node/index.js';

package/src/barretenberg_wasm/fetch_code/node/index.ts

@@ -0,0 +1,34 @@
+import { readFile } from 'fs/promises';
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+import pako from 'pako';
+
+function getCurrentDir() {
+  if (typeof __dirname !== 'undefined') {
+    return __dirname;
+  } else {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    return dirname(fileURLToPath(import.meta.url));
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export async function fetchCode(multithreaded: boolean, wasmPath?: string) {
+  const path = wasmPath ?? getCurrentDir() + '/../../barretenberg-threads.wasm.gz';
+  // Default bb wasm is compressed, but user could point it to a non-compressed version
+  const maybeCompressedData = await readFile(path);
+  const buffer = new Uint8Array(maybeCompressedData);
+  const isGzip =
+    // Check magic number
+    buffer[0] === 0x1f &&
+    buffer[1] === 0x8b &&
+    // Check compression method:
+    buffer[2] === 0x08;
+  if (isGzip) {
+    const decompressedData = pako.ungzip(buffer);
+    return decompressedData.buffer as unknown as Uint8Array<ArrayBuffer>;
+  } else {
+    return buffer;
+  }
+}

package/src/barretenberg_wasm/fetch_code/wasm-module.d.ts

@@ -0,0 +1,4 @@
+declare module '*.wasm.gz' {
+  const content: string;
+  export default content;
+}

package/src/barretenberg_wasm/helpers/browser/index.ts

@@ -0,0 +1,54 @@
+import { wrap } from 'comlink';
+
+export function getSharedMemoryAvailable() {
+  const globalScope = typeof window !== 'undefined' ? window : globalThis;
+  return typeof SharedArrayBuffer !== 'undefined' && globalScope.crossOriginIsolated;
+}
+
+export function getRemoteBarretenbergWasm<T>(worker: Worker) {
+  return wrap<T>(worker);
+}
+
+export function getNumCpu() {
+  return navigator.hardwareConcurrency;
+}
+
+export function threadLogger(useCustomLogger: boolean): ((msg: string) => void) | undefined {
+  if (useCustomLogger) {
+    // Post log messages back to main thread for routing through user-provided logger
+    return (msg: string) => {
+      postMessage({ type: 'log', msg });
+    };
+  }
+  // Use console.log directly when no custom logger is provided
+  return console.log;
+}
+
+export function killSelf() {
+  self.close();
+}
+
+export function getAvailableThreads(logger: (msg: string) => void): number {
+  if (typeof navigator !== 'undefined' && navigator.hardwareConcurrency) {
+    return navigator.hardwareConcurrency;
+  } else {
+    logger(`Could not detect environment to query number of threads. Falling back to one thread.`);
+    return 1;
+  }
+}
+
+// Solution to async initialization of workers, taken from
+// https://github.com/GoogleChromeLabs/comlink/issues/635#issuecomment-1598913044
+
+/** The message expected by the `readinessListener`. */
+export const Ready = { ready: true };
+
+/** Listen for the readiness message from the Worker and call the `callback` once. */
+export function readinessListener(worker: Worker, callback: () => void) {
+  worker.addEventListener('message', function ready(event: MessageEvent<typeof Ready>) {
+    if (!!event.data && event.data.ready === true) {
+      worker.removeEventListener('message', ready);
+      callback();
+    }
+  });
+}

package/src/barretenberg_wasm/helpers/index.ts

@@ -0,0 +1 @@
+export * from './node/index.js';

package/src/barretenberg_wasm/helpers/node/index.ts

@@ -0,0 +1,62 @@
+import { Worker, parentPort } from 'worker_threads';
+import os from 'os';
+import { wrap } from 'comlink';
+import { nodeEndpoint } from './node_endpoint.js';
+import { writeSync } from 'fs';
+
+export function getSharedMemoryAvailable() {
+  return true;
+}
+
+/**
+ * Comlink allows you to produce a Proxy to the worker, enabling you to call methods as if it were a normal class.
+ * Note we give it the type information it needs so the returned Proxy object looks like that type.
+ * Node has a different implementation, needing this nodeEndpoint wrapper, hence this function exists here.
+ */
+export function getRemoteBarretenbergWasm<T>(worker: Worker) {
+  return wrap<T>(nodeEndpoint(worker));
+}
+
+/**
+ * Returns number of cpus as reported by the system, unless overriden by HARDWARE_CONCURRENCY env var.
+ */
+export function getNumCpu() {
+  return +process.env.HARDWARE_CONCURRENCY! || os.cpus().length;
+}
+
+/**
+ * Returns a logger function for worker threads.
+ * When a custom logger is provided, posts messages back to the main thread.
+ * Otherwise, writes directly to stdout.
+ */
+export function threadLogger(useCustomLogger: boolean): ((msg: string) => void) | undefined {
+  if (useCustomLogger) {
+    return (msg: string) => {
+      if (parentPort) {
+        parentPort.postMessage({ type: 'log', msg });
+      }
+    };
+  }
+  // Write directly to stdout when no custom logger is provided
+  return (msg: string) => {
+    writeSync(1, msg + '\n');
+  };
+}
+
+export function killSelf(): never {
+  // Extordinarily hard process termination. Due to how parent threads block on child threads etc, even process.exit
+  // doesn't seem to be able to abort the process. The following does.
+  process.kill(process.pid);
+  throw new Error();
+}
+
+export function getAvailableThreads(logger: (msg: string) => void): number {
+  try {
+    return os.cpus().length;
+  } catch (e: any) {
+    logger(
+      `Could not detect environment to query number of threads. Falling back to one thread. Error: ${e.message ?? e}`,
+    );
+    return 1;
+  }
+}

package/src/barretenberg_wasm/index.test.ts

@@ -0,0 +1,46 @@
+import { createMainWorker } from '../barretenberg_wasm/barretenberg_wasm_main/factory/node/index.js';
+import { BarretenbergWasmMainWorker } from '../barretenberg_wasm/barretenberg_wasm_main/index.js';
+import { getRemoteBarretenbergWasm } from '../barretenberg_wasm/helpers/index.js';
+import { fetchModuleAndThreads } from '../barretenberg_wasm/index.js';
+import { Worker } from 'worker_threads';
+
+describe('barretenberg wasm', () => {
+  let wasm: BarretenbergWasmMainWorker;
+  let worker: Worker;
+
+  beforeAll(async () => {
+    worker = await createMainWorker();
+    wasm = getRemoteBarretenbergWasm<BarretenbergWasmMainWorker>(worker);
+    const { module, threads } = await fetchModuleAndThreads(2);
+    await wasm.init(module, threads);
+  }, 20000);
+
+  afterAll(async () => {
+    await wasm.destroy();
+    await worker.terminate();
+  });
+
+  it('should new malloc, transfer and slice mem', async () => {
+    const length = 1024;
+    const ptr = await wasm.call('bbmalloc', length);
+    const buf = Buffer.alloc(length, 128);
+    await wasm.writeMemory(ptr, Uint8Array.from(buf));
+    const result = Buffer.from(await wasm.getMemorySlice(ptr, ptr + length));
+    await wasm.call('bbfree', ptr);
+    expect(result).toStrictEqual(buf);
+  });
+
+  it('test abort', async () => {
+    await expect(() => wasm.call('test_abort')).rejects.toThrow();
+  });
+
+  it('should new malloc, transfer and slice mem', async () => {
+    const length = 1024;
+    const ptr = await wasm.call('bbmalloc', length);
+    const buf = Buffer.alloc(length, 128);
+    await wasm.writeMemory(ptr, Uint8Array.from(buf));
+    const result = Buffer.from(await wasm.getMemorySlice(ptr, ptr + length));
+    await wasm.call('bbfree', ptr);
+    expect(result).toStrictEqual(buf);
+  });
+});

package/src/barretenberg_wasm/index.ts

@@ -1 +1,21 @@
-export * from './barretenberg_wasm.js';
+import { getSharedMemoryAvailable, getAvailableThreads } from './helpers/node/index.js';
+import { fetchCode } from './fetch_code/index.js';
+
+export async function fetchModuleAndThreads(
+  desiredThreads = 32,
+  wasmPath?: string,
+  logger: (msg: string) => void = () => {},
+) {
+  const shared = getSharedMemoryAvailable();
+
+  const availableThreads = shared ? await getAvailableThreads(logger) : 1;
+  // We limit the number of threads to 32 as we do not benefit from greater numbers.
+  const limitedThreads = Math.min(desiredThreads, availableThreads, 32);
+
+  logger(`Fetching bb wasm from ${wasmPath ?? 'default location'}`);
+  const code = await fetchCode(shared, wasmPath);
+  logger(`Compiling bb wasm of ${code.byteLength} bytes`);
+  const module = await WebAssembly.compile(code);
+  logger('Compilation of bb wasm complete');
+  return { module, threads: limitedThreads };
+}

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,55 @@
+/**
+ * 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 Custom path to bb NAPI module for native backend (overrides automatic detection) */
+  napiPath?: 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,107 @@
+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(options.napiPath);
+      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,
+        napiPath,
+        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(options.napiPath);
+      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, napiPath, 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());
+    });
+  }
+}