@aztec/pxe 0.0.1-commit.d3ec352c → 0.0.1-commit.d58ff9d0

package/src/contract_function_simulator/pick_notes.ts

@@ -1,4 +1,4 @@
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { Comparator, type Note } from '@aztec/stdlib/note';
 
 export interface PropertySelector {
@@ -85,9 +85,24 @@ interface ContainsNote {
 }
 
 const selectPropertyFromPackedNoteContent = (noteData: Fr[], selector: PropertySelector): Fr => {
+  if (selector.index >= noteData.length) {
+    throw new Error(`Property selector index ${selector.index} out of bounds for note with ${noteData.length} fields`);
+  }
+  if (selector.offset + selector.length > Fr.SIZE_IN_BYTES) {
+    throw new Error(
+      `Property selector range (offset=${selector.offset}, length=${selector.length}) exceeds Fr buffer size of ${Fr.SIZE_IN_BYTES} bytes`,
+    );
+  }
   const noteValueBuffer = noteData[selector.index].toBuffer();
-  const noteValue = noteValueBuffer.subarray(selector.offset, selector.offset + selector.length);
-  return Fr.fromBuffer(noteValue);
+  // Noir's PropertySelector counts offset from the LSB (last byte of the big-endian buffer),
+  // so offset=0,length=Fr.SIZE_IN_BYTES reads the entire field, and offset=0,length=1 reads the last byte.
+  const start = Fr.SIZE_IN_BYTES - selector.offset - selector.length;
+  const end = Fr.SIZE_IN_BYTES - selector.offset;
+  const noteValue = noteValueBuffer.subarray(start, end);
+  // Left-pad to Fr.SIZE_IN_BYTES so Fr.fromBuffer interprets the value correctly.
+  const padded = Buffer.alloc(Fr.SIZE_IN_BYTES);
+  noteValue.copy(padded, Fr.SIZE_IN_BYTES - noteValue.length);
+  return Fr.fromBuffer(padded);
 };
 
 const selectNotes = <T extends ContainsNote>(noteDatas: T[], selects: Select[]): T[] =>
@@ -103,7 +118,11 @@ const selectNotes = <T extends ContainsNote>(noteDatas: T[], selects: Select[]):
         [Comparator.GTE]: () => !noteValueFr.lt(value),
       };
 
-      return comparatorSelector[comparator]();
+      const fn = comparatorSelector[comparator];
+      if (!fn) {
+        throw new Error(`Invalid comparator value: ${comparator}`);
+      }
+      return fn();
     }),
   );
 

package/src/contract_function_simulator/transient_array_service.ts

