@aztec/txe 0.0.1-commit.993d240 → 0.0.1-commit.9a89641

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

@@ -0,0 +1,44 @@
+/* eslint-disable camelcase */
+import { createSafeJsonRpcServer } from '@aztec/foundation/json-rpc/server';
+import type { Logger } from '@aztec/foundation/log';
+import type { ApiSchemaFor } from '@aztec/foundation/schemas';
+import { zodFor } from '@aztec/stdlib/schemas';
+
+import { z } from 'zod';
+
+import { ForeignCallArgsSchema, type ForeignCallResult, ForeignCallResultSchema } from '../../utils/encoding.js';
+import { TXE_ORACLE_REGISTRY } from '../txe_oracle_registry.js';
+import { type OracleTestCallInput, OracleTestResolver } from './resolver.js';
+
+const OracleTestCallInputSchema = zodFor<OracleTestCallInput>()(
+  z.object({
+    session_id: z.number().nonnegative(),
+    function: z.string(),
+    root_path: z.string(),
+    package_name: z.string(),
+    inputs: ForeignCallArgsSchema,
+  }),
+);
+
+/** Narrowed interface exposing only the RPC method. */
+interface OracleTestRpcHandler {
+  resolve_foreign_call(callData: OracleTestCallInput): Promise<ForeignCallResult>;
+}
+
+const OracleTestRpcHandlerSchema: ApiSchemaFor<OracleTestRpcHandler> = {
+  resolve_foreign_call: z.function({
+    input: z.tuple([OracleTestCallInputSchema]),
+    output: ForeignCallResultSchema,
+  }),
+};
+
+/** Creates an RPC server backed by the oracle test resolver. */
+export function createOracleTestRpcServer(logger: Logger) {
+  const resolver = OracleTestResolver.fromRegistry(TXE_ORACLE_REGISTRY, logger);
+  const server = createSafeJsonRpcServer<OracleTestRpcHandler>(resolver, OracleTestRpcHandlerSchema, {
+    http200OnError: true,
+  });
+  return { server, resolver };
+}
+
+export { OracleTestResolver } from './resolver.js';

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

