@aztec/bb.js 0.0.1-alpha.6 → 0.0.1-commit.24de95ac

package/src/barretenberg/pedersen.test.ts

@@ -0,0 +1,69 @@
+import { BarretenbergSync } from './index.js';
+import { Timer } from '../benchmark/timer.js';
+import { Fr } from '../types/index.js';
+
+describe('pedersen sync', () => {
+  let api: BarretenbergSync;
+
+  beforeAll(async () => {
+    api = await BarretenbergSync.initSingleton();
+  });
+
+  it('pedersenHash', () => {
+    const response = api.pedersenHash({ inputs: [new Fr(4n).toBuffer(), new Fr(8n).toBuffer()], hashIndex: 7 });
+    const result = Fr.fromBuffer(response.hash);
+    expect(result).toMatchSnapshot();
+  });
+
+  it('pedersenHash perf test', () => {
+    const loops = 1000;
+    const fields = Array.from({ length: loops * 2 }).map(() => Fr.random());
+    const t = new Timer();
+    for (let i = 0; i < loops; ++i) {
+      api.pedersenHash({ inputs: [fields[i * 2].toBuffer(), fields[i * 2 + 1].toBuffer()], hashIndex: 0 });
+    }
+    const us = t.us() / loops;
+    console.log(`Executed ${loops} hashes at an average ${us}us / hash`);
+  });
+
+  // TODO: pedersenHashes not yet in new msgpack API
+  // it.skip('pedersenHashes perf test', () => {
+  //   const loops = 10;
+  //   const numHashesPerLoop = 1024;
+  //   const fields = Array.from({ length: numHashesPerLoop * 2 }).map(() => Fr.random());
+  //   const t = new Timer();
+  //   for (let i = 0; i < loops; ++i) {
+  //     // api.pedersenHashes(fields, 0); // Not in new API yet
+  //   }
+  //   const us = t.us() / (numHashesPerLoop * loops);
+  //   console.log(`Executed ${numHashesPerLoop * loops} hashes at an average ${us}us / hash`);
+  // });
+
+  it('pedersenHashBuffer', () => {
+    const input = Buffer.alloc(123);
+    input.writeUint32BE(321, 0);
+    input.writeUint32BE(456, 119);
+    const response = api.pedersenHashBuffer({ input, hashIndex: 0 });
+    const r = Fr.fromBuffer(response.hash);
+    expect(r).toMatchSnapshot();
+  });
+
+  it('pedersenCommit', () => {
+    const response = api.pedersenCommit({
+      inputs: [new Fr(4n).toBuffer(), new Fr(8n).toBuffer(), new Fr(12n).toBuffer()],
+      hashIndex: 0,
+    });
+    const result = { x: Fr.fromBuffer(response.point.x), y: Fr.fromBuffer(response.point.y) };
+    expect(result).toMatchSnapshot();
+  });
+
+  it.skip('pedersenCommit perf test', () => {
+    const loops = 1000;
+    const fields = Array.from({ length: loops * 2 }).map(() => Fr.random());
+    const t = new Timer();
+    for (let i = 0; i < loops; ++i) {
+      api.pedersenCommit({ inputs: [fields[i * 2].toBuffer(), fields[i * 2 + 1].toBuffer()], hashIndex: 0 });
+    }
+    console.log(t.us() / loops);
+  });
+});

package/src/barretenberg/poseidon.bench.test.ts