@@ -0,0 +1,91 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+/**
+ * In-memory store for transient arrays.
+ *
+ * Unlike {@link EphemeralArrayService} (one instance per call frame), a single `TransientArrayService` instance is shared
+ * across all frames of one top-level PXE call (a transaction simulation or utility call), so arrays survive across nested
+ * private and utility calls. Entries are keyed by `(contract address, slot)`; the contract address is supplied by the
+ * oracle from its execution context, so a contract can only ever name its own arrays. The store is purely in-memory and
+ * is discarded when the top-level PXE call completes — it is never persisted.
+ */
+export class TransientArrayService {
+  /** Maps a `(contract address, slot)` key to the serialized elements stored there. */
+  #arrays: Map<string, Fr[][]> = new Map();
+
+  #key(contractAddress: AztecAddress, slot: Fr): string {
+    return `${contractAddress.toString()}:${slot.toString()}`;
+  }
+
+  /** Returns all elements at the given key, or an empty array if uninitialized. */
+  readArrayAt(contractAddress: AztecAddress, slot: Fr): Fr[][] {
+    return this.#arrays.get(this.#key(contractAddress, slot)) ?? [];
+  }
+
+  #setArray(contractAddress: AztecAddress, slot: Fr, array: Fr[][]): void {
+    this.#arrays.set(this.#key(contractAddress, slot), array);
+  }
+
+  /** Returns the number of elements stored at the given key. */
+  len(contractAddress: AztecAddress, slot: Fr): number {
+    return this.readArrayAt(contractAddress, slot).length;
+  }
+
+  /** Appends an element and returns the new length. */
+  push(contractAddress: AztecAddress, slot: Fr, elements: Fr[]): number {
+    const array = this.readArrayAt(contractAddress, slot);
+    array.push(elements);
+    this.#setArray(contractAddress, slot, array);
+    return array.length;
+  }
+
+  /** Removes and returns the last element. Throws if empty. */
+  pop(contractAddress: AztecAddress, slot: Fr): Fr[] {
+    const array = this.readArrayAt(contractAddress, slot);
+    if (array.length === 0) {
+      throw new Error(`Transient array at slot ${slot} is empty`);
+    }
+    const element = array.pop()!;
+    this.#setArray(contractAddress, slot, array);
+    return element;
+  }
+
+  /** Returns the element at the given index. Throws if out of bounds. */
+  get(contractAddress: AztecAddress, slot: Fr, index: number): Fr[] {
+    const array = this.readArrayAt(contractAddress, slot);
+    if (index < 0 || index >= array.length) {
+      throw new Error(
+        `Transient array index ${index} out of bounds for array of length ${array.length} at slot ${slot}`,
+      );
+    }
+    return array[index];
+  }
+
+  /** Overwrites the element at the given index. Throws if out of bounds. */
+  set(contractAddress: AztecAddress, slot: Fr, index: number, value: Fr[]): void {
+    const array = this.readArrayAt(contractAddress, slot);
+    if (index < 0 || index >= array.length) {
+      throw new Error(
+        `Transient array index ${index} out of bounds for array of length ${array.length} at slot ${slot}`,
+      );
+    }
+    array[index] = value;
+  }
+
+  /** Removes the element at the given index, shifting subsequent elements backward. Throws if out of bounds. */
+  remove(contractAddress: AztecAddress, slot: Fr, index: number): void {
+    const array = this.readArrayAt(contractAddress, slot);
+    if (index < 0 || index >= array.length) {
+      throw new Error(
+        `Transient array index ${index} out of bounds for array of length ${array.length} at slot ${slot}`,
+      );
+    }
+    array.splice(index, 1);
+  }
+
+  /** Removes all elements at the given key. */
+  clear(contractAddress: AztecAddress, slot: Fr): void {
+    this.#arrays.delete(this.#key(contractAddress, slot));
+  }
+}

package/src/contract_logging.ts

@@ -0,0 +1,52 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import { type LogLevel, type Logger, applyStringFormatting, createLogger } from '@aztec/foundation/log';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { DebugLog } from '@aztec/stdlib/logs';
+
+/** Resolves a contract address to a human-readable name, if available. */
+export type ContractNameResolver = (address: AztecAddress) => Promise<string | undefined>;
+export type CONTRACT_LOG_KIND = 'aztecnr' | 'user';
+
+/**
+ * Creates a logger whose output is prefixed with `contract:<name>(<addrAbbrev>)`.
+ */
+export async function createContractLogger(
+  contractAddress: AztecAddress,
+  getContractName: ContractNameResolver,
+  kind: CONTRACT_LOG_KIND,
+  options?: { instanceId?: string },
+): Promise<Logger> {
+  const addrAbbrev = contractAddress.toString().slice(0, 10);
+  const name = await getContractName(contractAddress);
+
+  const prefix = kind == 'aztecnr' ? 'aztecnr' : 'contract';
+  const module = name ? `${prefix}:${name}(${addrAbbrev})` : `${prefix}:Unknown(${addrAbbrev})`;
+  return createLogger(module, options);
+}
+
+/**
+ * Formats and emits a single contract log message through the given logger.
+ */
+export function logContractMessage(logger: Logger, level: LogLevel, message: string, fields: Fr[]): void {
+  logger[level](applyStringFormatting(message, fields));
+}
+
+/**
+ * Displays debug logs collected during public function simulation,
+ * using the `contract:` prefixed logger format.
+ */
+export async function displayDebugLogs(debugLogs: DebugLog[], getContractName: ContractNameResolver): Promise<void> {
+  for (const log of debugLogs) {
+    const { kind, message } = stripAztecnrLogPrefix(log.message);
+    const logger = await createContractLogger(log.contractAddress, getContractName, kind);
+    logContractMessage(logger, log.level, message, log.fields);
+  }
+}
+
+export function stripAztecnrLogPrefix(message: string): { kind: CONTRACT_LOG_KIND; message: string } {
+  if (message.startsWith('[aztec-nr] ')) {
+    return { kind: 'aztecnr', message: message.slice('[aztec-nr] '.length) };
+  } else {
+    return { kind: 'user', message };
+  }
+}

