@aztec/pxe 5.0.0-rc.1 → 5.0.0

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,18 +92,22 @@ 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 { MessageContextService } from '../messages/message_context_service.js';
+import type { TxResolverService } from '../messages/tx_resolver_service.js';
 import type { AddressStore } from '../storage/address_store/address_store.js';
 import { CapsuleService } from '../storage/capsule_store/capsule_service.js';
 import type { CapsuleStore } from '../storage/capsule_store/capsule_store.js';
 import type { ContractStore } from '../storage/contract_store/contract_store.js';
+import { FactService } from '../storage/fact_store/index.js';
+import type { FactStore } from '../storage/fact_store/index.js';
 import type { NoteStore } from '../storage/note_store/note_store.js';
 import type { PrivateEventStore } from '../storage/private_event_store/private_event_store.js';
 import type { RecipientTaggingStore } from '../storage/tagging_store/recipient_tagging_store.js';
-import type { SenderAddressBookStore } from '../storage/tagging_store/sender_address_book_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';
@@ -114,10 +120,6 @@ import { TransientArrayService } from './transient_array_service.js';
 
 /** Options for ContractFunctionSimulator.run. */
 export type ContractSimulatorRunOpts = {
-  /** The address of the contract (should match request.origin). */
-  contractAddress: AztecAddress;
-  /** The function selector of the entry point. */
-  selector: FunctionSelector;
   /** The address calling the function. Can be replaced to simulate a call from another contract or account. */
   msgSender?: AztecAddress;
   /** The block header to use as base state for this run. */
@@ -133,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;
@@ -140,12 +145,13 @@ export type ContractFunctionSimulatorArgs = {
   l2TipsStore: L2TipsProvider;
   senderTaggingStore: SenderTaggingStore;
   recipientTaggingStore: RecipientTaggingStore;
-  senderAddressBookStore: SenderAddressBookStore;
+  taggingSecretSourcesStore: TaggingSecretSourcesStore;
   capsuleStore: CapsuleStore;
+  factStore: FactStore;
   privateEventStore: PrivateEventStore;
   simulator: CircuitSimulator;
   contractSyncService: ContractSyncService;
-  messageContextService: MessageContextService;
+  txResolver: TxResolverService;
   hooks?: ExecutionHooks;
 };
 
@@ -155,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;
@@ -162,16 +170,19 @@ export class ContractFunctionSimulator {
   private readonly l2TipsStore: L2TipsProvider;
   private readonly senderTaggingStore: SenderTaggingStore;
   private readonly recipientTaggingStore: RecipientTaggingStore;
-  private readonly senderAddressBookStore: SenderAddressBookStore;
+  private readonly taggingSecretSourcesStore: TaggingSecretSourcesStore;
   private readonly capsuleStore: CapsuleStore;
+  private readonly factStore: FactStore;
   private readonly privateEventStore: PrivateEventStore;
   private readonly simulator: CircuitSimulator;
   private readonly contractSyncService: ContractSyncService;
-  private readonly messageContextService: MessageContextService;
+  private readonly txResolver: TxResolverService;
   private readonly hooks: ExecutionHooks | undefined;
 
   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;
@@ -179,12 +190,13 @@ export class ContractFunctionSimulator {
     this.l2TipsStore = args.l2TipsStore;
     this.senderTaggingStore = args.senderTaggingStore;
     this.recipientTaggingStore = args.recipientTaggingStore;
-    this.senderAddressBookStore = args.senderAddressBookStore;
+    this.taggingSecretSourcesStore = args.taggingSecretSourcesStore;
     this.capsuleStore = args.capsuleStore;
+    this.factStore = args.factStore;
     this.privateEventStore = args.privateEventStore;
     this.simulator = args.simulator;
     this.contractSyncService = args.contractSyncService;
-    this.messageContextService = args.messageContextService;
+    this.txResolver = args.txResolver;
     this.hooks = args.hooks;
     this.log = createLogger('simulator');
   }
@@ -196,9 +208,7 @@ export class ContractFunctionSimulator {
   public async run(
     request: TxExecutionRequest,
     {
-      contractAddress,
-      selector,
-      msgSender = AztecAddress.fromField(Fr.MAX_FIELD_VALUE),
+      msgSender = AztecAddress.NULL_MSG_SENDER,
       anchorBlockHeader,
       senderForTags,
       scopes,
@@ -207,18 +217,30 @@ export class ContractFunctionSimulator {
   ): Promise<PrivateExecutionResult> {
     const simulatorSetupTimer = new Timer();
 
-    const entryPointArtifact = await this.contractStore.getFunctionArtifactWithDebugMetadata(contractAddress, selector);
+    const contractAddress = request.origin;
 
-    if (entryPointArtifact.functionType !== FunctionType.PRIVATE) {
-      throw new Error(`Cannot run ${entryPointArtifact.functionType} function as private`);
-    }
+    const anchoredContractData = new AnchoredContractData(
+      this.contractStore,
+      this.contractClassService,
+      anchorBlockHeader,
+      this.overrides,
+    );
 
-    if (request.origin !== contractAddress) {
+    const entryPointArtifact = await anchoredContractData.getFunctionArtifactWithDebugMetadata(
+      contractAddress,
+      request.functionSelector,
+    );
+    if (!entryPointArtifact) {
       throw new Error(
-        `Request origin does not match contract address in simulation. Request origin: ${request.origin}, contract address: ${contractAddress}`,
+        `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`);
+    }
+
     // reserve the first side effect for the tx hash (inserted by the private kernel)
     const startSideEffectCounter = 2;
 
@@ -241,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) => {
@@ -251,17 +274,18 @@ export class ContractFunctionSimulator {
       executionCache: HashedValuesCache.create(request.argsOfCalls),
       noteCache,
       taggingIndexCache,
-      contractStore: this.contractStore,
+      anchoredContractData,
       noteStore: this.noteStore,
       keyStore: this.keyStore,
       addressStore: this.addressStore,
       aztecNode: this.aztecNode,
       senderTaggingStore: this.senderTaggingStore,
       recipientTaggingStore: this.recipientTaggingStore,
-      senderAddressBookStore: this.senderAddressBookStore,
+      taggingSecretSourcesStore: this.taggingSecretSourcesStore,
       capsuleService: new CapsuleService(this.capsuleStore, scopes),
+      factService: new FactService(this.factStore, scopes),
       privateEventStore: this.privateEventStore,
-      messageContextService: this.messageContextService,
+      txResolver: this.txResolver,
       contractSyncService: this.contractSyncService,
       jobId,
       totalPublicCalldataCount: 0,
@@ -290,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
@@ -314,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'));
     }
@@ -325,10 +348,6 @@ export class ContractFunctionSimulator {
   /**
    * Runs a utility function.
    * @param call - The function call to execute.
-   * @param authwits - Authentication witnesses required for the function call.
-   * @param anchorBlockHeader - The block header to use as base state for this run.
-   * @param scopes - Optional array of account addresses whose notes can be accessed in this call. Defaults to all
-   * accounts if not specified.
    * @returns A return value of the utility function in a form as returned by the simulator (Noir fields)
    */
   public async runUtility(
@@ -338,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`);
@@ -349,20 +381,26 @@ export class ContractFunctionSimulator {
     };
 
     const oracle = new UtilityExecutionOracle({
-      contractAddress: call.to,
+      callContext: CallContext.from({
+        msgSender: AztecAddress.NULL_MSG_SENDER,
+        contractAddress: call.to,
+        functionSelector: call.selector,
+        isStaticCall: true,
+      }),
       authWitnesses: authwits,
       capsules: [],
       anchorBlockHeader,
-      contractStore: this.contractStore,
+      anchoredContractData,
       noteStore: this.noteStore,
       keyStore: this.keyStore,
       addressStore: this.addressStore,
       aztecNode: this.aztecNode,
       recipientTaggingStore: this.recipientTaggingStore,
-      senderAddressBookStore: this.senderAddressBookStore,
+      taggingSecretSourcesStore: this.taggingSecretSourcesStore,
       capsuleService: new CapsuleService(this.capsuleStore, scopes),
+      factService: new FactService(this.factStore, scopes),
       privateEventStore: this.privateEventStore,
-      messageContextService: this.messageContextService,
+      txResolver: this.txResolver,
       contractSyncService: this.contractSyncService,
       l2TipsStore: this.l2TipsStore,
       jobId,
@@ -617,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
@@ -885,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

@@ -1,40 +1,47 @@
 export {
   ORACLE_REGISTRY,
   makeEntry,
-  type HandlersForPrefix,
   type NamedValue,
   type OracleRegistryEntry,
   type ParamTypes,
-  type StripOraclePrefix,
 } from './oracle/oracle_registry.js';
 export {
   ARRAY,
   AZTEC_ADDRESS,
   BIGINT,
+  BLOCK_HASH,
   BLOCK_NUMBER,
   BOOL,
   BOUNDED_VEC,
   BUFFER,
   BYTE,
+  CONTRACT_INSTANCE,
   DELIVERY_MODE,
   EPHEMERAL_ARRAY,
+  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';
@@ -42,22 +49,30 @@ export { ExecutionTaggingIndexCache } from './execution_tagging_index_cache.js';
 export { HashedValuesCache } from './hashed_values_cache.js';
 export { pickNotes } from './pick_notes.js';
 export type { IMiscOracle, IUtilityExecutionOracle, IPrivateExecutionOracle } from './oracle/interfaces.js';
+export type { FactCollection } from './noir-structs/fact_collection.js';
 export type { NoteData } from './noir-structs/note_data.js';
-export { MessageLoadOracleInputs } from './oracle/message_load_oracle_inputs.js';
-export { MessageContextService } from '../messages/message_context_service.js';
+export type { ResolvedTaggingStrategy } from './noir-structs/resolved_tagging_strategy.js';
+export type { MessageLoadOracleInputs } from './oracle/message_load_oracle_inputs.js';
+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';
 export { BoundedVec } from './noir-structs/bounded_vec.js';
+export type { ContractClassLogData } from './noir-structs/contract_class_log_data.js';
+export type { EmbeddedCurvePoint } from './noir-structs/embedded_curve_point.js';
 export { EphemeralArray } from './noir-structs/ephemeral_array.js';
 export { Option } from './noir-structs/option.js';
-export { UtilityContext } from './noir-structs/utility_context.js';
+export type { UtilityContext } from './noir-structs/utility_context.js';
 export { EventValidationRequest } from './noir-structs/event_validation_request.js';
-export { LogRetrievalRequest } from './noir-structs/log_retrieval_request.js';
-export { LogRetrievalResponse } from './noir-structs/log_retrieval_response.js';
+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 { ProvidedSecret } from './noir-structs/provided_secret.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';
 export { TransientArrayService } from './transient_array_service.js';

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

@@ -1,9 +1,4 @@
-/**
- * TypeScript counterpart of Noir's `BoundedVec<T, MaxLen>`.
- *
- * Carries the actual `data` plus wire-format metadata (`maxLength`, `elementSize`) so the ACVM
- * serializer can pad the storage slot to exactly `maxLength * elementSize` fields.
- */
+/** TypeScript counterpart of Noir's `BoundedVec<T, MaxLen>`. */
 export class BoundedVec<T> {
   private constructor(
     public readonly data: T[],
@@ -15,16 +10,11 @@ export class BoundedVec<T> {
    * Construct a BoundedVec with data.
    *
    * @param data - Actual elements. Length must be `<= maxLength`.
-   * @param maxLength - Maximum capacity declared at the Noir call site.
-   *   The storage slot is padded to this many elements.
-   * @param elementSize - Number of Fr fields each element contributes when serialized.
-   *   `1` for scalar elements (u8, Field) — this is the default.
-   *   `> 1` for compound elements (e.g. a packed note that spans multiple fields).
-   *
-   * @example A bounded vec of bytes (elementSize defaults to 1):
-   * ```ts
-   * BoundedVec.from({ data: plaintext, maxLength: ciphertext.maxLength })
-   * ```
+   * @param maxLength - Maximum capacity declared at the Noir call site. The storage slot is padded to this many
+   *   elements.
+   * @param elementSize - Number of Fr fields each element contributes when serialized. Only consulted for
+   *   variable-width elements whose width isn't statically known from their shape (e.g. a packed note spanning
+   *   `packedHintedNoteLength` fields); fixed-width elements derive it from the shape, so it can be omitted.
    *
    * @example A bounded vec of packed notes, each spanning `packedHintedNoteLength` fields:
    * ```ts
@@ -43,13 +33,11 @@ export class BoundedVec<T> {
     return new BoundedVec<T>(data, maxLength, elementSize);
   }
 
-  /**
-   * Construct an empty BoundedVec, typically used as a shape template for `Option.empty(...)`.
-   *
-   * @param maxLength - Maximum capacity declared at the Noir call site.
-   * @param elementSize - Number of Fr fields each element contributes when serialized (default 1).
-   */
-  static empty<T>({ maxLength, elementSize = 1 }: { maxLength: number; elementSize?: number }): BoundedVec<T> {
-    return new BoundedVec<T>([], maxLength, elementSize);
+  equals(other: BoundedVec<T>, innerEquals: (a: T, b: T) => boolean): boolean {
+    return (
+      this.maxLength === other.maxLength &&
+      this.data.length === other.data.length &&
+      this.data.every((value, i) => innerEquals(value, other.data[i]))
+    );
   }
 }

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

@@ -0,0 +1,9 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+/** Wire form of a contract class log. */
+export type ContractClassLogData = {
+  contractAddress: AztecAddress;
+  fields: Fr[];
+  emittedLength: number;
+};

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

@@ -0,0 +1,4 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+
+/** Wire form of a Grumpkin point crossing the oracle boundary: Noir's `EmbeddedCurvePoint` serializes to `[x, y]`. */
+export type EmbeddedCurvePoint = { x: Fr; y: Fr };

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

@@ -21,7 +21,7 @@ export class EventValidationRequest {
   static fromFields(fields: Fr[] | FieldReader): EventValidationRequest {
     const reader = FieldReader.asReader(fields);
 
-    const contractAddress = AztecAddress.fromField(reader.readField());
+    const contractAddress = AztecAddress.fromFieldUnsafe(reader.readField());
     const eventTypeId = EventSelector.fromField(reader.readField());
 
     const randomness = reader.readField();

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

@@ -0,0 +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';
+
+/**
+ * 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 (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<RetractableFactOrigin> };

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

@@ -0,0 +1,64 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+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';
+import { Option } from './option.js';
+
+/**
+ * A fact collection.
+ */
+export type FactCollection = {
+  contractAddress: AztecAddress;
+  scope: AztecAddress;
+  factCollectionTypeId: Fr;
+  factCollectionId: Fr;
+  facts: EphemeralArray<Fact>;
+};
+
+/**
+ * Builds the Noir-facing `FactCollection` from stored facts.
+ */
+export function toNoirFactCollection(
+  service: EphemeralArrayService,
+  contractAddress: AztecAddress,
+  scope: AztecAddress,
+  factCollectionTypeId: Fr,
+  factCollectionId: Fr,
+  facts: FactWithOriginState[],
+): FactCollection {
+  return {
+    contractAddress,
+    scope,
+    factCollectionTypeId,
+    factCollectionId,
+    facts: EphemeralArray.fromValues(
+      service,
+      facts.map(
+        (fact: FactWithOriginState): Fact => ({
+          factTypeId: fact.factTypeId,
+          payload: EphemeralArray.fromValues(service, fact.payload),
+          originBlock: fact.originBlock
+            ? Option.some(fact.originBlock)
+            : Option.none<RetractableFactOrigin>({
+                blockNumber: 0,
+                blockHash: Fr.ZERO,
+                blockState: OriginBlockState.Pending,
+              }),
+        }),
+      ),
+    ),
+  };
+}
+
+/**
+ * A zeroed `FactCollection` used only as a serialization shape template for the `None` case of
+ * `Option<FactCollection>`. Noir's `Option<T>` is fixed-width on the wire, so `None` must emit the same number of
+ * (zeroed) field slots as `Some`.
+ **/
+export function emptyFactCollection(service: EphemeralArrayService): FactCollection {
+  return toNoirFactCollection(service, AztecAddress.ZERO, AztecAddress.ZERO, Fr.ZERO, Fr.ZERO, []);
+}