@aztec/pxe 5.0.0-rc.2 → 5.0.0

package/src/contract_function_simulator/aztec_node_read_cache.ts

@@ -0,0 +1,89 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { BlockHash, BlockParameter } from '@aztec/stdlib/block';
+import type { AztecNode } from '@aztec/stdlib/interfaces/server';
+import type { TxHash } from '@aztec/stdlib/tx';
+
+/**
+ * Per-execution cache for immutable Aztec node reads.
+ */
+export class AztecNodeReadCache {
+  private readonly cache = new Map<string, Promise<unknown>>();
+
+  constructor(private readonly aztecNode: AztecNode) {}
+
+  /** Fetches a block without reissuing the same node request. */
+  public getBlock(block: BlockParameter) {
+    return this.#cachedRead(`block:${this.#keyPart(block)}`, () => this.aztecNode.getBlock(block));
+  }
+
+  /** Fetches a transaction receipt with its effect attached. */
+  public getTxReceiptWithEffect(txHash: TxHash) {
+    return this.#cachedRead(`tx-receipt-with-effect:${txHash.toString()}`, () =>
+      this.aztecNode.getTxReceipt(txHash, { includeTxEffect: true } as const),
+    );
+  }
+
+  /** Fetches an archive-tree witness for a block hash. */
+  public getBlockHashMembershipWitness(referenceBlock: BlockParameter, blockHash: BlockHash) {
+    return this.#cachedRead(
+      `block-hash-membership-witness:${this.#keyPart(referenceBlock)}:${blockHash.toString()}`,
+      () => this.aztecNode.getBlockHashMembershipWitness(referenceBlock, blockHash),
+    );
+  }
+
+  /** Fetches a public-data-tree witness for a leaf slot. */
+  public getPublicDataWitness(referenceBlock: BlockParameter, leafSlot: Fr) {
+    return this.#cachedRead(`public-data-witness:${this.#keyPart(referenceBlock)}:${leafSlot.toString()}`, () =>
+      this.aztecNode.getPublicDataWitness(referenceBlock, leafSlot),
+    );
+  }
+
+  /** Fetches public storage for a single slot. */
+  public getPublicStorageAt(referenceBlock: BlockParameter, contractAddress: AztecAddress, storageSlot: Fr) {
+    return this.#cachedRead(
+      `public-storage:${this.#keyPart(referenceBlock)}:${contractAddress.toString()}:${storageSlot.toString()}`,
+      () => this.aztecNode.getPublicStorageAt(referenceBlock, contractAddress, storageSlot),
+    );
+  }
+
+  /** Fetches a contiguous public storage range, reusing cached reads for overlapping slots. */
+  public getPublicStorageRange(
+    referenceBlock: BlockParameter,
+    contractAddress: AztecAddress,
+    startStorageSlot: Fr,
+    numberOfElements: number,
+  ) {
+    const slots = Array(numberOfElements)
+      .fill(0)
+      .map((_, i) => new Fr(startStorageSlot.value + BigInt(i)));
+
+    return Promise.all(slots.map(storageSlot => this.getPublicStorageAt(referenceBlock, contractAddress, storageSlot)));
+  }
+
+  #cachedRead<T>(key: string, fetch: () => Promise<T>): Promise<T> {
+    const cached = this.cache.get(key);
+    if (cached) {
+      return cached as Promise<T>;
+    }
+
+    const promise = fetch();
+    promise.catch(() => this.cache.delete(key));
+    this.cache.set(key, promise);
+    return promise;
+  }
+
+  #keyPart(value: unknown): string {
+    if (['string', 'number', 'bigint', 'boolean'].includes(typeof value)) {
+      return String(value);
+    }
+    if (value && typeof value === 'object') {
+      const toString = (value as { toString?: () => string }).toString;
+      if (toString && toString !== Object.prototype.toString) {
+        return toString.call(value);
+      }
+      return JSON.stringify(value, (_key, nested) => (typeof nested === 'bigint' ? nested.toString() : nested));
+    }
+    return String(value);
+  }
+}

