@aztec-labs/pxe 6.0.0-nightly.20260829

package/dest/contract/contract_call_graph.d.ts

@@ -0,0 +1,51 @@
+import { FunctionSelector } from '@aztec-labs/stdlib/abi';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { ChangeSetId } from '../storage/staged_write_coordinator.js';
+/** Confidence a call must reach to be predicted. */
+export declare const PREDICTION_THRESHOLD = 2;
+/** Cap on a call's confidence, so a function called by many operations is still dropped within a few missed ones. */
+export declare const MAX_CONFIDENCE = 5;
+/**
+ * A call graph over contract functions - who calls whom - learned from the direct calls observed in past operations, so
+ * a function's predicted callees can sync their contracts before execution reaches them.
+ *
+ * A function's direct calls tend to repeat across operations: 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 learn} for how each call's confidence is learned from committed operations.
+ *
+ * Purely in-memory bookkeeping: the graph is lost when PXE is rebuilt (e.g. on restart).
+ */
+export declare class ContractCallGraph {
+    private readonly enabled;
+    private readonly activeChangeSets;
+    private readonly callConfidence;
+    constructor(enabled: boolean);
+    /** Records that `caller` directly called `callee` in the given change set. */
+    recordCall({ changeSetId, caller, callee }: {
+        changeSetId: ChangeSetId;
+        caller: ContractFunction;
+        callee: ContractFunction;
+    }): void;
+    /** Predicts the functions `caller` will call directly. */
+    predictDirectCallees(caller: ContractFunction): ContractFunction[];
+    /**
+     * Learns from a committed change set: the calls it observed update each caller's confidence. A function that called
+     * nothing keeps its callees untouched, so read-only uses (e.g. reading notes or events) erode nothing.
+     */
+    learn(changeSetId: ChangeSetId): void;
+    /** Drops a discarded change set without learning. */
+    discard(changeSetId: ChangeSetId): void;
+}
+/** 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;
+};
+/** A {@link ContractFunction} flattened to a `contractAddress:selector` string, so maps can key on it. */
+export type CallKey = `0x${string}:${string}`;
+export declare function toCallKey({ address, selector }: ContractFunction): CallKey;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29udHJhY3RfY2FsbF9ncmFwaC5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2NvbnRyYWN0L2NvbnRyYWN0X2NhbGxfZ3JhcGgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFDMUQsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLGtDQUFrQyxDQUFDO0FBRWhFLE9BQU8sS0FBSyxFQUFFLFdBQVcsRUFBRSxNQUFNLHdDQUF3QyxDQUFDO0FBRTFFLG9EQUFvRDtBQUNwRCxlQUFPLE1BQU0sb0JBQW9CLElBQUksQ0FBQztBQUV0QyxxSEFBcUg7QUFDckgsZUFBTyxNQUFNLGNBQWMsSUFBSSxDQUFDO0FBRWhDOzs7Ozs7Ozs7OztHQVdHO0FBQ0gscUJBQWEsaUJBQWlCO0lBT2hCLE9BQU8sQ0FBQyxRQUFRLENBQUMsT0FBTztJQUxwQyxPQUFPLENBQUMsUUFBUSxDQUFDLGdCQUFnQixDQUEyRDtJQUc1RixPQUFPLENBQUMsUUFBUSxDQUFDLGNBQWMsQ0FBaUQ7SUFFaEYsWUFBNkIsT0FBTyxFQUFFLE9BQU8sRUFBSTtJQUVqRCw4RUFBOEU7SUFDOUUsVUFBVSxDQUFDLEVBQ1QsV0FBVyxFQUNYLE1BQU0sRUFDTixNQUFNLEVBQ1AsRUFBRTtRQUNELFdBQVcsRUFBRSxXQUFXLENBQUM7UUFDekIsTUFBTSxFQUFFLGdCQUFnQixDQUFDO1FBQ3pCLE1BQU0sRUFBRSxnQkFBZ0IsQ0FBQztLQUMxQixHQUFHLElBQUksQ0FpQlA7SUFFRCwwREFBMEQ7SUFDMUQsb0JBQW9CLENBQUMsTUFBTSxFQUFFLGdCQUFnQixHQUFHLGdCQUFnQixFQUFFLENBS2pFO0lBRUQ7OztPQUdHO0lBQ0gsS0FBSyxDQUFDLFdBQVcsRUFBRSxXQUFXLEdBQUcsSUFBSSxDQXNCcEM7SUFFRCxxREFBcUQ7SUFDckQsT0FBTyxDQUFDLFdBQVcsRUFBRSxXQUFXLEdBQUcsSUFBSSxDQUV0QztDQUNGO0FBRUQsZ0VBQWdFO0FBQ2hFLE1BQU0sTUFBTSxnQkFBZ0IsR0FBRztJQUM3QiwyREFBMkQ7SUFDM0QsT0FBTyxFQUFFLFlBQVksQ0FBQztJQUN0QixvQ0FBb0M7SUFDcEMsUUFBUSxFQUFFLGdCQUFnQixDQUFDO0NBQzVCLENBQUM7QUFFRiwwR0FBMEc7QUFDMUcsTUFBTSxNQUFNLE9BQU8sR0FBRyxLQUFLLE1BQU0sSUFBSSxNQUFNLEVBQUUsQ0FBQztBQUU5Qyx3QkFBZ0IsU0FBUyxDQUFDLEVBQUUsT0FBTyxFQUFFLFFBQVEsRUFBRSxFQUFFLGdCQUFnQixHQUFHLE9BQU8sQ0FFMUUifQ==

