@aztec/pxe 0.0.1-commit.42ee6df9b → 0.0.1-commit.431c48d

package/src/config/index.ts

@@ -1,6 +1,7 @@
 import {
   type ConfigMappingsType,
   booleanConfigHelper,
+  enumConfigHelper,
   getConfigFromMappings,
   numberConfigHelper,
   parseBooleanEnv,
@@ -9,6 +10,7 @@ import { type ChainConfig, chainConfigMappings } from '@aztec/stdlib/config';
 import { type DataStoreConfig, dataConfigMappings } from '@aztec/stdlib/kv-store';
 
 export { getPackageInfo } from './package_info.js';
+export * from '../hooks/index.js';
 
 /**
  * Configuration settings for the prover factory
@@ -26,9 +28,33 @@ export interface BlockSynchronizerConfig {
   l2BlockBatchSize: number;
   /** Which chain tip to sync to (proposed, checkpointed, proven, finalized) */
   syncChainTip?: 'proposed' | 'checkpointed' | 'proven' | 'finalized';
+  /**
+   * Whether PXE should automatically sync with the node before each operation (simulate, prove, profile,
+   * execute utility, get private events, update contract). When disabled, callers (e.g. wallets) are
+   * responsible for calling `pxe.sync()` explicitly
+   */
+  autoSync: boolean;
 }
 
