@aztec/bb.js 3.0.0-canary.a9708bd → 3.0.0-manual.20251030

package/src/barretenberg/backend.ts

@@ -1,14 +1,6 @@
 import { BackendOptions, Barretenberg, CircuitOptions } from './index.js';
-import { RawBuffer } from '../types/raw_buffer.js';
-import {
-  ProofData,
-  reconstructHonkProof,
-  splitHonkProof,
-  PAIRING_POINTS_SIZE,
-  uint8ArrayToHex,
-  hexToUint8Array,
-} from '../proof/index.js';
-import { fromClientIVCProof, toClientIVCProof } from '../cbind/generated/api_types.js';
+import { ProofData, uint8ArrayToHex, hexToUint8Array } from '../proof/index.js';
+import { fromChonkProof, toChonkProof } from '../cbind/generated/api_types.js';
 import { ungzip } from 'pako';
 import { Buffer } from 'buffer';
 import { Decoder, Encoder } from 'msgpackr';
@@ -45,12 +37,20 @@ export type UltraHonkBackendOptions = {
   starknetZK?: boolean;
 };
 
-function getProofSettingsFromOptions(
-  options?: UltraHonkBackendOptions,
-): { ipaAccumulation: boolean; oracleHashType: string; disableZk: boolean, optimizedSolidityVerifier: boolean } {
+function getProofSettingsFromOptions(options?: UltraHonkBackendOptions): {
+  ipaAccumulation: boolean;
+  oracleHashType: string;
+  disableZk: boolean;
+  optimizedSolidityVerifier: boolean;
+} {
   return {
     ipaAccumulation: false,
-    oracleHashType: options?.keccak || options?.keccakZK ? 'keccak' : (options?.starknet || options?.starknetZK ? 'starknet' : 'poseidon2'),
+    oracleHashType:
+      options?.keccak || options?.keccakZK
+        ? 'keccak'
+        : options?.starknet || options?.starknetZK
+          ? 'starknet'
+          : 'poseidon2',
     // TODO no current way to target non-zk poseidon2 hash
     disableZk: options?.keccak || options?.starknet ? true : false,
     optimizedSolidityVerifier: false,
@@ -75,7 +75,10 @@ export class UltraHonkVerifierBackend {
     }
   }
 
-  async verifyProof(proofData: ProofData & { verificationKey: Uint8Array }, options?: UltraHonkBackendOptions): Promise<boolean> {
+  async verifyProof(
+    proofData: ProofData & { verificationKey: Uint8Array },
+    options?: UltraHonkBackendOptions,
+  ): Promise<boolean> {
     await this.instantiate();
 
     const proofFrs: Uint8Array[] = [];
@@ -136,7 +139,7 @@ export class UltraHonkBackend {
         bytecode: Buffer.from(this.acirUncompressedBytecode),
         verificationKey: Buffer.from([]), // Empty VK - lower performance.
       },
-      settings: getProofSettingsFromOptions(options)
+      settings: getProofSettingsFromOptions(options),
     });
     console.log(`Generated proof for circuit with ${publicInputs.length} public inputs and ${proof.length} fields.`);
 
@@ -164,7 +167,7 @@ export class UltraHonkBackend {
       },
       settings: getProofSettingsFromOptions(options),
     });
