@aztec/pxe 0.0.1-commit.24de95ac → 0.0.1-commit.2606882

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/proxied_contract_data_source.ts

@@ -1,66 +1,60 @@
-import { FunctionSelector } from '@aztec/stdlib/abi';
-import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { type FunctionSelector, findFunctionArtifactBySelector } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import type { ContractOverrides } from '@aztec/stdlib/tx';
 
-import type { ContractDataProvider } from '../storage/index.js';
+import type { ContractStore } from '../storage/contract_store/contract_store.js';
 
 /*
- * Proxy generator for a ContractDataProvider that allows overriding contract instances and artifacts, so
- * the contract function simulator can execute different bytecode on certain addresses. An example use case
- * would be overriding your own account contract so that valid signatures don't have to be provided while simulating.
+ * Proxy generator for a ContractStore that allows overriding contract instances at given addresses,
+ * so the contract function simulator can execute different bytecode on certain addresses. An example
+ * use case would be overriding your own account contract so that valid signatures don't have to be
+ * provided while simulating.
+ *
+ * Function artifact lookups for an overridden address are routed via the override-instance's
+ * `currentContractClassId` rather than the underlying ContractStore's address→class mapping —
+ * `ContractStore.getFunctionArtifact` calls `this.getContractInstance` internally, which the proxy
+ * cannot intercept (the binding sees the raw target, not the proxy). The target class must be
+ * registered ahead of time via `pxe.registerContractClass(...)`.
  */