-export type PXEConfig = KernelProverConfig & DataStoreConfig & ChainConfig & BlockSynchronizerConfig;
+/**
+ * Configuration settings for the contract sync service.
+ */
+export interface ContractSyncConfig {
+  /**
+   * Whether PXE speculatively syncs contracts it predicts will follow the one requested, running them concurrently
+   * with it instead of waiting for execution to reach them. When enabled, repeated flows sync faster, but a wrong
+   * prediction spends unnecessary node requests syncing contracts the job never uses.
+   *
+   * Experimental, off by default.
+   */
+  concurrentContractSyncEnabled: boolean;
+}
+
+export type PXEConfig = KernelProverConfig &
+  DataStoreConfig &
+  ChainConfig &
+  BlockSynchronizerConfig &
+  ContractSyncConfig;
 
 export type CliPXEOptions = {
   /** Custom Aztec Node URL to connect to  */
@@ -58,14 +84,19 @@ export const pxeConfigMappings: ConfigMappingsType<PXEConfig> = {
   syncChainTip: {
     env: 'PXE_SYNC_CHAIN_TIP',
     description: 'Which chain tip to sync to (proposed, checkpointed, proven, finalized)',
-    defaultValue: 'proposed',
-    parseEnv: (val: string) => {
-      const allowedValues = ['proposed', 'checkpointed', 'proven', 'finalized'];
-      if (allowedValues.includes(val)) {
-        return val;
-      }
-      throw new Error(`Invalid value for PXE_SYNC_CHAIN_TIP: ${val}. Allowed values are: ${allowedValues.join(', ')}`);
-    },
+    ...enumConfigHelper(['proposed', 'checkpointed', 'proven', 'finalized'], 'proposed'),
+  },
+  autoSync: {
+    env: 'PXE_AUTO_SYNC',
+    description:
+      'Whether PXE syncs with the node automatically before each operation. Disable to let the caller (e.g. a wallet) drive syncs explicitly via pxe.sync().',
+    ...booleanConfigHelper(true),
+  },
+  concurrentContractSyncEnabled: {
+    env: 'PXE_CONCURRENT_CONTRACT_SYNC_ENABLED',
+    description:
+      'Whether PXE speculatively syncs contracts it predicts will follow the one requested, running them concurrently with it. Repeated flows sync faster, but a wrong prediction spends unnecessary node requests. Experimental, off by default.',
+    ...booleanConfigHelper(false),
   },
 };
 

package/src/config/package_info.ts

@@ -1,3 +1,3 @@
 export function getPackageInfo() {
-  return { version: '5.0.0', name: '@aztec/pxe' };
+  return { version: '5.3.0', name: '@aztec/pxe' };
 }

package/src/contract/contract_call_graph.ts

@@ -0,0 +1,113 @@
+import { FunctionSelector } from '@aztec/stdlib/abi';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+/** Confidence a call must reach to be predicted. */
+export const PREDICTION_THRESHOLD = 2;
+
+/** Cap on a call's confidence, so a function called by many jobs is still dropped within a few missed ones. */
+export const MAX_CONFIDENCE = 5;
+
+/**
+ * A call graph over contract functions - who calls whom - learned from the direct calls observed in past jobs, so
+ * a function's predicted callees can sync their contracts before execution reaches them.
+ *
+ * A function's direct calls tend to repeat across jobs: constrained delivery calls the handshake registry, a transfer
+ * may call an authwit, an AMM calls its tokens. The same function does not always make the same calls, though: they
+ * can depend on context or storage state. A call must therefore repeat often enough to earn confidence before it is
+ * predicted. Calls are keyed per function, not per contract, since different functions of a contract call different
+ * contracts. See {@link commitJob} for how each call's confidence is learned from committed jobs.
+ *
+ * Purely in-memory bookkeeping: the graph is lost when PXE is rebuilt (e.g. on restart).
+ */
+export class ContractCallGraph {
+  // job -> caller function -> functions it called directly
+  private readonly activeJobs: Map<JobId, Map<CallKey, Set<CallKey>>> = new Map();
+
+  // caller function -> function it calls directly -> confidence score
+  private readonly callConfidence: Map<CallKey, Map<CallKey, number>> = new Map();
+
+  constructor(private readonly enabled: boolean) {}
+
+  /** Records that `caller` directly called `callee` in the given job. */
+  recordCall({ jobId, caller, callee }: { jobId: JobId; caller: ContractFunction; callee: ContractFunction }): void {
+    // Same-contract calls are ignored: our goal is to warm a callee's contract ahead of use, and the target of such
+    // a call is already warm.
+    if (!this.enabled || caller.address.equals(callee.address)) {
+      return;
+    }
+    let callsInJob = this.activeJobs.get(jobId);
+    if (!callsInJob) {
+      callsInJob = new Map();
+      this.activeJobs.set(jobId, callsInJob);
+    }
+    let callees = callsInJob.get(toCallKey(caller));
+    if (!callees) {
+      callees = new Set();
+      callsInJob.set(toCallKey(caller), callees);
+    }
+    callees.add(toCallKey(callee));
+  }
+
+  /** Predicts the functions `caller` will call directly. */
+  predictDirectCallees(caller: ContractFunction): ContractFunction[] {
+    const callees = this.callConfidence.get(toCallKey(caller)) ?? new Map<CallKey, number>();
+    return [...callees.entries()]
+      .filter(([, confidence]) => confidence >= PREDICTION_THRESHOLD)
+      .map(([callee]) => fromCallKey(callee));
+  }
+
+  /**
+   * Commits the job so the calls it observed are recorded and learned from. A function that called nothing keeps its
+   * callees untouched, so read-only uses (e.g. reading notes or events) erode nothing.
+   */
+  commitJob(jobId: JobId): void {
+    const callsInJob = this.activeJobs.get(jobId);
+    this.activeJobs.delete(jobId);
+    if (!callsInJob) {
+      return;
+    }
+
+    for (const [caller, observed] of callsInJob) {
+      const callees = this.callConfidence.get(caller) ?? new Map<CallKey, number>();
+      for (const [callee, confidence] of callees) {
+        const delta = observed.has(callee) ? 1 : -1;
+        const updated = Math.min(confidence + delta, MAX_CONFIDENCE);
+        if (updated === 0) {
+          callees.delete(callee);
+        } else {
+          callees.set(callee, updated);
+        }
+      }
+      // First-time callees enter at 1, below PREDICTION_THRESHOLD: a call must repeat before it is predicted.
+      [...observed].filter(callee => !callees.has(callee)).forEach(callee => callees.set(callee, 1));
+      this.callConfidence.set(caller, callees);
+    }
+  }
+
+  /** Drops a discarded job without learning. */
+  discardJob(jobId: JobId): void {
+    this.activeJobs.delete(jobId);
+  }
+}
+
+/** A specific function of a contract, as observed in a call. */
+export type ContractFunction = {
+  /** The address of the contract the function belongs to. */
+  address: AztecAddress;
+  /** The selector of the function. */
+  selector: FunctionSelector;
+};
+
+type JobId = string;
+
+/** A {@link ContractFunction} flattened to a `contractAddress:selector` string, so maps can key on it. */
+export type CallKey = `0x${string}:${string}`;
+
+export function toCallKey({ address, selector }: ContractFunction): CallKey {
+  return `${address.toString()}:${selector.toString()}`;
+}
+
+function fromCallKey(key: CallKey): ContractFunction {
+  const [address, selector] = key.split(':');
+  return { address: AztecAddress.fromStringUnsafe(address), selector: FunctionSelector.fromString(selector) };
+}

package/src/contract/contract_class_service.ts

@@ -0,0 +1,45 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import { isProtocolContract } from '@aztec/protocol-contracts';
+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 { ContractStore } from '../storage/contract_store/contract_store.js';
+
+/**
+ * Resolves the contract class id that an address runs at a given anchor block, as tracked by the chain.
+ *
+ * PXE does not store a contract's current class id: it is mutable, chain-derived state that changes when a contract is
+ * upgraded and can be undone by a reorg. Instead this service asks the node for the current class at an anchor block,
+ * falling back to a local instance if no upgrades were scheduled.
+ */
+export class ContractClassService {
+  constructor(
+    private node: AztecNode,
+    private contractStore: ContractStore,
+  ) {}
+
+  /**
+   * Returns the class id that corresponds to `address` as of `anchorBlockHeader`, or `undefined` if no instance is
+   * registered for `address`. A missing instance is an absence the caller decides how to handle, not an error; genuine
+   * failures (e.g. the node being unreachable) still throw.
+   */
+  async getCurrentClassId(address: AztecAddress, anchorBlockHeader: BlockHeader): Promise<Fr | undefined> {
+    // Protocol contracts are not in the registry and cannot be upgraded, so their original class is always current.
+    // Short-circuiting avoids a node round-trip.
+    if (isProtocolContract(address)) {
+      const instance = await this.contractStore.getContractInstance(address);
+      return instance?.originalContractClassId;
+    }
+
+    // The node resolves the current class from the same scheduled value change the AVM enforces against the public
+    // data tree. If the contract was upgraded the node returns a non-undefined instance; an undefined result means no
+    // upgrade happened (or the node has no record of it, e.g. it was never publicly deployed), so the original class
+    // is current.
+    const nodeInstance = await this.node.getContract(address, await anchorBlockHeader.hash());
+    if (nodeInstance) {
+      return nodeInstance.currentContractClassId;
+    }
+    return (await this.contractStore.getContractInstance(address))?.originalContractClassId;
+  }
+}

package/src/contract/contract_sync_service.ts

@@ -0,0 +1,342 @@
+import type { Logger } from '@aztec/foundation/log';
+import { allToCompletion } from '@aztec/foundation/promise';
+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 { ContractSyncConfig } from '../config/index.js';
+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 { type CallKey, ContractCallGraph, type ContractFunction, toCallKey } from './contract_call_graph.js';
+import type { ContractClassService } from './contract_class_service.js';
+import { syncScope } from './helpers.js';
+
+/**
+ * Maximum number of scope syncs running concurrently within a single sync call. Sized to trade off parallelism
+ * on non-ACIR work (node RPC, note store reads) against memory pressure from concurrent circuit execution.
+ */
+export const MAX_CONCURRENT_SCOPE_SYNCS = 5;
+
+/**
+ * Selector of the macro-generated `sync_state` utility function, which is the same for every contract.
+ * Pinned against a compiled artifact in tests, so a macro signature change fails there.
+ */
+export const SYNC_STATE_SELECTOR = FunctionSelector.fromString('0x418ef5da');
+
+/**
+ * Service for syncing the private state of contracts. 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`). The value is a promise that resolves when the contract is synced.
+  private readonly syncedContracts: Map<SyncKey, Promise<void>> = new Map();
+
+  // Per-job speculation state, dropped when the job commits or discards.
+  private readonly speculationByJob: Map<JobId, JobSpeculation> = new Map();
+
+  // Predicts a function's callees from the calls observed in past jobs, driving speculative sync.
+  private readonly callGraph: ContractCallGraph;
+
+  constructor(
+    private aztecNode: AztecNode,
+    private contractStore: ContractStore,
+    private contractClassService: ContractClassService,
+    private noteStore: NoteStore,
+    private log: Logger,
+    { concurrentContractSyncEnabled }: ContractSyncConfig,
+  ) {
+    this.callGraph = new ContractCallGraph(concurrentContractSyncEnabled);
+  }
+
+  /**
+   * Ensures a contract's private state is synchronized.
+   * Uses a cache to avoid redundant sync operations - the cache is wiped when the anchor block changes.
+   */
+  async ensureContractSynced({
+    contract,
+    functionToInvokeAfterSync,
+    utilityExecutor,
+    anchorBlockHeader,
+    jobId,
+    scopes,
+    triggeredBy,
+  }: ContractSyncRequest): Promise<void> {
+    // A call is recorded only when both functions are known: the invoked callee and the caller that triggered it.
+    if (functionToInvokeAfterSync && triggeredBy) {
+      this.callGraph.recordCall({
+        jobId,
+        caller: triggeredBy,
+        callee: { address: contract, selector: functionToInvokeAfterSync },
+      });
+    }
+
+    await this.#startSyncIfNeeded(
+      contract,
+      functionToInvokeAfterSync,
+      utilityExecutor,
+      anchorBlockHeader,
+      jobId,
+      scopes,
+    );
+  }
+
+  /**
+   * Waits until every speculative sync the job fired has finished, then rejects if any failed, so the job discards
+   * instead of committing. This is needed because a sync that fails midway can leave partial staged writes, and a
+   * speculative failure might not be surfaced by any request.
+   */
+  async settle(jobId: JobId): Promise<void> {
+    // A speculative sync's execution can fire more speculative syncs mid-drain, so loop until no new promises
+    // appear, and only escalate once nothing is still writing.
+    const { syncs } = this.#speculationForJob(jobId);
+    const failures: unknown[] = [];
+    while (syncs.length > 0) {
+      const results = await Promise.allSettled(syncs.splice(0));
+      failures.push(...results.filter(result => result.status === 'rejected').map(result => result.reason));
+    }
+    if (failures.length > 0) {
+      throw new AggregateError(
+        failures,
+        'Speculative syncs failed, so the job must discard its staged writes instead of committing',
+      );
+    }
+  }
+
+  /** 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();
+  }
+
+  commit(jobId: JobId): Promise<void> {
+    this.callGraph.commitJob(jobId);
+    this.speculationByJob.delete(jobId);
+    return Promise.resolve();
+  }
+
+  discardStaged(jobId: JobId): 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.callGraph.discardJob(jobId);
+    this.speculationByJob.delete(jobId);
+    return Promise.resolve();
+  }
+
+  /**
+   * For each unsynced scope, creates a promise that waits on:
+   *  1. Note nullifier sync (shared, batched across all unsynced scopes).
+   *  2. Per-scope sync (individual, semaphore-bounded).
+   * When concurrent contract sync is enabled, the predicted direct callees of the invoked function and of the
+   * contract's `sync_state` start speculatively too, once the contract's own syncs have started (see
+   * {@link #speculativelySync}).
+   * @returns A promise that resolves once every requested scope is synced, including syncs already in flight from
+   * concurrent calls. Speculative syncs are not included: those are only awaited by a later request that needs
+   * their contract, or by the job's {@link settle}.
+   */
+  async #startSyncIfNeeded(
+    contractAddress: AztecAddress,
+    functionToInvokeAfterSync: FunctionSelector | null,
+    utilityExecutor: (call: FunctionCall, scopes: AztecAddress[]) => Promise<any>,
+    anchorBlockHeader: BlockHeader,
+    jobId: JobId,
+    scopes: AztecAddress[],
+  ): Promise<void> {
+    const scopesToSync = scopes.filter(scope => !this.syncedContracts.has(toKey(contractAddress, scope)));
+    if (scopesToSync.length > 0) {
+      this.log.debug(`Syncing contract ${contractAddress} for ${scopesToSync.length} scope(s)`);
+
+      const syncNullifiersPromise = this.#syncNoteNullifiers(contractAddress, anchorBlockHeader, jobId, scopesToSync);
+
+      // We build a new semaphore for each sync call, so it rate-limits the scopes within that single call. We do
+      // this so that if these scope syncs trigger nested syncs, the nested ones can execute without causing a deadlock.
+      const syncSlot = new Semaphore(MAX_CONCURRENT_SCOPE_SYNCS);
+
+      for (const scope of scopesToSync) {
+        const key = toKey(contractAddress, scope);
+        const syncScopePromise = runBounded(syncSlot, () =>
+          syncScope(
+            contractAddress,
+            this.contractStore,
+            this.contractClassService,
+            anchorBlockHeader,
+            functionToInvokeAfterSync,
+            utilityExecutor,
+            scope,
+          ),
+        );
+        // This cached promise is what every later request for this scope awaits, and both branches write staged data,
+        // so it must run both to completion even when one fails.
+        const promise = allToCompletion([syncNullifiersPromise, syncScopePromise])
+          .then(() => {})
+          .catch(err => {
+            this.syncedContracts.delete(key);
+            throw err;
+          });
+        this.syncedContracts.set(key, promise);
+      }
+    }
+
+    // `sync_state` itself calls other contracts (e.g. most contract syncs query the handshake registry), so its
+    // predicted callees start syncing alongside the contract's own syncs.
+    this.#speculativelySync(contractAddress, SYNC_STATE_SELECTOR, utilityExecutor, anchorBlockHeader, jobId, scopes);
+    this.#speculativelySync(
+      contractAddress,
+      functionToInvokeAfterSync,
+      utilityExecutor,
+      anchorBlockHeader,
+      jobId,
+      scopes,
+    );
+
+    await this.#awaitSync(contractAddress, scopes);
+  }
+
+  /**
+   * Starts the syncs of the contracts the given function is predicted to call (see {@link ContractCallGraph} for how
+   * predictions are learned). Each started sync speculates from its own function in turn, so the whole predicted call
+   * tree syncs in parallel with the contract instead of one contract at a time as execution reaches it.
+   *
+   * A wrong prediction is cheap: the extra node requests are batched into round trips the job already makes, and the
+   * synced data simply goes unused.
+   */
+  #speculativelySync(
+    contractAddress: AztecAddress,
+    functionToInvokeAfterSync: FunctionSelector | null,
+    utilityExecutor: (call: FunctionCall, scopes: AztecAddress[]) => Promise<any>,
+    anchorBlockHeader: BlockHeader,
+    jobId: JobId,
+    scopes: AztecAddress[],
+  ): void {
+    // Without a function there is no key to predict from (the request is a direct read).
+    if (!functionToInvokeAfterSync) {
+      return;
+    }
+    const speculation = this.#speculationForJob(jobId);
+    const caller: ContractFunction = { address: contractAddress, selector: functionToInvokeAfterSync };
+    for (const callee of this.callGraph.predictDirectCallees(caller)) {
+      // The job's set of already-speculated functions stops the recursion when the predicted graph has a cycle.
+      if (speculation.speculated.has(toCallKey(callee))) {
+        continue;
+      }
+      speculation.speculated.add(toCallKey(callee));
+      const syncPromise = this.#startSyncIfNeeded(
+        callee.address,
+        callee.selector,
+        utilityExecutor,
+        anchorBlockHeader,
+        jobId,
+        scopes,
+      );
+      speculation.syncs.push(syncPromise);
+      // `settle` only escalates these failures at the end of the job: catch here so one does not become an unhandled
+      // rejection before then, and log it.
+      syncPromise.catch(err => {
+        this.log.warn(`Speculative sync of ${callee.address} failed`, { jobId, error: err?.message });
+      });
+    }
+  }
+
+  /** Syncs note nullifiers across all unsynced scopes in a single batched call. */
+  async #syncNoteNullifiers(
+    contractAddress: AztecAddress,
+    anchorBlockHeader: BlockHeader,
+    jobId: JobId,
+    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);
+  }
+
+  #speculationForJob(jobId: JobId): JobSpeculation {
+    let speculation = this.speculationByJob.get(jobId);
+    if (!speculation) {
+      speculation = { speculated: new Set(), syncs: [] };
+      this.speculationByJob.set(jobId, speculation);
+    }
+    return speculation;
+  }
+
+  /** 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 allToCompletion(promises);
+  }
+}
+
+/** A request to synchronize a contract's private state. */
+type ContractSyncRequest = {
+  /** The contract to sync. */
+  contract: AztecAddress;
+  /**
+   * The function that will be invoked after the sync, or null when nothing will be invoked (e.g. reading
+   * notes/events directly).
+   */
+  functionToInvokeAfterSync: FunctionSelector | null;
+  /** Executes a utility function call under the given scopes. Syncs run each contract's sync_state through it. */
+  utilityExecutor: (call: FunctionCall, scopes: AztecAddress[]) => Promise<any>;
+  /** The anchor block to sync at. */
+  anchorBlockHeader: BlockHeader;
+  /** The job requesting the sync. */
+  jobId: JobId;
+  /** Access scopes to pass through to the utility executor (affects whose account's private state is discovered). */
+  scopes: AztecAddress[];
+  /**
+   * The function whose execution triggered this sync request, or undefined when the request is a job's top-level use
+   * (an entry call or a direct read) rather than a nested call.
+   */
+  triggeredBy: ContractFunction | undefined;
+};
+
+type JobId = string;
+
+/** A job's speculation state. */
+type JobSpeculation = {
+  /** Functions prediction already ran for, so the recursion stops on cycles in the predicted graph. */
+  speculated: Set<CallKey>;
+  /** Every sync fired by prediction, awaited by {@link settle} before the job commits or discards. */
+  syncs: Promise<void>[];
+};
+
+/** Key of a contract's sync cache entry for a single scope: `contractAddress:scopeAddress`. */
+type SyncKey = `0x${string}:0x${string}`;
+
+function toKey(contract: AztecAddress, scope: AztecAddress): SyncKey {
+  return `${contract.toString()}:${scope.toString()}`;
+}
+
+/** Runs fn while holding a slot in the given semaphore, bounding concurrent scope syncs within a single call. */
+async function runBounded<T>(syncSlot: Semaphore, fn: () => Promise<T>): Promise<T> {
+  await syncSlot.acquire();
+  try {
+    return await fn();
+  } finally {
+    syncSlot.release();
+  }
+}

