@aztec/pxe 0.0.1-commit.f504929 → 0.0.1-commit.f5a9928

package/src/contract_function_simulator/pick_notes.ts

@@ -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

@@ -5,18 +5,22 @@ 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_log::<name>(<addrAbbrev>)`.
+ * 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 module = name ? `contract_log::${name}(${addrAbbrev})` : `contract_log::Unknown(${addrAbbrev})`;
+
+  const prefix = kind == 'aztecnr' ? 'aztecnr' : 'contract';
+  const module = name ? `${prefix}:${name}(${addrAbbrev})` : `${prefix}:Unknown(${addrAbbrev})`;
   return createLogger(module, options);
 }
 
@@ -29,11 +33,20 @@ export function logContractMessage(logger: Logger, level: LogLevel, message: str
 
 /**
  * Displays debug logs collected during public function simulation,
- * using the `contract_log::` prefixed logger format.
+ * using the `contract:` prefixed logger format.
  */
 export async function displayDebugLogs(debugLogs: DebugLog[], getContractName: ContractNameResolver): Promise<void> {
   for (const log of debugLogs) {
-    const logger = await createContractLogger(log.contractAddress, getContractName);
-    logContractMessage(logger, log.level, log.message, log.fields);
+    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

@@ -1,12 +1,12 @@
 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 { AccessScopes } from '../access_scopes.js';
 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 { ContractSyncService } from '../contract_sync/contract_sync_service.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';
@@ -22,7 +22,7 @@ export class PXEDebugUtils {
     contractFunctionSimulator: ContractFunctionSimulator,
     call: FunctionCall,
     authWitnesses: AuthWitness[] | undefined,
-    scopes: AccessScopes,
+    scopes: AztecAddress[],
     jobId: string,
   ) => Promise<any>;
 
@@ -41,7 +41,7 @@ export class PXEDebugUtils {
       contractFunctionSimulator: ContractFunctionSimulator,
       call: FunctionCall,
       authWitnesses: AuthWitness[] | undefined,
-      scopes: AccessScopes,
+      scopes: AztecAddress[],
       jobId: string,
     ) => Promise<any>,
   ) {
@@ -82,12 +82,4 @@ export class PXEDebugUtils {
       return this.noteStore.getNotes(filter, jobId);
     });
   }
-
-  /**
-   * Triggers a sync of the PXE with the node.
-   * Blocks until the sync is complete.
-   */
-  public sync(): Promise<void> {
-    return this.#putJobInQueue(() => this.blockStateSynchronizer.sync());
-  }
 }

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

@@ -1,4 +1,3 @@
-export * from '../../../access_scopes.js';
 export * from '../../../notes_filter.js';
 export * from '../../../pxe.js';
 export * from '../../../config/index.js';
@@ -7,3 +6,4 @@ export * from '../../../contract_logging.js';
 export * from '../../../storage/index.js';
 export * from './utils.js';
 export type { PXECreationOptions } from '../../pxe_creation_options.js';
+export { openBrowserStore } from '../store.js';

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

@@ -1,15 +1,15 @@
-import { BBPrivateKernelProver } from '@aztec/bb-prover/client';
 import { BBBundlePrivateKernelProver } from '@aztec/bb-prover/client/bundle';
 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 { getDefaultStandardPreloadedContracts } from '@aztec/standard-contracts/preloaded';
 import type { AztecNode } from '@aztec/stdlib/interfaces/client';
 
 import type { PXEConfig } from '../../../config/index.js';
 import { PXE } from '../../../pxe.js';
 import { PXE_DATA_SCHEMA_VERSION } from '../../../storage/metadata.js';
-import type { PXECreationOptions } from '../../pxe_creation_options.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.
@@ -29,37 +29,55 @@ export async function createPXE(
   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 ?? createLogger('pxe:data:idb', { actor });
+  const storeLogger = loggers.store ?? createLogger('pxe:data', { actor });
 
   const store =
-    options.store ?? (await createStore('pxe_data', configWithContracts, PXE_DATA_SCHEMA_VERSION, storeLogger));
+    options.store ??
+    (await openBrowserStore(
+      'pxe_data',
+      PXE_DATA_SCHEMA_VERSION,
+      {
+        l1ChainId,
+        rollupAddress: l1ContractAddresses.rollupAddress,
+        dataStoreMapSizeKb: configWithContracts.dataStoreMapSizeKb,
+      },
+      storeLogger,
+    ));
 
   const simulator = options.simulator ?? new WASMSimulator();
   const proverLogger = loggers.prover ?? createLogger('pxe:bb:wasm:bundle', { actor });
 
   let prover;
-  if (options.proverOrOptions instanceof BBPrivateKernelProver) {
+  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: getDefaultStandardPreloadedContracts,
+  };
 
   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,4 +1,3 @@
-export * from '../../../access_scopes.js';
 export * from '../../../notes_filter.js';
 export * from '../../../pxe.js';
 export * from '../../../config/index.js';
@@ -7,3 +6,4 @@ export * from '../../../error_enriching.js';
 export * from '../../../contract_logging.js';
 export * from './utils.js';
 export { type PXECreationOptions } from '../../pxe_creation_options.js';
+export { openBrowserStore } from '../store.js';

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

@@ -1,15 +1,15 @@
-import { BBPrivateKernelProver } from '@aztec/bb-prover/client';
 import { BBLazyPrivateKernelProver } from '@aztec/bb-prover/client/lazy';
 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 { getDefaultStandardPreloadedContracts } from '@aztec/standard-contracts/preloaded/lazy';
 import type { AztecNode } from '@aztec/stdlib/interfaces/client';
 
 import type { PXEConfig } from '../../../config/index.js';
 import { PXE } from '../../../pxe.js';
 import { PXE_DATA_SCHEMA_VERSION } from '../../../storage/metadata.js';
-import type { PXECreationOptions } from '../../pxe_creation_options.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.
@@ -27,39 +27,57 @@ export async function createPXE(
 ) {
   const actor = options.loggerActorLabel;
 
-  const l1Contracts = await aztecNode.getL1ContractAddresses();
+  const { l1ChainId, l1ContractAddresses, rollupVersion } = await aztecNode.getNodeInfo();
   const configWithContracts = {
     ...config,
-    l1Contracts,
+    ...l1ContractAddresses,
+    l1ChainId,
+    rollupVersion,
   } as PXEConfig;
 
   const loggers = options.loggers ?? {};
 
-  const storeLogger = loggers.store ?? createLogger('pxe:data:idb', { actor });
+  const storeLogger = loggers.store ?? createLogger('pxe:data', { actor });
 
   const store =
-    options.store ?? (await createStore('pxe_data', configWithContracts, PXE_DATA_SCHEMA_VERSION, storeLogger));
+    options.store ??
+    (await openBrowserStore(
+      'pxe_data',
+      PXE_DATA_SCHEMA_VERSION,
+      {
+        l1ChainId,
+        rollupAddress: l1ContractAddresses.rollupAddress,
+        dataStoreMapSizeKb: configWithContracts.dataStoreMapSizeKb,
+      },
+      storeLogger,
+    ));
 
   const simulator = options.simulator ?? new WASMSimulator();
   const proverLogger = loggers.prover ?? createLogger('pxe:bb:wasm:bundle', { actor });
 
   let prover;
-  if (options.proverOrOptions instanceof BBPrivateKernelProver) {
+  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: getDefaultStandardPreloadedContracts,
+  };
 
   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

@@ -2,7 +2,10 @@ import type { BBPrivateKernelProverOptions } from '@aztec/bb-prover/client';
 import type { Logger } from '@aztec/foundation/log';
 import type { AztecAsyncKVStore } from '@aztec/kv-store';
 import type { CircuitSimulator } from '@aztec/simulator/client';
-import type { PrivateKernelProver } from '@aztec/stdlib/interfaces/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 };
@@ -11,4 +14,21 @@ export type PXECreationOptions = {
   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,12 +1,16 @@
-export * from '../../access_scopes.js';
+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 * from './store.js';
 export { NoteService } from '../../notes/note_service.js';
-export { ORACLE_VERSION } from '../../oracle_version.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_sync/contract_sync_service.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';

package/src/entrypoints/server/store.ts

@@ -0,0 +1,47 @@
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { type LoggerBindings, createLogger } from '@aztec/foundation/log';
+import { type AztecLMDBStoreV2, openStoreAt } from '@aztec/kv-store/lmdb-v2';
+
+import { mkdir } from 'fs/promises';
+import { join } from 'path';
+
+import { storeIdentitySlug } from '../../storage/store_identity.js';
+
+/** Location and identity inputs for opening an identity-partitioned PXE-side store. */
+export type IdentityStoreConfig = {
+  dataDirectory: string;
+  /** Maximum LMDB map size in KB. When omitted, the kv-store default map size applies. */
+  dataStoreMapSizeKb?: number;
+  l1ChainId: number;
+  rollupAddress: EthAddress;
+};
+
+/**
+ * Opens the persistent LMDB store selected by `name` and identity triple `(l1ChainId, rollupAddress, schemaVersion)`.
+ * A store exists per identity: reopening with the same identity returns the same data, a different identity selects
+ * a different (possibly fresh) store. Callers wanting an ephemeral store use `openTmpStore` explicitly instead.
+ */
+export async function openStore(
+  name: string,
+  schemaVersion: number,
+  config: IdentityStoreConfig,
+  bindings?: LoggerBindings,
+): Promise<AztecLMDBStoreV2> {
+  // Stores live under `<dataDirectory>/<name>-stores/<l1ChainId>-<rollupAddress>-v<schemaVersion>`, a sibling of the
+  // legacy `<dataDirectory>/<name>` directory: older binaries reset the legacy directory on a rollup mismatch, so
+  // per-identity stores must not nest inside it.
+  const subDir = join(
+    config.dataDirectory,
+    `${name}-stores`,
+    storeIdentitySlug({ l1ChainId: config.l1ChainId, rollupAddress: config.rollupAddress, schemaVersion }),
+  );
+  await mkdir(subDir, { recursive: true });
+
+  createLogger(`pxe:data:${name}`, bindings).info(`Opening ${name} data store (LMDB v2)`, {
+    storeName: name,
+    subDir,
+    dataStoreMapSizeKb: config.dataStoreMapSizeKb,
+  });
+
+  return openStoreAt(subDir, config.dataStoreMapSizeKb, undefined, bindings);
+}