package/src/contract_function_simulator/contract_function_simulator.ts

@@ -19,6 +19,7 @@ import {
   MAX_PRIVATE_LOGS_PER_TX,
   MAX_TX_LIFETIME,
   PRIVATE_TX_L2_GAS_OVERHEAD,
+  PUBLIC_DATA_WRITE_LENGTH,
   PUBLIC_TX_L2_GAS_OVERHEAD,
   TX_DA_GAS_OVERHEAD,
 } from '@aztec/constants';
@@ -80,6 +81,7 @@ import { MerkleTreeId } from '@aztec/stdlib/trees';
 import {
   BlockHeader,
   CallContext,
+  type ContractOverrides,
   HashedValues,
   type OffchainEffect,
   PrivateExecutionResult,
@@ -90,7 +92,8 @@ import {
   getFinalMinRevertibleSideEffectCounter,
 } from '@aztec/stdlib/tx';
 
-import type { ContractSyncService } from '../contract_sync/contract_sync_service.js';
+import type { ContractClassService } from '../contract/contract_class_service.js';
+import type { ContractSyncService } from '../contract/contract_sync_service.js';
 import type { ExecutionHooks } from '../hooks/index.js';
 import type { TxResolverService } from '../messages/tx_resolver_service.js';
 import type { AddressStore } from '../storage/address_store/address_store.js';
@@ -104,6 +107,7 @@ import type { PrivateEventStore } from '../storage/private_event_store/private_e
 import type { RecipientTaggingStore } from '../storage/tagging_store/recipient_tagging_store.js';
 import type { SenderTaggingStore } from '../storage/tagging_store/sender_tagging_store.js';
 import type { TaggingSecretSourcesStore } from '../storage/tagging_store/tagging_secret_sources_store.js';
+import { AnchoredContractData } from './anchored_contract_data.js';
 import type { BenchmarkedNode } from './benchmarked_node.js';
 import { ExecutionNoteCache } from './execution_note_cache.js';
 import { ExecutionTaggingIndexCache } from './execution_tagging_index_cache.js';
@@ -131,6 +135,9 @@ export type ContractSimulatorRunOpts = {
 /** Args for ContractFunctionSimulator constructor. */
 export type ContractFunctionSimulatorArgs = {
   contractStore: ContractStore;
+  contractClassService: ContractClassService;
+  /** Per-simulation contract overrides. */
+  overrides?: ContractOverrides;
   noteStore: NoteStore;
   keyStore: KeyStore;
   addressStore: AddressStore;
@@ -154,6 +161,8 @@ export type ContractFunctionSimulatorArgs = {
 export class ContractFunctionSimulator {
   private readonly log: Logger;
   private readonly contractStore: ContractStore;
+  private readonly contractClassService: ContractClassService;
+  private readonly overrides: ContractOverrides | undefined;
   private readonly noteStore: NoteStore;
   private readonly keyStore: KeyStore;
   private readonly addressStore: AddressStore;
@@ -172,6 +181,8 @@ export class ContractFunctionSimulator {
 
   constructor(args: ContractFunctionSimulatorArgs) {
     this.contractStore = args.contractStore;
+    this.contractClassService = args.contractClassService;
+    this.overrides = args.overrides;
     this.noteStore = args.noteStore;
     this.keyStore = args.keyStore;
     this.addressStore = args.addressStore;
@@ -208,10 +219,23 @@ export class ContractFunctionSimulator {
 
     const contractAddress = request.origin;
 
-    const entryPointArtifact = await this.contractStore.getFunctionArtifactWithDebugMetadata(
+    const anchoredContractData = new AnchoredContractData(
+      this.contractStore,
+      this.contractClassService,
+      anchorBlockHeader,
+      this.overrides,
+    );
+
+    const entryPointArtifact = await anchoredContractData.getFunctionArtifactWithDebugMetadata(
       contractAddress,
       request.functionSelector,
     );
+    if (!entryPointArtifact) {
+      throw new Error(
+        `Cannot run function ${request.functionSelector} on ${contractAddress}: the contract is not registered. ` +
+          `Register it via wallet.registerContract(...).`,
+      );
+    }
 
     if (entryPointArtifact.functionType !== FunctionType.PRIVATE) {
       throw new Error(`Cannot run ${entryPointArtifact.functionType} function as private`);
@@ -239,6 +263,7 @@ export class ContractFunctionSimulator {
     const privateExecutionOracle = new PrivateExecutionOracle({
       argsHash: request.firstCallArgsHash,
       txContext: request.txContext,
+      txRequestSalt: request.salt,
       callContext,
       anchorBlockHeader,
       utilityExecutor: async (call, execScopes) => {
@@ -249,7 +274,7 @@ export class ContractFunctionSimulator {
       executionCache: HashedValuesCache.create(request.argsOfCalls),
       noteCache,
       taggingIndexCache,
-      contractStore: this.contractStore,
+      anchoredContractData,
       noteStore: this.noteStore,
       keyStore: this.keyStore,
       addressStore: this.addressStore,
@@ -289,8 +314,7 @@ export class ContractFunctionSimulator {
       );
       const simulatorTeardownTimer = new Timer();
 
-      noteCache.finish();
-      const firstNullifierHint = noteCache.getNonceGenerator();
+      const firstNullifier = noteCache.getNonceGenerator();
 
       const publicCallRequests = collectNested([executionResult], r =>
         r.publicInputs.publicCallRequests
@@ -313,9 +337,9 @@ export class ContractFunctionSimulator {
       }
 
       // Not to be confused with a PrivateCallExecutionResult. This is a superset
-      // of the PrivateCallExecutionResult, containing also firstNullifierHint
+      // of the PrivateCallExecutionResult, containing also firstNullifier
       // and publicFunctionsCalldata.
-      return new PrivateExecutionResult(executionResult, firstNullifierHint, publicFunctionsCalldata);
+      return new PrivateExecutionResult(executionResult, firstNullifier, publicFunctionsCalldata);
     } catch (err) {
       throw createSimulationError(err instanceof Error ? err : new Error('Unknown error during private execution'));
     }
@@ -333,7 +357,20 @@ export class ContractFunctionSimulator {
     scopes: AztecAddress[],
     jobId: string,
   ): Promise<{ result: Fr[]; offchainEffects: OffchainEffect[] }> {
-    const entryPointArtifact = await this.contractStore.getFunctionArtifactWithDebugMetadata(call.to, call.selector);
+    const anchoredContractData = new AnchoredContractData(
+      this.contractStore,
+      this.contractClassService,
+      anchorBlockHeader,
+      this.overrides,
+    );
+
+    const entryPointArtifact = await anchoredContractData.getFunctionArtifactWithDebugMetadata(call.to, call.selector);
+    if (!entryPointArtifact) {
+      throw new Error(
+        `Cannot run function ${call.selector} on ${call.to}: the contract is not registered. ` +
+          `Register it via wallet.registerContract(...).`,
+      );
+    }
 
     if (entryPointArtifact.functionType !== FunctionType.UTILITY) {
       throw new Error(`Cannot run ${entryPointArtifact.functionType} function as utility`);
@@ -353,7 +390,7 @@ export class ContractFunctionSimulator {
       authWitnesses: authwits,
       capsules: [],
       anchorBlockHeader,
-      contractStore: this.contractStore,
+      anchoredContractData,
       noteStore: this.noteStore,
       keyStore: this.keyStore,
       addressStore: this.addressStore,
@@ -618,12 +655,12 @@ export async function generateSimulatedProvingResult(
     siloedNullifiers,
     minRevertibleSideEffectCounter,
   );
+  // The protocol nullifier is the nonce generator and the tx's first nullifier. It is injected by the
+  // init kernel (at counter 1, index 0) rather than emitted by any private call, so it is absent from
+  // the executed nullifiers above. Mirror the kernel here by prepending it as the first non-revertible
+  // nullifier.
   const nonceGenerator = privateExecutionResult.firstNullifier;
-  if (nonRevertibleNullifiers.length === 0) {
-    nonRevertibleNullifiers.push(nonceGenerator);
-  } else if (!nonRevertibleNullifiers[0].equals(nonceGenerator)) {
-    throw new Error('The first non revertible nullifier should be equal to the nonce generator. This is a bug!');
-  }
+  nonRevertibleNullifiers.unshift(nonceGenerator);
 
   if (isPrivateOnlyTx) {
     // We must make the note hashes unique by using the
@@ -886,6 +923,11 @@ function meterGasUsed(data: PrivateToRollupAccumulatedData | PrivateToPublicAccu
   );
   meteredL2Gas += numContractClassLogs * L2_GAS_PER_CONTRACT_CLASS_LOG;
 
+  if (isPrivateOnlyTx) {
+    // The public data write that the private tx base rollup always performs to update the fee payer's balance.
+    meteredDAFields += PUBLIC_DATA_WRITE_LENGTH;
+  }
+
   const meteredDAGas = meteredDAFields * DA_GAS_PER_FIELD;
 
   if ((data as PrivateToPublicAccumulatedData).publicCallRequests) {

package/src/contract_function_simulator/execution_note_cache.ts

@@ -43,12 +43,6 @@ export class ExecutionNoteCache {
 
   private inRevertiblePhase = false;
 
-  /**
-   * Whether the protocol nullifier was used for nonce generation.
-   * We don't need to use the protocol nullifier if a non-revertible nullifier is emitted.
-   */
-  private usedProtocolNullifierForNonces: boolean | undefined;
-
   constructor(private readonly protocolNullifier: Fr) {}
 
   /**
@@ -64,12 +58,9 @@ export class ExecutionNoteCache {
     this.inRevertiblePhase = true;
     this.minRevertibleSideEffectCounter = minRevertibleSideEffectCounter;
 
-    const nullifiers = this.getEmittedNullifiers();
-    // If there are no nullifiers emitted by private calls so far, we use the protocol nullifier as the nonce generator.
-    // Note: There could still be nullifiers emitted after the counter is set, but those nullifiers are revertible, so
-    // we don't want to use them as the nonce generator.
-    this.usedProtocolNullifierForNonces = nullifiers.length === 0;
-    const nonceGenerator = this.usedProtocolNullifierForNonces ? this.protocolNullifier : new Fr(nullifiers[0]);
+    // The protocol nullifier is always the tx's first nullifier (injected by the kernel init), so it is the
+    // nonce generator for every note hash.
+    const nonceGenerator = this.protocolNullifier;
 
     // The existing pending notes are all non-revertible.
     // They cannot be squashed by nullifiers emitted after minRevertibleSideEffectCounter is set.
@@ -102,14 +93,6 @@ export class ExecutionNoteCache {
     return sideEffectCounter >= this.minRevertibleSideEffectCounter;
   }
 
-  public finish() {
-    // If we never entered the revertible phase, and there are no nullifiers emitted, we need to use the protocol
-    // nullifier as the nonce generator.
-    if (!this.inRevertiblePhase) {
-      this.usedProtocolNullifierForNonces = this.getEmittedNullifiers().length === 0;
-    }
-  }
-
   /**
    * Add a new note to cache.
    * @param note - New note created during execution.
@@ -223,19 +206,15 @@ export class ExecutionNoteCache {
   }
 
   /**
-   * @returns All nullifiers emitted by private calls in this transaction. If the protocol nullifier was used as the
-   * nonce generator, it is injected as the first nullifier.
+   * @returns All nullifiers of the transaction: the protocol nullifier (the kernel-injected first nullifier),
+   * followed by those emitted by private calls.
    */
   getAllNullifiers(): Fr[] {
-    if (this.usedProtocolNullifierForNonces === undefined) {
-      throw new Error('usedProtocolNullifierForNonces is not set yet. Call finish() to complete the transaction.');
-    }
-    const allNullifiers = this.getEmittedNullifiers();
-    return [...(this.usedProtocolNullifierForNonces ? [this.protocolNullifier] : []), ...allNullifiers];
+    return [this.protocolNullifier, ...this.getEmittedNullifiers()];
   }
 
   getNonceGenerator(): Fr {
-    return this.getAllNullifiers()[0];
+    return this.protocolNullifier;
   }
 
   #recordNullifier(contractAddress: AztecAddress, siloedNullifier: bigint) {

package/src/contract_function_simulator/index.ts

@@ -21,23 +21,27 @@ export {
   ETH_ADDRESS,
   EVENT_VALIDATION_REQUEST,
   FIELD,
+  FIXED_ARRAY,
   FUNCTION_SELECTOR,
   LOG_RETRIEVAL_REQUEST,
   LOG_RETRIEVAL_RESPONSE,
   MEMBERSHIP_WITNESS,
-  MESSAGE_CONTEXT,
   NOTE_SELECTOR,
   NOTE_VALIDATION_REQUEST,
   OPTION,
   PENDING_TAGGED_LOG,
   POINT,
   PROVIDED_SECRET,
+  SLOT_NUMBER,
   STR,
+  STRUCT,
   U32,
+  tryFieldWidth,
   type InputSlot,
   type MaybePromise,
   type OutputSlot,
   type SlotShape,
+  type StructField,
   type TypeMapping,
 } from './oracle/oracle_type_mappings.js';
 export { ExecutionNoteCache } from './execution_note_cache.js';
@@ -53,6 +57,7 @@ export { TxResolverService } from '../messages/tx_resolver_service.js';
 export { UtilityExecutionOracle } from './oracle/utility_execution_oracle.js';
 export { PrivateExecutionOracle } from './oracle/private_execution_oracle.js';
 export { buildACIRCallback, UnavailableOracleError } from './oracle/acir_callback.js';
+export { LEGACY_ORACLE_REGISTRY } from './oracle/legacy_oracle_registry.js';
 export { executePrivateFunction, extractPrivateCircuitPublicInputs } from './oracle/private_execution.js';
 export { generateSimulatedProvingResult } from './contract_function_simulator.js';
 export { packAsHintedNote } from './oracle/note_packing_utils.js';
@@ -66,6 +71,7 @@ export { EventValidationRequest } from './noir-structs/event_validation_request.
 export type { LogRetrievalRequest } from './noir-structs/log_retrieval_request.js';
 export type { LogRetrievalResponse } from './noir-structs/log_retrieval_response.js';
 export { NoteValidationRequest } from './noir-structs/note_validation_request.js';
+export type { PendingTaggedLog } from './noir-structs/pending_tagged_log.js';
 export type { TxEffectData } from './noir-structs/tx_effect_data.js';
 export type { ProvidedSecret } from './noir-structs/provided_secret.js';
 export { ResolvedTx } from './noir-structs/resolved_tx.js';

package/src/contract_function_simulator/noir-structs/fact.ts

@@ -1,13 +1,13 @@
 import type { Fr } from '@aztec/foundation/curves/bn254';
 
+import type { RetractableFactOrigin } from '../../storage/fact_store/index.js';
 import type { EphemeralArray } from './ephemeral_array.js';
 import type { Option } from './option.js';
-import type { OriginBlock } from './origin_block.js';
 
 /**
  * A single fact returned within a fact collection by the fact store oracles.
  *
- * A TS version of the `Fact` struct in `facts/mod.nr`. `originBlock` is `Some` for a retractable fact (pruned on
- * reorg of that block) and `None` for a non-retractable one.
+ * A TS version of the `Fact` struct in `facts/mod.nr`. `originBlock` is `Some` for a retractable fact (carrying its
+ * origin block's current chain state) and `None` for a non-retractable one.
  */
-export type Fact = { factTypeId: Fr; payload: EphemeralArray<Fr>; originBlock: Option<OriginBlock> };
+export type Fact = { factTypeId: Fr; payload: EphemeralArray<Fr>; originBlock: Option<RetractableFactOrigin> };

package/src/contract_function_simulator/noir-structs/fact_collection.ts

@@ -1,7 +1,8 @@
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 
-import type { Fact as FactFromStore, OriginBlock } from '../../storage/fact_store/index.js';
+import type { FactWithOriginState, RetractableFactOrigin } from '../../storage/fact_store/index.js';
+import { OriginBlockState } from '../../storage/fact_store/index.js';
 import type { EphemeralArrayService } from '../ephemeral_array_service.js';
 import { EphemeralArray } from './ephemeral_array.js';
 import type { Fact } from './fact.js';
@@ -27,7 +28,7 @@ export function toNoirFactCollection(
   scope: AztecAddress,
   factCollectionTypeId: Fr,
   factCollectionId: Fr,
-  facts: FactFromStore[],
+  facts: FactWithOriginState[],
 ): FactCollection {
   return {
     contractAddress,
@@ -37,12 +38,16 @@ export function toNoirFactCollection(
     facts: EphemeralArray.fromValues(
       service,
       facts.map(
-        (fact: FactFromStore): Fact => ({
+        (fact: FactWithOriginState): Fact => ({
           factTypeId: fact.factTypeId,
           payload: EphemeralArray.fromValues(service, fact.payload),
           originBlock: fact.originBlock
             ? Option.some(fact.originBlock)
-            : Option.none<OriginBlock>({ blockNumber: 0, blockHash: Fr.ZERO }),
+            : Option.none<RetractableFactOrigin>({
+                blockNumber: 0,
+                blockHash: Fr.ZERO,
+                blockState: OriginBlockState.Pending,
+              }),
         }),
       ),
     ),

package/src/contract_function_simulator/noir-structs/log_retrieval_response.ts

@@ -1,5 +1,8 @@
+import type { BlockNumber } from '@aztec/foundation/branded-types';
 import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { BlockHash } from '@aztec/stdlib/block';
 import type { TxHash } from '@aztec/stdlib/tx';
+import type { UInt64 } from '@aztec/stdlib/types';
 
 /**
  * Intermediate struct used to perform batch log retrieval by PXE. The `utilityBulkRetrieveLogs` oracle stores values of this
@@ -10,4 +13,7 @@ export type LogRetrievalResponse = {
   txHash: TxHash;
   uniqueNoteHashesInTx: Fr[];
   firstNullifierInTx: Fr;
+  blockNumber: BlockNumber;
+  blockTimestamp: UInt64;
+  blockHash: BlockHash;
 };

package/src/contract_function_simulator/noir-structs/pending_tagged_log.ts

@@ -0,0 +1,12 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+
+import type { ResolvedTx } from './resolved_tx.js';
+
+/**
+ * Represents a pending tagged log as it is stored in the pending tagged log array to which the fetchTaggedLogs oracle
+ * inserts found private logs. A TS version of `pending_tagged_log.nr`.
+ */
+export type PendingTaggedLog = {
+  log: Fr[];
+  context: ResolvedTx;
+};

package/src/contract_function_simulator/noir-structs/provided_secret.ts

@@ -1,5 +1,5 @@
 import type { Fr } from '@aztec/foundation/curves/bn254';
 import type { AppTaggingSecretKind } from '@aztec/stdlib/logs';
 
-/** A tagging secret an app supplies explicitly to `getPendingTaggedLogs` when PXE cannot derive it internally. */
+/** A tagging secret an app supplies explicitly to `getPendingTaggedLogsV2` when PXE cannot derive it internally. */
 export type ProvidedSecret = { secret: Fr; mode: AppTaggingSecretKind };

package/src/contract_function_simulator/noir-structs/resolved_tagging_strategy.ts

@@ -3,6 +3,7 @@ import { Fr } from '@aztec/foundation/curves/bn254';
 // Keep in sync with aztec::messages::delivery::ResolvedTaggingStrategy
 const NON_INTERACTIVE_HANDSHAKE = 1;
 const UNCONSTRAINED_SECRET = 2;
+const INTERACTIVE_HANDSHAKE = 3;
 
 /**
  * The tagging secret PXE hands to the contract after applying the wallet's {@link TaggingSecretStrategy} choice
@@ -13,6 +14,14 @@ export type ResolvedTaggingStrategy =
       /** A non-interactive handshake: the recipient re-derives the secret from the onchain handshake registry. */
       type: 'non-interactive-handshake';
     }
+  | {
+      /**
+       * An interactive handshake: the registry obtains the recipient's signed authorization through the custom
+       * request oracle, and the recipient learns the secret while signing. Nothing announcing the handshake is
+       * published onchain.
+       */
+      type: 'interactive-handshake';
+    }
   | {
       /**
        * An app-siloed, recipient-directional secret, ready to use. Only sound for unconstrained delivery.
@@ -29,6 +38,8 @@ export function resolvedTaggingStrategyToFields(resolved: ResolvedTaggingStrateg
       return [new Fr(NON_INTERACTIVE_HANDSHAKE), Fr.ZERO];
     case 'unconstrained-secret':
       return [new Fr(UNCONSTRAINED_SECRET), resolved.secret];
+    case 'interactive-handshake':
+      return [new Fr(INTERACTIVE_HANDSHAKE), Fr.ZERO];
   }
 }
 
@@ -36,10 +47,20 @@ export function resolvedTaggingStrategyToFields(resolved: ResolvedTaggingStrateg
 export function resolvedTaggingStrategyFromFields(kind: number, secret: Fr): ResolvedTaggingStrategy {
   switch (kind) {
     case NON_INTERACTIVE_HANDSHAKE:
+      assertAbsentSecret(kind, secret);
       return { type: 'non-interactive-handshake' };
+    case INTERACTIVE_HANDSHAKE:
+      assertAbsentSecret(kind, secret);
+      return { type: 'interactive-handshake' };
     case UNCONSTRAINED_SECRET:
       return { type: 'unconstrained-secret', secret };
     default:
       throw new Error(`Unrecognized resolved tagging strategy kind: ${kind}`);
   }
 }
+
+function assertAbsentSecret(kind: number, secret: Fr): void {
+  if (!secret.isZero()) {
+    throw new Error(`Resolved tagging strategy ${kind} must not include a secret`);
+  }
+}

package/src/contract_function_simulator/oracle/acir_callback.ts

@@ -2,7 +2,8 @@ import type { ACIRCallback, ACVMField } from '@aztec/simulator/client';
 
 import { ORACLE_VERSION_MAJOR, ORACLE_VERSION_MINOR } from '../../oracle_version.js';
 import type { IMiscOracle, IPrivateExecutionOracle, IUtilityExecutionOracle } from './interfaces.js';
-import { ORACLE_REGISTRY } from './oracle_registry.js';
+import { LEGACY_ORACLE_REGISTRY, type LegacyOracleEntry } from './legacy_oracle_registry.js';
+import { type NamedValue, ORACLE_REGISTRY, type OracleRegistryEntry, makeEntry } from './oracle_registry.js';
 
 export class UnavailableOracleError extends Error {
   constructor(oracleName: string) {
@@ -17,26 +18,71 @@ export class UnavailableOracleError extends Error {
  * `aztec_{scope}_{methodName}` convention to resolve the handler, and calling the method directly. Unknown oracle
  * names produce enhanced error messages based on the contract's oracle version.
  */
-export function buildACIRCallback(handler: OracleHandler): ACIRCallback {
+export function buildACIRCallback(
+  handler: OracleHandler,
+  registries: {
+    real?: Record<string, OracleRegistryEntry>;
+    legacy?: Record<string, LegacyOracleEntry>;
+  } = {},
+): ACIRCallback {
+  const { real = ORACLE_REGISTRY, legacy: legacyRegistry = LEGACY_ORACLE_REGISTRY } = registries;
   const target = {} as ACIRCallback;
-  for (const [oracleKey, entry] of Object.entries(ORACLE_REGISTRY)) {
-    const match = oracleKey.match(/^aztec_(\w+?)_(.+)$/);
-    if (!match) {
-      throw new Error(`Oracle "${oracleKey}" does not follow the aztec_{scope}_{method} convention`);
-    }
-    const [, scope, methodName] = match;
+  for (const [oracleKey, entry] of Object.entries(real)) {
+    const { scope, methodName } = parseOracleName(oracleKey, 'Oracle');
     target[oracleKey] = async (...inputs: ACVMField[][]) => {
       assertHandlerSupportsScope(handler, scope);
       const named = entry.deserializeParams(inputs);
-      const positional = named.map(p => p.value);
+      const positional = named.map((p: NamedValue) => p.value);
       const result = await (handler as any)[methodName](...positional);
       return entry.serializeReturn(result);
     };
   }
 
-  return new Proxy(target, {
+  // Legacy oracle names: served for contracts compiled against a retired oracle version. Each reuses the current
+  // handler of its `modernOracle` and reshapes the wire (params and/or return) back to what the old bytecode expects.
+  for (const [legacyKey, legacy] of Object.entries(legacyRegistry)) {
+    const { scope } = parseOracleName(legacyKey, 'Legacy oracle');
+    if (legacyKey in target) {
+      throw new Error(`Legacy oracle "${legacyKey}" collides with a live oracle of the same name in the registry`);
+    }
+    const modernEntry = real[legacy.modernOracle];
+    const { methodName } = parseOracleName(legacy.modernOracle, 'Oracle');
+    // Override only the side whose wire changed; inherit the other from the modern entry.
+    const paramOverride = legacy.params;
+    const paramSource = paramOverride ? makeEntry({ params: [...paramOverride.legacyType] }) : modernEntry;
+    const returnOverride = legacy.returnType;
+    const returnSource = returnOverride ? makeEntry({ returnType: returnOverride.legacyType }) : modernEntry;
+    target[legacyKey] = async (...inputs: ACVMField[][]) => {
+      assertHandlerSupportsScope(handler, scope);
+      const legacyArgs = paramSource.deserializeParams(inputs).map(p => p.value);
+      const positional = paramOverride ? await paramOverride.mapping(legacyArgs) : legacyArgs;
+      const result = await (handler as any)[methodName](...positional);
+      return returnSource.serializeReturn(returnOverride ? returnOverride.mapping(result) : result);
+    };
+  }
+
+  return new Proxy(target, makeUnknownOracleTrap(handler));
+}
+
+/** Parses an `aztec_{scope}_{method}` oracle name into its parts, throwing if it doesn't follow the convention. */
+function parseOracleName(key: string, label: string): { scope: string; methodName: string } {
+  const match = key.match(/^aztec_(\w+?)_(.+)$/);
+  if (!match) {
+    throw new Error(`${label} "${key}" does not follow the aztec_{scope}_{method} convention`);
+  }
+  return { scope: match[1], methodName: match[2] };
+}
+
+/**
+ * Proxy trap for the callback table: a known oracle name passes through; an unknown one throws a diagnostic keyed on
+ * the contract's oracle version (version unknown, contract newer than this environment, or a same-version mismatch).
+ */
+function makeUnknownOracleTrap(handler: OracleHandler): ProxyHandler<ACIRCallback> {
+  return {
     get(obj, prop: string) {
-      if (prop in obj) {
+      // Own-property check only: `in` would match inherited `Object.prototype` keys (e.g. `constructor`, `toString`)
+      // and return the built-in instead of falling through to the unknown-oracle diagnostic below.
+      if (Object.hasOwn(obj, prop)) {
         return (obj as Record<string, unknown>)[prop];
       }
 
@@ -76,7 +122,7 @@ export function buildACIRCallback(handler: OracleHandler): ACIRCallback {
         }
       };
     },
-  });
+  };
 }
 
 type OracleHandler = IMiscOracle & (IUtilityExecutionOracle | IPrivateExecutionOracle);