@aztec/txe 5.0.0-rc.1 → 5.0.0-rc.2

package/src/oracle/test-resolver/resolver.ts

@@ -1,14 +1,16 @@
 /* eslint-disable camelcase */
 import type { Logger } from '@aztec/foundation/log';
 import { createLogger } from '@aztec/foundation/log';
-import { withHexPrefix, withoutHexPrefix } from '@aztec/foundation/string';
-import type { InputSlot, OracleRegistryEntry } from '@aztec/pxe/simulator';
+import { withoutHexPrefix } from '@aztec/foundation/string';
+import { BOUNDED_VEC, BYTE, BoundedVec, Option, type OracleRegistryEntry, makeEntry } from '@aztec/pxe/simulator';
 
 import type { ForeignCallArgs, ForeignCallResult } from '../../utils/encoding.js';
-import type { OracleTestScenario } from './fixtures.js';
+import { toInputSlots } from '../txe_oracle_registry.js';
+import { synthesizeDefaultFixtures } from './default_fixtures.js';
 
-/** Name of the meta-oracle that Noir tests call to select a fixture scenario by name. */
+/** Name of the meta-oracle that Noir tests call to announce the next call's scenario by name. */
 const SET_SCENARIO_ORACLE = 'aztec_oracle_test_set_scenario';
