@aztec/txe 0.0.1-commit.a072138 → 0.0.1-commit.a4600f49

package/src/oracle/txe_oracle_public_context.ts

@@ -1,9 +1,11 @@
 import { BlockNumber } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { type Logger, createLogger } from '@aztec/foundation/log';
+import type { ContractStore } from '@aztec/pxe/server';
 import { PublicDataWrite } from '@aztec/stdlib/avm';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import type { L2Block } from '@aztec/stdlib/block';
+import type { ContractInstancePreimageWithAddress } from '@aztec/stdlib/contract';
 import { computePublicDataTreeLeafSlot, siloNoteHash, siloNullifier } from '@aztec/stdlib/hash';
 import {
   MerkleTreeId,
@@ -29,6 +31,7 @@ export class TXEOraclePublicContext implements IAvmExecutionOracle {
     private forkedWorldTrees: MerkleTreeWriteOperations,
     private txRequestHash: Fr,
     private globalVariables: GlobalVariables,
+    private contractStore: ContractStore,
   ) {
     this.logger = createLogger('txe:public_context');
 
@@ -39,46 +42,46 @@ export class TXEOraclePublicContext implements IAvmExecutionOracle {
     });
   }
 
-  avmOpcodeAddress(): Promise<AztecAddress> {
+  address(): Promise<AztecAddress> {
     return Promise.resolve(this.contractAddress);
   }
 
-  avmOpcodeSender(): Promise<AztecAddress> {
+  sender(): Promise<AztecAddress> {
     return Promise.resolve(AztecAddress.ZERO); // todo: change?
   }
 
-  avmOpcodeBlockNumber(): Promise<BlockNumber> {
+  blockNumber(): Promise<BlockNumber> {
     return Promise.resolve(this.globalVariables.blockNumber);
   }
 
-  avmOpcodeTimestamp(): Promise<bigint> {
+  timestamp(): Promise<bigint> {
     return Promise.resolve(this.globalVariables.timestamp);
   }
 
-  avmOpcodeIsStaticCall(): Promise<boolean> {
+  isStaticCall(): Promise<boolean> {
     return Promise.resolve(false);
   }
 
-  avmOpcodeChainId(): Promise<Fr> {
+  chainId(): Promise<Fr> {
     return Promise.resolve(this.globalVariables.chainId);
   }
 
-  avmOpcodeVersion(): Promise<Fr> {
+  version(): Promise<Fr> {
     return Promise.resolve(this.globalVariables.version);
   }
 
-  async avmOpcodeEmitNullifier(nullifier: Fr) {
+  async emitNullifier(nullifier: Fr) {
     const siloedNullifier = await siloNullifier(this.contractAddress, nullifier);
     this.transientSiloedNullifiers.push(siloedNullifier);
   }
 
-  async avmOpcodeEmitNoteHash(noteHash: Fr) {
+  async emitNoteHash(noteHash: Fr) {
     const siloedNoteHash = await siloNoteHash(this.contractAddress, noteHash);
     // TODO: make the note hash unique - they are only siloed right now
     this.transientUniqueNoteHashes.push(siloedNoteHash);
   }
 
-  async avmOpcodeNullifierExists(siloedNullifier: Fr): Promise<boolean> {
+  async nullifierExists(siloedNullifier: Fr): Promise<boolean> {
     const treeIndex = (
       await this.forkedWorldTrees.findLeafIndices(MerkleTreeId.NULLIFIER_TREE, [siloedNullifier.toBuffer()])
     )[0];
@@ -87,7 +90,7 @@ export class TXEOraclePublicContext implements IAvmExecutionOracle {
     return treeIndex !== undefined || transientIndex !== undefined;
   }
 
-  async avmOpcodeStorageWrite(slot: Fr, value: Fr) {
+  async storageWrite(slot: Fr, value: Fr) {
     this.logger.debug('AVM storage write', { slot, value });
 
     const dataWrite = new PublicDataWrite(await computePublicDataTreeLeafSlot(this.contractAddress, slot), value);
@@ -99,7 +102,7 @@ export class TXEOraclePublicContext implements IAvmExecutionOracle {
     ]);
   }
 
-  async avmOpcodeStorageRead(slot: Fr, contractAddress: AztecAddress): Promise<Fr> {
+  async storageRead(slot: Fr, contractAddress: AztecAddress): Promise<Fr> {
     const leafSlot = await computePublicDataTreeLeafSlot(contractAddress, slot);
 
     const lowLeafResult = await this.forkedWorldTrees.getPreviousValueIndex(
@@ -122,6 +125,65 @@ export class TXEOraclePublicContext implements IAvmExecutionOracle {
     return value;
   }
 
+  getContractInstanceDeployer(address: AztecAddress): Promise<{ member: Fr; exists: boolean }[]> {
+    return this.getContractInstanceMember(address, i => i.deployer.toField());
+  }
+
+  getContractInstanceClassId(address: AztecAddress): Promise<{ member: Fr; exists: boolean }[]> {
+    // TXE has no contract updates, so the current class always equals the original.
+    return this.getContractInstanceMember(address, i => i.originalContractClassId);
+  }
+
+  getContractInstanceInitializationHash(address: AztecAddress): Promise<{ member: Fr; exists: boolean }[]> {
+    return this.getContractInstanceMember(address, i => i.initializationHash);
+  }
+
+  getContractInstanceImmutablesHash(address: AztecAddress): Promise<{ member: Fr; exists: boolean }[]> {
+    return this.getContractInstanceMember(address, i => i.immutablesHash);
+  }
+
+  // The one-element array mirrors the oracles' Noir return type, `[GetContractInstanceResult; 1]`.
+  private async getContractInstanceMember(
+    address: AztecAddress,
+    accessor: (instance: ContractInstancePreimageWithAddress) => Fr,
+  ): Promise<{ member: Fr; exists: boolean }[]> {
+    const instance = await this.contractStore.getContractInstance(address);
+    if (!instance) {
+      return [{ member: Fr.ZERO, exists: false }];
+    }
+    return [{ member: accessor(instance), exists: true }];
+  }
+
+  returndataSize(): Promise<number> {
+    throw new Error(
+      'Contract calls are forbidden inside a `TestEnvironment::public_context`, use `public_call` instead',
+    );
+  }
+
+  returndataCopy(_rdOffset: number, _copySize: number): Promise<Fr[]> {
+    throw new Error(
+      'Contract calls are forbidden inside a `TestEnvironment::public_context`, use `public_call` instead',
+    );
+  }
+
+  call(_l2Gas: number, _daGas: number, _address: AztecAddress, _argsLength: number, _args: Fr[]): Promise<void> {
+    throw new Error(
+      'Contract calls are forbidden inside a `TestEnvironment::public_context`, use `public_call` instead',
+    );
+  }
+
+  staticCall(_l2Gas: number, _daGas: number, _address: AztecAddress, _argsLength: number, _args: Fr[]): Promise<void> {
+    throw new Error(
+      'Contract calls are forbidden inside a `TestEnvironment::public_context`, use `public_call` instead',
+    );
+  }
+
+  successCopy(): Promise<boolean> {
+    throw new Error(
+      'Contract calls are forbidden inside a `TestEnvironment::public_context`, use `public_call` instead',
+    );
+  }
+
   async close(): Promise<L2Block> {
     this.logger.debug('Exiting Public Context, building block with collected side effects', {
       blockNumber: this.globalVariables.blockNumber,

package/src/oracle/txe_oracle_registry.ts

@@ -0,0 +1,536 @@
+/* eslint-disable camelcase */
+import {
+  GAS_SETTINGS_LENGTH,
+  MAX_NOTE_HASHES_PER_TX,
+  MAX_NULLIFIERS_PER_TX,
+  MAX_PRIVATE_LOGS_PER_TX,
+  PRIVATE_CONTEXT_INPUTS_LENGTH,
+  PRIVATE_LOG_SIZE_IN_FIELDS,
+} from '@aztec/constants';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { Point } from '@aztec/foundation/curves/grumpkin';
+import { withHexPrefix, withoutHexPrefix } from '@aztec/foundation/string';
+import type { TaggingSecretStrategy } from '@aztec/pxe/server';
+import {
+  ARRAY,
+  AZTEC_ADDRESS,
+  BIGINT,
+  BLOCK_NUMBER,
+  BOOL,
+  ETH_ADDRESS,
+  FIELD,
+  FIXED_ARRAY,
+  FUNCTION_SELECTOR,
+  type InputSlot,
+  type MaybePromise,
+  OPTION,
+  ORACLE_REGISTRY,
+  type OracleRegistryEntry,
+  type OutputSlot,
+  type ParamTypes,
+  STR,
+  STRUCT,
+  type SlotShape,
+  type TypeMapping,
+  U32,
+  buildACIRCallback,
+  makeEntry,
+} from '@aztec/pxe/simulator';
+import { EventSelector } from '@aztec/stdlib/abi';
+import { CompleteAddress } from '@aztec/stdlib/contract';
+import { GasSettings } from '@aztec/stdlib/gas';
+import { PrivateContextInputs } from '@aztec/stdlib/kernel';
+import type { PrivateLog } from '@aztec/stdlib/logs';
+import type { TxHash } from '@aztec/stdlib/tx';
+
+import {
+  MAX_OFFCHAIN_EFFECTS_PER_TXE_QUERY,
+  MAX_OFFCHAIN_EFFECT_LEN,
+  MAX_PRIVATE_EVENTS_PER_TXE_QUERY,
+  MAX_PRIVATE_EVENT_LEN,
+} from '../constants.js';
+import type { ForeignCallArgs, ForeignCallResult } from '../utils/encoding.js';
+
+// Spreading `ORACLE_REGISTRY` re-materializes its entries into `TXE_ORACLE_REGISTRY`'s inferred type, which names the
+// protocol types below. Re-exporting them gives tsc a portable path to each instead of falling back to a deep
+// node_modules path that breaks .d.ts portability (TS2742).
+export type { ContractClassLogData, EmbeddedCurvePoint, TxEffectData } from '@aztec/pxe/simulator';
+export type { BlockHash } from '@aztec/stdlib/block';
+export type { MembershipWitness } from '@aztec/foundation/trees';
+export type { NullifierMembershipWitness, PublicDataWitness } from '@aztec/stdlib/trees';
+
+const GAS_SETTINGS: TypeMapping<GasSettings> = {
+  deserialization: {
+    fn: ([reader]) => GasSettings.fromFields(reader.readFieldArray(GAS_SETTINGS_LENGTH)),
+  },
+  shape: [{ len: GAS_SETTINGS_LENGTH }],
+};
+
+// Tagging secret strategy discriminants. Must match the Noir test helper `TaggingSecretStrategy` in
+// aztec-nr `test/helpers/tagging_secret_strategy.nr`. This is a test-only oracle (only `set_tagging_secret_strategy`
+// reads it), so the mapping lives here on the TXE side rather than in the production oracle type mappings.
+const STRATEGY_NON_INTERACTIVE_HANDSHAKE = 1;
+const STRATEGY_ARBITRARY_SECRET = 2;
+const STRATEGY_ADDRESS_DERIVED = 3;
+const STRATEGY_INTERACTIVE_HANDSHAKE = 4;
+
+const TAGGING_SECRET_STRATEGY: TypeMapping<TaggingSecretStrategy> = {
+  serialization: {
+    fn: strategy => {
+      switch (strategy.type) {
+        case 'non-interactive-handshake':
+          return [new Fr(STRATEGY_NON_INTERACTIVE_HANDSHAKE), Fr.ZERO, Fr.ZERO];
+        case 'interactive-handshake':
+          return [new Fr(STRATEGY_INTERACTIVE_HANDSHAKE), Fr.ZERO, Fr.ZERO];
+        case 'address-derived':
+          return [new Fr(STRATEGY_ADDRESS_DERIVED), Fr.ZERO, Fr.ZERO];
+        case 'arbitrary-secret':
+          return [new Fr(STRATEGY_ARBITRARY_SECRET), strategy.secret.x, strategy.secret.y];
+      }
+    },
+  },
+  deserialization: {
+    fn: ([kindReader, xReader, yReader]) => {
+      const kind = kindReader.readField().toNumber();
+      const [x, y] = [xReader.readField(), yReader.readField()];
+      switch (kind) {
+        case STRATEGY_NON_INTERACTIVE_HANDSHAKE:
+          return { type: 'non-interactive-handshake' };
+        case STRATEGY_INTERACTIVE_HANDSHAKE:
+          return { type: 'interactive-handshake' };
+        case STRATEGY_ADDRESS_DERIVED:
+          return { type: 'address-derived' };
+        case STRATEGY_ARBITRARY_SECRET:
+          return { type: 'arbitrary-secret', secret: Point.fromFields([x, y]) };
+        default:
+          throw new Error(`Unrecognized tagging secret strategy kind: ${kind}`);
+      }
+    },
+  },
+  shape: ['scalar', 'scalar', 'scalar'],
+};
+
+const PRIVATE_CONTEXT_INPUTS: TypeMapping<PrivateContextInputs> = {
+  serialization: { fn: v => v.toFields() },
+  shape: Array<SlotShape>(PRIVATE_CONTEXT_INPUTS_LENGTH).fill('scalar'),
+};
+
+const COMPLETE_ADDRESS: TypeMapping<CompleteAddress> = {
+  serialization: { fn: v => [v.address.toField(), ...v.publicKeys.toFields()] },
+  shape: Array<SlotShape>(8).fill('scalar'), // address + 7 public-key fields
+};
+
+const TXE_TX_EFFECTS: TypeMapping<{
+  txHash: TxHash;
+  noteHashes: Fr[];
+  nullifiers: Fr[];
+  privateLogs: PrivateLog[];
+}> = {
+  serialization: {
+    fn: ({ txHash, noteHashes, nullifiers, privateLogs }) => {
+      const emittedLogs = privateLogs.map(log => log.getEmittedFields());
+      const rawLogStorage = emittedLogs
+        .map(fields => fields.concat(Array(PRIVATE_LOG_SIZE_IN_FIELDS - fields.length).fill(Fr.ZERO)))
+        .concat(
+          Array(MAX_PRIVATE_LOGS_PER_TX - emittedLogs.length).fill(Array(PRIVATE_LOG_SIZE_IN_FIELDS).fill(Fr.ZERO)),
+        )
+        .flat();
+      const logLengths = emittedLogs
+        .map(fields => new Fr(fields.length))
+        .concat(Array(MAX_PRIVATE_LOGS_PER_TX - emittedLogs.length).fill(Fr.ZERO));
+      const paddedNoteHashes = noteHashes.concat(Array(MAX_NOTE_HASHES_PER_TX - noteHashes.length).fill(Fr.ZERO));
+      const paddedNullifiers = nullifiers.concat(Array(MAX_NULLIFIERS_PER_TX - nullifiers.length).fill(Fr.ZERO));
+
+      return [
+        txHash.hash,
+        paddedNoteHashes,
+        new Fr(noteHashes.length),
+        paddedNullifiers,
+        new Fr(nullifiers.length),
+        rawLogStorage,
+        logLengths,
+        new Fr(emittedLogs.length),
+      ] as (Fr | Fr[])[];
+    },
+  },
+  // txHash, padded note hashes + count, padded nullifiers + count, flattened private-log storage + lengths + count.
+  shape: [
+    'scalar',
+    { len: MAX_NOTE_HASHES_PER_TX },
+    'scalar',
+    { len: MAX_NULLIFIERS_PER_TX },
+    'scalar',
+    { len: MAX_PRIVATE_LOGS_PER_TX * PRIVATE_LOG_SIZE_IN_FIELDS },
+    { len: MAX_PRIVATE_LOGS_PER_TX },
+    'scalar',
+  ],
+};
+
+const TXE_OFFCHAIN_EFFECTS: TypeMapping<{ effects: Fr[][] }> = {
+  serialization: {
+    fn: ({ effects }) => {
+      const rawArrayStorage = effects
+        .map(e => e.concat(Array(MAX_OFFCHAIN_EFFECT_LEN - e.length).fill(Fr.ZERO)))
+        .concat(
+          Array(MAX_OFFCHAIN_EFFECTS_PER_TXE_QUERY - effects.length).fill(Array(MAX_OFFCHAIN_EFFECT_LEN).fill(Fr.ZERO)),
+        )
+        .flat();
+      const effectLengths = effects
+        .map(e => new Fr(e.length))
+        .concat(Array(MAX_OFFCHAIN_EFFECTS_PER_TXE_QUERY - effects.length).fill(Fr.ZERO));
+
+      return [rawArrayStorage, effectLengths, new Fr(effects.length)] as (Fr | Fr[])[];
+    },
+  },
+  // Flattened effect storage, per-effect lengths, then the effect count.
+  shape: [
+    { len: MAX_OFFCHAIN_EFFECTS_PER_TXE_QUERY * MAX_OFFCHAIN_EFFECT_LEN },
+    { len: MAX_OFFCHAIN_EFFECTS_PER_TXE_QUERY },
+    'scalar',
+  ],
+};
+
+const TXE_CALL_CONTEXT: TypeMapping<{ txHash: Fr; anchorBlockTimestamp: bigint }> = {
+  serialization: {
+    fn: ({ txHash, anchorBlockTimestamp }) => {
+      const isSome = txHash.isZero() ? 0 : 1;
+      return [new Fr(isSome), txHash, new Fr(anchorBlockTimestamp)];
+    },
+  },
+  shape: ['scalar', 'scalar', 'scalar'], // discriminant, txHash, anchor block timestamp
+};
+
+const CONTRACT_INSTANCE_MEMBER: TypeMapping<{ exists: boolean; member: Fr }[]> = FIXED_ARRAY(
+  STRUCT([
+    { name: 'exists', type: BOOL },
+    { name: 'member', type: FIELD },
+  ]),
+  1,
+);
+
+const EVENT_SELECTOR: TypeMapping<EventSelector> = {
+  serialization: { fn: v => [v.toField()] },
+  deserialization: { fn: ([reader]) => EventSelector.fromField(reader.readField()) },
+  shape: ['scalar'],
+};
+
+const TXE_PRIVATE_EVENTS: TypeMapping<Fr[][]> = {
+  serialization: {
+    fn: events => {
+      const rawArrayStorage = events
+        .map(e => e.concat(Array(MAX_PRIVATE_EVENT_LEN - e.length).fill(Fr.ZERO)))
+        .concat(
+          Array(MAX_PRIVATE_EVENTS_PER_TXE_QUERY - events.length).fill(Array(MAX_PRIVATE_EVENT_LEN).fill(Fr.ZERO)),
+        )
+        .flat();
+      const eventLengths = events
+        .map(e => new Fr(e.length))
+        .concat(Array(MAX_PRIVATE_EVENTS_PER_TXE_QUERY - events.length).fill(Fr.ZERO));
+      return [rawArrayStorage, eventLengths, new Fr(events.length)] as (Fr | Fr[])[];
+    },
+  },
+  // Flattened event storage, per-event lengths, then the event count.
+  shape: [
+    { len: MAX_PRIVATE_EVENTS_PER_TXE_QUERY * MAX_PRIVATE_EVENT_LEN },
+    { len: MAX_PRIVATE_EVENTS_PER_TXE_QUERY },
+    'scalar',
+  ],
+};
+
+export const TXE_ORACLE_REGISTRY = {
+  ...ORACLE_REGISTRY,
+
+  aztec_txe_assertCompatibleOracleVersion: makeEntry({
+    params: [
+      { name: 'major', type: U32 },
+      { name: 'minor', type: U32 },
+    ],
+  }),
+
+  aztec_txe_setTopLevelTXEContext: makeEntry(),
+
+  aztec_txe_setPrivateTXEContext: makeEntry({
+    params: [
+      { name: 'contractAddress', type: OPTION(AZTEC_ADDRESS) },
+      { name: 'anchorBlockNumber', type: OPTION(BLOCK_NUMBER) },
+      { name: 'gasSettings', type: GAS_SETTINGS },
+    ],
+    returnType: PRIVATE_CONTEXT_INPUTS,
+  }),
+
+  aztec_txe_setPublicTXEContext: makeEntry({
+    params: [{ name: 'contractAddress', type: OPTION(AZTEC_ADDRESS) }],
+  }),
+
+  aztec_txe_setUtilityTXEContext: makeEntry({
+    params: [{ name: 'contractAddress', type: OPTION(AZTEC_ADDRESS) }],
+  }),
+
+  aztec_txe_getDefaultAddress: makeEntry({ returnType: AZTEC_ADDRESS }),
+
+  aztec_txe_getNextBlockNumber: makeEntry({ returnType: BLOCK_NUMBER }),
+
+  aztec_txe_getNextBlockTimestamp: makeEntry({ returnType: BIGINT }),
+
+  aztec_txe_advanceBlocksBy: makeEntry({
+    params: [{ name: 'blocks', type: U32 }],
+  }),
+
+  aztec_txe_advanceTimestampBy: makeEntry({
+    params: [{ name: 'duration', type: BIGINT }],
+  }),
+
+  aztec_txe_deploy: makeEntry({
+    params: [
+      { name: 'contractPath', type: STR },
+      { name: 'initializer', type: STR },
+      { name: 'argsLength', type: U32 },
+      { name: 'args', type: ARRAY(FIELD) },
+      { name: 'secret', type: FIELD },
+      { name: 'salt', type: FIELD },
+      { name: 'deployer', type: AZTEC_ADDRESS },
+    ],
+    returnType: ARRAY(FIELD),
+  }),
+
+  aztec_txe_createAccount: makeEntry({
+    params: [{ name: 'secret', type: FIELD }],
+    returnType: COMPLETE_ADDRESS,
+  }),
+
+  aztec_txe_addAccount: makeEntry({
+    params: [{ name: 'secret', type: FIELD }],
+    returnType: COMPLETE_ADDRESS,
+  }),
+
+  aztec_txe_addAuthWitness: makeEntry({
+    params: [
+      { name: 'address', type: AZTEC_ADDRESS },
+      { name: 'messageHash', type: FIELD },
+    ],
+  }),
+
+  aztec_txe_sendL1ToL2Message: makeEntry({
+    params: [
+      { name: 'content', type: FIELD },
+      { name: 'secretHash', type: FIELD },
+      { name: 'sender', type: ETH_ADDRESS },
+      { name: 'recipient', type: AZTEC_ADDRESS },
+    ],
+    returnType: FIELD,
+  }),
+
+  aztec_txe_setTaggingSecretStrategy: makeEntry({
+    params: [{ name: 'strategy', type: OPTION(TAGGING_SECRET_STRATEGY) }],
+  }),
+
+  aztec_txe_getLastBlockTimestamp: makeEntry({
+    returnType: BIGINT,
+  }),
+
+  aztec_txe_getLastTxEffects: makeEntry({ returnType: TXE_TX_EFFECTS }),
+  aztec_txe_getLastCallOffchainEffects: makeEntry({ returnType: TXE_OFFCHAIN_EFFECTS }),
+  aztec_txe_getLastCallContext: makeEntry({ returnType: TXE_CALL_CONTEXT }),
+
+  aztec_txe_getPrivateEvents: makeEntry({
+    params: [
+      { name: 'selector', type: EVENT_SELECTOR },
+      { name: 'contractAddress', type: AZTEC_ADDRESS },
+      { name: 'scope', type: AZTEC_ADDRESS },
+    ],
+    returnType: TXE_PRIVATE_EVENTS,
+  }),
+
+  aztec_txe_privateCallNewFlow: makeEntry({
+    params: [
+      { name: 'from', type: OPTION(AZTEC_ADDRESS) },
+      { name: 'targetContractAddress', type: AZTEC_ADDRESS },
+      { name: 'functionSelector', type: FUNCTION_SELECTOR },
+      { name: 'args', type: ARRAY(FIELD) },
+      { name: 'argsHash', type: FIELD },
+      { name: 'isStaticCall', type: BOOL },
+      { name: 'additionalScopes', type: ARRAY(AZTEC_ADDRESS) },
+      { name: 'authorizedUtilityCallTargets', type: ARRAY(AZTEC_ADDRESS) },
+      { name: 'gasSettings', type: GAS_SETTINGS },
+    ],
+    returnType: ARRAY(FIELD),
+  }),
+
+  aztec_txe_executeUtilityFunction: makeEntry({
+    params: [
+      { name: 'from', type: OPTION(AZTEC_ADDRESS) },
+      { name: 'targetContractAddress', type: AZTEC_ADDRESS },
+      { name: 'functionSelector', type: FUNCTION_SELECTOR },
+      { name: 'args', type: ARRAY(FIELD) },
+      { name: 'authorizedUtilityCallTargets', type: ARRAY(AZTEC_ADDRESS) },
+    ],
+    returnType: ARRAY(FIELD),
+  }),
+
+  aztec_txe_publicCallNewFlow: makeEntry({
+    params: [
+      { name: 'from', type: OPTION(AZTEC_ADDRESS) },
+      { name: 'address', type: AZTEC_ADDRESS },
+      { name: 'calldata', type: ARRAY(FIELD) },
+      { name: 'isStaticCall', type: BOOL },
+      { name: 'gasSettings', type: GAS_SETTINGS },
+    ],
+    returnType: ARRAY(FIELD),
+  }),
+
+  aztec_avm_address: makeEntry({ returnType: AZTEC_ADDRESS }),
+
+  aztec_avm_sender: makeEntry({ returnType: AZTEC_ADDRESS }),
+
+  aztec_avm_blockNumber: makeEntry({ returnType: BLOCK_NUMBER }),
+
+  aztec_avm_timestamp: makeEntry({ returnType: BIGINT }),
+
+  aztec_avm_isStaticCall: makeEntry({ returnType: BOOL }),
+
+  aztec_avm_chainId: makeEntry({ returnType: FIELD }),
+
+  aztec_avm_version: makeEntry({ returnType: FIELD }),
+
+  aztec_avm_emitNullifier: makeEntry({
+    params: [{ name: 'nullifier', type: FIELD }],
+  }),
+
+  aztec_avm_emitNoteHash: makeEntry({
+    params: [{ name: 'noteHash', type: FIELD }],
+  }),
+
+  aztec_avm_nullifierExists: makeEntry({
+    params: [{ name: 'siloedNullifier', type: FIELD }],
+    returnType: BOOL,
+  }),
+
+  aztec_avm_storageRead: makeEntry({
+    params: [
+      { name: 'slot', type: FIELD },
+      { name: 'contractAddress', type: AZTEC_ADDRESS },
+    ],
+    returnType: FIELD,
+  }),
+
+  aztec_avm_storageWrite: makeEntry({
+    params: [
+      { name: 'slot', type: FIELD },
+      { name: 'value', type: FIELD },
+    ],
+  }),
+
+  aztec_avm_emitPublicLog: makeEntry({
+    params: [{ name: 'message', type: ARRAY(FIELD) }],
+  }),
+
+  aztec_avm_returndataSize: makeEntry({ returnType: U32 }),
+
+  aztec_avm_returndataCopy: makeEntry({
+    params: [
+      { name: 'rdOffset', type: U32 },
+      { name: 'copySize', type: U32 },
+    ],
+    returnType: ARRAY(FIELD),
+  }),
+
+  aztec_avm_call: makeEntry({
+    params: [
+      { name: 'l2Gas', type: U32 },
+      { name: 'daGas', type: U32 },
+      { name: 'address', type: AZTEC_ADDRESS },
+      { name: 'argsLength', type: U32 },
+      { name: 'args', type: ARRAY(FIELD) },
+    ],
+  }),
+
+  aztec_avm_staticCall: makeEntry({
+    params: [
+      { name: 'l2Gas', type: U32 },
+      { name: 'daGas', type: U32 },
+      { name: 'address', type: AZTEC_ADDRESS },
+      { name: 'argsLength', type: U32 },
+      { name: 'args', type: ARRAY(FIELD) },
+    ],
+  }),
+
+  aztec_avm_successCopy: makeEntry({ returnType: BOOL }),
+
+  aztec_avm_getContractInstanceDeployer: makeEntry({
+    params: [{ name: 'address', type: AZTEC_ADDRESS }],
+    returnType: CONTRACT_INSTANCE_MEMBER,
+  }),
+  aztec_avm_getContractInstanceClassId: makeEntry({
+    params: [{ name: 'address', type: AZTEC_ADDRESS }],
+    returnType: CONTRACT_INSTANCE_MEMBER,
+  }),
+  aztec_avm_getContractInstanceInitializationHash: makeEntry({
+    params: [{ name: 'address', type: AZTEC_ADDRESS }],
+    returnType: CONTRACT_INSTANCE_MEMBER,
+  }),
+  aztec_avm_getContractInstanceImmutablesHash: makeEntry({
+    params: [{ name: 'address', type: AZTEC_ADDRESS }],
+    returnType: CONTRACT_INSTANCE_MEMBER,
+  }),
+} satisfies Record<string, OracleRegistryEntry>;
+
+export function toInputSlots(inputs: ForeignCallArgs): InputSlot[] {
+  // TXE foreign calls use bare hex strings, but Fr.fromString requires a 0x prefix to parse as hex.
+  return inputs.map(v => (Array.isArray(v) ? (v as string[]).map(withHexPrefix) : [withHexPrefix(v as string)]));
+}
+
+/**
+ * Deserializes oracle inputs, calls the handler with typed params, serializes the result, and wraps
+ * it in a `ForeignCallResult`. Normalizes `ForeignCallArgs` (which may contain bare strings) into
+ * `InputSlot[]` (always arrays) before deserialization.
+ */
+export async function callTxeHandler<K extends keyof typeof TXE_ORACLE_REGISTRY>({
+  oracle,
+  inputs,
+  handler,
+}: {
+  oracle: K;
+  inputs: ForeignCallArgs;
+  handler: (
+    params: ParamTypes<ReturnType<(typeof TXE_ORACLE_REGISTRY)[K]['deserializeParams']>>,
+  ) => MaybePromise<Parameters<(typeof TXE_ORACLE_REGISTRY)[K]['serializeReturn']>[0]>;
+}): Promise<ForeignCallResult> {
+  const entry = TXE_ORACLE_REGISTRY[oracle] as OracleRegistryEntry;
+  const named = entry.deserializeParams(toInputSlots(inputs));
+  const positional = named.map((p: { value: unknown }) => p.value);
+  const result = await handler(positional as any);
+  return outputSlotsToForeignCallResult(entry.serializeReturn(result));
+}
+
+/**
+ * Dispatches an oracle that has been retired into the PXE legacy registry. TXE has no explicit handler method for such
+ * names; this runs them through the same `buildACIRCallback` legacy path that contract execution already uses, so
+ * TXE's top-level oracle path and its in-contract path treat the legacy registry identically.
+ */
+const legacyCallbacksByHandler = new WeakMap<object, ReturnType<typeof buildACIRCallback>>();
+
+export async function callTxeLegacyHandler(
+  oracle: string,
+  inputs: ForeignCallArgs,
+  oracleHandler: Parameters<typeof buildACIRCallback>[0],
+): Promise<ForeignCallResult> {
+  // `buildACIRCallback` materializes the whole real+legacy closure set, so memoize it per handler rather than
+  // rebuilding on every call (TXE routes one legacy oracle through here on each top-level discovery).
+  let callback = legacyCallbacksByHandler.get(oracleHandler);
+  if (!callback) {
+    callback = buildACIRCallback(oracleHandler);
+    legacyCallbacksByHandler.set(oracleHandler, callback);
+  }
+  const outputSlots = await callback[oracle](...toInputSlots(inputs));
+  return outputSlotsToForeignCallResult(outputSlots);
+}
+
+/**
+ * Strips the `0x` prefix from each serialized output slot (TXE foreign calls use bare hex strings) and wraps them in a
+ * `ForeignCallResult`.
+ */
+function outputSlotsToForeignCallResult(outputSlots: OutputSlot[]): ForeignCallResult {
+  return {
+    values: outputSlots.map(slot => (Array.isArray(slot) ? slot.map(withoutHexPrefix) : withoutHexPrefix(slot))),
+  };
+}