@aztec/pxe 0.0.1-commit.f2ce05ee → 0.0.1-commit.f5d02921e

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

@@ -4,6 +4,7 @@ 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 { AccessScopes } from '../access_scopes.js';
 import type { StagedStore } from '../job_coordinator/job_coordinator.js';
 import type { ContractStore } from '../storage/contract_store/contract_store.js';
 import type { NoteStore } from '../storage/note_store/note_store.js';
@@ -18,23 +19,25 @@ import { syncState, verifyCurrentClassId } from './helpers.js';
 export class ContractSyncService implements StagedStore {
   readonly storeName = 'contract_sync';
 
-  // Tracks contracts synced since last wipe. Key is contract address string, value is a promise that resolves when
-  // the contract is synced.
+  // 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();
 
-  // Per-job overridden contract addresses - these contracts should not be synced.
-  private overriddenContracts: Map<string, Set<string>> = new Map();
+  // Per-job excluded contract addresses - these contracts should not be synced.
+  private excludedFromSync: Map<string, Set<string>> = new Map();
 
   constructor(
     private aztecNode: AztecNode,
     private contractStore: ContractStore,
     private noteStore: NoteStore,
+    private getRegisteredAccounts: () => Promise<AztecAddress[]>,
     private log: Logger,
   ) {}
 
   /** Sets contracts that should be skipped during sync for a specific job. */
-  setOverriddenContracts(jobId: string, addresses: Set<string>): void {
-    this.overriddenContracts.set(jobId, addresses);
+  setExcludedFromSync(jobId: string, addresses: Set<string>): void {
+    this.excludedFromSync.set(jobId, addresses);
   }
 
   /**
@@ -44,64 +47,74 @@ export class ContractSyncService implements StagedStore {
    * @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) => Promise<any>,
+    utilityExecutor: (call: FunctionCall, scopes: AccessScopes) => Promise<any>,
     anchorBlockHeader: BlockHeader,
     jobId: string,
+    scopes: AccessScopes,
   ): Promise<void> {
-    const key = contractAddress.toString();
-
-    // Skip sync if this contract has an override for this job
-    const overrides = this.overriddenContracts.get(jobId);
-    if (overrides?.has(key)) {
+    if (this.#shouldSkipSync(jobId, contractAddress)) {
       return;
     }
 
-    const existing = this.syncedContracts.get(key);
-    if (existing) {
-      return existing;
-    }
-
-    const syncPromise = this.#doSync(
-      contractAddress,
-      functionToInvokeAfterSync,
-      utilityExecutor,
-      anchorBlockHeader,
-      jobId,
+    this.#startSyncIfNeeded(contractAddress, scopes, scopesToSync =>
+      this.#syncContract(
+        contractAddress,
+        functionToInvokeAfterSync,
+        utilityExecutor,
+        anchorBlockHeader,
+        jobId,
+        scopesToSync,
+      ),
     );
-    this.syncedContracts.set(key, syncPromise);
 
-    try {
-      await syncPromise;
-    } catch (err) {
-      // There was an error syncing the contract, so we remove it from the cache so that it can be retried.
-      this.syncedContracts.delete(key);
-      throw err;
+    await this.#awaitSync(contractAddress, scopes);
+  }
+
+  /** Clears sync cache entries for the given scopes of a contract. Also clears the ALL_SCOPES entry. */
+  invalidateContractForScopes(contractAddress: AztecAddress, scopes: AztecAddress[]): void {
+    if (scopes.length === 0) {
+      return;
     }
+    scopes.forEach(scope => this.syncedContracts.delete(toKey(contractAddress, scope)));
+    this.syncedContracts.delete(toKey(contractAddress, 'ALL_SCOPES'));
   }
 
-  async #doSync(
+  async #syncContract(
     contractAddress: AztecAddress,
     functionToInvokeAfterSync: FunctionSelector | null,
-    utilityExecutor: (call: FunctionCall) => Promise<any>,
+    utilityExecutor: (call: FunctionCall, scopes: AccessScopes) => Promise<any>,
     anchorBlockHeader: BlockHeader,
     jobId: string,
+    scopes: AccessScopes,
   ): Promise<void> {
     this.log.debug(`Syncing contract ${contractAddress}`);
+
+    // Resolve ALL_SCOPES to actual registered accounts, since sync_state must be called once per account.
+    const scopeAddresses = scopes === 'ALL_SCOPES' ? await this.getRegisteredAccounts() : scopes;
+
     await Promise.all([
-      syncState(
-        contractAddress,
-        this.contractStore,
-        functionToInvokeAfterSync,
-        utilityExecutor,
-        this.noteStore,
-        this.aztecNode,
-        anchorBlockHeader,
-        jobId,
-      ),
+      // Call sync_state sequentially for each scope address — each invocation synchronizes one account's private
+      // state using scoped capsule arrays.
+      (async () => {
+        for (const scope of scopeAddresses) {
+          await syncState(
+            contractAddress,
+            this.contractStore,
+            functionToInvokeAfterSync,
+            utilityExecutor,
+            this.noteStore,
+            this.aztecNode,
+            anchorBlockHeader,
+            jobId,
+            scope,
+          );
+        }
+      })(),
       verifyCurrentClassId(contractAddress, this.aztecNode, this.contractStore, anchorBlockHeader),
     ]);
     this.log.debug(`Contract ${contractAddress} synced`);
@@ -114,8 +127,8 @@ export class ContractSyncService implements StagedStore {
   }
 
   commit(jobId: string): Promise<void> {
-    // Clear overridden contracts for this job
-    this.overriddenContracts.delete(jobId);
+    // Clear excluded contracts for this job
+    this.excludedFromSync.delete(jobId);
     return Promise.resolve();
   }
 
@@ -123,7 +136,57 @@ export class ContractSyncService implements StagedStore {
     // 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.overriddenContracts.delete(jobId);
+    this.excludedFromSync.delete(jobId);
     return Promise.resolve();
   }
+  /** Returns true if sync should be skipped for this contract */
+  #shouldSkipSync(jobId: string, contractAddress: AztecAddress): boolean {
+    return !!this.excludedFromSync.get(jobId)?.has(contractAddress.toString());
+  }
+
+  /** If there are unsynced scopes, starts sync and stores the promise in cache with error cleanup. */
+  #startSyncIfNeeded(
+    contractAddress: AztecAddress,
+    scopes: AccessScopes,
+    syncFn: (scopesToSync: AccessScopes) => Promise<void>,
+  ): void {
+    const scopesToSync = this.#getScopesToSync(contractAddress, scopes);
+    const keys = toKeys(contractAddress, scopesToSync);
+    if (keys.length === 0) {
+      return;
+    }
+    const promise = syncFn(scopesToSync).catch(err => {
+      keys.forEach(key => this.syncedContracts.delete(key));
+      throw err;
+    });
+    keys.forEach(key => this.syncedContracts.set(key, promise));
+  }
+
+  /** Filters out scopes that are already cached, returning only those that still need syncing. */
+  #getScopesToSync(contractAddress: AztecAddress, scopes: AccessScopes): AccessScopes {
+    if (this.syncedContracts.has(toKey(contractAddress, 'ALL_SCOPES'))) {
+      // If we are already syncing all scopes, then return an empty list
+      return [];
+    }
+    if (scopes === 'ALL_SCOPES') {
+      return 'ALL_SCOPES';
+    }
+    return scopes.filter(scope => !this.syncedContracts.has(toKey(contractAddress, scope)));
+  }
+
+  /** Collects all relevant scope promises (including in-flight ones from concurrent calls) and awaits them. */
+  async #awaitSync(contractAddress: AztecAddress, scopes: AccessScopes): Promise<void> {
+    const promises = toKeys(contractAddress, scopes)
+      .map(key => this.syncedContracts.get(key))
+      .filter(p => p !== undefined);
+    await Promise.all(promises);
+  }
+}
+
+function toKeys(contract: AztecAddress, scopes: AccessScopes) {
+  return scopes === 'ALL_SCOPES' ? [toKey(contract, scopes)] : scopes.map(scope => toKey(contract, scope));
+}
+
+function toKey(contract: AztecAddress, scope: AztecAddress | 'ALL_SCOPES') {
+  return scope === 'ALL_SCOPES' ? `${contract.toString()}:*` : `${contract.toString()}:${scope.toString()}`;
 }