package/src/contract/helpers.ts

@@ -0,0 +1,35 @@
+import type { FunctionCall, FunctionSelector } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { BlockHeader } from '@aztec/stdlib/tx';
+
+import type { ContractStore } from '../storage/contract_store/contract_store.js';
+import type { ContractClassService } from './contract_class_service.js';
+import { isSkipSyncContract } from './skip_sync_contracts.js';
+
+export async function syncScope(
+  contractAddress: AztecAddress,
+  contractStore: ContractStore,
+  contractClassService: ContractClassService,
+  anchorBlockHeader: BlockHeader,
+  functionToInvokeAfterSync: FunctionSelector | null,
+  utilityExecutor: (privateSyncCall: FunctionCall, scopes: AztecAddress[]) => Promise<any>,
+  scope: AztecAddress,
+) {
+  // Some canonical contracts hold no private state, so there is nothing to sync (see `skipSyncContracts`).
+  if (isSkipSyncContract(contractAddress)) {
+    return;
+  }
+
+  const classId = await contractClassService.getCurrentClassId(contractAddress, anchorBlockHeader);
+  if (!classId) {
+    throw new Error(`Cannot sync contract ${contractAddress}: its instance is not registered nor published.`);
+  }
+  const syncStateFunctionCall = await contractStore.getFunctionCall('sync_state', [scope], contractAddress, classId);
+  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]);
+}