@@ -0,0 +1,245 @@
+/* eslint-disable camelcase */
+import type { Logger } from '@aztec/foundation/log';
+import { createLogger } from '@aztec/foundation/log';
+import { withoutHexPrefix } from '@aztec/foundation/string';
+import { BOUNDED_VEC, BoundedVec, Option, type OracleRegistryEntry, U8, makeEntry } from '@aztec/pxe/simulator';
+
+import type { ForeignCallArgs, ForeignCallResult } from '../../utils/encoding.js';
+import { toInputSlots } from '../txe_oracle_registry.js';
+import { synthesizeDefaultFixtures } from './default_fixtures.js';
+
+/** 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(U8) }] });
+
+export type OracleTestCallInput = {
+  session_id: number;
+  function: string;
+  root_path: string;
+  package_name: string;
+  inputs: ForeignCallArgs;
+};
+
+/**
+ * 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 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>();
+  private readonly pendingScenario = new Map<number, string>();
+  private readonly logger: Logger;
+
+  constructor(
+    private readonly registry: Record<string, OracleRegistryEntry>,
+    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 `#[generate_oracle_tests]` 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;
+    this.logger.debug('Resolving oracle', { oracleName });
+
+    if (oracleName === SET_SCENARIO_ORACLE) {
+      return this.#handleSetScenario(callData);
+    }
+
+    if (!(oracleName in this.registry)) {
+      throw new Error(`Oracle '${oracleName}' not found in registry`);
+    }
+    const entry = this.registry[oracleName];
+
+    const scenarios = this.fixtures[oracleName];
+    if (!scenarios || scenarios.length === 0) {
+      throw new Error(`No fixture defined for oracle '${oracleName}'`);
+    }
+
+    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 });
+
+    const outputSlots = entry.serializeReturn(match.output);
+    return {
+      values: outputSlots.map(slot => (Array.isArray(slot) ? slot.map(withoutHexPrefix) : withoutHexPrefix(slot))),
+    };
+  }
+
+  /** Returns oracles that have a fixture defined but were never called during testing. */
+  getUncalledFixtures(): string[] {
+    return Object.keys(this.fixtures).filter(name => !this.calledOracles.has(name));
+  }
+
+  /** Returns oracles in the registry that have no fixture defined at all. */
+  getMissingFixtures(): string[] {
+    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 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, scenario });
+    this.pendingScenario.set(callData.session_id, scenario);
+
+    return { values: [] };
+  }
+
+  /** 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 announced = this.pendingScenario.get(sessionId);
+
+    if (announced !== undefined) {
+      this.pendingScenario.delete(sessionId);
+      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}`);
+      }
+      return match;
+    }
+
+    if (fixtures.length === 1) {
+      return fixtures[0];
+    }
+
+    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,
+    fixture: OracleTestScenario,
+    oracleName: string,
+  ): void {
+    const expectedInputs = fixture.inputs;
+    if (Object.keys(expectedInputs).length === 0) {
+      return;
+    }
+
+    const scenarioLabel = fixture.scenario ? ` (scenario '${fixture.scenario}')` : '';
+    const named = entry.deserializeParams(toInputSlots(rawInputs));
+
+    for (const param of named) {
+      if (!(param.name in expectedInputs)) {
+        throw new Error(
+          `Unexpected param '${param.name}' for oracle '${oracleName}'. ` +
+            `Expected: ${Object.keys(expectedInputs).join(', ')}`,
+        );
+      }
+      if (!valuesEqual(param.value, expectedInputs[param.name])) {
+        throw new Error(
+          `Input mismatch for oracle '${oracleName}'${scenarioLabel}: ` +
+            `param '${param.name}' expected ${String(expectedInputs[param.name])} ` +
+            `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 (!isNonNullObject(actual) || !isNonNullObject(expected)) {
+    // Primitive scalars; String() bridges bigint vs number representations of the same seed. A primitive compared
+    // against an object is never equal.
+    return isNonNullObject(actual) === isNonNullObject(expected) && String(actual) === String(expected);
+  }
+  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]));
+  }
+  if (isPlainObject(actual) && isPlainObject(expected)) {
+    const expectedKeys = Object.keys(expected);
+    return (
+      Object.keys(actual).length === expectedKeys.length &&
+      expectedKeys.every(key => valuesEqual(actual[key], expected[key]))
+    );
+  }
+  if (actual.constructor !== expected.constructor) {
+    return false;
+  }
+  if (hasEquals(actual)) {
+    return actual.equals(expected);
+  }
+  const actualStr = customStringForm(actual);
+  const expectedStr = customStringForm(expected);
+  if (actualStr !== undefined && expectedStr !== undefined) {
+    return actualStr === expectedStr;
+  }
+  // Comparing blindly here could pass vacuously (e.g. two '[object Object]' strings), so refuse instead.
+  throw new Error(
+    `valuesEqual cannot compare a '${actual.constructor?.name}' against a '${expected.constructor?.name}'. Add a branch for the type.`,
+  );
+}
+
+function isNonNullObject(value: unknown): value is object {
+  return typeof value === 'object' && value !== null;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return isNonNullObject(value) && value.constructor === Object;
+}
+
+function hasEquals(value: object): value is { equals(other: unknown): boolean } {
+  return typeof (value as { equals?: unknown }).equals === 'function';
+}
+
+/** The value's string form when its class overrides `toString` (a meaningful representation), undefined otherwise. */
+function customStringForm(value: object): string | undefined {
+  const { toString } = value;
+  if (typeof toString !== 'function' || toString === Object.prototype.toString) {
+    return undefined;
+  }
+  return toString.call(value);
+}
+
+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

@@ -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');
 
@@ -122,7 +125,36 @@ export class TXEOraclePublicContext implements IAvmExecutionOracle {
     return value;
   }
 
-  returndataSize(): Promise<Fr> {
+  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',
     );
@@ -134,19 +166,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',
     );