package/src/contract_sync/helpers.ts

@@ -6,6 +6,7 @@ import { DelayedPublicMutableValues, DelayedPublicMutableValuesWithHash } from '
 import type { AztecNode } from '@aztec/stdlib/interfaces/client';
 import type { BlockHeader } from '@aztec/stdlib/tx';
 
+import type { AccessScopes } from '../access_scopes.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';
@@ -42,15 +43,16 @@ export async function syncState(
   contractAddress: AztecAddress,
   contractStore: ContractStore,
   functionToInvokeAfterSync: FunctionSelector | null,
-  utilityExecutor: (privateSyncCall: FunctionCall) => Promise<any>,
+  utilityExecutor: (privateSyncCall: FunctionCall, scopes: AccessScopes) => Promise<any>,
   noteStore: NoteStore,
   aztecNode: AztecNode,
   anchorBlockHeader: BlockHeader,
   jobId: string,
+  scope: AztecAddress,
 ) {
   // Protocol contracts don't have private state to sync
   if (!isProtocolContract(contractAddress)) {
-    const syncStateFunctionCall = await contractStore.getFunctionCall('sync_state', [], contractAddress);
+    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.',
@@ -58,10 +60,14 @@ export async function syncState(
     }
 
     const noteService = new NoteService(noteStore, aztecNode, anchorBlockHeader, jobId);
+    const scopes: AccessScopes = [scope];
 
     // Both sync_state and syncNoteNullifiers interact with the note store, but running them in parallel is safe
     // because note store is designed to handle concurrent operations.
-    await Promise.all([utilityExecutor(syncStateFunctionCall), noteService.syncNoteNullifiers(contractAddress)]);
+    await Promise.all([
+      utilityExecutor(syncStateFunctionCall, scopes),
+      noteService.syncNoteNullifiers(contractAddress, scopes),
+    ]);
   }
 }
 

