@aztec/p2p 0.0.1-commit.4d79d1f2d → 0.0.1-commit.4d9804df

package/src/services/tx_collection/config.ts

@@ -1,26 +1,9 @@
-import {
-  type ConfigMappingsType,
-  booleanConfigHelper,
-  enumConfigHelper,
-  numberConfigHelper,
-} from '@aztec/foundation/config';
+import { type ConfigMappingsType, numberConfigHelper } from '@aztec/foundation/config';
 import { MAX_RPC_TXS_LEN } from '@aztec/stdlib/interfaces/api-limit';
 
-export type MissingTxsCollectorType = 'new' | 'old';
-
 export type TxCollectionConfig = {
   /** How long to wait before starting reqresp for fast collection  */
   txCollectionFastNodesTimeoutBeforeReqRespMs: number;
-  /** How often to collect from configured nodes */
-  txCollectionSlowNodesIntervalMs: number;
-  /** How ofter to collect from peers */
-  txCollectionSlowReqRespIntervalMs: number;
-  /** How long to wait for a reqresp response during slow collection */
-  txCollectionSlowReqRespTimeoutMs: number;
-  /** How often to reconcile found txs with the tx pool */
-  txCollectionReconcileIntervalMs: number;
-  /** Whether to disable the slow collection loop if we are dealing with any immediate requests */
-  txCollectionDisableSlowDuringFastRequests: boolean;
   /** How many ms to wait between retried request to a node via RPC during fast collection */
   txCollectionFastNodeIntervalMs: number;
   /** A comma-separated list of Aztec node RPC URLs to use for tx collection */
@@ -29,14 +12,16 @@ export type TxCollectionConfig = {
   txCollectionFastMaxParallelRequestsPerNode: number;
   /** Maximum number of transactions to request from a node in a single batch */
   txCollectionNodeRpcMaxBatchSize: number;
-  /** Which collector implementation to use for missing txs collection */
-  txCollectionMissingTxsCollectorType: MissingTxsCollectorType;
   /** A comma-separated list of file store URLs (s3://, gs://, file://, http://) for tx collection */
   txCollectionFileStoreUrls: string[];
-  /** Delay in ms before file store collection starts after slow collection is triggered */
-  txCollectionFileStoreSlowDelayMs: number;
-  /** Delay in ms before file store collection starts after fast collection is triggered */
+  /** Delay in ms from reqresp start before file store collection begins */
   txCollectionFileStoreFastDelayMs: number;
+  /** Number of concurrent workers for fast file store collection */
+  txCollectionFileStoreFastWorkerCount: number;
+  /** Base backoff time in ms for fast file store collection retries */
+  txCollectionFileStoreFastBackoffBaseMs: number;
+  /** Max backoff time in ms for fast file store collection retries */
+  txCollectionFileStoreFastBackoffMaxMs: number;
 };
 
 export const txCollectionConfigMappings: ConfigMappingsType<TxCollectionConfig> = {
@@ -45,31 +30,6 @@ export const txCollectionConfigMappings: ConfigMappingsType<TxCollectionConfig>
     description: 'How long to wait before starting reqresp for fast collection',
     ...numberConfigHelper(200),
   },
-  txCollectionSlowNodesIntervalMs: {
-    env: 'TX_COLLECTION_SLOW_NODES_INTERVAL_MS',
-    description: 'How often to collect from configured nodes in the slow collection loop',
-    ...numberConfigHelper(12_000),
-  },
-  txCollectionSlowReqRespIntervalMs: {
-    env: 'TX_COLLECTION_SLOW_REQ_RESP_INTERVAL_MS',
-    description: 'How often to collect from peers via reqresp in the slow collection loop',
-    ...numberConfigHelper(12_000),
-  },
-  txCollectionSlowReqRespTimeoutMs: {
-    env: 'TX_COLLECTION_SLOW_REQ_RESP_TIMEOUT_MS',
-    description: 'How long to wait for a reqresp response during slow collection',
-    ...numberConfigHelper(20_000),
-  },
-  txCollectionReconcileIntervalMs: {
-    env: 'TX_COLLECTION_RECONCILE_INTERVAL_MS',
-    description: 'How often to reconcile found txs from the tx pool',
-    ...numberConfigHelper(60_000),
-  },
-  txCollectionDisableSlowDuringFastRequests: {
-    env: 'TX_COLLECTION_DISABLE_SLOW_DURING_FAST_REQUESTS',
-    description: 'Whether to disable the slow collection loop if we are dealing with any immediate requests',
-    ...booleanConfigHelper(true),
-  },
   txCollectionFastNodeIntervalMs: {
     env: 'TX_COLLECTION_FAST_NODE_INTERVAL_MS',
     description: 'How many ms to wait between retried request to a node via RPC during fast collection',
@@ -96,11 +56,6 @@ export const txCollectionConfigMappings: ConfigMappingsType<TxCollectionConfig>
     description: 'Maximum number of transactions to request from a node in a single batch',
     ...numberConfigHelper(MAX_RPC_TXS_LEN),
   },
-  txCollectionMissingTxsCollectorType: {
-    env: 'TX_COLLECTION_MISSING_TXS_COLLECTOR_TYPE',
-    description: 'Which collector implementation to use for missing txs collection (new or old)',
-    ...enumConfigHelper(['new', 'old'] as const, 'new'),
-  },
   txCollectionFileStoreUrls: {
     env: 'TX_COLLECTION_FILE_STORE_URLS',
     description: 'A comma-separated list of file store URLs (s3://, gs://, file://, http://) for tx collection',
@@ -111,14 +66,24 @@ export const txCollectionConfigMappings: ConfigMappingsType<TxCollectionConfig>
         .filter(url => url.length > 0),
     defaultValue: [],
   },
-  txCollectionFileStoreSlowDelayMs: {
-    env: 'TX_COLLECTION_FILE_STORE_SLOW_DELAY_MS',
-    description: 'Delay before file store collection starts after slow collection',
-    ...numberConfigHelper(24_000),
-  },
   txCollectionFileStoreFastDelayMs: {
     env: 'TX_COLLECTION_FILE_STORE_FAST_DELAY_MS',
-    description: 'Delay before file store collection starts after fast collection',
+    description: 'Delay in ms from reqresp start before file store collection begins',
     ...numberConfigHelper(2_000),
   },
+  txCollectionFileStoreFastWorkerCount: {
+    env: 'TX_COLLECTION_FILE_STORE_FAST_WORKER_COUNT',
+    description: 'Number of concurrent workers for fast file store collection',
+    ...numberConfigHelper(5),
+  },
+  txCollectionFileStoreFastBackoffBaseMs: {
+    env: 'TX_COLLECTION_FILE_STORE_FAST_BACKOFF_BASE_MS',
+    description: 'Base backoff time in ms for fast file store collection retries',
+    ...numberConfigHelper(1_000),
+  },
+  txCollectionFileStoreFastBackoffMaxMs: {
+    env: 'TX_COLLECTION_FILE_STORE_FAST_BACKOFF_MAX_MS',
+    description: 'Max backoff time in ms for fast file store collection retries',
+    ...numberConfigHelper(5_000),
+  },
 };