package/src/debug/pxe_debug_utils.ts

@@ -0,0 +1,85 @@
+import type { FunctionCall } from '@aztec/stdlib/abi';
+import type { AuthWitness } from '@aztec/stdlib/auth-witness';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { NoteDao } from '@aztec/stdlib/note';
+import type { ContractOverrides } from '@aztec/stdlib/tx';
+
+import type { BlockSynchronizer } from '../block_synchronizer/block_synchronizer.js';
+import type { ContractSyncService } from '../contract/contract_sync_service.js';
+import type { ContractFunctionSimulator } from '../contract_function_simulator/contract_function_simulator.js';
+import type { NotesFilter } from '../notes_filter.js';
+import type { AnchorBlockStore } from '../storage/index.js';
+import type { NoteStore } from '../storage/note_store/note_store.js';
+
+/**
+ * Methods provided by this class might help debugging but must not be used in production.
+ * No backwards compatibility or API stability should be expected. Use at your own risk.
+ */
+export class PXEDebugUtils {
+  #putJobInQueue!: <T>(job: (jobId: string) => Promise<T>) => Promise<T>;
+  #getSimulatorForTx!: (overrides?: { contracts?: ContractOverrides }) => ContractFunctionSimulator;
+  #executeUtility!: (
+    contractFunctionSimulator: ContractFunctionSimulator,
+    call: FunctionCall,
+    authWitnesses: AuthWitness[] | undefined,
+    scopes: AztecAddress[],
+    jobId: string,
+  ) => Promise<any>;
+
+  constructor(
+    private contractSyncService: ContractSyncService,
+    private noteStore: NoteStore,
+    private blockStateSynchronizer: BlockSynchronizer,
+    private anchorBlockStore: AnchorBlockStore,
+  ) {}
+
+  /** Not injected through constructor since they're are co-dependant */
+  public setPXEHelpers(
+    putJobInQueue: <T>(job: (jobId: string) => Promise<T>) => Promise<T>,
+    getSimulatorForTx: (overrides?: { contracts?: ContractOverrides }) => ContractFunctionSimulator,
+    executeUtility: (
+      contractFunctionSimulator: ContractFunctionSimulator,
+      call: FunctionCall,
+      authWitnesses: AuthWitness[] | undefined,
+      scopes: AztecAddress[],
+      jobId: string,
+    ) => Promise<any>,
+  ) {
+    this.#putJobInQueue = putJobInQueue;
+    this.#getSimulatorForTx = getSimulatorForTx;
+    this.#executeUtility = executeUtility;
+  }
+
+  /**
+   * A debugging utility to get notes based on the provided filter.
+   *
+   * Note that this should not be used in production code because the structure of notes is considered to be
+   * an implementation detail of contracts. This is only meant to be used for debugging purposes. If you need to obtain
+   * note-related information in production code, please implement a custom utility function on your contract and call
+   * that function instead (e.g. `get_balance(owner: AztecAddress) -> u128` utility function on a Token contract).
+   *
+   * @param filter - The filter to apply to the notes.
+   * @returns The requested notes.
+   */
+  public getNotes(filter: NotesFilter): Promise<NoteDao[]> {
+    return this.#putJobInQueue(async (jobId: string) => {
+      await this.blockStateSynchronizer.sync();
+
+      const anchorBlockHeader = await this.anchorBlockStore.getBlockHeader();
+
+      const contractFunctionSimulator = this.#getSimulatorForTx();
+
+      await this.contractSyncService.ensureContractSynced(
+        filter.contractAddress,
+        null,
+        async (privateSyncCall, execScopes) =>
+          await this.#executeUtility(contractFunctionSimulator, privateSyncCall, [], execScopes, jobId),
+        anchorBlockHeader,
+        jobId,
+        filter.scopes,
+      );
+
+      return this.noteStore.getNotes(filter, jobId);
+    });
+  }
+}

package/src/entrypoints/client/bundle/index.ts