package/src/debug/pxe_debug_utils.ts

@@ -1,12 +1,13 @@
 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, NotesFilter } from '@aztec/stdlib/note';
+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 { 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';
 
@@ -17,11 +18,11 @@ import type { NoteStore } from '../storage/note_store/note_store.js';
 export class PXEDebugUtils {
   #putJobInQueue!: <T>(job: (jobId: string) => Promise<T>) => Promise<T>;
   #getSimulatorForTx!: (overrides?: { contracts?: ContractOverrides }) => ContractFunctionSimulator;
-  #simulateUtility!: (
+  #executeUtility!: (
     contractFunctionSimulator: ContractFunctionSimulator,
     call: FunctionCall,
     authWitnesses: AuthWitness[] | undefined,
-    scopes: AztecAddress[] | undefined,
+    scopes: AccessScopes,
     jobId: string,
   ) => Promise<any>;
 
@@ -36,17 +37,17 @@ export class PXEDebugUtils {
   public setPXEHelpers(
     putJobInQueue: <T>(job: (jobId: string) => Promise<T>) => Promise<T>,
     getSimulatorForTx: (overrides?: { contracts?: ContractOverrides }) => ContractFunctionSimulator,
-    simulateUtility: (
+    executeUtility: (
       contractFunctionSimulator: ContractFunctionSimulator,
       call: FunctionCall,
       authWitnesses: AuthWitness[] | undefined,
-      scopes: AztecAddress[] | undefined,
+      scopes: AccessScopes,
       jobId: string,
     ) => Promise<any>,
   ) {
     this.#putJobInQueue = putJobInQueue;
     this.#getSimulatorForTx = getSimulatorForTx;
-    this.#simulateUtility = simulateUtility;
+    this.#executeUtility = executeUtility;
   }
 
   /**
@@ -71,10 +72,11 @@ export class PXEDebugUtils {
       await this.contractSyncService.ensureContractSynced(
         filter.contractAddress,
         null,
-        async privateSyncCall =>
-          await this.#simulateUtility(contractFunctionSimulator, privateSyncCall, [], undefined, jobId),
+        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,6 +1,9 @@
+export * from '../../../access_scopes.js';
+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 type { PXECreationOptions } from '../../pxe_creation_options.js';

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

@@ -52,6 +52,14 @@ export async function createPXE(
   const protocolContractsProvider = new BundledProtocolContractsProvider();
 
   const pxeLogger = loggers.pxe ?? createLogger('pxe:service', { actor });
-  const pxe = await PXE.create(aztecNode, store, prover, simulator, protocolContractsProvider, config, pxeLogger);
+  const pxe = await PXE.create({
+    node: aztecNode,
+    store,
+    proofCreator: prover,
+    simulator,
+    protocolContractsProvider,
+    config,
+    loggerOrSuffix: pxeLogger,
+  });
   return pxe;
 }

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

@@ -1,6 +1,9 @@
+export * from '../../../access_scopes.js';
+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 { type PXECreationOptions } from '../../pxe_creation_options.js';

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

@@ -52,6 +52,14 @@ export async function createPXE(
   const protocolContractsProvider = new LazyProtocolContractsProvider();
 
   const pxeLogger = loggers.pxe ?? createLogger('pxe:service', { actor });
-  const pxe = await PXE.create(aztecNode, store, prover, simulator, protocolContractsProvider, config, pxeLogger);
+  const pxe = await PXE.create({
+    node: aztecNode,
+    store,
+    proofCreator: prover,
+    simulator,
+    protocolContractsProvider,
+    config,
+    loggerOrSuffix: pxeLogger,
+  });
   return pxe;
 }

package/src/entrypoints/server/index.ts

@@ -1,3 +1,5 @@
+export * from '../../access_scopes.js';
+export * from '../../notes_filter.js';
 export * from '../../pxe.js';
 export * from '../../config/index.js';
 export * from '../../error_enriching.js';

package/src/entrypoints/server/utils.ts

@@ -58,14 +58,14 @@ export async function createPXE(
   const protocolContractsProvider = new BundledProtocolContractsProvider();
 
   const pxeLogger = loggers.pxe ?? createLogger('pxe:service', { actor });
-  const pxe = await PXE.create(
-    aztecNode,
-    options.store,
-    prover,
+  const pxe = await PXE.create({
+    node: aztecNode,
+    store: options.store,
+    proofCreator: prover,
     simulator,
     protocolContractsProvider,
-    configWithContracts,
-    pxeLogger,
-  );
+    config: configWithContracts,
+    loggerOrSuffix: pxeLogger,
+  });
   return pxe;
 }

package/src/events/event_service.ts

@@ -1,4 +1,5 @@
 import type { Fr } from '@aztec/foundation/curves/bn254';
+import { createLogger } from '@aztec/foundation/log';
 import type { EventSelector } from '@aztec/stdlib/abi';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { siloNullifier } from '@aztec/stdlib/hash';
@@ -13,6 +14,7 @@ export class EventService {
     private readonly aztecNode: AztecNode,
     private readonly privateEventStore: PrivateEventStore,
     private readonly jobId: string,
+    private readonly log = createLogger('pxe:event_service'),
   ) {}
 
   public async validateAndStoreEvent(
@@ -36,19 +38,30 @@ export class EventService {
     const anchorBlockNumber = this.anchorBlockHeader.getBlockNumber();
 
     if (!txEffect) {
-      throw new Error(`Could not find tx effect for tx hash ${txHash}`);
+      // We error out instead of just logging a warning and skipping the event because this would indicate a bug. This
+      // is because the node has already served info about this tx either when obtaining the log (TxScopedL2Log contain
+      // tx info) or when getting metadata for the offchain message (before the message got passed to `process_log`).
+      throw new Error(`Could not find tx effect for tx hash ${txHash} when processing an event.`);
     }
 
     if (txEffect.l2BlockNumber > anchorBlockNumber) {
-      throw new Error(`Could not find tx effect for tx hash ${txHash} as of block number ${anchorBlockNumber}`);
+      // We should never process a message from a tx past the anchor block. If we got here, a preprocessing step made
+      // a mistake.
+      throw new Error(
+        `Obtained a newer tx effect for ${txHash} for an event validation request than the anchor block ${anchorBlockNumber}. This is a bug as smart contracts should not issue event validation requests for events from blocks newer than the anchor block.`,
+      );
     }
 
     // Find the index of the event commitment in the nullifiers array to determine event ordering within the tx
     const eventIndexInTx = txEffect.data.nullifiers.findIndex(n => n.equals(siloedEventCommitment));
     if (eventIndexInTx === -1) {
-      throw new Error(
-        `Event commitment ${eventCommitment} (siloed as ${siloedEventCommitment}) is not present in tx ${txHash}`,
+      // Unlike in NoteService, this might not be a bug since the commitment hasn't been verified yet in the message
+      // processing pipeline. A malformed or malicious message could trigger this condition. Because of this we don't
+      // error out and we just show a warning.
+      this.log.warn(
+        `Skipping event whose commitment is not present in its tx. siloedEventCommitment=${siloedEventCommitment}, contract=${contractAddress}, selector=${selector}, eventCommitment=${eventCommitment}, txHash=${txHash}`,
       );
+      return;
     }
 
     return this.privateEventStore.storePrivateEventLog(