+export const SET_SCENARIO_ENTRY = makeEntry({ params: [{ name: 'name', type: BOUNDED_VEC(BYTE) }] });
 
 export type OracleTestCallInput = {
   session_id: number;
@@ -19,12 +21,22 @@ export type OracleTestCallInput = {
 };
 
 /**
- * Oracle resolver for roundtrip tests. Selects a fixture scenario, verifies that the received inputs match, and
+ * One test case for an oracle: the expected deserialized `inputs`, the `output` to serialize back to Noir, and the
+ * `scenario` name (`some`/`none`) the matching Noir test announces. Single-scenario oracles leave `scenario` undefined
+ * and are selected automatically.
+ */
+export interface OracleTestScenario {
+  scenario?: string;
+  inputs: Record<string, unknown>;
+  output: unknown;
+}
+
+/**
+ * Oracle resolver for serialization tests. Selects a fixture scenario, verifies that the received inputs match, and
  * returns the corresponding fixture output.
  *
- * For oracles with a single fixture, it is selected automatically. For oracles with multiple fixtures, Noir tests
- * must call the `oracle_test_set_scenario` meta-oracle to select a specific scenario by name before calling the
- * real oracle.
+ * For oracles with a single scenario, it is selected automatically. For oracles with multiple scenarios, the Noir test
+ * announces the scenario by name via the `aztec_oracle_test_set_scenario` meta-oracle before calling the real oracle.
  */
 export class OracleTestResolver {
   private readonly calledOracles = new Set<string>();
@@ -33,12 +45,20 @@ export class OracleTestResolver {
 
   constructor(
     private readonly registry: Record<string, OracleRegistryEntry>,
-    private readonly fixtures: Partial<Record<string, OracleTestScenario[]>>,
+    private readonly fixtures: Record<string, OracleTestScenario[]>,
     logger?: Logger,
   ) {
     this.logger = logger ?? createLogger('txe:test-resolver');
   }
 
+  /**
+   * Builds a resolver whose fixtures are the default scenarios synthesized from the registry's type mappings. The
+   * matching Noir serialization tests are auto-generated by `#[auto_serialization_test]` from the same convention.
+   */
+  static fromRegistry(registry: Record<string, OracleRegistryEntry>, logger?: Logger): OracleTestResolver {
+    return new OracleTestResolver(registry, synthesizeDefaultFixtures(registry), logger);
+  }
+
   // eslint-disable-next-line require-await
   async resolve_foreign_call(callData: OracleTestCallInput): Promise<ForeignCallResult> {
     const oracleName = callData.function;
@@ -48,8 +68,6 @@ export class OracleTestResolver {
       return this.#handleSetScenario(callData);
     }
 
-    this.calledOracles.add(oracleName);
-
     if (!(oracleName in this.registry)) {
       throw new Error(`Oracle '${oracleName}' not found in registry`);
     }
@@ -62,6 +80,7 @@ export class OracleTestResolver {
 
     const match = this.#selectScenario(callData.session_id, oracleName, scenarios);
     this.#verifyInputs(callData.inputs, entry, match, oracleName);
+    this.calledOracles.add(oracleName);
 
     this.logger.debug('Verified scenario for oracle', { oracleName });
 
@@ -81,62 +100,57 @@ export class OracleTestResolver {
     return Object.keys(this.registry).filter(name => !(name in this.fixtures));
   }
 
+  /**
+   * Records the scenario name for the session's next oracle call. A test announces once per multi-scenario position
+   * (param or return), so successive announcements accumulate joined with `+`, matching the names the fixture
+   * synthesizer builds (e.g. `some+some`).
+   */
   #handleSetScenario(callData: { session_id: number; inputs: ForeignCallArgs }): ForeignCallResult {
-    const charCodes = callData.inputs[0] as string[];
-    const scenarioName = charCodes
-      .map(hex => Number(BigInt(hex.startsWith('0x') ? hex : `0x${hex}`)))
-      .map(code => String.fromCharCode(code))
-      .join('');
+    const name = decodeScenarioName(callData.inputs);
+    const existing = this.pendingScenario.get(callData.session_id);
+    const scenario = existing !== undefined ? `${existing}+${name}` : name;
 
-    this.logger.debug('Setting scenario for next oracle call', { sessionId: callData.session_id, scenarioName });
-    this.pendingScenario.set(callData.session_id, scenarioName);
+    this.logger.debug('Setting scenario for next oracle call', { sessionId: callData.session_id, scenario });
+    this.pendingScenario.set(callData.session_id, scenario);
 
     return { values: [] };
   }
 
-  /** Selects a scenario by pending name (for multi-fixture oracles) or returns the single fixture. */
+  /** Selects the fixture by the announced scenario name (for multi-scenario oracles) or returns the single fixture. */
   #selectScenario(sessionId: number, oracleName: string, fixtures: OracleTestScenario[]): OracleTestScenario {
-    const selectedName = this.pendingScenario.get(sessionId);
+    const announced = this.pendingScenario.get(sessionId);
 
-    if (selectedName !== undefined) {
+    if (announced !== undefined) {
       this.pendingScenario.delete(sessionId);
-      const matches = fixtures.filter(s => s.scenario === selectedName);
-      if (matches.length === 0) {
-        const available = fixtures.map(s => s.scenario).join(', ');
-        throw new Error(`No scenario named '${selectedName}' for oracle '${oracleName}'. Available: ${available}`);
+      const match = fixtures.find(s => s.scenario === announced);
+      if (!match) {
+        const available = fixtures.map(s => s.scenario ?? '<default>').join(', ');
+        throw new Error(`No scenario '${announced}' for oracle '${oracleName}'. Available: ${available}`);
       }
-      if (matches.length > 1) {
-        throw new Error(`Duplicate scenario name '${selectedName}' for oracle '${oracleName}'`);
-      }
-      return matches[0];
+      return match;
     }
 
     if (fixtures.length === 1) {
       return fixtures[0];
     }
 
-    throw new Error(
-      `Oracle '${oracleName}' has ${fixtures.length} fixture scenarios. ` +
-        `Use #[oracle_test("scenario_name")] to select one.`,
-    );
+    throw new Error(`Oracle '${oracleName}' has ${fixtures.length} scenarios but none was announced before the call.`);
   }
 
   /** Deserializes actual inputs and verifies they match the scenario's expected inputs. */
   #verifyInputs(
     rawInputs: ForeignCallArgs,
     entry: OracleRegistryEntry,
-    scenario: OracleTestScenario,
+    fixture: OracleTestScenario,
     oracleName: string,
   ): void {
-    const expectedInputs = scenario.inputs as Record<string, unknown>;
+    const expectedInputs = fixture.inputs;
     if (Object.keys(expectedInputs).length === 0) {
       return;
     }
 
-    const normalized: InputSlot[] = rawInputs.map(v =>
-      Array.isArray(v) ? (v as string[]).map(withHexPrefix) : [withHexPrefix(v as string)],
-    );
-    const named = entry.deserializeParams(normalized);
+    const scenarioLabel = fixture.scenario ? ` (scenario '${fixture.scenario}')` : '';
+    const named = entry.deserializeParams(toInputSlots(rawInputs));
 
     for (const param of named) {
       if (!(param.name in expectedInputs)) {
@@ -146,20 +160,39 @@ export class OracleTestResolver {
         );
       }
       if (!valuesEqual(param.value, expectedInputs[param.name])) {
-        const scenarioLabel = scenario.scenario ? ` (scenario '${scenario.scenario}')` : '';
         throw new Error(
           `Input mismatch for oracle '${oracleName}'${scenarioLabel}: ` +
             `param '${param.name}' expected ${String(expectedInputs[param.name])} ` +
-            `but got ${String(param.value)}`,
+            `but got ${String(param.value)}. ${versionBumpHint(oracleName)}`,
         );
       }
     }
   }
 }
 
+/**
+ * Decodes the scenario name announced by `set_oracle_test_scenario`, whose argument is a `BoundedVec<u8, N>`
+ */
+function decodeScenarioName(inputs: ForeignCallArgs): string {
+  const [{ value }] = SET_SCENARIO_ENTRY.deserializeParams(toInputSlots(inputs));
+  return String.fromCharCode(...value.data);
+}
+
 function valuesEqual(actual: unknown, expected: unknown): boolean {
+  if (actual instanceof Option && expected instanceof Option) {
+    return actual.equals(expected, valuesEqual);
+  }
+  if (actual instanceof BoundedVec && expected instanceof BoundedVec) {
+    return actual.equals(expected, valuesEqual);
+  }
   if (Array.isArray(actual) && Array.isArray(expected)) {
     return actual.length === expected.length && actual.every((v, i) => valuesEqual(v, expected[i]));
   }
   return String(actual) === String(expected);
 }
+
+function versionBumpHint(oracle: string): string {
+  return oracle.startsWith('aztec_txe_') || oracle.startsWith('aztec_avm_')
+    ? 'If you changed this oracle, consider bumping the TXE oracle version in yarn-project/txe/src/oracle/txe_oracle_version.ts.'
+    : 'If you changed this oracle, consider bumping the PXE oracle version in yarn-project/pxe/src/oracle_version.ts.';
+}

package/src/oracle/txe_oracle_public_context.ts

@@ -164,19 +164,19 @@ export class TXEOraclePublicContext implements IAvmExecutionOracle {
     );
   }
 
-  call(_l2Gas: number, _daGas: number, _address: AztecAddress, _argsLength: number, _args: Fr[]): Promise<Fr[]> {
+  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<Fr[]> {
+  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<Fr> {
+  successCopy(): Promise<boolean> {
     throw new Error(
       'Contract calls are forbidden inside a `TestEnvironment::public_context`, use `public_call` instead',
     );

package/src/oracle/txe_oracle_registry.ts

@@ -4,16 +4,20 @@ import {
   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,
   FUNCTION_SELECTOR,
   type InputSlot,
@@ -23,6 +27,7 @@ import {
   type OracleRegistryEntry,
   type ParamTypes,
   STR,
+  type SlotShape,
   type TypeMapping,
   U32,
   makeEntry,
@@ -42,20 +47,68 @@ import {
 } 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> = {
-  serialization: { fn: v => v.toFields() },
   deserialization: {
     fn: ([reader]) => GasSettings.fromFields(reader.readFieldArray(GAS_SETTINGS_LENGTH)),
-    slots: 1,
   },
+  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 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 '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_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<{
@@ -91,6 +144,17 @@ const TXE_TX_EFFECTS: TypeMapping<{
       ] 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[][] }> = {
@@ -109,6 +173,12 @@ const TXE_OFFCHAIN_EFFECTS: TypeMapping<{ effects: Fr[][] }> = {
       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 }> = {
@@ -118,15 +188,18 @@ const TXE_CALL_CONTEXT: TypeMapping<{ txHash: Fr; anchorBlockTimestamp: bigint }
       return [new Fr(isSome), txHash, new Fr(anchorBlockTimestamp)];
     },
   },
+  shape: ['scalar', 'scalar', 'scalar'], // discriminant, txHash, anchor block timestamp
 };
 
 const CONTRACT_INSTANCE_MEMBER: TypeMapping<{ member: Fr; exists: boolean }> = {
   serialization: { fn: ({ member, exists }) => [member, new Fr(exists)] },
+  shape: ['scalar', 'scalar'],
 };
 
 const EVENT_SELECTOR: TypeMapping<EventSelector> = {
   serialization: { fn: v => [v.toField()] },
-  deserialization: { fn: ([reader]) => EventSelector.fromField(reader.readField()), slots: 1 },
+  deserialization: { fn: ([reader]) => EventSelector.fromField(reader.readField()) },
+  shape: ['scalar'],
 };
 
 const TXE_PRIVATE_EVENTS: TypeMapping<Fr[][]> = {
@@ -144,9 +217,15 @@ const TXE_PRIVATE_EVENTS: TypeMapping<Fr[][]> = {
       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: Record<string, OracleRegistryEntry> = {
+export const TXE_ORACLE_REGISTRY = {
   ...ORACLE_REGISTRY,
 
   aztec_txe_assertCompatibleOracleVersion: makeEntry({
@@ -219,6 +298,20 @@ export const TXE_ORACLE_REGISTRY: Record<string, OracleRegistryEntry> = {
     ],
   }),
 
+  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,
   }),
@@ -253,6 +346,7 @@ export const TXE_ORACLE_REGISTRY: Record<string, OracleRegistryEntry> = {
 
   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) },
@@ -336,7 +430,6 @@ export const TXE_ORACLE_REGISTRY: Record<string, OracleRegistryEntry> = {
       { name: 'argsLength', type: U32 },
       { name: 'args', type: ARRAY(FIELD) },
     ],
-    returnType: ARRAY(FIELD),
   }),
 
   aztec_avm_staticCall: makeEntry({
@@ -347,10 +440,9 @@ export const TXE_ORACLE_REGISTRY: Record<string, OracleRegistryEntry> = {
       { name: 'argsLength', type: U32 },
       { name: 'args', type: ARRAY(FIELD) },
     ],
-    returnType: ARRAY(FIELD),
   }),
 
-  aztec_avm_successCopy: makeEntry({ returnType: FIELD }),
+  aztec_avm_successCopy: makeEntry({ returnType: BOOL }),
 
   aztec_avm_getContractInstanceDeployer: makeEntry({
     params: [{ name: 'address', type: AZTEC_ADDRESS }],
@@ -368,7 +460,12 @@ export const TXE_ORACLE_REGISTRY: Record<string, OracleRegistryEntry> = {
     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
@@ -387,11 +484,7 @@ export async function callTxeHandler<K extends keyof typeof TXE_ORACLE_REGISTRY>
   ) => MaybePromise<Parameters<(typeof TXE_ORACLE_REGISTRY)[K]['serializeReturn']>[0]>;
 }): Promise<ForeignCallResult> {
   const entry = TXE_ORACLE_REGISTRY[oracle] as OracleRegistryEntry;
-  // TXE foreign calls use bare hex strings, but Fr.fromString requires a 0x prefix to parse as hex.
-  const normalized: InputSlot[] = inputs.map(v =>
-    Array.isArray(v) ? (v as string[]).map(withHexPrefix) : [withHexPrefix(v as string)],
-  );
-  const named = entry.deserializeParams(normalized);
+  const named = entry.deserializeParams(toInputSlots(inputs));
   const positional = named.map((p: { value: unknown }) => p.value);
   const result = await handler(positional as any);
   const outputSlots = entry.serializeReturn(result);