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

package/src/block_synchronizer/block_synchronizer.ts

@@ -10,6 +10,7 @@ import type { BlockHeader } from '@aztec/stdlib/tx';
 import type { BlockSynchronizerConfig } from '../config/index.js';
 import type { ContractSyncService } from '../contract_sync/contract_sync_service.js';
 import type { AnchorBlockStore } from '../storage/anchor_block_store/index.js';
+import type { FactStore } from '../storage/fact_store/fact_store.js';
 import type { NoteStore } from '../storage/note_store/index.js';
 import type { PrivateEventStore } from '../storage/private_event_store/private_event_store.js';
 import { blockStreamSourceFromAztecNode } from './block_stream_source.js';
@@ -26,32 +27,32 @@ export class BlockSynchronizer implements L2BlockStreamEventHandler {
   protected readonly blockStream: L2BlockStream;
 
   constructor(
-    private node: AztecNode,
-    private store: AztecAsyncKVStore,
-    private anchorBlockStore: AnchorBlockStore,
-    private noteStore: NoteStore,
-    private privateEventStore: PrivateEventStore,
-    private l2TipsStore: L2TipsKVStore,
-    private contractSyncService: ContractSyncService,
-    private config: Partial<BlockSynchronizerConfig> = {},
+    private readonly node: AztecNode,
+    private readonly store: AztecAsyncKVStore,
+    private readonly anchorBlockStore: AnchorBlockStore,
+    private readonly noteStore: NoteStore,
+    private readonly privateEventStore: PrivateEventStore,
+    private readonly factStore: FactStore,
+    private readonly l2TipsStore: L2TipsKVStore,
+    private readonly contractSyncService: ContractSyncService,
+    private readonly config: Partial<BlockSynchronizerConfig> = {},
     bindings?: LoggerBindings,
   ) {
     this.log = createLogger('pxe:block_synchronizer', bindings);
-    this.blockStream = this.createBlockStream(config);
+    this.blockStream = this.createBlockStream();
     this.eventQueue.start();
   }
 
-  protected createBlockStream(config: Partial<BlockSynchronizerConfig>): L2BlockStream {
+  protected createBlockStream(): L2BlockStream {
     return new L2BlockStream(
       blockStreamSourceFromAztecNode(this.node),
       this.l2TipsStore,
       this,
       createLogger('pxe:block_stream', this.log.getBindings()),
       {
-        batchSize: config.l2BlockBatchSize,
-        // Skipping finalized blocks makes us sync much faster - we only need to download blocks other than the latest one
-        // in order to detect reorgs, and there can be no reorgs on finalized block, making this safe.
-        skipFinalized: true,
+        // PXE only tracks chain tips (it anchors on tip events and never replays payloads), so the stream runs
+        // in tips-only mode: no block downloads, just the tip events that move the anchor and detect reorgs.
+        tipsOnly: true,
       },
     );
   }
@@ -62,21 +63,43 @@ export class BlockSynchronizer implements L2BlockStreamEventHandler {
   }
 
   private async doHandleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void> {
-    await this.l2TipsStore.handleBlockStreamEvent(event);
-
     switch (event.type) {
-      case 'blocks-added': {
+      case 'chain-proposed': {
         if (this.config.syncChainTip === undefined || this.config.syncChainTip === 'proposed') {
-          const lastBlock = event.blocks.at(-1)!;
-          await this.updateAnchorBlockHeader(lastBlock.header);
+          // Fetch the proposed tip header by hash. By-hash is safer than by-number against a same-height reorg.
+          const block = await this.node.getBlockData(BlockHash.fromString(event.block.hash));
+          if (!block) {
+            // The node served a proposed tip whose block data it cannot return — a node inconsistency, since the
+            // stream events and the block data come from the same node (same reasoning as the chain-pruned throw
+            // below). Throwing here propagates before the tips-store cursor advances, so the cursor stays put and the
+            // next sync re-emits chain-proposed (at-least-once). Were we to warn-and-skip, the cursor would advance and
+            // a quiet chain would never re-emit, leaving the anchor stale indefinitely.
+            throw new Error(
+              `Block header for proposed block ${event.block.number} and hash ${event.block.hash} not found. This ` +
+                `likely indicates a bug in the node, as we receive block stream events and fetch block headers from ` +
+                `the same node.`,
+            );
+          }
+          await this.updateAnchorBlockHeader(block.header);
         }
         break;
       }
+      // Never emitted in tips-only mode; PXE anchors on chain-proposed instead. Kept for union exhaustiveness.
+      case 'blocks-added':
+        break;
       case 'chain-checkpointed': {
         if (this.config.syncChainTip === 'checkpointed') {
-          // Get the last block header from the checkpoint
-          const lastBlock = event.checkpoint.checkpoint.blocks.at(-1)!;
-          await this.updateAnchorBlockHeader(lastBlock.header);
+          // Fetch the checkpointed tip header by hash. By-hash is safer than by-number against a
+          // same-height reorg; a missing result means the block was reorged out between the event
+          // and this fetch, so we skip the anchor update and let a later event correct it.
+          const block = await this.node.getBlockData(BlockHash.fromString(event.block.hash));
+          if (block) {
+            await this.updateAnchorBlockHeader(block.header);
+          } else {
+            this.log.warn(
+              `Block header not found for checkpointed block ${event.block.number}, skipping anchor update`,
+            );
+          }
         }
         break;
       }
@@ -110,7 +133,7 @@ export class BlockSynchronizer implements L2BlockStreamEventHandler {
             `Ignoring prune event to block ${event.block.number} greater than current anchor block ${currentAnchorBlockNumber}`,
             { pruneEvent: event, currentAnchorBlockHeader: currentAnchorBlockHeader.toInspect() },
           );
-          return;
+          break;
         }
 
         this.log.warn(`Pruning data after block ${event.block.number} due to reorg`, { pruneBlock: event.block });
@@ -131,11 +154,21 @@ export class BlockSynchronizer implements L2BlockStreamEventHandler {
         await this.store.transactionAsync(async () => {
           await this.noteStore.rollback(event.block.number);
           await this.privateEventStore.rollback(event.block.number);
+          await this.factStore.rollback(event.block.number);
           await this.updateAnchorBlockHeader(newAnchorBlockHeader);
         });
         break;
       }
+      default: {
+        const _: never = event;
+        break;
+      }
     }
+
+    // Advance the tips store cursor only after the anchor update / prune rollback above succeeds. If that work
+    // throws, the cursor stays put and the stream re-emits this event on the next sync pass (at-least-once),
+    // matching the prover-node's handle-first/tips-last ordering. The SerialQueue makes this reorder safe.
+    await this.l2TipsStore.handleBlockStreamEvent(event);
   }
 
   /** Updates the anchor block header to the target block */

package/src/config/index.ts

@@ -10,6 +10,7 @@ import { type ChainConfig, chainConfigMappings } from '@aztec/stdlib/config';
 import { type DataStoreConfig, dataConfigMappings } from '@aztec/stdlib/kv-store';
 
 export { getPackageInfo } from './package_info.js';
+export * from '../hooks/index.js';
 
 /**
  * Configuration settings for the prover factory

package/src/contract_function_simulator/contract_function_simulator.ts

@@ -92,16 +92,18 @@ import {
 
 import type { ContractSyncService } from '../contract_sync/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 type { BenchmarkedNode } from './benchmarked_node.js';
 import { ExecutionNoteCache } from './execution_note_cache.js';
 import { ExecutionTaggingIndexCache } from './execution_tagging_index_cache.js';
@@ -114,10 +116,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. */
@@ -140,12 +138,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;
 };
 
@@ -162,12 +161,13 @@ 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) {
@@ -179,12 +179,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 +197,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 +206,17 @@ export class ContractFunctionSimulator {
   ): Promise<PrivateExecutionResult> {
     const simulatorSetupTimer = new Timer();
 
-    const entryPointArtifact = await this.contractStore.getFunctionArtifactWithDebugMetadata(contractAddress, selector);
+    const contractAddress = request.origin;
+
+    const entryPointArtifact = await this.contractStore.getFunctionArtifactWithDebugMetadata(
+      contractAddress,
+      request.functionSelector,
+    );
 
     if (entryPointArtifact.functionType !== FunctionType.PRIVATE) {
       throw new Error(`Cannot run ${entryPointArtifact.functionType} function as private`);
     }
 
-    if (request.origin !== contractAddress) {
-      throw new Error(
-        `Request origin does not match contract address in simulation. Request origin: ${request.origin}, contract address: ${contractAddress}`,
-      );
-    }
-
     // reserve the first side effect for the tx hash (inserted by the private kernel)
     const startSideEffectCounter = 2;
 
@@ -258,10 +256,11 @@ export class ContractFunctionSimulator {
       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,
@@ -325,10 +324,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(
@@ -349,7 +344,12 @@ 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,
@@ -359,10 +359,11 @@ export class ContractFunctionSimulator {
       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,

package/src/contract_function_simulator/index.ts

@@ -1,23 +1,24 @@
 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,
   FUNCTION_SELECTOR,
@@ -25,6 +26,7 @@ export {
   LOG_RETRIEVAL_RESPONSE,
   MEMBERSHIP_WITNESS,
   MESSAGE_CONTEXT,
+  NOTE_SELECTOR,
   NOTE_VALIDATION_REQUEST,
   OPTION,
   PENDING_TAGGED_LOG,
@@ -35,6 +37,7 @@ export {
   type InputSlot,
   type MaybePromise,
   type OutputSlot,
+  type SlotShape,
   type TypeMapping,
 } from './oracle/oracle_type_mappings.js';
 export { ExecutionNoteCache } from './execution_note_cache.js';
@@ -42,9 +45,11 @@ 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';
@@ -52,12 +57,16 @@ export { executePrivateFunction, extractPrivateCircuitPublicInputs } from './ora
 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 { 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 { 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.
+ */
+export type Fact = { factTypeId: Fr; payload: EphemeralArray<Fr>; originBlock: Option<OriginBlock> };

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

@@ -0,0 +1,59 @@
+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 { 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: FactFromStore[],
+): FactCollection {
+  return {
+    contractAddress,
+    scope,
+    factCollectionTypeId,
+    factCollectionId,
+    facts: EphemeralArray.fromValues(
+      service,
+      facts.map(
+        (fact: FactFromStore): 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 }),
+        }),
+      ),
+    ),
+  };
+}
+
+/**
+ * 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, []);
+}

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

@@ -1,8 +1,9 @@
-import { BlockNumber } from '@aztec/foundation/branded-types';
+import type { BlockNumber } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/curves/bn254';
-import { FieldReader } from '@aztec/foundation/serialize';
-import { AztecAddress } from '@aztec/stdlib/aztec-address';
-import { Tag } from '@aztec/stdlib/logs';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { Tag } from '@aztec/stdlib/logs';
+
+import type { Option } from './option.js';
 
 /** Discriminant for which log source to query. */
 export enum LogSource {
@@ -15,47 +16,20 @@ export enum LogSource {
  * Intermediate struct used to perform batch log retrieval by PXE. The `utilityBulkRetrieveLogs` oracle expects values of this
  * type to be stored in a `EphemeralArray`.
  */
-export class LogRetrievalRequest {
-  constructor(
-    public contractAddress: AztecAddress,
-    public tag: Tag,
-    public source: LogSource = LogSource.PUBLIC_AND_PRIVATE,
-    public fromBlock?: BlockNumber,
-    public toBlock?: BlockNumber,
-  ) {}
-
-  toFields(): Fr[] {
-    return [
-      this.contractAddress.toField(),
-      this.tag.value,
-      new Fr(this.source),
-      new Fr(this.fromBlock !== undefined ? 1 : 0),
-      new Fr(this.fromBlock ?? 0),
-      new Fr(this.toBlock !== undefined ? 1 : 0),
-      new Fr(this.toBlock ?? 0),
-    ];
-  }
-
-  static fromFields(fields: Fr[] | FieldReader): LogRetrievalRequest {
-    const reader = FieldReader.asReader(fields);
-
-    const contractAddress = AztecAddress.fromField(reader.readField());
-    const tag = new Tag(reader.readField());
-    const sourceNum = reader.readField().toNumber();
-    if (!(sourceNum in LogSource)) {
-      const validNames = Object.keys(LogSource).filter(k => isNaN(Number(k)));
-      throw new Error(`Invalid LogSource value ${sourceNum}, expected one of ${validNames.join(', ')}`);
-    }
-    const source = sourceNum as LogSource;
-
-    const fromBlockIsSome = reader.readBoolean();
-    const fromBlockValue = reader.readField();
-    const fromBlock = fromBlockIsSome ? BlockNumber(fromBlockValue.toNumber()) : undefined;
-
-    const toBlockIsSome = reader.readBoolean();
-    const toBlockValue = reader.readField();
-    const toBlock = toBlockIsSome ? BlockNumber(toBlockValue.toNumber()) : undefined;
-
-    return new LogRetrievalRequest(contractAddress, tag, source, fromBlock, toBlock);
+export type LogRetrievalRequest = {
+  contractAddress: AztecAddress;
+  tag: Tag;
+  source: LogSource;
+  fromBlock: Option<BlockNumber>;
+  toBlock: Option<BlockNumber>;
+};
+
+/** Parses a `LogSource` from its wire field, throwing on an out-of-range value. */
+export function logSourceFromField(field: Fr): LogSource {
+  const sourceNum = field.toNumber();
+  if (!(sourceNum in LogSource)) {
+    const validNames = Object.keys(LogSource).filter(k => isNaN(Number(k)));
+    throw new Error(`Invalid LogSource value ${sourceNum}, expected one of ${validNames.join(', ')}`);
   }
+  return sourceNum as LogSource;
 }