package/dest/contract/contract_call_graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract_call_graph.d.ts","sourceRoot":"","sources":["../../src/contract/contract_call_graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wCAAwC,CAAC;AAE1E,oDAAoD;AACpD,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,qHAAqH;AACrH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAiB;IAOhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA2D;IAG5F,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiD;IAEhF,YAA6B,OAAO,EAAE,OAAO,EAAI;IAEjD,8EAA8E;IAC9E,UAAU,CAAC,EACT,WAAW,EACX,MAAM,EACN,MAAM,EACP,EAAE;QACD,WAAW,EAAE,WAAW,CAAC;QACzB,MAAM,EAAE,gBAAgB,CAAC;QACzB,MAAM,EAAE,gBAAgB,CAAC;KAC1B,GAAG,IAAI,CAiBP;IAED,0DAA0D;IAC1D,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAKjE;IAED;;;OAGG;IACH,KAAK,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAsBpC;IAED,qDAAqD;IACrD,OAAO,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAEtC;CACF;AAED,gEAAgE;AAChE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,2DAA2D;IAC3D,OAAO,EAAE,YAAY,CAAC;IACtB,oCAAoC;IACpC,QAAQ,EAAE,gBAAgB,CAAC;CAC5B,CAAC;AAEF,0GAA0G;AAC1G,MAAM,MAAM,OAAO,GAAG,KAAK,MAAM,IAAI,MAAM,EAAE,CAAC;AAE9C,wBAAgB,SAAS,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAE1E"}

package/dest/contract/contract_call_graph.js