-export class ProxiedContractDataProviderFactory {
-  static create(contractDataProvider: ContractDataProvider, overrides?: ContractOverrides) {
+export class ProxiedContractStoreFactory {
+  static create(contractStore: ContractStore, overrides?: ContractOverrides) {
     if (!overrides) {
-      return contractDataProvider;
+      return contractStore;
     }
 
-    return new Proxy(contractDataProvider, {
-      get(target, prop: keyof ContractDataProvider) {
-        switch (prop) {
-          case 'getContractInstance': {
-            return async (address: AztecAddress) => {
-              if (overrides[address.toString()]) {
-                const { instance } = overrides[address.toString()]!;
-                instance.address = address;
-                const realInstance = await target.getContractInstance(address);
-                if (!realInstance) {
-                  throw new Error(`Contract instance not found for address: ${address}`);
-                }
-                instance.currentContractClassId = realInstance.currentContractClassId;
-                instance.originalContractClassId = realInstance.originalContractClassId;
-                return instance;
-              } else {
-                return target.getContractInstance(address);
-              }
-            };
-          }
-          case 'getFunctionArtifact': {
-            return async (contractAddress: AztecAddress, selector: FunctionSelector) => {
-              if (overrides[contractAddress.toString()]) {
-                const { artifact } = overrides[contractAddress.toString()]!;
-                const functions = artifact.functions;
-                for (let i = 0; i < functions.length; i++) {
-                  const fn = functions[i];
-                  const fnSelector = await FunctionSelector.fromNameAndParameters(fn.name, fn.parameters);
-                  if (fnSelector.equals(selector)) {
-                    return fn;
-                  }
-                }
-              } else {
-                return target.getFunctionArtifact(contractAddress, selector);
-              }
-            };
-          }
-          default: {
-            const value = Reflect.get(target, prop);
-            if (typeof value === 'function') {
-              return value.bind(target);
+    return new Proxy(contractStore, {
+      get(target, prop: keyof ContractStore) {
+        if (prop === 'getContractInstance') {
+          return (address: AztecAddress) => {
+            const override = overrides[address.toString()];
+            return override ? Promise.resolve(override.instance) : target.getContractInstance(address);
+          };
+        }
+        if (prop === 'getFunctionArtifact' || prop === 'getFunctionArtifactWithDebugMetadata') {
+          return async (contractAddress: AztecAddress, selector: FunctionSelector) => {
+            const override = overrides[contractAddress.toString()];
+            if (!override) {
+              return (target[prop] as Function).call(target, contractAddress, selector);
+            }
+            const artifact = await target.getContractArtifact(override.instance.currentContractClassId);
+            if (!artifact) {
+              throw new Error(
+                `No artifact registered for override class ${override.instance.currentContractClassId} ` +
+                  `at ${contractAddress}. Register it via pxe.registerContractClass(...) before simulating.`,
+              );
+            }
+            const fn = await findFunctionArtifactBySelector(artifact, selector);
+            if (!fn) {
+              throw new Error(
+                `Function with selector ${selector} not found in stub artifact for overridden contract at ${contractAddress}.`,
+              );
             }
-            return value;
-          }
+            return { ...fn, contractName: artifact.name };
+          };
         }
+        const value = Reflect.get(target, prop);
+        return typeof value === 'function' ? value.bind(target) : value;
       },
-    });
+    }) satisfies ContractStore;
   }
 }

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/contract_sync/contract_sync_service.ts

@@ -0,0 +1,189 @@
+import type { Logger } from '@aztec/foundation/log';
+import { Semaphore } from '@aztec/foundation/queue';
+import { isProtocolContract } from '@aztec/protocol-contracts';
+import type { FunctionCall, FunctionSelector } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { AztecNode } from '@aztec/stdlib/interfaces/client';
+import type { BlockHeader } from '@aztec/stdlib/tx';
+
+import type { StagedStore } from '../job_coordinator/job_coordinator.js';
+import { NoteService } from '../notes/note_service.js';
+import type { ContractStore } from '../storage/contract_store/contract_store.js';
+import type { NoteStore } from '../storage/note_store/note_store.js';
+import { syncScope, verifyCurrentClassId } from './helpers.js';
+
+/** Maximum number of scope syncs running concurrently across the PXE. */
+const MAX_CONCURRENT_SCOPE_SYNCS = 5;
+
+/**
+ * Service for syncing the private state of contracts and verifying that the PXE holds the current class artifact.
+ * It uses a cache to avoid redundant sync operations - the cache is wiped when the anchor block changes.
+ *
+ * TODO: The StagedStore naming is broken here. Figure out a better name.
+ */
+export class ContractSyncService implements StagedStore {
+  readonly storeName = 'contract_sync';
+
+  // Tracks contracts synced since last wipe. The cache is keyed per individual scope address
+  // (`contractAddress:scopeAddress`), or `contractAddress:*` for all scopes (all accounts).
+  // The value is a promise that resolves when the contract is synced.
+  private syncedContracts: Map<string, Promise<void>> = new Map();
+
+  // Tracks class ID verification per contract. Keyed by contract address only (no scope), since
+  // class ID verification is scope-independent. Cleared on wipe/discard.
+  private classIdVerificationCache: Map<string, Promise<void>> = new Map();
+
+  // Bounds the number of scope syncs running concurrently. Scopes beyond this limit queue here. Sized to trade off
+  // parallelism on non-ACIR work (node RPC, note store reads) against memory pressure from concurrent circuit
+  // execution.
+  #syncSlot = new Semaphore(MAX_CONCURRENT_SCOPE_SYNCS);
+
+  constructor(
+    private aztecNode: AztecNode,
+    private contractStore: ContractStore,
+    private noteStore: NoteStore,
+    private log: Logger,
+  ) {}
+
+  /**
+   * Ensures a contract's private state is synchronized and that the PXE holds the current class artifact.
+   * Uses a cache to avoid redundant sync operations - the cache is wiped when the anchor block changes.
+   * @param contractAddress - The address of the contract to sync.
+   * @param functionToInvokeAfterSync - The function selector that will be called after sync (used to validate it's
+   * not sync_state itself).
+   * @param utilityExecutor - Executor function for running the sync_state utility function.
+   * @param scopes - Access scopes to pass through to the utility executor (affects whose account's private state is discovered).
+   */
+  async ensureContractSynced(
+    contractAddress: AztecAddress,
+    functionToInvokeAfterSync: FunctionSelector | null,
+    utilityExecutor: (call: FunctionCall, scopes: AztecAddress[]) => Promise<any>,
+    anchorBlockHeader: BlockHeader,
+    jobId: string,
+    scopes: AztecAddress[],
+  ): Promise<void> {
+    this.#startSyncIfNeeded(contractAddress, scopes, anchorBlockHeader, jobId, scope =>
+      syncScope(contractAddress, this.contractStore, functionToInvokeAfterSync, utilityExecutor, scope),
+    );
+
+    await this.#awaitSync(contractAddress, scopes);
+  }
+
+  /** Clears sync cache entries for the given scopes of a contract. */
+  invalidateContractForScopes(contractAddress: AztecAddress, scopes: AztecAddress[]): void {
+    if (scopes.length === 0) {
+      return;
+    }
+    scopes.forEach(scope => this.syncedContracts.delete(toKey(contractAddress, scope)));
+  }
+
+  /** Clears sync cache. Called by BlockSynchronizer when anchor block changes. */
+  wipe(): void {
+    this.log.debug(`Wiping contract sync cache (${this.syncedContracts.size} entries)`);
+    this.syncedContracts.clear();
+    this.classIdVerificationCache.clear();
+  }
+
+  commit(_jobId: string): Promise<void> {
+    return Promise.resolve();
+  }
+
+  discardStaged(_jobId: string): Promise<void> {
+    // We clear the synced contracts cache here because, when the job is discarded, any associated database writes from
+    // the sync are also undone.
+    this.syncedContracts.clear();
+    this.classIdVerificationCache.clear();
+    return Promise.resolve();
+  }
+
+  /**
+   * For each unsynced scope, creates a promise that waits on:
+   *  1. Class ID verification (cached per contract, scope-independent).
+   *  2. Note nullifier sync (shared, batched across all unsynced scopes).
+   *  3. Per-scope sync (individual, semaphore-bounded).
+   */
+  #startSyncIfNeeded(
+    contractAddress: AztecAddress,
+    scopes: AztecAddress[],
+    anchorBlockHeader: BlockHeader,
+    jobId: string,
+    syncScopeFn: (scope: AztecAddress) => Promise<void>,
+  ): void {
+    const scopesToSync = scopes.filter(scope => !this.syncedContracts.has(toKey(contractAddress, scope)));
+    if (scopesToSync.length === 0) {
+      return;
+    }
+
+    this.log.debug(`Syncing contract ${contractAddress} for ${scopesToSync.length} scope(s)`);
+
+    const verifyPromise = this.#verifyClassId(contractAddress, anchorBlockHeader);
+    const syncNullifiersPromise = this.#syncNoteNullifiers(contractAddress, anchorBlockHeader, jobId, scopesToSync);
+
+    for (const scope of scopesToSync) {
+      const key = toKey(contractAddress, scope);
+      const promise = Promise.all([verifyPromise, syncNullifiersPromise, this.#runBounded(() => syncScopeFn(scope))])
+        .then(() => {})
+        .catch(err => {
+          this.syncedContracts.delete(key);
+          throw err;
+        });
+      this.syncedContracts.set(key, promise);
+    }
+  }
+
+  /** Verifies the local class ID matches the on-chain value (cached, evicts on failure so retries re-verify). */
+  #verifyClassId(contractAddress: AztecAddress, anchorBlockHeader: BlockHeader): Promise<void> {
+    const contractKey = contractAddress.toString();
+    const cached = this.classIdVerificationCache.get(contractKey);
+    if (cached) {
+      return cached;
+    }
+    const promise = verifyCurrentClassId(contractAddress, this.aztecNode, this.contractStore, anchorBlockHeader).catch(
+      err => {
+        this.classIdVerificationCache.delete(contractKey);
+        throw err;
+      },
+    );
+    this.classIdVerificationCache.set(contractKey, promise);
+    return promise;
+  }
+
+  /** Syncs note nullifiers across all unsynced scopes in a single batched call. */
+  async #syncNoteNullifiers(
+    contractAddress: AztecAddress,
+    anchorBlockHeader: BlockHeader,
+    jobId: string,
+    scopes: AztecAddress[],
+  ): Promise<void> {
+    // Protocol contracts don't have private state to sync
+    if (isProtocolContract(contractAddress)) {
+      return;
+    }
+    // This runs in parallel with per-scope sync (which also writes to the note store). That's safe because
+    // the note store handles concurrent operations.
+    const noteService = new NoteService(this.noteStore, this.aztecNode, anchorBlockHeader, jobId);
+    await noteService.syncNoteNullifiers(contractAddress, scopes);
+  }
+
+  /** Runs fn while holding a slot in #syncSlot, bounding total concurrent scope syncs. */
+  async #runBounded<T>(fn: () => Promise<T>): Promise<T> {
+    await this.#syncSlot.acquire();
+    try {
+      return await fn();
+    } finally {
+      this.#syncSlot.release();
+    }
+  }
+
+  /** Collects all relevant scope promises (including in-flight ones from concurrent calls) and awaits them. */
+  async #awaitSync(contractAddress: AztecAddress, scopes: AztecAddress[]): Promise<void> {
+    const promises = scopes
+      .map(scope => this.syncedContracts.get(toKey(contractAddress, scope)))
+      .filter(p => p !== undefined);
+    await Promise.all(promises);
+  }
+}
+
+function toKey(contract: AztecAddress, scope: AztecAddress) {
+  return `${contract.toString()}:${scope.toString()}`;
+}

package/src/contract_sync/helpers.ts

@@ -0,0 +1,86 @@
+import { ProtocolContractAddress, isProtocolContract } from '@aztec/protocol-contracts';
+import type { FunctionCall, FunctionSelector } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { ContractInstance } from '@aztec/stdlib/contract';
+import { DelayedPublicMutableValues, DelayedPublicMutableValuesWithHash } from '@aztec/stdlib/delayed-public-mutable';
+import type { AztecNode } from '@aztec/stdlib/interfaces/client';
+import type { BlockHeader } from '@aztec/stdlib/tx';
+
+import type { ContractStore } from '../storage/contract_store/contract_store.js';
+
+/**
+ * Read the current class id of a contract from the execution data provider or AztecNode. If not found, class id
+ * from the instance is used.
+ * @param contractAddress - The address of the contract to read the class id for.
+ * @param instance - The instance of the contract.
+ * @param aztecNode - The Aztec node to query for storage.
+ * @param header - The header of the block at which to load the DelayedPublicMutable storing the class id.
+ * @returns The current class id.
+ */
+export async function readCurrentClassId(
+  contractAddress: AztecAddress,
+  instance: ContractInstance,
+  aztecNode: AztecNode,
+  header: BlockHeader,
+) {
+  const blockHash = await header.hash();
+  const timestamp = header.globalVariables.timestamp;
+  const { delayedPublicMutableSlot } = await DelayedPublicMutableValuesWithHash.getContractUpdateSlots(contractAddress);
+  const delayedPublicMutableValues = await DelayedPublicMutableValues.readFromTree(delayedPublicMutableSlot, slot =>
+    aztecNode.getPublicStorageAt(blockHash, ProtocolContractAddress.ContractInstanceRegistry, slot),
+  );
+  let currentClassId = delayedPublicMutableValues.svc.getCurrentAt(timestamp)[0];
+  if (currentClassId.isZero()) {
+    currentClassId = instance.originalContractClassId;
+  }
+  return currentClassId;
+}
+
+export async function syncScope(
+  contractAddress: AztecAddress,
+  contractStore: ContractStore,
+  functionToInvokeAfterSync: FunctionSelector | null,
+  utilityExecutor: (privateSyncCall: FunctionCall, scopes: AztecAddress[]) => Promise<any>,
+  scope: AztecAddress,
+) {
+  // Protocol contracts don't have private state to sync
+  if (isProtocolContract(contractAddress)) {
+    return;
+  }
+
+  const syncStateFunctionCall = await contractStore.getFunctionCall('sync_state', [scope], contractAddress);
+  if (functionToInvokeAfterSync && functionToInvokeAfterSync.equals(syncStateFunctionCall.selector)) {
+    throw new Error(
+      'Forbidden `sync_state` invocation. `sync_state` can only be invoked by PXE, manual execution can lead to inconsistencies.',
+    );
+  }
+
+  await utilityExecutor(syncStateFunctionCall, [scope]);
+}
+
+/**
+ * Verify that the current class id of a contract obtained from AztecNode is the same as the one in contract data
+ * provider (i.e. PXE's own storage).
+ * @param contractAddress - The address of the contract to verify.
+ * @param aztecNode - The Aztec node to query for storage.
+ * @param contractStore - The contract store to fetch the local instance from.
+ * @param header - The header of the block at which to verify the current class id.
+ */
+export async function verifyCurrentClassId(
+  contractAddress: AztecAddress,
+  aztecNode: AztecNode,
+  contractStore: ContractStore,
+  header: BlockHeader,
+) {
+  const instance = await contractStore.getContractInstance(contractAddress);
+  if (!instance) {
+    throw new Error(`No contract instance found for address ${contractAddress.toString()}`);
+  }
+
+  const currentClassId = await readCurrentClassId(contractAddress, instance, aztecNode, header);
+  if (!instance.currentContractClassId.equals(currentClassId)) {
+    throw new Error(
+      `Contract ${contractAddress} is outdated, current class id is ${currentClassId}, local class id is ${instance.currentContractClassId}`,
+    );
+  }
+}

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 { 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';
+
+/**
+ * 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,8 @@
+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';

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

@@ -1,14 +1,15 @@
-import { BBWASMBundlePrivateKernelProver } from '@aztec/bb-prover/client/wasm/bundle';
-import { randomBytes } from '@aztec/foundation/crypto';
+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 { 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';
 
 /**
  * Create and start an PXE instance with the given AztecNode.
@@ -25,34 +26,45 @@ 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 l1ContractAddresses = await aztecNode.getL1ContractAddresses();
   const configWithContracts = {
     ...config,
-    l1Contracts,
+    ...l1ContractAddresses,
   } as PXEConfig;
 
-  const storeLogger = loggers.store ? loggers.store : createLogger('pxe:data:idb' + (logSuffix ? `:${logSuffix}` : ''));
+  const storeLogger = loggers.store ?? createLogger('pxe:data:idb', { actor });
 
-  const store = options.store ?? (await createStore('pxe_data', configWithContracts, storeLogger));
+  const store =
+    options.store ?? (await createStore('pxe_data', configWithContracts, PXE_DATA_SCHEMA_VERSION, 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 BBWASMBundlePrivateKernelProver(simulator, 16, 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()],
+  };
 
-  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,
+    store,
+    proofCreator: prover,
+    simulator,
+    protocolContractsProvider,
+    preloadedContractsProvider,
+    config,
+    loggerOrSuffix: pxeLogger,
+    hooks: options.hooks,
+  });
   return pxe;
 }