@@ -0,0 +1,268 @@
+import { Barretenberg, BarretenbergSync } from '../index.js';
+import { Fr } from '../types/fields.js';
+import { serializeBufferable } from '../serialize/index.js';
+import { BarretenbergWasmMain } from '../barretenberg_wasm/barretenberg_wasm_main/index.js';
+import { fetchModuleAndThreads } from '../barretenberg_wasm/index.js';
+import { BackendType } from './index.js';
+
+/**
+ * Async API benchmark test: WASM vs Native backends with proper non-blocking I/O
+ *
+ * This test uses the async Barretenberg API which properly handles:
+ * - Non-blocking I/O for native backend (event-based)
+ * - Concurrent operations via promises
+ * - Better performance for native backend compared to sync API
+ */
+describe('poseidon2Hash benchmark (Async API): WASM vs Native', () => {
+  const ITERATIONS = 10000;
+  const SIZES = [2, 4, 8];
+
+  let wasmApi: Barretenberg | null = null;
+  let nativeSocketApi: Barretenberg | null = null;
+  let nativeShmApi: Barretenberg | null = null;
+  let nativeShmSyncApi: BarretenbergSync | null = null;
+  let wasm: BarretenbergWasmMain;
+
+  beforeAll(async () => {
+    // Setup direct WASM access for baseline benchmark (always required)
+    wasm = new BarretenbergWasmMain();
+    const { module } = await fetchModuleAndThreads(1);
+    await wasm.init(module, 1);
+
+    // Setup WASM API
+    try {
+      wasmApi = await Barretenberg.new({ backend: BackendType.Wasm, threads: 1 });
+    } catch (error) {
+      console.warn('Failed to initialize WASM backend:', error instanceof Error ? error.message : String(error));
+    }
+
+    // Setup native socket API
+    try {
+      nativeSocketApi = await Barretenberg.new({ backend: BackendType.NativeUnixSocket, threads: 1 });
+    } catch (error) {
+      console.warn(
+        'Failed to initialize Native Socket backend:',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+
+    // Setup native shared memory API (async)
+    try {
+      nativeShmApi = await Barretenberg.new({ backend: BackendType.NativeSharedMemory, threads: 1 });
+    } catch (error) {
+      console.warn(
+        'Failed to initialize Native Shared Memory (async) backend:',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+
+    // Setup native shared memory API (sync)
+    try {
+      nativeShmSyncApi = await BarretenbergSync.new({ backend: BackendType.NativeSharedMemory, threads: 1 });
+    } catch (error) {
+      console.warn(
+        'Failed to initialize Native Shared Memory (sync) backend:',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+  }, 20000);
+
+  afterAll(async () => {
+    await wasm.destroy();
+    if (wasmApi) {
+      await wasmApi.destroy();
+    }
+    if (nativeSocketApi) {
+      await nativeSocketApi.destroy();
+    }
+    if (nativeShmApi) {
+      await nativeShmApi.destroy();
+    }
+    if (nativeShmSyncApi) {
+      nativeShmSyncApi.destroy();
+    }
+  });
+
+  async function directPoseidon2Hash(inputsBuffer: Fr[]): Promise<Fr> {
+    const inArgs = [inputsBuffer].map(serializeBufferable);
+    const outTypes = [Fr];
+    const result = wasm.callWasmExport(
+      'poseidon2_hash',
+      inArgs,
+      outTypes.map(t => t.SIZE_IN_BYTES),
+    );
+    const out = result.map((r, i) => outTypes[i].fromBuffer(r));
+    return Promise.resolve(out[0]);
+  }
+
+  it.each(SIZES)('benchmark with %p field elements', async size => {
+    // Generate random inputs
+    const inputs = Array(size)
+      .fill(0)
+      .map(() => Fr.random());
+
+    // Benchmark 1: Direct WASM (baseline - always available)
+    const directStart = performance.now();
+    for (let i = 0; i < ITERATIONS; i++) {
+      await directPoseidon2Hash(inputs);
+    }
+    const directTime = performance.now() - directStart;
+
+    // Benchmark 2: WASM (async)
+    let wasmTime = 0;
+    if (wasmApi) {
+      const wasmStart = performance.now();
+      for (let i = 0; i < ITERATIONS; i++) {
+        await wasmApi.poseidon2Hash({ inputs: inputs.map(fr => fr.toBuffer()) });
+      }
+      wasmTime = performance.now() - wasmStart;
+    }
+
+    // Benchmark 3: Native Socket (async with non-blocking I/O)
+    let nativeSocketTime = 0;
+    if (nativeSocketApi) {
+      const nativeSocketStart = performance.now();
+      for (let i = 0; i < ITERATIONS; i++) {
+        await nativeSocketApi.poseidon2Hash({ inputs: inputs.map(fr => fr.toBuffer()) });
+      }
+      nativeSocketTime = performance.now() - nativeSocketStart;
+    }
+
+    // Benchmark 4: Native Shared Memory (async)
+    let nativeShmTime = 0;
+    if (nativeShmApi) {
+      const nativeShmStart = performance.now();
+      for (let i = 0; i < ITERATIONS; i++) {
+        await nativeShmApi.poseidon2Hash({ inputs: inputs.map(fr => fr.toBuffer()) });
+      }
+      nativeShmTime = performance.now() - nativeShmStart;
+    }
+
+    // Benchmark 5: Native Shared Memory (sync)
+    let nativeShmSyncTime = 0;
+    if (nativeShmSyncApi) {
+      const nativeShmSyncStart = performance.now();
+      for (let i = 0; i < ITERATIONS; i++) {
+        nativeShmSyncApi.poseidon2Hash({ inputs: inputs.map(fr => fr.toBuffer()) });
+      }
+      nativeShmSyncTime = performance.now() - nativeShmSyncStart;
+    }
+
+    // Calculate metrics (all relative to WASM baseline)
+    const directOverhead = ((directTime - wasmTime) / wasmTime) * 100;
+    const nativeSocketOverhead = ((nativeSocketTime - wasmTime) / wasmTime) * 100;
+    const nativeShmOverhead = ((nativeShmTime - wasmTime) / wasmTime) * 100;
+    const nativeShmSyncOverhead = ((nativeShmSyncTime - wasmTime) / wasmTime) * 100;
+
+    const avgDirectTimeUs = (directTime / ITERATIONS) * 1000; // microseconds
+    const avgWasmTimeUs = (wasmTime / ITERATIONS) * 1000;
+    const avgNativeSocketTimeUs = (nativeSocketTime / ITERATIONS) * 1000;
+    const avgNativeShmTimeUs = (nativeShmTime / ITERATIONS) * 1000;
+    const avgNativeShmSyncTimeUs = (nativeShmSyncTime / ITERATIONS) * 1000;
+
+    process.stdout.write(`┌─ Size ${size.toString().padStart(3)} field elements ──────────────────────────────────┐\n`);
+    const formatOverhead = (overhead: number): string => {
+      const sign = overhead >= 0 ? '+' : '-';
+      const value = Math.abs(overhead).toFixed(1).padStart(6);
+      return `${sign}${value}%`;
+    };
+
+    if (wasmApi) {
+      process.stdout.write(
+        `│ WASM:               ${wasmTime.toFixed(2).padStart(8)}ms (${avgWasmTimeUs.toFixed(2).padStart(7)}µs/call) [baseline] │\n`,
+      );
+    } else {
+      process.stdout.write(`│ WASM:                                          unavailable │\n`);
+    }
+
+    process.stdout.write(
+      `│ Direct WASM:        ${directTime.toFixed(2).padStart(8)}ms (${avgDirectTimeUs.toFixed(2).padStart(7)}µs/call) ${formatOverhead(directOverhead)}   │\n`,
+    );
+
+    if (nativeSocketApi) {
+      process.stdout.write(
+        `│ Native Socket:      ${nativeSocketTime.toFixed(2).padStart(8)}ms (${avgNativeSocketTimeUs.toFixed(2).padStart(7)}µs/call) ${formatOverhead(nativeSocketOverhead)}   │\n`,
+      );
+    } else {
+      process.stdout.write(`│ Native Socket:                                 unavailable │\n`);
+    }
+
+    if (nativeShmApi) {
+      process.stdout.write(
+        `│ Native Shared:      ${nativeShmTime.toFixed(2).padStart(8)}ms (${avgNativeShmTimeUs.toFixed(2).padStart(7)}µs/call) ${formatOverhead(nativeShmOverhead)}   │\n`,
+      );
+    } else {
+      process.stdout.write(`│ Native Shared:                                 unavailable │\n`);
+    }
+
+    if (nativeShmSyncApi) {
+      process.stdout.write(
+        `│ Native Shared Sync: ${nativeShmSyncTime.toFixed(2).padStart(8)}ms (${avgNativeShmSyncTimeUs.toFixed(2).padStart(7)}µs/call) ${formatOverhead(nativeShmSyncOverhead)}   │\n`,
+      );
+    } else {
+      process.stdout.write(`│ Native Shared Sync:                            unavailable │\n`);
+    }
+
+    process.stdout.write(`└────────────────────────────────────────────────────────────┘\n`);
+
+    // Sanity check: verify all backends produce same result as direct WASM
+    const directResult = await directPoseidon2Hash(inputs);
+
+    if (wasmApi) {
+      const wasmResult = await wasmApi.poseidon2Hash({ inputs: inputs.map(fr => fr.toBuffer()) });
+      expect(Buffer.from(wasmResult.hash)).toEqual(directResult.toBuffer());
+    }
+
+    if (nativeSocketApi) {
+      const nativeSocketResult = await nativeSocketApi.poseidon2Hash({ inputs: inputs.map(fr => fr.toBuffer()) });
+      expect(Buffer.from(nativeSocketResult.hash)).toEqual(directResult.toBuffer());
+    }
+
+    if (nativeShmApi) {
+      const nativeShmResult = await nativeShmApi.poseidon2Hash({ inputs: inputs.map(fr => fr.toBuffer()) });
+      expect(Buffer.from(nativeShmResult.hash)).toEqual(directResult.toBuffer());
+    }
+
+    if (nativeShmSyncApi) {
+      const nativeShmSyncResult = nativeShmSyncApi.poseidon2Hash({ inputs: inputs.map(fr => fr.toBuffer()) });
+      expect(Buffer.from(nativeShmSyncResult.hash)).toEqual(directResult.toBuffer());
+    }
+
+    // Test always passes, this is just for measuring performance
+    expect(true).toBe(true);
+  });
+
+  const TEST_VECTORS = [1, 2, 3, 5, 10, 50, 100];
+  const NUM_RANDOM_TESTS = 10;
+
+  it.each(TEST_VECTORS)('produces identical results for %p field elements', async size => {
+    // Test with multiple random input vectors
+    for (let test = 0; test < NUM_RANDOM_TESTS; test++) {
+      const inputs = Array(size)
+        .fill(0)
+        .map(() => Fr.random());
+
+      const directResult = await directPoseidon2Hash(inputs);
+
+      if (wasmApi) {
+        const wasmResult = await wasmApi.poseidon2Hash({ inputs: inputs.map(fr => fr.toBuffer()) });
+        expect(Buffer.from(wasmResult.hash)).toEqual(directResult.toBuffer());
+      }
+
+      if (nativeSocketApi) {
+        const nativeSocketResult = await nativeSocketApi.poseidon2Hash({ inputs: inputs.map(fr => fr.toBuffer()) });
+        expect(Buffer.from(nativeSocketResult.hash)).toEqual(directResult.toBuffer());
+      }
+
+      if (nativeShmApi) {
+        const nativeShmResult = await nativeShmApi.poseidon2Hash({ inputs: inputs.map(fr => fr.toBuffer()) });
+        expect(Buffer.from(nativeShmResult.hash)).toEqual(directResult.toBuffer());
+      }
+
+      if (nativeShmSyncApi) {
+        const nativeShmSyncResult = nativeShmSyncApi.poseidon2Hash({ inputs: inputs.map(fr => fr.toBuffer()) });
+        expect(Buffer.from(nativeShmSyncResult.hash)).toEqual(directResult.toBuffer());
+      }
+    }
+  });
+});

package/src/barretenberg/poseidon.test.ts

@@ -0,0 +1,39 @@
+import { BarretenbergSync } from './index.js';
+import { Timer } from '../benchmark/timer.js';
+import { Fr } from '../types/index.js';
+
+describe('poseidon sync', () => {
+  let api: BarretenbergSync;
+
+  beforeAll(async () => {
+    api = await BarretenbergSync.initSingleton();
+  });
+
+  it('poseidonHash', () => {
+    const result = api.poseidon2Hash({ inputs: [new Fr(4n).toBuffer(), new Fr(8n).toBuffer()] });
+    expect(result).toMatchSnapshot();
+  });
+
+  it('poseidonHash perf test', () => {
+    const loops = 1000;
+    const fields = Array.from({ length: loops * 2 }).map(() => Fr.random().toBuffer());
+    const t = new Timer();
+    for (let i = 0; i < loops; ++i) {
+      api.poseidon2Hash({ inputs: [fields[i * 2], fields[i * 2 + 1]] });
+    }
+    const us = t.us() / loops;
+    console.log(`Executed ${loops} hashes at an average ${us}us / hash`);
+  });
+
+  // it('poseidonHashes perf test', () => {
+  //   const loops = 10;
+  //   const numHashesPerLoop = 1024;
+  //   const fields = Array.from({ length: numHashesPerLoop * 2 }).map(() => Fr.random());
+  //   const t = new Timer();
+  //   for (let i = 0; i < loops; ++i) {
+  //     api.poseidon2Hashes(fields);
+  //   }
+  //   const us = t.us() / (numHashesPerLoop * loops);
+  //   console.log(`Executed ${numHashesPerLoop * loops} hashes at an average ${us}us / hash`);
+  // });
+});

package/src/barretenberg_wasm/barretenberg_wasm_base/index.ts

@@ -0,0 +1,138 @@
+import { createDebugLogger } from '../../log/index.js';
+import { randomBytes } from '../../random/index.js';
+
+/**
+ * Base implementation of BarretenbergWasm.
+ * Contains code that is common to the "main thread" implementation and the "child thread" implementation.
+ */
+export class BarretenbergWasmBase {
+  protected memStore: { [key: string]: Uint8Array } = {};
+  protected memory!: WebAssembly.Memory;
+  protected instance!: WebAssembly.Instance;
+  protected logger: (msg: string) => void = createDebugLogger('bb_wasm_base');
+
+  protected getImportObj(memory: WebAssembly.Memory) {
+    /* eslint-disable camelcase */
+    const importObj = {
+      // We need to implement a part of the wasi api:
+      // https://github.com/WebAssembly/WASI/blob/main/phases/snapshot/docs.md
+      // We literally only need to support random_get, everything else is noop implementated in barretenberg.wasm.
+      wasi_snapshot_preview1: {
+        random_get: (out: any, length: number) => {
+          out = out >>> 0;
+          const randomData = randomBytes(length);
+          const mem = this.getMemory();
+          mem.set(randomData, out);
+        },
+        clock_time_get: (a1: number, a2: number, out: number) => {
+          out = out >>> 0;
+          const ts = BigInt(new Date().getTime()) * 1000000n;
+          const view = new DataView(this.getMemory().buffer);
+          view.setBigUint64(out, ts, true);
+        },
+        proc_exit: () => {
+          this.logger('PANIC: proc_exit was called.');
+          throw new Error();
+        },
+      },
+
+      // These are functions implementations for imports we've defined are needed.
+      // The native C++ build defines these in a module called "env". We must implement TypeScript versions here.
+      env: {
+        /**
+         * The 'info' call we use for logging in C++, calls this under the hood.
+         * The native code will just print to std:err (to avoid std::cout which is used for IPC).
+         * Here we just emit the log line for the client to decide what to do with.
+         */
+        logstr: (addr: number) => {
+          const str = this.stringFromAddress(addr);
+          const m = this.getMemory();
+          const str2 = `${str} (mem: ${(m.length / (1024 * 1024)).toFixed(2)}MiB)`;
+          this.logger(str2);
+        },
+
+        throw_or_abort_impl: (addr: number) => {
+          const str = this.stringFromAddress(addr);
+          throw new Error(str);
+        },
+
+        get_data: (keyAddr: number, outBufAddr: number) => {
+          const key = this.stringFromAddress(keyAddr);
+          outBufAddr = outBufAddr >>> 0;
+          const data = this.memStore[key];
+          if (!data) {
+            this.logger(`get_data miss ${key}`);
+            return;
+          }
+          // this.logger(`get_data hit ${key} size: ${data.length} dest: ${outBufAddr}`);
+          // this.logger(Buffer.from(data.slice(0, 64)).toString('hex'));
+          this.writeMemory(outBufAddr, data);
+        },
+
+        set_data: (keyAddr: number, dataAddr: number, dataLength: number) => {
+          const key = this.stringFromAddress(keyAddr);
+          dataAddr = dataAddr >>> 0;
+          this.memStore[key] = this.getMemorySlice(dataAddr, dataAddr + dataLength);
+          // this.logger(`set_data: ${key} length: ${dataLength}`);
+        },
+
+        memory,
+      },
+    };
+    /* eslint-enable camelcase */
+
+    return importObj;
+  }
+
+  public exports(): any {
+    return this.instance.exports;
+  }
+
+  /**
+   * When returning values from the WASM, use >>> operator to convert signed representation to unsigned representation.
+   */
+  public call(name: string, ...args: any) {
+    if (!this.exports()[name]) {
+      throw new Error(`WASM function ${name} not found.`);
+    }
+    try {
+      return this.exports()[name](...args) >>> 0;
+    } catch (err: any) {
+      const message = `WASM function ${name} aborted, error: ${err}`;
+      this.logger(message);
+      this.logger(err.stack);
+      throw err;
+    }
+  }
+
+  public memSize() {
+    return this.getMemory().length;
+  }
+
+  /**
+   * Returns a copy of the data, not a view.
+   */
+  public getMemorySlice(start: number, end: number) {
+    return this.getMemory().subarray(start, end).slice();
+  }
+
+  public writeMemory(offset: number, arr: Uint8Array) {
+    const mem = this.getMemory();
+    mem.set(arr, offset);
+  }
+
+  public getMemory() {
+    return new Uint8Array(this.memory.buffer);
+  }
+
+  // PRIVATE METHODS
+
+  private stringFromAddress(addr: number) {
+    addr = addr >>> 0;
+    const m = this.getMemory();
+    let i = addr;
+    for (; m[i] !== 0; ++i);
+    const textDecoder = new TextDecoder('ascii');
+    return textDecoder.decode(m.slice(addr, i));
+  }
+}

package/src/barretenberg_wasm/barretenberg_wasm_main/factory/browser/index.ts

@@ -0,0 +1,11 @@
+import { logOptions } from '../../../../log/index.js';
+import { readinessListener } from '../../../helpers/browser/index.js';
+
+export async function createMainWorker() {
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  const worker = new Worker(new URL('./main.worker.js', import.meta.url), { type: 'module' });
+  worker.postMessage({ log: logOptions });
+  await new Promise<void>(resolve => readinessListener(worker, resolve));
+  return worker;
+}

package/src/barretenberg_wasm/barretenberg_wasm_main/factory/browser/main.worker.ts

@@ -0,0 +1,13 @@
+import { expose } from 'comlink';
+import { BarretenbergWasmMain } from '../../index.js';
+import { Ready } from '../../../helpers/browser/index.js';
+import { initLogger } from '../../../../log/browser/index.js';
+
+addEventListener('message', e => {
+  if (e.data.log) {
+    initLogger(e.data.log);
+  }
+});
+
+expose(new BarretenbergWasmMain());
+postMessage(Ready);

package/src/barretenberg_wasm/barretenberg_wasm_main/factory/node/index.ts

@@ -0,0 +1,21 @@
+import { Worker } from 'worker_threads';
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { logOptions } from '../../../../log/index.js';
+
+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));
+  }
+}
+
+export function createMainWorker() {
+  const __dirname = getCurrentDir();
+  const worker = new Worker(__dirname + `/main.worker.js`);
+  worker.postMessage({ log: logOptions });
+  return Promise.resolve(worker);
+}

package/src/barretenberg_wasm/barretenberg_wasm_main/factory/node/main.worker.ts

@@ -0,0 +1,19 @@
+import { parentPort } from 'worker_threads';
+import { expose } from 'comlink';
+import { BarretenbergWasmMain } from '../../index.js';
+import { nodeEndpoint } from '../../../helpers/node/node_endpoint.js';
+import { initLogger } from '../../../../log/node/index.js';
+
+if (!parentPort) {
+  throw new Error('No parentPort');
+}
+
+const endpoint = nodeEndpoint(parentPort);
+
+endpoint.addEventListener('message', (e: any) => {
+  if (e.data.log) {
+    initLogger(e.data.log);
+  }
+});
+
+expose(new BarretenbergWasmMain(), nodeEndpoint(parentPort));

package/src/barretenberg_wasm/barretenberg_wasm_main/heap_allocator.ts

@@ -0,0 +1,72 @@
+import { type BarretenbergWasmMain } from './index.js';
+
+/**
+ * Keeps track of heap allocations so they can be easily freed.
+ * The WASM memory layout has 1024 bytes of unused "scratch" space at the start (addresses 0-1023).
+ * We can leverage this for IO rather than making expensive bb_malloc bb_free calls.
+ * Heap allocations will be created for input/output args that don't fit into the scratch space.
+ * Input scratch grows UP from 0, output scratch grows DOWN from 1024, meeting in the middle.
+ * This maximizes space utilization while preventing overlap.
+ */
+export class HeapAllocator {
+  private allocs: number[] = [];
+  private inScratchPtr = 0; // Next input starts here, grows UP
+  private outScratchPtr = 1024; // Next output ends here, grows DOWN
+
+  constructor(private wasm: BarretenbergWasmMain) {}
+
+  getInputs(buffers: (Uint8Array | number)[]) {
+    return buffers.map(bufOrNum => {
+      if (typeof bufOrNum === 'object') {
+        const size = bufOrNum.length;
+        // Check if there's room in scratch space (inputs grow up, outputs grow down)
+        if (this.inScratchPtr + size <= this.outScratchPtr) {
+          const ptr = this.inScratchPtr;
+          this.inScratchPtr += size; // Grow UP
+          this.wasm.writeMemory(ptr, bufOrNum);
+          return ptr;
+        } else {
+          // Fall back to heap allocation
+          const ptr = this.wasm.call('bbmalloc', size);
+          this.wasm.writeMemory(ptr, bufOrNum);
+          this.allocs.push(ptr);
+          return ptr;
+        }
+      } else {
+        return bufOrNum;
+      }
+    });
+  }
+
+  getOutputPtrs(outLens: (number | undefined)[]) {
+    return outLens.map(len => {
+      // If the obj is variable length, we need a 4 byte ptr to write the serialized data address to.
+      // WARNING: 4 only works with WASM as it has 32 bit memory.
+      const size = len || 4;
+
+      // Check if there's room in scratch space (inputs grow up, outputs grow down)
+      if (this.inScratchPtr + size <= this.outScratchPtr) {
+        this.outScratchPtr -= size; // Grow DOWN
+        return this.outScratchPtr;
+      } else {
+        // Fall back to heap allocation
+        const ptr = this.wasm.call('bbmalloc', size);
+        this.allocs.push(ptr);
+        return ptr;
+      }
+    });
+  }
+
+  addOutputPtr(ptr: number) {
+    // Only add to dealloc list if it's a heap allocation (not in scratch space 0-1023)
+    if (ptr >= 1024) {
+      this.allocs.push(ptr);
+    }
+  }
+
+  freeAll() {
+    for (const ptr of this.allocs) {
+      this.wasm.call('bbfree', ptr);
+    }
+  }
+}