package/src/services/tx_collection/file_store_tx_collection.ts

@@ -1,136 +1,96 @@
+import { times } from '@aztec/foundation/collection';
 import { type Logger, createLogger } from '@aztec/foundation/log';
-import { FifoMemoryQueue } from '@aztec/foundation/queue';
-import { Tx, TxHash } from '@aztec/stdlib/tx';
+import { sleep } from '@aztec/foundation/sleep';
+import { DateProvider } from '@aztec/foundation/timer';
+import { TxHash } from '@aztec/stdlib/tx';
 
 import type { FileStoreTxSource } from './file_store_tx_source.js';
+import type { IRequestTracker } from './request_tracker.js';
 import type { TxAddContext, TxCollectionSink } from './tx_collection_sink.js';
 
-// Internal constants (not configurable by node operators)
-const FILE_STORE_DOWNLOAD_CONCURRENCY = 5; // Max concurrent downloads
+/** Configuration for a FileStoreTxCollection instance. */
+export type FileStoreCollectionConfig = {
+  workerCount: number;
+  backoffBaseMs: number;
+  backoffMaxMs: number;
+};
+
+type FileStoreTxEntry = {
+  txHash: string;
+  attempts: number;
+  lastAttemptTime: number;
+  nextSourceIndex: number;
+};
 
 /**
  * Collects txs from file stores as a fallback after P2P methods have been tried.
- * Runs in parallel to slow/fast collection. The delay before starting file store
- * collection is managed by the TxCollection orchestrator, not this class.
+ * Each call to startCollecting spins up its own worker pool which pulls entries with priority
+ * (fewest attempts first), retries with round-robin across sources, and applies exponential
+ * backoff between full cycles through all sources. Workers self-terminate when the request
+ * tracker is cancelled (deadline / all-fetched / external) or when there is nothing left to do.
  */
 export class FileStoreTxCollection {
-  /** Map from tx hash to add context for txs queued for download. */
-  private pendingTxs = new Map<string, TxAddContext>();
-
-  /**
-   * Tracks tx hashes found elsewhere, even before startCollecting is called.
-   * Needed because the orchestrator delays startCollecting via a real sleep, but foundTxs
-   * may arrive during that delay — before the hashes are added to pendingTxs.
-   */
-  private foundTxHashes = new Set<string>();
-
-  /** Queue of tx hashes to be downloaded. */
-  private downloadQueue = new FifoMemoryQueue<TxHash>();
-
-  /** Worker promises for concurrent downloads. */
-  private workers: Promise<void>[] = [];
-
-  /** Whether the collection has been started. */
-  private started = false;
-
   constructor(
-    private readonly fileStoreSources: FileStoreTxSource[],
+    private readonly sources: FileStoreTxSource[],
     private readonly txCollectionSink: TxCollectionSink,
+    private readonly config: FileStoreCollectionConfig,
+    private readonly dateProvider: DateProvider = new DateProvider(),
     private readonly log: Logger = createLogger('p2p:file_store_tx_collection'),
   ) {}
 
-  /** Starts the file store collection workers. */
-  public start() {
-    if (this.fileStoreSources.length === 0) {
-      this.log.debug('No file store sources configured, skipping file store collection');
+  /**
+   * Spins up workers to download all txs still missing from the tracker, racing across the
+   * configured file store sources. Resolves once all workers settle.
+   */
+  public async startCollecting(requestTracker: IRequestTracker, context: TxAddContext): Promise<void> {
+    if (this.sources.length === 0 || requestTracker.checkCancelled()) {
       return;
     }
 
-    this.started = true;
-    this.downloadQueue = new FifoMemoryQueue<TxHash>();
-
-    // Start concurrent download workers
-    for (let i = 0; i < FILE_STORE_DOWNLOAD_CONCURRENCY; i++) {
-      this.workers.push(this.downloadQueue.process(txHash => this.processDownload(txHash)));
+    // eslint-disable-next-line aztec-custom/no-non-primitive-in-collections
+    const entries: Set<FileStoreTxEntry> = new Set();
+    for (const hashStr of requestTracker.missingTxHashes) {
+      entries.add({
+        txHash: hashStr,
+        attempts: 0,
+        lastAttemptTime: 0,
+        nextSourceIndex: Math.floor(Math.random() * this.sources.length),
+      });
     }
 
-    this.log.info(`Started file store tx collection with ${this.fileStoreSources.length} sources`, {
-      sources: this.fileStoreSources.map(s => s.getInfo()),
-      concurrency: FILE_STORE_DOWNLOAD_CONCURRENCY,
-    });
-  }
-
-  /** Stops all collection activity. */
-  public async stop() {
-    if (!this.started) {
+    // Yield before spawning so the synchronous caller can finish any follow-up (eg. marking a tx
+    // as fetched on the tracker, or cancelling it) before workers begin scanning entries.
+    await Promise.resolve();
+    if (requestTracker.checkCancelled()) {
       return;
     }
-    this.started = false;
-    this.downloadQueue.end();
-    await Promise.all(this.workers);
-    this.workers = [];
-    this.pendingTxs.clear();
-    this.foundTxHashes.clear();
-  }
-
-  /** Remove the given tx hashes from pending. */
-  public stopCollecting(txHashes: TxHash[]) {
-    for (const txHash of txHashes) {
-      const hashStr = txHash.toString();
-      this.pendingTxs.delete(hashStr);
-    }
-  }
 
-  /** Clears all pending state. Items already in the download queue will still be processed but won't be re-queued. */
-  public clearPending() {
-    this.pendingTxs.clear();
-    this.foundTxHashes.clear();
+    await Promise.allSettled(times(this.config.workerCount, () => this.workerLoop(entries, requestTracker, context)));
   }
 
-  /** Queue the given tx hashes for file store collection. */
-  public startCollecting(txHashes: TxHash[], context: TxAddContext) {
-    for (const txHash of txHashes) {
-      const hashStr = txHash.toString();
-      if (!this.pendingTxs.has(hashStr) && !this.foundTxHashes.has(hashStr)) {
-        this.pendingTxs.set(hashStr, context);
-        this.downloadQueue.put(txHash);
+  private async workerLoop(
+    // eslint-disable-next-line aztec-custom/no-non-primitive-in-collections
+    entries: Set<FileStoreTxEntry>,
+    requestTracker: IRequestTracker,
+    context: TxAddContext,
+  ): Promise<void> {
+    while (!requestTracker.checkCancelled() && entries.size > 0) {
+      const action = this.getNextAction(entries, requestTracker);
+      if (action.type === 'sleep') {
+        await Promise.race([sleep(action.ms), requestTracker.cancellationToken]);
+        continue;
       }
-    }
-  }
 
-  /** Stop tracking txs that were found elsewhere. */
-  public foundTxs(txs: Tx[]) {
-    for (const tx of txs) {
-      const hashStr = tx.getTxHash().toString();
-      this.pendingTxs.delete(hashStr);
-      this.foundTxHashes.add(hashStr);
-    }
-  }
-
-  /** Processes a single tx hash from the download queue. */
-  private async processDownload(txHash: TxHash) {
-    const hashStr = txHash.toString();
-    const context = this.pendingTxs.get(hashStr);
-
-    // Skip if already found by another method
-    if (!context) {
-      return;
-    }
-
-    await this.downloadTx(txHash, context);
-    this.pendingTxs.delete(hashStr);
-  }
-
-  /** Attempt to download a tx from file stores (round-robin). */
-  private async downloadTx(txHash: TxHash, context: TxAddContext) {
-    const startIndex = Math.floor(Math.random() * this.fileStoreSources.length);
-    for (let i = startIndex; i < startIndex + this.fileStoreSources.length; i++) {
-      const source = this.fileStoreSources[i % this.fileStoreSources.length];
+      const entry = action.entry;
+      const source = this.sources[entry.nextSourceIndex % this.sources.length];
+      entry.nextSourceIndex++;
+      entry.attempts++;
+      entry.lastAttemptTime = this.dateProvider.now();
 
       try {
         const result = await this.txCollectionSink.collect(
-          hashes => source.getTxsByHash(hashes),
-          [txHash],
+          () => source.getTxsByHash([TxHash.fromString(entry.txHash)]),
+          [entry.txHash],
           {
             description: `file-store ${source.getInfo()}`,
             method: 'file-store',
@@ -138,15 +98,56 @@ export class FileStoreTxCollection {
           },
           context,
         );
-
         if (result.txs.length > 0) {
-          return;
+          entries.delete(entry);
         }
       } catch (err) {
-        this.log.trace(`Failed to download tx ${txHash} from ${source.getInfo()}`, { err });
+        this.log.trace(`Error downloading tx ${entry.txHash} from ${source.getInfo()}`, { err });
       }
     }
+  }
 
-    this.log.trace(`Tx ${txHash} not found in any file store`);
+  /** Single-pass scan: removes stale entries, finds the best ready entry, or computes sleep time. */
+  private getNextAction(
+    // eslint-disable-next-line aztec-custom/no-non-primitive-in-collections
+    entries: Set<FileStoreTxEntry>,
+    requestTracker: IRequestTracker,
+  ): { type: 'process'; entry: FileStoreTxEntry } | { type: 'sleep'; ms: number } {
+    const now = this.dateProvider.now();
+    let best: FileStoreTxEntry | undefined;
+    let earliestReadyAt = Infinity;
+
+    for (const entry of entries) {
+      // Drop entries whose tx was already found via another collection path.
+      if (!requestTracker.isMissing(entry.txHash)) {
+        entries.delete(entry);
+        continue;
+      }
+      const backoffMs = this.getBackoffMs(entry);
+      const readyAt = entry.lastAttemptTime + backoffMs;
+      if (readyAt > now) {
+        earliestReadyAt = Math.min(earliestReadyAt, readyAt);
+        continue;
+      }
+      if (!best || entry.attempts < best.attempts) {
+        best = entry;
+      }
+    }
+
+    if (best) {
+      return { type: 'process', entry: best };
+    }
+    // earliestReadyAt is finite whenever there are surviving entries; if entries became empty,
+    // the outer worker loop will exit on its next iteration via entries.size === 0.
+    return { type: 'sleep', ms: earliestReadyAt === Infinity ? 0 : earliestReadyAt - now };
+  }
+
+  /** Computes backoff for an entry. Backoff applies after a full cycle through all sources. */
+  private getBackoffMs(entry: FileStoreTxEntry): number {
+    const fullCycles = Math.floor(entry.attempts / this.sources.length);
+    if (fullCycles === 0) {
+      return 0;
+    }
+    return Math.min(this.config.backoffBaseMs * Math.pow(2, fullCycles - 1), this.config.backoffMaxMs);
   }
 }

package/src/services/tx_collection/file_store_tx_source.ts

@@ -1,26 +1,54 @@
+import { partitionAsync } from '@aztec/foundation/collection';
 import { type Logger, createLogger } from '@aztec/foundation/log';
+import { Timer } from '@aztec/foundation/timer';
 import { type ReadOnlyFileStore, createReadOnlyFileStore } from '@aztec/stdlib/file-store';
-import { Tx, type TxHash } from '@aztec/stdlib/tx';
+import { Tx, type TxHash, type TxValidator } from '@aztec/stdlib/tx';
+import {
+  type Histogram,
+  Metrics,
+  type TelemetryClient,
+  type UpDownCounter,
+  getTelemetryClient,
+} from '@aztec/telemetry-client';
 
-import type { TxSource } from './tx_source.js';
+import type { TxSource, TxSourceCollectionResult } from './tx_source.js';
 
 /** TxSource implementation that downloads txs from a file store. */
 export class FileStoreTxSource implements TxSource {
+  private downloadsSuccess: UpDownCounter;
+  private downloadsFailed: UpDownCounter;
+  private downloadDuration: Histogram;
+  private downloadSize: Histogram;
+
   private constructor(
     private readonly fileStore: ReadOnlyFileStore,
     private readonly baseUrl: string,
+    private readonly basePath: string,
+    private readonly txValidator: TxValidator,
     private readonly log: Logger,
-  ) {}
+    telemetry: TelemetryClient,
+  ) {
+    const meter = telemetry.getMeter('file-store-tx-source');
+    this.downloadsSuccess = meter.createUpDownCounter(Metrics.TX_FILE_STORE_DOWNLOADS_SUCCESS);
+    this.downloadsFailed = meter.createUpDownCounter(Metrics.TX_FILE_STORE_DOWNLOADS_FAILED);
+    this.downloadDuration = meter.createHistogram(Metrics.TX_FILE_STORE_DOWNLOAD_DURATION);
+    this.downloadSize = meter.createHistogram(Metrics.TX_FILE_STORE_DOWNLOAD_SIZE);
+  }
 
   /**
    * Creates a FileStoreTxSource from a URL.
    * @param url - The file store URL (s3://, gs://, file://, http://, https://).
+   * @param basePath - Base path for tx files within the store.
    * @param log - Optional logger.
+   * @param telemetry - Optional telemetry client.
    * @returns The FileStoreTxSource instance, or undefined if creation fails.
    */
   public static async create(
     url: string,
+    basePath: string,
+    txValidator: TxValidator,
     log: Logger = createLogger('p2p:file_store_tx_source'),
+    telemetry: TelemetryClient = getTelemetryClient(),
   ): Promise<FileStoreTxSource | undefined> {
     try {
       const fileStore = await createReadOnlyFileStore(url, log);
@@ -28,7 +56,7 @@ export class FileStoreTxSource implements TxSource {
         log.warn(`Failed to create file store for URL: ${url}`);
         return undefined;
       }
-      return new FileStoreTxSource(fileStore, url, log);
+      return new FileStoreTxSource(fileStore, url, basePath, txValidator, log, telemetry);
     } catch (err) {
       log.warn(`Error creating file store for URL: ${url}`, { error: err });
       return undefined;
@@ -39,32 +67,63 @@ export class FileStoreTxSource implements TxSource {
     return `file-store:${this.baseUrl}`;
   }
 
-  public getTxsByHash(txHashes: TxHash[]): Promise<(Tx | undefined)[]> {
-    return Promise.all(
+  public async getTxsByHash(txHashes: TxHash[]): Promise<TxSourceCollectionResult> {
+    const results = await Promise.all(
       txHashes.map(async txHash => {
-        const path = `txs/${txHash.toString()}.bin`;
+        const path = `${this.basePath}/txs/${txHash.toString()}.bin`;
+        const timer = new Timer();
         try {
           const buffer = await this.fileStore.read(path);
-          return Tx.fromBuffer(buffer);
+          const tx = Tx.fromBuffer(buffer);
+          return { tx, downloadDuration: timer.ms(), downloadSize: buffer.length };
         } catch {
-          // Tx not found or error reading - return undefined
+          this.downloadsFailed.add(1);
           return undefined;
         }
       }),
     );
+
+    const txs = results.filter(tx => tx !== undefined);
+    const [validTxs, invalidTxs] = await partitionAsync(
+      txs,
+      async ({ tx, downloadDuration, downloadSize }): Promise<boolean> => {
+        const valid = await this.txValidator.validateTx(tx);
+        if (valid.result === 'valid') {
+          this.downloadsSuccess.add(1);
+          this.downloadDuration.record(Math.ceil(downloadDuration));
+          this.downloadSize.record(downloadSize);
+          return true;
+        } else {
+          this.downloadsFailed.add(1);
+          return false;
+        }
+      },
+    );
+
+    return {
+      validTxs: validTxs.map(({ tx }) => tx),
+      invalidTxHashes: invalidTxs.map(({ tx }) => tx.getTxHash().toString()),
+    };
   }
 }
 
 /**
  * Creates FileStoreTxSource instances from URLs.
  * @param urls - Array of file store URLs.
+ * @param basePath - Base path for tx files within each store.
  * @param log - Optional logger.
+ * @param telemetry - Optional telemetry client.
  * @returns Array of successfully created FileStoreTxSource instances.
  */
 export async function createFileStoreTxSources(
   urls: string[],
+  basePath: string,
+  txValidator: TxValidator,
   log: Logger = createLogger('p2p:file_store_tx_source'),
+  telemetry: TelemetryClient = getTelemetryClient(),
 ): Promise<FileStoreTxSource[]> {
-  const sources = await Promise.all(urls.map(url => FileStoreTxSource.create(url, log)));
+  const sources = await Promise.all(
+    urls.map(url => FileStoreTxSource.create(url, basePath, txValidator, log, telemetry)),
+  );
   return sources.filter((s): s is FileStoreTxSource => s !== undefined);
 }

package/src/services/tx_collection/index.ts

@@ -1,8 +1,3 @@
-export { TxCollection, type FastCollectionRequestInput } from './tx_collection.js';
+export { TxCollection, type FastCollectionRequestInput, type IReqRespTxsCollector } from './tx_collection.js';
 export { type TxSource, createNodeRpcTxSources, NodeRpcTxSource } from './tx_source.js';
-export {
-  type MissingTxsCollector,
-  BatchTxRequesterCollector,
-  SendBatchRequestCollector,
-} from './proposal_tx_collector.js';
 export { FileStoreTxSource, createFileStoreTxSources } from './file_store_tx_source.js';

package/src/services/tx_collection/instrumentation.ts

@@ -18,7 +18,7 @@ export class TxCollectionInstrumentation {
     const meter = client.getMeter(name);
 
     this.txsCollected = createUpDownCounterWithDefault(meter, Metrics.TX_COLLECTOR_COUNT, {
-      [Attributes.TX_COLLECTION_METHOD]: ['fast-req-resp', 'fast-node-rpc', 'slow-req-resp', 'slow-node-rpc'],
+      [Attributes.TX_COLLECTION_METHOD]: ['fast-req-resp', 'fast-node-rpc', 'file-store'],
     });
 
     this.collectionDurationPerTx = meter.createHistogram(Metrics.TX_COLLECTOR_DURATION_PER_TX);

package/src/services/tx_collection/request_tracker.ts

@@ -0,0 +1,127 @@
+import { type PromiseWithResolvers, promiseWithResolvers } from '@aztec/foundation/promise';
+import type { DateProvider } from '@aztec/foundation/timer';
+import { TxHash } from '@aztec/stdlib/tx';
+import type { Tx } from '@aztec/stdlib/tx';
+
+/**
+ * Tracks which transactions are still missing and need to be fetched.
+ * Manages the request deadline and serves as the sole source of cancellation signal.
+ * The request is cancelled when all txs are fetched or the deadline expires.
+ */
+export interface IRequestTracker {
+  /** Returns the set of transaction hashes that are still missing. */
+  get missingTxHashes(): Set<string>;
+  /** Size of this.missingTxHashes */
+  get numberOfMissingTxs(): number;
+  /** Are all requested txs fetched */
+  allFetched(): boolean;
+  /** Checks that transaction is still missing */
+  isMissing(txHash: string): boolean;
+  /** Marks a transaction as fetched. Returns true if it was previously missing. */
+  markFetched(tx: Tx): boolean;
+  /** Get list of collected txs */
+  get collectedTxs(): Tx[];
+  /** The deadline for this request. */
+  get deadline(): Date;
+  /** Remaining time in milliseconds until deadline. Returns 0 if already past. */
+  get timeoutMs(): number;
+  /** Checks whether the request is cancelled (deadline expired or all fetched). May trigger cancellation if deadline has passed. */
+  checkCancelled(): boolean;
+  /** Resolves when deadline expires or all txs are fetched. */
+  get cancellationToken(): Promise<void>;
+  /** Externally cancel the request. */
+  cancel(): void;
+}
+
+export class RequestTracker implements IRequestTracker {
+  public readonly collectedTxs: Tx[] = [];
+  private done = false;
+  private readonly cancellationTokenPromise: PromiseWithResolvers<void>;
+  private readonly deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+
+  private constructor(
+    public readonly missingTxHashes: Set<string>,
+    public readonly deadline: Date,
+    private readonly dateProvider?: DateProvider,
+  ) {
+    this.cancellationTokenPromise = promiseWithResolvers<void>();
+
+    if (missingTxHashes.size === 0) {
+      this.finish();
+      return;
+    }
+
+    const now = this.dateProvider?.now() ?? Date.now();
+    const remaining = deadline.getTime() - now;
+    if (remaining <= 0) {
+      this.finish();
+    } else {
+      this.deadlineTimer = setTimeout(() => this.finish(), remaining);
+    }
+  }
+
+  public static create(hashes: TxHash[] | string[], deadline: Date, dateProvider?: DateProvider) {
+    return new RequestTracker(new Set(hashes.map(hash => hash.toString())), deadline, dateProvider);
+  }
+
+  markFetched(tx: Tx): boolean {
+    if (this.missingTxHashes.delete(tx.txHash.toString())) {
+      this.collectedTxs.push(tx);
+      if (this.allFetched()) {
+        this.finish();
+      }
+      return true;
+    }
+    return false;
+  }
+
+  get numberOfMissingTxs(): number {
+    return this.missingTxHashes.size;
+  }
+
+  allFetched(): boolean {
+    return this.numberOfMissingTxs === 0;
+  }
+
+  isMissing(txHash: string): boolean {
+    return this.missingTxHashes.has(txHash.toString());
+  }
+
+  get timeoutMs(): number {
+    const now = this.dateProvider?.now() ?? Date.now();
+    return Math.max(0, this.deadline.getTime() - now);
+  }
+
+  checkCancelled(): boolean {
+    if (this.done) {
+      return true;
+    }
+    // Synchronous fallback: check deadline even if setTimeout hasn't fired yet.
+    // This prevents macrotask starvation in tight async loops from blocking cancellation.
+    const now = this.dateProvider?.now() ?? Date.now();
+    if (now >= this.deadline.getTime()) {
+      this.finish();
+      return true;
+    }
+    return false;
+  }
+
+  get cancellationToken(): Promise<void> {
+    return this.cancellationTokenPromise.promise;
+  }
+
+  cancel(): void {
+    this.finish();
+  }
+
+  private finish() {
+    if (this.done) {
+      return;
+    }
+    this.done = true;
+    if (this.deadlineTimer) {
+      clearTimeout(this.deadlineTimer);
+    }
+    this.cancellationTokenPromise.resolve();
+  }
+}