@@ -1,7 +1,9 @@
+export * from '../../../notes_filter.js';
 export * from '../../../pxe.js';
 export * from '../../../config/index.js';
 export * from '../../../error_enriching.js';
+export * from '../../../contract_logging.js';
 export * from '../../../storage/index.js';
 export * from './utils.js';
-export { PXEOracleInterface } from '../../../contract_function_simulator/pxe_oracle_interface.js';
 export type { PXECreationOptions } from '../../pxe_creation_options.js';
+export { openBrowserStore } from '../store.js';

package/src/entrypoints/client/bundle/utils.ts

@@ -1,14 +1,17 @@
 import { BBBundlePrivateKernelProver } from '@aztec/bb-prover/client/bundle';
-import { randomBytes } from '@aztec/foundation/crypto';
 import { createLogger } from '@aztec/foundation/log';
-import { createStore } from '@aztec/kv-store/indexeddb';
 import { BundledProtocolContractsProvider } from '@aztec/protocol-contracts/providers/bundle';
 import { WASMSimulator } from '@aztec/simulator/client';
+import { getStandardAuthRegistry } from '@aztec/standard-contracts/auth-registry';
+import { getStandardHandshakeRegistry } from '@aztec/standard-contracts/handshake-registry';
+import { getStandardMultiCallEntrypoint } from '@aztec/standard-contracts/multi-call-entrypoint';
 import type { AztecNode } from '@aztec/stdlib/interfaces/client';
 
 import type { PXEConfig } from '../../../config/index.js';
 import { PXE } from '../../../pxe.js';