-    const {verified} = await this.api.circuitVerify({
+    const { verified } = await this.api.circuitVerify({
       verificationKey: vkResult.bytes,
       publicInputs: proofData.publicInputs.map(hexToUint8Array),
       proof: proofFrs,
@@ -187,10 +190,13 @@ export class UltraHonkBackend {
   }
 
   /** @description Returns a solidity verifier */
-  async getSolidityVerifier(vk?: Uint8Array): Promise<string> {
+  async getSolidityVerifier(vk: Uint8Array, options?: UltraHonkBackendOptions): Promise<string> {
     await this.instantiate();
-    const vkBuf = vk ?? (await this.api.acirWriteVkUltraKeccakHonk(this.acirUncompressedBytecode));
-    return await this.api.acirHonkSolidityVerifier(this.acirUncompressedBytecode, new RawBuffer(vkBuf));
+    const result = await this.api.circuitWriteSolidityVerifier({
+      verificationKey: vk,
+      settings: getProofSettingsFromOptions(options),
+    });
+    return result.solidityCode;
   }
 
   // TODO(https://github.com/noir-lang/noir/issues/5661): Update this to handle Honk recursive aggregation in the browser once it is ready in the backend itself
@@ -233,7 +239,7 @@ export class UltraHonkBackend {
       // We use an empty string for the vk hash here as it is unneeded as part of the recursive artifacts
       // The user can be expected to hash the vk inside their circuit to check whether the vk is the circuit
       // they expect
-      vkHash: uint8ArrayToHex(vkResult.hash)
+      vkHash: uint8ArrayToHex(vkResult.hash),
     };
   }
 
@@ -262,12 +268,12 @@ export class AztecClientBackend {
   private async instantiate(): Promise<void> {
     if (!this.api) {
       const api = await Barretenberg.new(this.options);
-      await api.initSRSClientIVC();
+      await api.initSRSChonk();
       this.api = api;
     }
   }
 
-  async prove(witnessBuf: Uint8Array[], vksBuf: Uint8Array[] = []): Promise<[Uint8Array, Uint8Array]> {
+  async prove(witnessBuf: Uint8Array[], vksBuf: Uint8Array[] = []): Promise<[Uint8Array[], Uint8Array, Uint8Array]> {
     if (vksBuf.length !== 0 && this.acirBuf.length !== witnessBuf.length) {
       throw new AztecClientBackendError('Witness and bytecodes must have the same stack depth!');
     }
@@ -278,7 +284,7 @@ export class AztecClientBackend {
     await this.instantiate();
 
     // Queue IVC start with the number of circuits
-    this.api.clientIvcStart({ numCircuits: this.acirBuf.length });
+    this.api.chonkStart({ numCircuits: this.acirBuf.length });
 
     // Queue load and accumulate for each circuit
     for (let i = 0; i < this.acirBuf.length; i++) {
@@ -288,45 +294,51 @@ export class AztecClientBackend {
       const functionName = `unknown_wasm_${i}`;
 
       // Load the circuit
-      this.api.clientIvcLoad({
+      this.api.chonkLoad({
         circuit: {
           name: functionName,
           bytecode: Buffer.from(bytecode),
           verificationKey: Buffer.from(vk),
-        }
+        },
       });
 
       // Accumulate with witness
-      this.api.clientIvcAccumulate({
+      this.api.chonkAccumulate({
         witness: Buffer.from(witness),
       });
-
     }
 
-
-
     // Generate the proof (and wait for all previous steps to finish)
-    const proveResult = await this.api.clientIvcProve({});
+    const proveResult = await this.api.chonkProve({});
     // The API currently expects a msgpack-encoded API.
-    const proof = new Encoder({useRecords: false}).encode(fromClientIVCProof(proveResult.proof));
+    const proof = new Encoder({ useRecords: false }).encode(fromChonkProof(proveResult.proof));
     // Generate the VK
-    const vkResult = await this.api.clientIvcComputeIvcVk({ circuit: {
-      name: 'hiding',
-      bytecode: this.acirBuf[this.acirBuf.length - 1],
-    } });
+    const vkResult = await this.api.chonkComputeIvcVk({
+      circuit: {
+        name: 'hiding',
+        bytecode: this.acirBuf[this.acirBuf.length - 1],
+      },
+    });
 
+    const proofFields = [
+      proveResult.proof.megaProof,
+      proveResult.proof.goblinProof.mergeProof,
+      proveResult.proof.goblinProof.eccvmProof.preIpaProof,
+      proveResult.proof.goblinProof.eccvmProof.ipaProof,
+      proveResult.proof.goblinProof.translatorProof,
+    ].flat();
 
     // Note: Verification may not work correctly until we properly serialize the proof
     if (!(await this.verify(proof, vkResult.bytes))) {
-      throw new AztecClientBackendError('Failed to verify the private (ClientIVC) transaction proof!');
+      throw new AztecClientBackendError('Failed to verify the private (Chonk) transaction proof!');
     }
-    return [proof, vkResult.bytes];
+    return [proofFields, proof, vkResult.bytes];
   }
 
   async verify(proof: Uint8Array, vk: Uint8Array): Promise<boolean> {
     await this.instantiate();
-    const result = await this.api.clientIvcVerify({
-      proof: toClientIVCProof(new Decoder({useRecords: false}).decode(proof)),
+    const result = await this.api.chonkVerify({
+      proof: toChonkProof(new Decoder({ useRecords: false }).decode(proof)),
       vk: Buffer.from(vk),
     });
     return result.valid;
@@ -336,12 +348,12 @@ export class AztecClientBackend {
     await this.instantiate();
     const circuitSizes: number[] = [];
     for (const buf of this.acirBuf) {
-      const gates = await this.api.clientIvcStats({
+      const gates = await this.api.chonkStats({
         circuit: {
           name: 'circuit',
           bytecode: buf,
         },
-        includeGatesPerOpcode: false
+        includeGatesPerOpcode: false,
       });
       circuitSizes.push(gates.circuitSize);
     }

package/src/barretenberg/blake2s.test.ts

@@ -1,11 +1,12 @@
-import { Barretenberg, BarretenbergSync } from './index.js';
-import { Buffer32, Fr } from '../types/index.js';
+import { BackendType, Barretenberg, BarretenbergSync } from './index.js';
+import { Fr } from '../types/index.js';
 
 describe('blake2s async', () => {
   let api: Barretenberg;
 
   beforeAll(async () => {
-    api = await Barretenberg.new({ threads: 1 });
+    // We're going to test over a worker backend to cover more code paths.
+    api = await Barretenberg.new({ threads: 1, backend: BackendType.WasmWorker });
   });
 
   afterAll(async () => {
@@ -14,14 +15,12 @@ describe('blake2s async', () => {
 
   it('blake2s', async () => {
     const input = Buffer.from('abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789');
-    const expected = Buffer32.fromBuffer(
-      new Uint8Array([
-        0x44, 0xdd, 0xdb, 0x39, 0xbd, 0xb2, 0xaf, 0x80, 0xc1, 0x47, 0x89, 0x4c, 0x1d, 0x75, 0x6a, 0xda, 0x3d, 0x1c,
-        0x2a, 0xc2, 0xb1, 0x00, 0x54, 0x1e, 0x04, 0xfe, 0x87, 0xb4, 0xa5, 0x9e, 0x12, 0x43,
-      ]),
-    );
-    const result = await api.blake2s(input);
-    expect(result).toEqual(expected);
+    const expected = new Uint8Array([
+      0x44, 0xdd, 0xdb, 0x39, 0xbd, 0xb2, 0xaf, 0x80, 0xc1, 0x47, 0x89, 0x4c, 0x1d, 0x75, 0x6a, 0xda, 0x3d, 0x1c, 0x2a,
+      0xc2, 0xb1, 0x00, 0x54, 0x1e, 0x04, 0xfe, 0x87, 0xb4, 0xa5, 0x9e, 0x12, 0x43,
+    ]);
+    const response = await api.blake2s({ data: input });
+    expect(response.hash).toEqual(expected);
   });
 
   it('blake2sToField', async () => {
@@ -32,7 +31,8 @@ describe('blake2s async', () => {
         0x2a, 0xc2, 0xb1, 0x00, 0x54, 0x1e, 0x04, 0xfe, 0x87, 0xb4, 0xa5, 0x9e, 0x12, 0x43,
       ]),
     );
-    const result = await api.blake2sToField(input);
+    const response = await api.blake2sToField({ data: input });
+    const result = Fr.fromBuffer(response.field);
     expect(result).toEqual(expected);
   });
 });
@@ -46,14 +46,12 @@ describe('blake2s sync', () => {
 
   it('blake2s', () => {
     const input = Buffer.from('abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789');
-    const expected = Buffer32.fromBuffer(
-      new Uint8Array([
-        0x44, 0xdd, 0xdb, 0x39, 0xbd, 0xb2, 0xaf, 0x80, 0xc1, 0x47, 0x89, 0x4c, 0x1d, 0x75, 0x6a, 0xda, 0x3d, 0x1c,
-        0x2a, 0xc2, 0xb1, 0x00, 0x54, 0x1e, 0x04, 0xfe, 0x87, 0xb4, 0xa5, 0x9e, 0x12, 0x43,
-      ]),
-    );
-    const result = api.blake2s(input);
-    expect(result).toEqual(expected);
+    const expected = new Uint8Array([
+      0x44, 0xdd, 0xdb, 0x39, 0xbd, 0xb2, 0xaf, 0x80, 0xc1, 0x47, 0x89, 0x4c, 0x1d, 0x75, 0x6a, 0xda, 0x3d, 0x1c, 0x2a,
+      0xc2, 0xb1, 0x00, 0x54, 0x1e, 0x04, 0xfe, 0x87, 0xb4, 0xa5, 0x9e, 0x12, 0x43,
+    ]);
+    const response = api.blake2s({ data: input });
+    expect(response.hash).toEqual(expected);
   });
 
   it('blake2sToField', () => {
@@ -64,7 +62,8 @@ describe('blake2s sync', () => {
         0x2a, 0xc2, 0xb1, 0x00, 0x54, 0x1e, 0x04, 0xfe, 0x87, 0xb4, 0xa5, 0x9e, 0x12, 0x43,
       ]),
     );
-    const result = api.blake2sToField(input);
+    const response = api.blake2sToField({ data: input });
+    const result = Fr.fromBuffer(response.field);
     expect(result).toEqual(expected);
   });
 });

package/src/barretenberg/index.ts

@@ -1,33 +1,13 @@
-import { proxy } from 'comlink';
-import { BarretenbergApi, BarretenbergApiSync } from '../barretenberg_api/index.js';
-import { createMainWorker } from '../barretenberg_wasm/barretenberg_wasm_main/factory/node/index.js';
-import { BarretenbergWasmMain, BarretenbergWasmMainWorker } from '../barretenberg_wasm/barretenberg_wasm_main/index.js';
-import { getRemoteBarretenbergWasm } from '../barretenberg_wasm/helpers/index.js';
 import { Crs, GrumpkinCrs } from '../crs/index.js';
-import { RawBuffer } from '../types/raw_buffer.js';
-import { fetchModuleAndThreads } from '../barretenberg_wasm/index.js';
 import { createDebugLogger } from '../log/index.js';
 import { AsyncApi } from '../cbind/generated/async.js';
-import { BbApiBase, CircuitComputeVk, CircuitProve, CircuitVerify, ClientIvcAccumulate, ClientIvcComputeIvcVk, ClientIvcStats, ClientIvcLoad, ClientIvcProve, ClientIvcStart, ClientIvcVerify, VkAsFields } from '../cbind/generated/api_types.js';
+import { SyncApi } from '../cbind/generated/sync.js';
+import { IMsgpackBackendSync, IMsgpackBackendAsync } from '../bb_backends/interface.js';
+import { BackendOptions, BackendType } from '../bb_backends/index.js';
+import { createAsyncBackend, createSyncBackend } from '../bb_backends/node/index.js';
 
 export { UltraHonkBackend, UltraHonkVerifierBackend, AztecClientBackend } from './backend.js';
-
-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 Logging function */
-  logger?: (msg: string) => void;
-};
+export * from '../bb_backends/index.js';
 
 export type CircuitOptions = {
   /** @description Whether to produce SNARK friendly proofs */
@@ -38,42 +18,46 @@ export type CircuitOptions = {
  * The main class library consumers interact with.
  * It extends the generated api, and provides a static constructor "new" to compose components.
  */
-export class Barretenberg extends BarretenbergApi {
+export class Barretenberg extends AsyncApi {
   private options: BackendOptions;
-  private bbApi: BbApiBase;
-
-  private constructor(
-    private worker: any,
-    wasm: BarretenbergWasmMainWorker,
-    options: BackendOptions,
-  ) {
-    super(wasm);
+
+  constructor(backend: IMsgpackBackendAsync, options: BackendOptions) {
+    super(backend);
     this.options = options;
-    this.bbApi = new AsyncApi(wasm);
   }
 
   /**
    * Constructs an instance of Barretenberg.
-   * Launches it within a worker. This is necessary as it blocks waiting on child threads to complete,
-   * and blocking the main thread in the browser is not allowed.
-   * It threads > 1 (defaults to hardware availability), child threads will be created on their own workers.
+   *
+   * If options.backend is set: uses that specific backend (throws if unavailable)
+   * If options.backend is unset: tries backends in order with fallback:
+   *   1. NativeSharedMemory (if bb binary available)
+   *   2. WasmWorker (in browser) or Wasm (in Node.js)
    */
   static async new(options: BackendOptions = {}) {
-    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 ?? createDebugLogger('bb_wasm_async')),
-      options.memory?.initial,
-      options.memory?.maximum,
-    );
-    return new Barretenberg(worker, wasm, options);
-  }
+    const logger = options.logger ?? createDebugLogger('bb_async');
+
+    if (options.backend) {
+      // Explicit backend required - no fallback
+      return await createAsyncBackend(options.backend, options, logger);
+    }
 
-  async getNumThreads() {
-    return await this.wasm.getNumThreads();
+    if (typeof window === 'undefined') {
+      try {
+        return await createAsyncBackend(BackendType.NativeSharedMemory, options, logger);
+      } catch (err: any) {
+        logger(`Shared memory unavailable (${err.message}), falling back to other backends`);
+        try {
+          return await createAsyncBackend(BackendType.NativeUnixSocket, options, logger);
+        } catch (err: any) {
+          logger(`Unix socket unavailable (${err.message}), falling back to WASM`);
+          return await createAsyncBackend(BackendType.Wasm, options, logger);
+        }
+      }
+    } else {
+      logger(`In browser, using WASM over worker backend.`);
+      return await createAsyncBackend(BackendType.WasmWorker, options, logger);
+    }
   }
 
   async initSRSForCircuitSize(circuitSize: number): Promise<void> {
@@ -81,18 +65,18 @@ export class Barretenberg extends BarretenbergApi {
     const crs = await Crs.new(Math.max(circuitSize, minSRSSize) + 1, this.options.crsPath, this.options.logger);
     // TODO(https://github.com/AztecProtocol/barretenberg/issues/1129): Do slab allocator initialization?
     // await this.commonInitSlabAllocator(circuitSize);
-    await this.srsInitSrs(new RawBuffer(crs.getG1Data()), crs.numPoints, new RawBuffer(crs.getG2Data()));
+    await this.srsInitSrs({ pointsBuf: crs.getG1Data(), numPoints: crs.numPoints, g2Point: crs.getG2Data() });
   }
 
-  async initSRSClientIVC(srsSize = this.getDefaultSrsSize()): Promise<void> {
+  async initSRSChonk(srsSize = this.getDefaultSrsSize()): Promise<void> {
     // crsPath can be undefined
     const crs = await Crs.new(srsSize + 1, this.options.crsPath, this.options.logger);
     const grumpkinCrs = await GrumpkinCrs.new(2 ** 16 + 1, this.options.crsPath, this.options.logger);
 
     // Load CRS into wasm global CRS state.
     // TODO: Make RawBuffer be default behavior, and have a specific Vector type for when wanting length prefixed.
-    await this.srsInitSrs(new RawBuffer(crs.getG1Data()), crs.numPoints, new RawBuffer(crs.getG2Data()));
-    await this.srsInitGrumpkinSrs(new RawBuffer(grumpkinCrs.getG1Data()), grumpkinCrs.numPoints);
+    await this.srsInitSrs({ pointsBuf: crs.getG1Data(), numPoints: crs.numPoints, g2Point: crs.getG2Data() });
+    await this.srsInitGrumpkinSrs({ pointsBuf: grumpkinCrs.getG1Data(), numPoints: grumpkinCrs.numPoints });
   }
 
   getDefaultSrsSize(): number {
@@ -104,101 +88,136 @@ export class Barretenberg extends BarretenbergApi {
     return 2 ** 20;
   }
 
+  async acirGetCircuitSizes(
+    bytecode: Uint8Array,
+    recursive: boolean,
+    honkRecursion: boolean,
+  ): Promise<[number, number]> {
+    const response = await this.circuitStats({
+      circuit: { name: '', bytecode, verificationKey: new Uint8Array() },
+      includeGatesPerOpcode: false,
+      settings: {
+        ipaAccumulation: false,
+        oracleHashType: honkRecursion ? 'poseidon2' : 'keccak',
+        disableZk: !recursive,
+        optimizedSolidityVerifier: false,
+      },
+    });
+    return [response.numGates, response.numGatesDyadic];
+  }
+
   async acirInitSRS(bytecode: Uint8Array, recursive: boolean, honkRecursion: boolean): Promise<void> {
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const [_total, subgroupSize] = await this.acirGetCircuitSizes(bytecode, recursive, honkRecursion);
+    const [_, subgroupSize] = await this.acirGetCircuitSizes(bytecode, recursive, honkRecursion);
     return this.initSRSForCircuitSize(subgroupSize);
   }
 
   async destroy() {
-    await this.wasm.destroy();
-    await this.worker.terminate();
-  }
-
-  getWasm() {
-    return this.wasm;
-  }
-
-  // Wrap ClientIVC methods used by AztecClientBackend and UltraHonkBackend
-  async clientIvcStart(command: ClientIvcStart) {
-    return this.bbApi.clientIvcStart(command);
-  }
-
-  async clientIvcLoad(command: ClientIvcLoad) {
-    return this.bbApi.clientIvcLoad(command);
-  }
-
-  async clientIvcAccumulate(command: ClientIvcAccumulate) {
-    return this.bbApi.clientIvcAccumulate(command);
+    return super.destroy();
   }
 
-  async clientIvcProve(command: ClientIvcProve) {
-    return this.bbApi.clientIvcProve(command);
-  }
-
-  async clientIvcVerify(command: ClientIvcVerify) {
-    return this.bbApi.clientIvcVerify(command);
-  }
-
-  async clientIvcComputeIvcVk(command: ClientIvcComputeIvcVk) {
-    return this.bbApi.clientIvcComputeIvcVk(command);
+  /**
+   * Initialize the singleton instance of Barretenberg.
+   * @param options Backend configuration options
+   */
+  static async initSingleton(options: BackendOptions = {}) {
+    if (!barretenbergSingletonPromise) {
+      barretenbergSingletonPromise = Barretenberg.new(options);
+    }
+    try {
+      barretenbergSingleton = await barretenbergSingletonPromise;
+      return barretenbergSingleton;
+    } catch (error) {
+      // If initialization fails, clear the singleton so next call can retry
+      barretenbergSingleton = undefined!;
+      barretenbergSingletonPromise = undefined!;
+      throw error;
+    }
   }
 
-  async clientIvcStats(command: ClientIvcStats) {
-    return this.bbApi.clientIvcStats(command);
+  static async destroySingleton() {
+    if (barretenbergSingleton) {
+      await barretenbergSingleton.destroy();
+      barretenbergSingleton = undefined!;
+      barretenbergSingletonPromise = undefined!;
+    }
   }
 
-  // Wrap circuit methods used by BbApiUltraHonkBackend
-  async circuitProve(command: CircuitProve) {
-    return this.bbApi.circuitProve(command);
+  /**
+   * Get the singleton instance of Barretenberg.
+   * Must call initSingleton() first.
+   */
+  static getSingleton() {
+    if (!barretenbergSingleton) {
+      throw new Error('First call Barretenberg.initSingleton() on @aztec/bb.js module.');
+    }
+    return barretenbergSingleton;
   }
+}
 
-  async circuitComputeVk(command: CircuitComputeVk) {
-    return this.bbApi.circuitComputeVk(command);
-  }
+let barretenbergSingletonPromise: Promise<Barretenberg>;
+let barretenbergSingleton: Barretenberg;
 
-  async circuitVerify(command: CircuitVerify) {
-    return this.bbApi.circuitVerify(command);
-  }
+let barretenbergSyncSingletonPromise: Promise<BarretenbergSync>;
+let barretenbergSyncSingleton: BarretenbergSync;
 
-  async vkAsFields(command: VkAsFields) {
-    return this.bbApi.vkAsFields(command);
+export class BarretenbergSync extends SyncApi {
+  constructor(backend: IMsgpackBackendSync) {
+    super(backend);
   }
 
-}
+  /**
+   * Create a new BarretenbergSync instance.
+   *
+   * If options.backend is set: uses that specific backend (throws if unavailable)
+   * If options.backend is unset: tries backends in order with fallback:
+   *   1. NativeSharedMem (if bb binary + NAPI module available)
+   *   2. Wasm
+   *
+   * Supported backends: Wasm, NativeSharedMem
+   * Not supported: WasmWorker (no workers in sync), NativeUnixSocket (async only)
+   */
+  static async new(options: BackendOptions = {}) {
+    const logger = options.logger ?? createDebugLogger('bb_sync');
 
-let barretenbergSyncSingletonPromise: Promise<BarretenbergSync>;
-let barretenbergSyncSingleton: BarretenbergSync;
+    if (options.backend) {
+      return await createSyncBackend(options.backend, options, logger);
+    }
 
-export class BarretenbergSync extends BarretenbergApiSync {
-  private constructor(wasm: BarretenbergWasmMain) {
-    super(wasm);
-  }
+    // Try native, fallback to WASM.
+    try {
+      return await createSyncBackend(BackendType.NativeSharedMemory, options, logger);
+    } catch (err: any) {
+      logger(`Shared memory unavailable (${err.message}), falling back to WASM`);
+    }
 
-  private static async new(wasmPath?: string, logger: (msg: string) => void = createDebugLogger('bb_wasm_sync')) {
-    const wasm = new BarretenbergWasmMain();
-    const { module, threads } = await fetchModuleAndThreads(1, wasmPath, logger);
-    await wasm.init(module, threads, logger);
-    return new BarretenbergSync(wasm);
+    return await createSyncBackend(BackendType.Wasm, options, logger);
   }
 
-  static async initSingleton(wasmPath?: string, logger: (msg: string) => void = createDebugLogger('bb_wasm_sync')) {
+  /**
+   * Initialize the singleton instance.
+   * @param options Backend configuration options
+   */
+  static async initSingleton(options: BackendOptions = {}) {
     if (!barretenbergSyncSingletonPromise) {
-      barretenbergSyncSingletonPromise = BarretenbergSync.new(wasmPath, logger);
+      barretenbergSyncSingletonPromise = BarretenbergSync.new(options);
     }
 
     barretenbergSyncSingleton = await barretenbergSyncSingletonPromise;
     return barretenbergSyncSingleton;
   }
 
+  static destroySingleton() {
+    if (barretenbergSyncSingleton) {
+      barretenbergSyncSingleton.destroy();
+      barretenbergSyncSingleton = undefined!;
+      barretenbergSyncSingletonPromise = undefined!;
+    }
+  }
+
   static getSingleton() {
     if (!barretenbergSyncSingleton) {
       throw new Error('First call BarretenbergSync.initSingleton() on @aztec/bb.js module.');
     }
     return barretenbergSyncSingleton;
   }
-
-  getWasm() {
-    return this.wasm;
-  }
 }