@@ -0,0 +1,91 @@
+import { FunctionSelector } from '@aztec-labs/stdlib/abi';
+import { AztecAddress } from '@aztec-labs/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 operations 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 operations, so
+ * a function's predicted callees can sync their contracts before execution reaches them.
+ *
+ * A function's direct calls tend to repeat across operations: 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 learn} for how each call's confidence is learned from committed operations.
+ *
+ * Purely in-memory bookkeeping: the graph is lost when PXE is rebuilt (e.g. on restart).
+ */ export class ContractCallGraph {
+    enabled;
+    // change set -> caller function -> functions it called directly
+    activeChangeSets;
+    // caller function -> function it calls directly -> confidence score
+    callConfidence;
+    constructor(enabled){
+        this.enabled = enabled;
+        this.activeChangeSets = new Map();
+        this.callConfidence = new Map();
+    }
+    /** Records that `caller` directly called `callee` in the given change set. */ recordCall({ changeSetId, caller, callee }) {
+        // 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 callsInChangeSet = this.activeChangeSets.get(changeSetId);
+        if (!callsInChangeSet) {
+            callsInChangeSet = new Map();
+            this.activeChangeSets.set(changeSetId, callsInChangeSet);
+        }
+        let callees = callsInChangeSet.get(toCallKey(caller));
+        if (!callees) {
+            callees = new Set();
+            callsInChangeSet.set(toCallKey(caller), callees);
+        }
+        callees.add(toCallKey(callee));
+    }
+    /** Predicts the functions `caller` will call directly. */ predictDirectCallees(caller) {
+        const callees = this.callConfidence.get(toCallKey(caller)) ?? new Map();
+        return [
+            ...callees.entries()
+        ].filter(([, confidence])=>confidence >= PREDICTION_THRESHOLD).map(([callee])=>fromCallKey(callee));
+    }
+    /**
+   * Learns from a committed change set: the calls it observed update each caller's confidence. A function that called
+   * nothing keeps its callees untouched, so read-only uses (e.g. reading notes or events) erode nothing.
+   */ learn(changeSetId) {
+        const callsInChangeSet = this.activeChangeSets.get(changeSetId);
+        this.activeChangeSets.delete(changeSetId);
+        if (!callsInChangeSet) {
+            return;
+        }
+        for (const [caller, observed] of callsInChangeSet){
+            const callees = this.callConfidence.get(caller) ?? new Map();
+            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 change set without learning. */ discard(changeSetId) {
+        this.activeChangeSets.delete(changeSetId);
+    }
+}
+export function toCallKey({ address, selector }) {
+    return `${address.toString()}:${selector.toString()}`;
+}
+function fromCallKey(key) {
+    const [address, selector] = key.split(':');
+    return {
+        address: AztecAddress.fromStringUnsafe(address),
+        selector: FunctionSelector.fromString(selector)
+    };
+}

package/dest/contract/contract_class_service.d.ts

@@ -0,0 +1,24 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { AztecNode } from '@aztec-labs/stdlib/interfaces/client';
+import type { BlockHeader } from '@aztec-labs/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 declare class ContractClassService {
+    private node;
+    private contractStore;
+    constructor(node: AztecNode, 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.
+     */
+    getCurrentClassId(address: AztecAddress, anchorBlockHeader: BlockHeader): Promise<Fr | undefined>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29udHJhY3RfY2xhc3Nfc2VydmljZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2NvbnRyYWN0L2NvbnRyYWN0X2NsYXNzX3NlcnZpY2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsRUFBRSxFQUFFLE1BQU0scUNBQXFDLENBQUM7QUFFOUQsT0FBTyxLQUFLLEVBQUUsWUFBWSxFQUFFLE1BQU0sa0NBQWtDLENBQUM7QUFDckUsT0FBTyxLQUFLLEVBQUUsU0FBUyxFQUFFLE1BQU0sc0NBQXNDLENBQUM7QUFDdEUsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFFekQsT0FBTyxLQUFLLEVBQUUsYUFBYSxFQUFFLE1BQU0sNkNBQTZDLENBQUM7QUFFakY7Ozs7OztHQU1HO0FBQ0gscUJBQWEsb0JBQW9CO0lBRTdCLE9BQU8sQ0FBQyxJQUFJO0lBQ1osT0FBTyxDQUFDLGFBQWE7SUFGdkIsWUFDVSxJQUFJLEVBQUUsU0FBUyxFQUNmLGFBQWEsRUFBRSxhQUFhLEVBQ2xDO0lBRUo7Ozs7T0FJRztJQUNHLGlCQUFpQixDQUFDLE9BQU8sRUFBRSxZQUFZLEVBQUUsaUJBQWlCLEVBQUUsV0FBVyxHQUFHLE9BQU8sQ0FBQyxFQUFFLEdBQUcsU0FBUyxDQUFDLENBaUJ0RztDQUNGIn0=

package/dest/contract/contract_class_service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract_class_service.d.ts","sourceRoot":"","sources":["../../src/contract/contract_class_service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,qCAAqC,CAAC;AAE9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AAEjF;;;;;;GAMG;AACH,qBAAa,oBAAoB;IAE7B,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,aAAa;IAFvB,YACU,IAAI,EAAE,SAAS,EACf,aAAa,EAAE,aAAa,EAClC;IAEJ;;;;OAIG;IACG,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,GAAG,OAAO,CAAC,EAAE,GAAG,SAAS,CAAC,CAiBtG;CACF"}

package/dest/contract/contract_class_service.js

@@ -0,0 +1,36 @@
+import { isProtocolContract } from '@aztec-labs/protocol-contracts';
+/**
+ * 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 {
+    node;
+    contractStore;
+    constructor(node, contractStore){
+        this.node = node;
+        this.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, anchorBlockHeader) {
+        // 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/dest/contract/contract_sync_service.d.ts

@@ -0,0 +1,82 @@
+import type { Logger } from '@aztec-labs/foundation/log';
+import { type FunctionCall, FunctionSelector } from '@aztec-labs/stdlib/abi';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { AztecNode } from '@aztec-labs/stdlib/interfaces/client';
+import type { BlockHeader } from '@aztec-labs/stdlib/tx';
+import type { ContractSyncConfig } from '../config/index.js';
+import type { OperationContributor } from '../operation_lifecycle.js';
+import type { ContractStore } from '../storage/contract_store/contract_store.js';
+import type { NoteStore } from '../storage/note_store/note_store.js';
+import type { ChangeSetId } from '../storage/staged_write_coordinator.js';
+import { type ContractFunction } from './contract_call_graph.js';
+import type { ContractClassService } from './contract_class_service.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 declare 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 declare const SYNC_STATE_SELECTOR: FunctionSelector;
+/**
+ * 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.
+ *
+ * Contributes to every synced operation (see {@link OperationContributor}): its syncs write into the operation's change
+ * set, so it settles them before the change set is decided and releases its per-change-set state on the outcome.
+ */
+export declare class ContractSyncService implements OperationContributor {
+    #private;
+    private aztecNode;
+    private contractStore;
+    private contractClassService;
+    private noteStore;
+    private log;
+    private readonly syncedContracts;
+    private readonly speculationByChangeSet;
+    private readonly callGraph;
+    constructor(aztecNode: AztecNode, contractStore: ContractStore, contractClassService: ContractClassService, noteStore: NoteStore, log: Logger, { concurrentContractSyncEnabled }: ContractSyncConfig);
+    /**
+     * 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.
+     */
+    ensureContractSynced({ contract, functionToInvokeAfterSync, utilityExecutor, anchorBlockHeader, changeSetId, scopes, triggeredBy }: ContractSyncRequest): Promise<void>;
+    /**
+     * Waits until every speculative sync the change set fired has finished, then rejects if any failed, so the change set
+     * 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.
+     */
+    settle(changeSetId: ChangeSetId): Promise<void>;
+    /** Clears sync cache entries for the given scopes of a contract. */
+    invalidateContractForScopes(contractAddress: AztecAddress, scopes: AztecAddress[]): void;
+    /** Clears sync cache. Called by BlockSynchronizer when anchor block changes. */
+    wipe(): void;
+    onOperationEnd(changeSetId: ChangeSetId, outcome: 'committed' | 'discarded'): void;
+}
+/** 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 change set requesting the sync. */
+    changeSetId: ChangeSetId;
+    /** 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 change set's top-level
+     * use (an entry call or a direct read) rather than a nested call.
+     */
+    triggeredBy: ContractFunction | undefined;
+};
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29udHJhY3Rfc3luY19zZXJ2aWNlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvY29udHJhY3QvY29udHJhY3Rfc3luY19zZXJ2aWNlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLE1BQU0sRUFBRSxNQUFNLDRCQUE0QixDQUFDO0FBSXpELE9BQU8sRUFBRSxLQUFLLFlBQVksRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBQzdFLE9BQU8sS0FBSyxFQUFFLFlBQVksRUFBRSxNQUFNLGtDQUFrQyxDQUFDO0FBQ3JFLE9BQU8sS0FBSyxFQUFFLFNBQVMsRUFBRSxNQUFNLHNDQUFzQyxDQUFDO0FBQ3RFLE9BQU8sS0FBSyxFQUFFLFdBQVcsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBRXpELE9BQU8sS0FBSyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sb0JBQW9CLENBQUM7QUFFN0QsT0FBTyxLQUFLLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSwyQkFBMkIsQ0FBQztBQUN0RSxPQUFPLEtBQUssRUFBRSxhQUFhLEVBQUUsTUFBTSw2Q0FBNkMsQ0FBQztBQUNqRixPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsTUFBTSxxQ0FBcUMsQ0FBQztBQUNyRSxPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsTUFBTSx3Q0FBd0MsQ0FBQztBQUMxRSxPQUFPLEVBQW1DLEtBQUssZ0JBQWdCLEVBQWEsTUFBTSwwQkFBMEIsQ0FBQztBQUM3RyxPQUFPLEtBQUssRUFBRSxvQkFBb0IsRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBR3hFOzs7R0FHRztBQUNILGVBQU8sTUFBTSwwQkFBMEIsSUFBSSxDQUFDO0FBRTVDOzs7R0FHRztBQUNILGVBQU8sTUFBTSxtQkFBbUIsa0JBQTRDLENBQUM7QUFFN0U7Ozs7OztHQU1HO0FBQ0gscUJBQWEsbUJBQW9CLFlBQVcsb0JBQW9COztJQVk1RCxPQUFPLENBQUMsU0FBUztJQUNqQixPQUFPLENBQUMsYUFBYTtJQUNyQixPQUFPLENBQUMsb0JBQW9CO0lBQzVCLE9BQU8sQ0FBQyxTQUFTO0lBQ2pCLE9BQU8sQ0FBQyxHQUFHO0lBYmIsT0FBTyxDQUFDLFFBQVEsQ0FBQyxlQUFlLENBQTBDO0lBRzFFLE9BQU8sQ0FBQyxRQUFRLENBQUMsc0JBQXNCLENBQXFEO0lBRzVGLE9BQU8sQ0FBQyxRQUFRLENBQUMsU0FBUyxDQUFvQjtJQUU5QyxZQUNVLFNBQVMsRUFBRSxTQUFTLEVBQ3BCLGFBQWEsRUFBRSxhQUFhLEVBQzVCLG9CQUFvQixFQUFFLG9CQUFvQixFQUMxQyxTQUFTLEVBQUUsU0FBUyxFQUNwQixHQUFHLEVBQUUsTUFBTSxFQUNuQixFQUFFLDZCQUE2QixFQUFFLEVBQUUsa0JBQWtCLEVBR3REO0lBRUQ7OztPQUdHO0lBQ0csb0JBQW9CLENBQUMsRUFDekIsUUFBUSxFQUNSLHlCQUF5QixFQUN6QixlQUFlLEVBQ2YsaUJBQWlCLEVBQ2pCLFdBQVcsRUFDWCxNQUFNLEVBQ04sV0FBVyxFQUNaLEVBQUUsbUJBQW1CLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQWtCckM7SUFFRDs7OztPQUlHO0lBQ0csTUFBTSxDQUFDLFdBQVcsRUFBRSxXQUFXLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQWVwRDtJQUVELG9FQUFvRTtJQUNwRSwyQkFBMkIsQ0FBQyxlQUFlLEVBQUUsWUFBWSxFQUFFLE1BQU0sRUFBRSxZQUFZLEVBQUUsR0FBRyxJQUFJLENBS3ZGO0lBRUQsZ0ZBQWdGO0lBQ2hGLElBQUksSUFBSSxJQUFJLENBR1g7SUFFRCxjQUFjLENBQUMsV0FBVyxFQUFFLFdBQVcsRUFBRSxPQUFPLEVBQUUsV0FBVyxHQUFHLFdBQVcsR0FBRyxJQUFJLENBVWpGO0NBaUtGO0FBRUQsMkRBQTJEO0FBQzNELEtBQUssbUJBQW1CLEdBQUc7SUFDekIsNEJBQTRCO0lBQzVCLFFBQVEsRUFBRSxZQUFZLENBQUM7SUFDdkI7OztPQUdHO0lBQ0gseUJBQXlCLEVBQUUsZ0JBQWdCLEdBQUcsSUFBSSxDQUFDO0lBQ25ELGdIQUFnSDtJQUNoSCxlQUFlLEVBQUUsQ0FBQyxJQUFJLEVBQUUsWUFBWSxFQUFFLE1BQU0sRUFBRSxZQUFZLEVBQUUsS0FBSyxPQUFPLENBQUMsR0FBRyxDQUFDLENBQUM7SUFDOUUsbUNBQW1DO0lBQ25DLGlCQUFpQixFQUFFLFdBQVcsQ0FBQztJQUMvQiwwQ0FBMEM7SUFDMUMsV0FBVyxFQUFFLFdBQVcsQ0FBQztJQUN6QixtSEFBbUg7SUFDbkgsTUFBTSxFQUFFLFlBQVksRUFBRSxDQUFDO0lBQ3ZCOzs7T0FHRztJQUNILFdBQVcsRUFBRSxnQkFBZ0IsR0FBRyxTQUFTLENBQUM7Q0FDM0MsQ0FBQyJ9

package/dest/contract/contract_sync_service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract_sync_service.d.ts","sourceRoot":"","sources":["../../src/contract/contract_sync_service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAIzD,OAAO,EAAE,KAAK,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wCAAwC,CAAC;AAC1E,OAAO,EAAmC,KAAK,gBAAgB,EAAa,MAAM,0BAA0B,CAAC;AAC7G,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGxE;;;GAGG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,kBAA4C,CAAC;AAE7E;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,oBAAoB;;IAY5D,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,oBAAoB;IAC5B,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,GAAG;IAbb,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA0C;IAG1E,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAqD;IAG5F,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAE9C,YACU,SAAS,EAAE,SAAS,EACpB,aAAa,EAAE,aAAa,EAC5B,oBAAoB,EAAE,oBAAoB,EAC1C,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,MAAM,EACnB,EAAE,6BAA6B,EAAE,EAAE,kBAAkB,EAGtD;IAED;;;OAGG;IACG,oBAAoB,CAAC,EACzB,QAAQ,EACR,yBAAyB,EACzB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,MAAM,EACN,WAAW,EACZ,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBrC;IAED;;;;OAIG;IACG,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAepD;IAED,oEAAoE;IACpE,2BAA2B,CAAC,eAAe,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,IAAI,CAKvF;IAED,gFAAgF;IAChF,IAAI,IAAI,IAAI,CAGX;IAED,cAAc,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,GAAG,WAAW,GAAG,IAAI,CAUjF;CAiKF;AAED,2DAA2D;AAC3D,KAAK,mBAAmB,GAAG;IACzB,4BAA4B;IAC5B,QAAQ,EAAE,YAAY,CAAC;IACvB;;;OAGG;IACH,yBAAyB,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACnD,gHAAgH;IAChH,eAAe,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9E,mCAAmC;IACnC,iBAAiB,EAAE,WAAW,CAAC;IAC/B,0CAA0C;IAC1C,WAAW,EAAE,WAAW,CAAC;IACzB,mHAAmH;IACnH,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB;;;OAGG;IACH,WAAW,EAAE,gBAAgB,GAAG,SAAS,CAAC;CAC3C,CAAC"}

package/dest/contract/contract_sync_service.js

@@ -0,0 +1,210 @@
+import { allToCompletion } from '@aztec-labs/foundation/promise';
+import { Semaphore } from '@aztec-labs/foundation/queue';
+import { isProtocolContract } from '@aztec-labs/protocol-contracts';
+import { FunctionSelector } from '@aztec-labs/stdlib/abi';
+import { NoteService } from '../notes/note_service.js';
+import { ContractCallGraph, toCallKey } from './contract_call_graph.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.
+ *
+ * Contributes to every synced operation (see {@link OperationContributor}): its syncs write into the operation's change
+ * set, so it settles them before the change set is decided and releases its per-change-set state on the outcome.
+ */ export class ContractSyncService {
+    aztecNode;
+    contractStore;
+    contractClassService;
+    noteStore;
+    log;
+    // 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.
+    syncedContracts;
+    // Per-change-set speculation state, dropped when the change set commits or discards.
+    speculationByChangeSet;
+    // Predicts a function's callees from the calls observed in past operations, driving speculative sync.
+    callGraph;
+    constructor(aztecNode, contractStore, contractClassService, noteStore, log, { concurrentContractSyncEnabled }){
+        this.aztecNode = aztecNode;
+        this.contractStore = contractStore;
+        this.contractClassService = contractClassService;
+        this.noteStore = noteStore;
+        this.log = log;
+        this.syncedContracts = new Map();
+        this.speculationByChangeSet = new Map();
+        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, changeSetId, scopes, triggeredBy }) {
+        // 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({
+                changeSetId,
+                caller: triggeredBy,
+                callee: {
+                    address: contract,
+                    selector: functionToInvokeAfterSync
+                }
+            });
+        }
+        await this.#startSyncIfNeeded(contract, functionToInvokeAfterSync, utilityExecutor, anchorBlockHeader, changeSetId, scopes);
+    }
+    /**
+   * Waits until every speculative sync the change set fired has finished, then rejects if any failed, so the change set
+   * 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(changeSetId) {
+        // 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.#speculationForChangeSet(changeSetId);
+        const failures = [];
+        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 operation must discard its staged writes instead of committing');
+        }
+    }
+    /** Clears sync cache entries for the given scopes of a contract. */ invalidateContractForScopes(contractAddress, scopes) {
+        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() {
+        this.log.debug(`Wiping contract sync cache (${this.syncedContracts.size} entries)`);
+        this.syncedContracts.clear();
+    }
+    onOperationEnd(changeSetId, outcome) {
+        if (outcome === 'committed') {
+            this.callGraph.learn(changeSetId);
+        } else {
+            // We clear the synced contracts cache here because, when the change set is discarded, any associated database
+            // writes from the sync are also undone.
+            this.syncedContracts.clear();
+            this.callGraph.discard(changeSetId);
+        }
+        this.speculationByChangeSet.delete(changeSetId);
+    }
+    /**
+   * 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 change set's {@link settle}.
+   */ async #startSyncIfNeeded(contractAddress, functionToInvokeAfterSync, utilityExecutor, anchorBlockHeader, changeSetId, scopes) {
+        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, changeSetId, 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, changeSetId, scopes);
+        this.#speculativelySync(contractAddress, functionToInvokeAfterSync, utilityExecutor, anchorBlockHeader, changeSetId, 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 operation already makes, and
+   * the synced data simply goes unused.
+   */ #speculativelySync(contractAddress, functionToInvokeAfterSync, utilityExecutor, anchorBlockHeader, changeSetId, scopes) {
+        // Without a function there is no key to predict from (the request is a direct read).
+        if (!functionToInvokeAfterSync) {
+            return;
+        }
+        const speculation = this.#speculationForChangeSet(changeSetId);
+        const caller = {
+            address: contractAddress,
+            selector: functionToInvokeAfterSync
+        };
+        for (const callee of this.callGraph.predictDirectCallees(caller)){
+            // The change set'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, changeSetId, scopes);
+            speculation.syncs.push(syncPromise);
+            // `settle` only escalates these failures at the end of the change set: 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`, {
+                    changeSetId,
+                    error: err?.message
+                });
+            });
+        }
+    }
+    /** Syncs note nullifiers across all unsynced scopes in a single batched call. */ async #syncNoteNullifiers(contractAddress, anchorBlockHeader, changeSetId, scopes) {
+        // 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, changeSetId);
+        await noteService.syncNoteNullifiers(contractAddress, scopes);
+    }
+    #speculationForChangeSet(changeSetId) {
+        let speculation = this.speculationByChangeSet.get(changeSetId);
+        if (!speculation) {
+            speculation = {
+                speculated: new Set(),
+                syncs: []
+            };
+            this.speculationByChangeSet.set(changeSetId, speculation);
+        }
+        return speculation;
+    }
+    /** Collects all relevant scope promises (including in-flight ones from concurrent calls) and awaits them. */ async #awaitSync(contractAddress, scopes) {
+        const promises = scopes.map((scope)=>this.syncedContracts.get(toKey(contractAddress, scope))).filter((p)=>p !== undefined);
+        await allToCompletion(promises);
+    }
+}
+function toKey(contract, scope) {
+    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(syncSlot, fn) {
+    await syncSlot.acquire();
+    try {
+        return await fn();
+    } finally{
+        syncSlot.release();
+    }
+}

package/dest/contract/helpers.d.ts

@@ -0,0 +1,7 @@
+import type { FunctionCall, FunctionSelector } from '@aztec-labs/stdlib/abi';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { BlockHeader } from '@aztec-labs/stdlib/tx';
+import type { ContractStore } from '../storage/contract_store/contract_store.js';
+import type { ContractClassService } from './contract_class_service.js';
+export declare function syncScope(contractAddress: AztecAddress, contractStore: ContractStore, contractClassService: ContractClassService, anchorBlockHeader: BlockHeader, functionToInvokeAfterSync: FunctionSelector | null, utilityExecutor: (privateSyncCall: FunctionCall, scopes: AztecAddress[]) => Promise<any>, scope: AztecAddress): Promise<void>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaGVscGVycy5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2NvbnRyYWN0L2hlbHBlcnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsWUFBWSxFQUFFLGdCQUFnQixFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFDN0UsT0FBTyxLQUFLLEVBQUUsWUFBWSxFQUFFLE1BQU0sa0NBQWtDLENBQUM7QUFDckUsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFFekQsT0FBTyxLQUFLLEVBQUUsYUFBYSxFQUFFLE1BQU0sNkNBQTZDLENBQUM7QUFDakYsT0FBTyxLQUFLLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUd4RSx3QkFBc0IsU0FBUyxDQUM3QixlQUFlLEVBQUUsWUFBWSxFQUM3QixhQUFhLEVBQUUsYUFBYSxFQUM1QixvQkFBb0IsRUFBRSxvQkFBb0IsRUFDMUMsaUJBQWlCLEVBQUUsV0FBVyxFQUM5Qix5QkFBeUIsRUFBRSxnQkFBZ0IsR0FBRyxJQUFJLEVBQ2xELGVBQWUsRUFBRSxDQUFDLGVBQWUsRUFBRSxZQUFZLEVBQUUsTUFBTSxFQUFFLFlBQVksRUFBRSxLQUFLLE9BQU8sQ0FBQyxHQUFHLENBQUMsRUFDeEYsS0FBSyxFQUFFLFlBQVksaUJBbUJwQiJ9

package/dest/contract/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/contract/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGxE,wBAAsB,SAAS,CAC7B,eAAe,EAAE,YAAY,EAC7B,aAAa,EAAE,aAAa,EAC5B,oBAAoB,EAAE,oBAAoB,EAC1C,iBAAiB,EAAE,WAAW,EAC9B,yBAAyB,EAAE,gBAAgB,GAAG,IAAI,EAClD,eAAe,EAAE,CAAC,eAAe,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACxF,KAAK,EAAE,YAAY,iBAmBpB"}

package/dest/contract/helpers.js

@@ -0,0 +1,20 @@
+import { isSkipSyncContract } from './skip_sync_contracts.js';
+export async function syncScope(contractAddress, contractStore, contractClassService, anchorBlockHeader, functionToInvokeAfterSync, utilityExecutor, scope) {
+    // 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/dest/contract/skip_sync_contracts.d.ts

@@ -0,0 +1,11 @@
+import type { AztecAddress } from '@aztec-labs/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 declare const skipSyncContracts: AztecAddress[];
+/** Returns whether the given contract should be skipped during private state synchronization. */
+export declare function isSkipSyncContract(address: AztecAddress): boolean;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2tpcF9zeW5jX2NvbnRyYWN0cy5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2NvbnRyYWN0L3NraXBfc3luY19jb250cmFjdHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBSUEsT0FBTyxLQUFLLEVBQUUsWUFBWSxFQUFFLE1BQU0sa0NBQWtDLENBQUM7QUFFckU7Ozs7O0dBS0c7QUFDSCxlQUFPLE1BQU0saUJBQWlCLEVBQUUsWUFBWSxFQUszQyxDQUFDO0FBRUYsaUdBQWlHO0FBQ2pHLHdCQUFnQixrQkFBa0IsQ0FBQyxPQUFPLEVBQUUsWUFBWSxHQUFHLE9BQU8sQ0FFakUifQ==

package/dest/contract/skip_sync_contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skip_sync_contracts.d.ts","sourceRoot":"","sources":["../../src/contract/skip_sync_contracts.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAAY,EAK3C,CAAC;AAEF,iGAAiG;AACjG,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAEjE"}

package/dest/contract/skip_sync_contracts.js

@@ -0,0 +1,18 @@
+import { ProtocolContractAddress } from '@aztec-labs/protocol-contracts';
+import { STANDARD_AUTH_REGISTRY_ADDRESS } from '@aztec-labs/standard-contracts/auth-registry/constants';
+import { STANDARD_MULTI_CALL_ENTRYPOINT_ADDRESS } from '@aztec-labs/standard-contracts/multi-call-entrypoint/constants';
+import { STANDARD_PUBLIC_CHECKS_ADDRESS } from '@aztec-labs/standard-contracts/public-checks/constants';
+/**
+ * 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 = [
+    ...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) {
+    return skipSyncContracts.some((a)=>a.equals(address));
+}

package/dest/contract_function_simulator/anchored_contract_data.d.ts

@@ -0,0 +1,36 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { FunctionArtifactWithContractName, FunctionSelector } from '@aztec-labs/stdlib/abi';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { ContractInstancePreimageWithAddress } from '@aztec-labs/stdlib/contract';
+import type { BlockHeader, ContractOverrides } from '@aztec-labs/stdlib/tx';
+import type { ContractClassService } from '../contract/contract_class_service.js';
+import type { ContractStore } from '../storage/contract_store/contract_store.js';
+/**
+ * Per-run view of contract data for a single simulation, bound to its anchor block.
+ *
+ * The {@link ContractStore} is pure class-id-keyed storage and has no notion of which class an address runs. This
+ * class bridges that gap: it resolves an address to its current class id (via the {@link ContractClassService}
+ * at the run's anchor block) and then serves artifacts from the store. It is also the single place contract
+ * overrides are applied — when an address is overridden, both its instance and its class id come from the override
+ * rather than the chain, so a simulation can execute different bytecode at that address. Overrides are only set for
+ * `simulateTx` (which skips the kernels), so the override path never reaches proving.
+ */
+export declare class AnchoredContractData {
+    private readonly store;
+    private readonly contractClassService;
+    private readonly anchorBlockHeader;
+    private readonly overrides?;
+    constructor(store: ContractStore, contractClassService: ContractClassService, anchorBlockHeader: BlockHeader, overrides?: ContractOverrides | undefined);
+    /** Returns the address preimage of the instance at `address`, from the override if any, else from storage. */
+    getContractInstance(address: AztecAddress): Promise<ContractInstancePreimageWithAddress | undefined>;
+    /**
+     * Resolves the class id `address` runs in this simulation: the override's class if overridden, else resolved against
+     * the chain at the anchor block.
+     */
+    getCurrentClassId(address: AztecAddress): Promise<Fr | undefined>;
+    getFunctionArtifact(address: AztecAddress, selector: FunctionSelector): Promise<FunctionArtifactWithContractName | undefined>;
+    getFunctionArtifactWithDebugMetadata(address: AztecAddress, selector: FunctionSelector): Promise<FunctionArtifactWithContractName | undefined>;
+    getDebugContractName(address: AztecAddress): Promise<string | undefined>;
+    getDebugFunctionName(address: AztecAddress, selector: FunctionSelector): Promise<string>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYW5jaG9yZWRfY29udHJhY3RfZGF0YS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2NvbnRyYWN0X2Z1bmN0aW9uX3NpbXVsYXRvci9hbmNob3JlZF9jb250cmFjdF9kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLEVBQUUsRUFBRSxNQUFNLHFDQUFxQyxDQUFDO0FBQzlELE9BQU8sS0FBSyxFQUFFLGdDQUFnQyxFQUFFLGdCQUFnQixFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFDakcsT0FBTyxLQUFLLEVBQUUsWUFBWSxFQUFFLE1BQU0sa0NBQWtDLENBQUM7QUFDckUsT0FBTyxLQUFLLEVBQUUsbUNBQW1DLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUN2RixPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUU1RSxPQUFPLEtBQUssRUFBRSxvQkFBb0IsRUFBRSxNQUFNLHVDQUF1QyxDQUFDO0FBQ2xGLE9BQU8sS0FBSyxFQUFFLGFBQWEsRUFBRSxNQUFNLDZDQUE2QyxDQUFDO0FBRWpGOzs7Ozs7Ozs7R0FTRztBQUNILHFCQUFhLG9CQUFvQjtJQUU3QixPQUFPLENBQUMsUUFBUSxDQUFDLEtBQUs7SUFDdEIsT0FBTyxDQUFDLFFBQVEsQ0FBQyxvQkFBb0I7SUFDckMsT0FBTyxDQUFDLFFBQVEsQ0FBQyxpQkFBaUI7SUFDbEMsT0FBTyxDQUFDLFFBQVEsQ0FBQyxTQUFTLENBQUM7SUFKN0IsWUFDbUIsS0FBSyxFQUFFLGFBQWEsRUFDcEIsb0JBQW9CLEVBQUUsb0JBQW9CLEVBQzFDLGlCQUFpQixFQUFFLFdBQVcsRUFDOUIsU0FBUyxDQUFDLCtCQUFtQixFQUM1QztJQUVKLDhHQUE4RztJQUM5RyxtQkFBbUIsQ0FBQyxPQUFPLEVBQUUsWUFBWSxHQUFHLE9BQU8sQ0FBQyxtQ0FBbUMsR0FBRyxTQUFTLENBQUMsQ0FNbkc7SUFFRDs7O09BR0c7SUFDSCxpQkFBaUIsQ0FBQyxPQUFPLEVBQUUsWUFBWSxHQUFHLE9BQU8sQ0FBQyxFQUFFLEdBQUcsU0FBUyxDQUFDLENBTWhFO0lBRUssbUJBQW1CLENBQ3ZCLE9BQU8sRUFBRSxZQUFZLEVBQ3JCLFFBQVEsRUFBRSxnQkFBZ0IsR0FDekIsT0FBTyxDQUFDLGdDQUFnQyxHQUFHLFNBQVMsQ0FBQyxDQUd2RDtJQUVLLG9DQUFvQyxDQUN4QyxPQUFPLEVBQUUsWUFBWSxFQUNyQixRQUFRLEVBQUUsZ0JBQWdCLEdBQ3pCLE9BQU8sQ0FBQyxnQ0FBZ0MsR0FBRyxTQUFTLENBQUMsQ0FHdkQ7SUFFSyxvQkFBb0IsQ0FBQyxPQUFPLEVBQUUsWUFBWSxHQUFHLE9BQU8sQ0FBQyxNQUFNLEdBQUcsU0FBUyxDQUFDLENBRzdFO0lBRUssb0JBQW9CLENBQUMsT0FBTyxFQUFFLFlBQVksRUFBRSxRQUFRLEVBQUUsZ0JBQWdCLEdBQUcsT0FBTyxDQUFDLE1BQU0sQ0FBQyxDQUc3RjtDQUNGIn0=