package/src/contract/skip_sync_contracts.ts

@@ -0,0 +1,23 @@
+import { ProtocolContractAddress } from '@aztec/protocol-contracts';
+import { STANDARD_AUTH_REGISTRY_ADDRESS } from '@aztec/standard-contracts/auth-registry/constants';
+import { STANDARD_MULTI_CALL_ENTRYPOINT_ADDRESS } from '@aztec/standard-contracts/multi-call-entrypoint/constants';
+import { STANDARD_PUBLIC_CHECKS_ADDRESS } from '@aztec/standard-contracts/public-checks/constants';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+/**
+ * Canonical contracts that hold no private state and are therefore never synced.
+ *
+ * The protocol contracts (registries, fee juice) plus the standard AuthRegistry, MultiCallEntrypoint and PublicChecks
+ * declare no notes and no events, so their macro-generated `sync_state` has nothing to discover.
+ */
+export const skipSyncContracts: AztecAddress[] = [
+  ...Object.values(ProtocolContractAddress),
+  STANDARD_AUTH_REGISTRY_ADDRESS,
+  STANDARD_MULTI_CALL_ENTRYPOINT_ADDRESS,
+  STANDARD_PUBLIC_CHECKS_ADDRESS,
+];
+
+/** Returns whether the given contract should be skipped during private state synchronization. */
+export function isSkipSyncContract(address: AztecAddress): boolean {
+  return skipSyncContracts.some(a => a.equals(address));
+}