-import type { PXECreationOptions } from '../../pxe_creation_options.js';
+import { PXE_DATA_SCHEMA_VERSION } from '../../../storage/metadata.js';
+import { type PXECreationOptions, isPrivateKernelProver } from '../../pxe_creation_options.js';
+import { openBrowserStore } from '../store.js';
 
 /**
  * Create and start an PXE instance with the given AztecNode.
@@ -25,34 +28,62 @@ export async function createPXE(
   config: PXEConfig,
   options: PXECreationOptions = { loggers: {} },
 ) {
-  const logSuffix =
-    typeof options.useLogSuffix === 'boolean'
-      ? options.useLogSuffix
-        ? randomBytes(3).toString('hex')
-        : undefined
-      : options.useLogSuffix;
-
+  const actor = options.loggerActorLabel;
   const loggers = options.loggers ?? {};
 
-  const l1Contracts = await aztecNode.getL1ContractAddresses();
+  const { l1ChainId, l1ContractAddresses, rollupVersion } = await aztecNode.getNodeInfo();
   const configWithContracts = {
     ...config,
-    l1Contracts,
+    ...l1ContractAddresses,
+    l1ChainId,
+    rollupVersion,
   } as PXEConfig;
 
-  const storeLogger = loggers.store ? loggers.store : createLogger('pxe:data:idb' + (logSuffix ? `:${logSuffix}` : ''));
+  const storeLogger = loggers.store ?? createLogger('pxe:data', { actor });
 
-  const store = options.store ?? (await createStore('pxe_data', configWithContracts, storeLogger));
+  const store =
+    options.store ??
+    (await openBrowserStore(
+      'pxe_data',
+      PXE_DATA_SCHEMA_VERSION,
+      {
+        l1ChainId,
+        rollupAddress: l1ContractAddresses.rollupAddress,
+        dataStoreMapSizeKb: configWithContracts.dataStoreMapSizeKb,
+      },
+      storeLogger,
+    ));
 
-  const simulator = new WASMSimulator();
-  const proverLogger = loggers.prover
-    ? loggers.prover
-    : createLogger('pxe:bb:wasm:bundle' + (logSuffix ? `:${logSuffix}` : ''));
+  const simulator = options.simulator ?? new WASMSimulator();
+  const proverLogger = loggers.prover ?? createLogger('pxe:bb:wasm:bundle', { actor });
 
-  const prover = options.prover ?? new BBBundlePrivateKernelProver(simulator, proverLogger);
+  let prover;
+  if (isPrivateKernelProver(options.proverOrOptions)) {
+    prover = options.proverOrOptions;
+  } else {
+    prover = new BBBundlePrivateKernelProver(simulator, { ...options.proverOrOptions, logger: proverLogger });
+  }
   const protocolContractsProvider = new BundledProtocolContractsProvider();
+  const preloadedContractsProvider = options.preloadedContractsProvider ?? {
+    getPreloadedContracts: async () => [
+      await getStandardMultiCallEntrypoint(),
+      await getStandardAuthRegistry(),
+      await getStandardHandshakeRegistry(),
+    ],
+  };
 
-  const pxeLogger = loggers.pxe ? loggers.pxe : createLogger('pxe:service' + (logSuffix ? `:${logSuffix}` : ''));
-  const pxe = await PXE.create(aztecNode, store, prover, simulator, protocolContractsProvider, config, pxeLogger);
+  const pxeLogger = loggers.pxe ?? createLogger('pxe:service', { actor });
+  const pxe = await PXE.create({
+    node: aztecNode,
+    nodeDebug: options.nodeDebug,
+    store,
+    proofCreator: prover,
+    simulator,
+    protocolContractsProvider,
+    preloadedContractsProvider,
+    config,
+    loggerOrSuffix: pxeLogger,
+    hooks: options.hooks,
+  });
   return pxe;
 }

package/src/entrypoints/client/lazy/index.ts

@@ -1,7 +1,9 @@
+export * from '../../../notes_filter.js';
 export * from '../../../pxe.js';
 export * from '../../../config/index.js';
 export * from '../../../storage/index.js';
 export * from '../../../error_enriching.js';
+export * from '../../../contract_logging.js';
 export * from './utils.js';
-export { PXEOracleInterface } from '../../../contract_function_simulator/pxe_oracle_interface.js';
 export { type PXECreationOptions } from '../../pxe_creation_options.js';
+export { openBrowserStore } from '../store.js';

package/src/entrypoints/client/lazy/utils.ts

@@ -1,14 +1,17 @@
 import { BBLazyPrivateKernelProver } from '@aztec/bb-prover/client/lazy';
-import { randomBytes } from '@aztec/foundation/crypto';
 import { createLogger } from '@aztec/foundation/log';
-import { createStore } from '@aztec/kv-store/indexeddb';
 import { LazyProtocolContractsProvider } from '@aztec/protocol-contracts/providers/lazy';
 import { WASMSimulator } from '@aztec/simulator/client';
+import { getStandardAuthRegistry } from '@aztec/standard-contracts/auth-registry/lazy';
+import { getStandardHandshakeRegistry } from '@aztec/standard-contracts/handshake-registry/lazy';
+import { getStandardMultiCallEntrypoint } from '@aztec/standard-contracts/multi-call-entrypoint/lazy';
 import type { AztecNode } from '@aztec/stdlib/interfaces/client';
 
 import type { PXEConfig } from '../../../config/index.js';
 import { PXE } from '../../../pxe.js';
-import type { PXECreationOptions } from '../../pxe_creation_options.js';
+import { PXE_DATA_SCHEMA_VERSION } from '../../../storage/metadata.js';
+import { type PXECreationOptions, isPrivateKernelProver } from '../../pxe_creation_options.js';
+import { openBrowserStore } from '../store.js';
 
 /**
  * Create and start an PXE instance with the given AztecNode.
@@ -16,7 +19,7 @@ import type { PXECreationOptions } from '../../pxe_creation_options.js';
  *
  * @param aztecNode - The AztecNode instance to be used by the server.
  * @param config - The PXE Config to use
- * @param
+ * @param options - (Optional) Optional information for creating an PXE.
  * @returns A Promise that resolves to the started PXE instance.
  */
 export async function createPXE(
@@ -24,35 +27,63 @@ export async function createPXE(
   config: PXEConfig,
   options: PXECreationOptions = { loggers: {} },
 ) {
-  const logSuffix =
-    typeof options.useLogSuffix === 'boolean'
-      ? options.useLogSuffix
-        ? randomBytes(3).toString('hex')
-        : undefined
-      : options.useLogSuffix;
-
-  const l1Contracts = await aztecNode.getL1ContractAddresses();
+  const actor = options.loggerActorLabel;
+
+  const { l1ChainId, l1ContractAddresses, rollupVersion } = await aztecNode.getNodeInfo();
   const configWithContracts = {
     ...config,
-    l1Contracts,
+    ...l1ContractAddresses,
+    l1ChainId,
+    rollupVersion,
   } as PXEConfig;
 
   const loggers = options.loggers ?? {};
 
-  const storeLogger = loggers.store ? loggers.store : createLogger('pxe:data:idb' + (logSuffix ? `:${logSuffix}` : ''));
-
-  const store = options.store ?? (await createStore('pxe_data', configWithContracts, storeLogger));
+  const storeLogger = loggers.store ?? createLogger('pxe:data', { actor });
 
-  const simulator = new WASMSimulator();
-  const proverLogger = loggers.prover
-    ? loggers.prover
-    : createLogger('pxe:bb:wasm:bundle' + (logSuffix ? `:${logSuffix}` : ''));
+  const store =
+    options.store ??
+    (await openBrowserStore(
+      'pxe_data',
+      PXE_DATA_SCHEMA_VERSION,
+      {
+        l1ChainId,
+        rollupAddress: l1ContractAddresses.rollupAddress,
+        dataStoreMapSizeKb: configWithContracts.dataStoreMapSizeKb,
+      },
+      storeLogger,
+    ));
 
-  const prover = options.prover ?? new BBLazyPrivateKernelProver(simulator, proverLogger);
+  const simulator = options.simulator ?? new WASMSimulator();
+  const proverLogger = loggers.prover ?? createLogger('pxe:bb:wasm:bundle', { actor });
 
+  let prover;
+  if (isPrivateKernelProver(options.proverOrOptions)) {
+    prover = options.proverOrOptions;
+  } else {
+    prover = new BBLazyPrivateKernelProver(simulator, { ...options.proverOrOptions, logger: proverLogger });
+  }
   const protocolContractsProvider = new LazyProtocolContractsProvider();
+  const preloadedContractsProvider = options.preloadedContractsProvider ?? {
+    getPreloadedContracts: async () => [
+      await getStandardMultiCallEntrypoint(),
+      await getStandardAuthRegistry(),
+      await getStandardHandshakeRegistry(),
+    ],
+  };
 
-  const pxeLogger = loggers.pxe ? loggers.pxe : createLogger('pxe:service' + (logSuffix ? `:${logSuffix}` : ''));
-  const pxe = await PXE.create(aztecNode, store, prover, simulator, protocolContractsProvider, config, pxeLogger);
+  const pxeLogger = loggers.pxe ?? createLogger('pxe:service', { actor });
+  const pxe = await PXE.create({
+    node: aztecNode,
+    nodeDebug: options.nodeDebug,
+    store,
+    proofCreator: prover,
+    simulator,
+    protocolContractsProvider,
+    preloadedContractsProvider,
+    config,
+    loggerOrSuffix: pxeLogger,
+    hooks: options.hooks,
+  });
   return pxe;
 }

package/src/entrypoints/client/store.ts

@@ -0,0 +1,54 @@
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import {
+  AztecSQLiteOPFSStore,
+  SqliteCorruptionError,
+  deleteStore,
+  storePoolDirectory,
+} from '@aztec/kv-store/sqlite-opfs';
+
+import { assertStoreIdentity, effectiveStoreName } from '../../storage/store_identity.js';
+
+/**
+ * Opens the persistent browser (sqlite-opfs) store selected by `name` and identity `(config.l1ChainId,
+ * config.rollupAddress, schemaVersion)` triple. A store exists per identity: reopening with the same identity returns
+ * the same data, a different identity selects a different (possibly fresh) store.
+ */
+export async function openBrowserStore(
+  name: string,
+  schemaVersion: number,
+  config: { l1ChainId: number; rollupAddress: EthAddress; dataStoreMapSizeKb?: number },
+  log: Logger = createLogger('pxe:data'),
+): Promise<AztecSQLiteOPFSStore> {
+  const identity = { l1ChainId: config.l1ChainId, rollupAddress: config.rollupAddress, schemaVersion };
+  const storeName = effectiveStoreName(name, identity);
+  log.info(`Creating ${storeName} SQLite-OPFS data store`, {
+    storeName,
+    dataStoreMapSizeKb: config.dataStoreMapSizeKb,
+  });
+  const openStore = () =>
+    AztecSQLiteOPFSStore.open(createLogger('kv-store:sqlite-opfs'), storeName, false, storePoolDirectory(storeName));
+
+  let store: AztecSQLiteOPFSStore;
+  try {
+    store = await openStore();
+  } catch (err) {
+    if (!(err instanceof SqliteCorruptionError)) {
+      throw err;
+    }
+    // A corrupt image is unrecoverable — no retry against the same bytes helps. Wipe the store's OPFS directory
+    // (safe: the failed open left no SAH-pool lock behind) and reopen a fresh, empty one, so the browser self-heals
+    // into a normal first-run rather than dead-ending on "database disk image is malformed" every load.
+    log.warn(`${storeName} store is corrupt (${err.message}); wiping and reopening fresh`);
+    await deleteStore(storeName);
+    store = await openStore();
+  }
+  try {
+    await assertStoreIdentity(store, storeName, identity);
+  } catch (err) {
+    // The store handle owns a worker and OPFS locks; release them before surfacing the refusal.
+    await store.close().catch(() => {});
+    throw err;
+  }
+  return store;
+}

package/src/entrypoints/pxe_creation_options.ts

@@ -1,10 +1,34 @@
+import type { BBPrivateKernelProverOptions } from '@aztec/bb-prover/client';
 import type { Logger } from '@aztec/foundation/log';
 import type { AztecAsyncKVStore } from '@aztec/kv-store';
-import type { PrivateKernelProver } from '@aztec/stdlib/interfaces/client';
+import type { CircuitSimulator } from '@aztec/simulator/client';
+import type { AztecNodeDebug, PrivateKernelProver } from '@aztec/stdlib/interfaces/client';
+
+import type { ExecutionHooks } from '../hooks/index.js';
+import type { PreloadedContractsProvider } from '../pxe.js';
 
 export type PXECreationOptions = {
   loggers?: { store?: Logger; pxe?: Logger; prover?: Logger };
-  useLogSuffix?: boolean | string;
-  prover?: PrivateKernelProver;
+  /** Actor label to include in log output (e.g., 'pxe-0', 'pxe-test'). */
+  loggerActorLabel?: string;
+  proverOrOptions?: PrivateKernelProver | BBPrivateKernelProverOptions;
   store?: AztecAsyncKVStore;
+  simulator?: CircuitSimulator;
+  /** Optional hooks to observe and influence contract execution. */
+  hooks?: ExecutionHooks;
+  /** Contracts to preload on startup. Replaces the default when set. */
+  preloadedContractsProvider?: PreloadedContractsProvider;
+  /**
+   * Optional debug API client for the same node. When provided, public function signatures are registered so the
+   * node can produce named public-execution stack traces. Only available on nodes started with debug endpoints
+   * enabled; omitted in prod-like setups.
+   */
+  nodeDebug?: AztecNodeDebug;
 };
+
+/** Checks if the given value implements the PrivateKernelProver interface via duck-typing. */
+export function isPrivateKernelProver(value: unknown): value is PrivateKernelProver {
+  return (
+    typeof value === 'object' && value !== null && typeof (value as PrivateKernelProver).createChonkProof === 'function'
+  );
+}

package/src/entrypoints/server/index.ts

@@ -1,8 +1,16 @@
+export { type AccountPrivacyKeys, type AccountPrivacySecretKeys } from '@aztec/key-store';
+
+export * from '../../notes_filter.js';
 export * from '../../pxe.js';
 export * from '../../config/index.js';
 export * from '../../error_enriching.js';
 export * from '../../storage/index.js';
 export * from './utils.js';
-export { PXEOracleInterface } from '../../contract_function_simulator/pxe_oracle_interface.js';
-export { ORACLE_VERSION } from '../../oracle_version.js';
+export * from './store.js';
+export { NoteService } from '../../notes/note_service.js';
+export { ORACLE_VERSION_MAJOR, ORACLE_VERSION_MINOR } from '../../oracle_version.js';
 export { type PXECreationOptions } from '../pxe_creation_options.js';
+export { JobCoordinator } from '../../job_coordinator/job_coordinator.js';
+export { ContractSyncService } from '../../contract/contract_sync_service.js';
+export { ContractClassService } from '../../contract/contract_class_service.js';
+export { AnchoredContractData } from '../../contract_function_simulator/anchored_contract_data.js';