@aztec/p2p 0.0.1-commit.d6f2b3f94 → 0.0.1-commit.d939eb5aa

package/src/services/tx_collection/fast_tx_collection.ts

@@ -1,12 +1,9 @@
 import { BlockNumber } from '@aztec/foundation/branded-types';
 import { times } from '@aztec/foundation/collection';
-import { AbortError, TimeoutError } from '@aztec/foundation/error';
 import { type Logger, createLogger } from '@aztec/foundation/log';
-import { promiseWithResolvers } from '@aztec/foundation/promise';
 import { sleep } from '@aztec/foundation/sleep';
 import { DateProvider, elapsed } from '@aztec/foundation/timer';
 import type { L2BlockInfo } from '@aztec/stdlib/block';
-import type { BlockProposal } from '@aztec/stdlib/p2p';
 import { type Tx, TxHash } from '@aztec/stdlib/tx';
 
 import type { PeerId } from '@libp2p/interface';
@@ -19,6 +16,7 @@ import {
   type MissingTxsCollector,
   SendBatchRequestCollector,
 } from './proposal_tx_collector.js';
+import { RequestTracker } from './request_tracker.js';
 import type { FastCollectionRequest, FastCollectionRequestInput } from './tx_collection.js';
 import type { TxAddContext, TxCollectionSink } from './tx_collection_sink.js';
 import type { TxSource } from './tx_source.js';
@@ -47,7 +45,9 @@ export class FastTxCollection {
   }
 
   public async stop() {
-    this.requests.forEach(request => request.promise.reject(new AbortError(`Stopped collection service`)));
+    this.requests.forEach(request => {
+      request.requestTracker.cancel();
+    });
     await Promise.resolve();
   }
 
@@ -74,82 +74,65 @@ export class FastTxCollection {
         ? { ...input.blockProposal.toBlockInfo(), blockNumber: input.blockNumber }
         : { ...input.block.toBlockInfo() };
 
-    // This promise is used to await for the collection to finish during the main collectFast method.
-    // It gets resolved in `foundTxs` when all txs have been collected, or rejected if the request is aborted or hits the deadline.
-    const promise = promiseWithResolvers<void>();
-    const timeoutTimer = setTimeout(() => promise.reject(new TimeoutError(`Timed out while collecting txs`)), timeout);
-
     const request: FastCollectionRequest = {
       ...input,
       blockInfo,
-      promise,
-      foundTxs: new Map<string, Tx>(),
-      missingTxHashes: new Set(txHashes.map(t => t.toString())),
-      deadline: opts.deadline,
+      requestTracker: RequestTracker.create(txHashes, opts.deadline, this.dateProvider),
     };
 
     const [duration] = await elapsed(() => this.collectFast(request, { ...opts }));
-    clearTimeout(timeoutTimer);
 
     this.log.verbose(
-      `Collected ${request.foundTxs.size} txs out of ${txHashes.length} for ${input.type} at slot ${blockInfo.slotNumber}`,
+      `Collected ${request.requestTracker.collectedTxs.length} txs out of ${txHashes.length} for ${input.type} at slot ${blockInfo.slotNumber}`,
       {
         ...blockInfo,
         duration,
         requestType: input.type,
-        missingTxs: [...request.missingTxHashes],
+        missingTxs: [...request.requestTracker.missingTxHashes],
       },
     );
-    return [...request.foundTxs.values()];
+    return request.requestTracker.collectedTxs;
   }
 
-  protected async collectFast(
-    request: FastCollectionRequest,
-    opts: { proposal?: BlockProposal; deadline: Date; pinnedPeer?: PeerId },
-  ) {
+  protected async collectFast(request: FastCollectionRequest, opts: { pinnedPeer?: PeerId }) {
     this.requests.add(request);
     const { blockInfo } = request;
 
     this.log.debug(
-      `Starting fast collection of ${request.missingTxHashes.size} txs for ${request.type} at slot ${blockInfo.slotNumber}`,
-      { ...blockInfo, requestType: request.type, deadline: opts.deadline },
+      `Starting fast collection of ${request.requestTracker.numberOfMissingTxs} txs for ${request.type} at slot ${blockInfo.slotNumber}`,
+      { ...blockInfo, requestType: request.type, deadline: request.requestTracker.deadline },
     );
 
     try {
       // Start blasting all nodes for the txs. We give them a little time to respond before we start reqresp.
-      // And keep an eye on the request promise to ensure we don't wait longer than the deadline or return as soon
-      // as we have collected all txs, whatever the source.
-      const nodeCollectionPromise = this.collectFastFromNodes(request, opts);
+      // We race against the cancellation token to exit as soon as all txs are collected, the deadline expires,
+      // or the request is externally cancelled.
+      const nodeCollectionPromise = this.collectFastFromNodes(request);
       const waitBeforeReqResp = sleep(this.config.txCollectionFastNodesTimeoutBeforeReqRespMs);
-      await Promise.race([request.promise.promise, waitBeforeReqResp]);
+      await Promise.race([request.requestTracker.cancellationToken, waitBeforeReqResp]);
 
-      // If we have collected all txs, we can stop here
-      if (request.missingTxHashes.size === 0) {
-        this.log.debug(`All txs collected for slot ${blockInfo.slotNumber} without reqresp`, blockInfo);
+      // If we have collected all txs or the request was cancelled, we can stop here.
+      // Wait for node collection to settle so inner tasks finish before we return.
+      if (request.requestTracker.checkCancelled()) {
+        if (request.requestTracker.allFetched()) {
+          this.log.debug(`All txs collected for slot ${blockInfo.slotNumber} without reqresp`, blockInfo);
+        }
+        await nodeCollectionPromise;
         return;
       }
 
       // Start blasting reqresp for the remaining txs. Note that node collection keeps running in parallel.
       // We stop when we have collected all txs, timed out, or both node collection and reqresp have given up.
-      const collectionPromise = Promise.allSettled([this.collectFastViaReqResp(request, opts), nodeCollectionPromise]);
-      await Promise.race([collectionPromise, request.promise.promise]);
+      // Inner tasks observe requestTracker.checkCancelled() and stop themselves, so this settles shortly after cancellation.
+      await Promise.allSettled([this.collectFastViaReqResp(request, opts), nodeCollectionPromise]);
     } catch (err) {
-      // Log and swallow all errors
-      const logCtx = {
+      this.log.error(`Error collecting txs for ${request.type} for slot ${blockInfo.slotNumber}`, err, {
         ...blockInfo,
-        errorMessage: err instanceof Error ? err.message : undefined,
-        missingTxs: [...request.missingTxHashes].map(txHash => txHash.toString()),
-      };
-      if (err instanceof Error && err.name === 'TimeoutError') {
-        this.log.warn(`Timed out collecting txs for ${request.type} at slot ${blockInfo.slotNumber}`, logCtx);
-      } else if (err instanceof Error && err.name === 'AbortError') {
-        this.log.warn(`Aborted collecting txs for ${request.type} at slot ${blockInfo.slotNumber}`, logCtx);
-      } else {
-        this.log.error(`Error collecting txs for ${request.type} for slot ${blockInfo.slotNumber}`, err, logCtx);
-      }
+        missingTxs: request.requestTracker.missingTxHashes.values().map(txHash => txHash.toString()),
+      });
     } finally {
       // Ensure no unresolved promises and remove the request from the set
-      request.promise.resolve();
+      request.requestTracker.cancel();
       this.requests.delete(request);
     }
   }
@@ -160,26 +143,28 @@ export class FastTxCollection {
    * the txs that have been requested less often whenever we need to send a new batch of requests. We ensure that no
    * tx is requested more than once at the same time to the same node.
    */
-  private async collectFastFromNodes(request: FastCollectionRequest, opts: { deadline: Date }): Promise<void> {
+  private async collectFastFromNodes(request: FastCollectionRequest): Promise<void> {
     if (this.nodes.length === 0) {
       return;
     }
 
     // Keep a shared priority queue of all txs pending to be requested, sorted by the number of attempts made to collect them.
-    const attemptsPerTx = [...request.missingTxHashes].map(txHash => ({ txHash, attempts: 0, found: false }));
+    const attemptsPerTx = [...request.requestTracker.missingTxHashes].map(txHash => ({
+      txHash,
+      attempts: 0,
+      found: false,
+    }));
 
     // Returns once we have finished all node loops. Each loop finishes when the deadline is hit, or all txs have been collected.
-    await Promise.allSettled(this.nodes.map(node => this.collectFastFromNode(request, node, attemptsPerTx, opts)));
+    await Promise.allSettled(this.nodes.map(node => this.collectFastFromNode(request, node, attemptsPerTx)));
   }
 
   private async collectFastFromNode(
     request: FastCollectionRequest,
     node: TxSource,
     attemptsPerTx: { txHash: string; attempts: number; found: boolean }[],
-    opts: { deadline: Date },
   ) {
-    const notFinished = () =>
-      this.dateProvider.now() <= +opts.deadline && request.missingTxHashes.size > 0 && this.requests.has(request);
+    const notFinished = () => !request.requestTracker.checkCancelled();
 
     const maxParallelRequests = this.config.txCollectionFastMaxParallelRequestsPerNode;
     const maxBatchSize = this.config.txCollectionNodeRpcMaxBatchSize;
@@ -196,7 +181,7 @@ export class FastTxCollection {
           if (!txToRequest) {
             // No more txs to process
             break;
-          } else if (!request.missingTxHashes.has(txToRequest.txHash)) {
+          } else if (!request.requestTracker.isMissing(txToRequest.txHash)) {
             // Mark as found if it was found somewhere else, we'll then remove it from the array.
             // We don't delete it now since 'array.splice' is pretty expensive, so we do it after sorting.
             txToRequest.found = true;
@@ -225,10 +210,17 @@ export class FastTxCollection {
           return;
         }
 
+        const txHashes = batch.map(({ txHash }) => txHash);
         // Collect this batch from the node
         await this.txCollectionSink.collect(
-          txHashes => node.getTxsByHash(txHashes),
-          batch.map(({ txHash }) => TxHash.fromString(txHash)),
+          async () => {
+            const result = await node.getTxsByHash(txHashes.map(TxHash.fromString));
+            for (const tx of result.validTxs) {
+              request.requestTracker.markFetched(tx);
+            }
+            return result;
+          },
+          txHashes,
           {
             description: `fast ${node.getInfo()}`,
             node: node.getInfo(),
@@ -243,9 +235,12 @@ export class FastTxCollection {
           activeRequestsToThisNode.delete(requestedTx.txHash);
         }
 
-        // Sleep a bit until hitting the node again (or not, depending on config)
+        // Sleep a bit until hitting the node again, but wake up immediately on cancellation
         if (notFinished()) {
-          await sleep(this.config.txCollectionFastNodeIntervalMs);
+          await Promise.race([
+            sleep(this.config.txCollectionFastNodeIntervalMs),
+            request.requestTracker.cancellationToken,
+          ]);
         }
       }
     };
@@ -255,45 +250,50 @@ export class FastTxCollection {
   }
 
   private async collectFastViaReqResp(request: FastCollectionRequest, opts: { pinnedPeer?: PeerId }) {
-    const timeoutMs = +request.deadline - this.dateProvider.now();
     const pinnedPeer = opts.pinnedPeer;
     const blockInfo = request.blockInfo;
     const slotNumber = blockInfo.slotNumber;
-    if (timeoutMs < 100) {
+    if (request.requestTracker.timeoutMs < 100) {
       this.log.warn(
         `Not initiating fast reqresp for txs for ${request.type} at slot ${blockInfo.slotNumber} due to timeout`,
-        { timeoutMs, ...blockInfo },
+        { timeoutMs: request.requestTracker.timeoutMs, ...blockInfo },
       );
       return;
     }
 
     this.log.debug(
-      `Starting fast reqresp for ${request.missingTxHashes.size} txs for ${request.type} at slot ${blockInfo.slotNumber}`,
-      { ...blockInfo, timeoutMs, pinnedPeer },
+      `Starting fast reqresp for ${request.requestTracker.numberOfMissingTxs} txs for ${request.type} at slot ${blockInfo.slotNumber}`,
+      { ...blockInfo, timeoutMs: request.requestTracker.timeoutMs, pinnedPeer },
     );
 
     try {
       await this.txCollectionSink.collect(
-        async txHashes => {
+        async () => {
+          let result: Tx[];
           if (request.type === 'proposal') {
-            return await this.missingTxsCollector.collectTxs(txHashes, request.blockProposal, pinnedPeer, timeoutMs);
+            result = await this.missingTxsCollector.collectTxs(
+              request.requestTracker,
+              request.blockProposal,
+              pinnedPeer,
+            );
           } else if (request.type === 'block') {
             const blockTxsSource = {
               txHashes: request.block.body.txEffects.map(e => e.txHash),
               archive: request.block.archive.root,
             };
-            return await this.missingTxsCollector.collectTxs(txHashes, blockTxsSource, pinnedPeer, timeoutMs);
+            result = await this.missingTxsCollector.collectTxs(request.requestTracker, blockTxsSource, pinnedPeer);
           } else {
             throw new Error(`Unknown request type: ${(request as any).type}`);
           }
+          return { validTxs: result, invalidTxHashes: [] };
         },
-        Array.from(request.missingTxHashes).map(txHash => TxHash.fromString(txHash)),
+        Array.from(request.requestTracker.missingTxHashes),
         { description: `reqresp for slot ${slotNumber}`, method: 'fast-req-resp', ...opts, ...request.blockInfo },
         this.getAddContext(request),
       );
     } catch (err) {
       this.log.error(`Error sending fast reqresp request for txs`, err, {
-        txs: [...request.missingTxHashes],
+        txs: [...request.requestTracker.missingTxHashes],
         ...blockInfo,
       });
     }
@@ -317,21 +317,18 @@ export class FastTxCollection {
       for (const tx of txs) {
         const txHash = tx.txHash.toString();
         // Remove the tx hash from the missing set, and add it to the found set.
-        if (request.missingTxHashes.has(txHash)) {
-          request.missingTxHashes.delete(txHash);
-          request.foundTxs.set(txHash, tx);
+        if (request.requestTracker.markFetched(tx)) {
           this.log.trace(`Found tx ${txHash} for fast collection request`, {
             ...request.blockInfo,
             txHash: tx.txHash.toString(),
             type: request.type,
           });
-          // If we found all txs for this request, we resolve the promise
-          if (request.missingTxHashes.size === 0) {
+          if (request.requestTracker.allFetched()) {
             this.log.trace(`All txs found for fast collection request`, {
               ...request.blockInfo,
               type: request.type,
             });
-            request.promise.resolve();
+            break;
           }
         }
       }
@@ -345,8 +342,7 @@ export class FastTxCollection {
   public stopCollectingForBlocksUpTo(blockNumber: BlockNumber): void {
     for (const request of this.requests) {
       if (request.blockInfo.blockNumber <= blockNumber) {
-        request.promise.reject(new AbortError(`Stopped collecting txs up to block ${blockNumber}`));
-        this.requests.delete(request);
+        request.requestTracker.cancel();
       }
     }
   }
@@ -358,8 +354,7 @@ export class FastTxCollection {
   public stopCollectingForBlocksAfter(blockNumber: BlockNumber): void {
     for (const request of this.requests) {
       if (request.blockInfo.blockNumber > blockNumber) {
-        request.promise.reject(new AbortError(`Stopped collecting txs after block ${blockNumber}`));
-        this.requests.delete(request);
+        request.requestTracker.cancel();
       }
     }
   }

package/src/services/tx_collection/file_store_tx_collection.ts

@@ -1,152 +1,202 @@
 import { type Logger, createLogger } from '@aztec/foundation/log';
-import { FifoMemoryQueue } from '@aztec/foundation/queue';
+import { type PromiseWithResolvers, promiseWithResolvers } from '@aztec/foundation/promise';
+import { sleep } from '@aztec/foundation/sleep';
+import { DateProvider } from '@aztec/foundation/timer';
 import { Tx, TxHash } from '@aztec/stdlib/tx';
 
 import type { FileStoreTxSource } from './file_store_tx_source.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;
+  context: TxAddContext;
+  deadline: Date;
+  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.
+ * Uses a shared worker pool that pulls entries with priority (fewest attempts first),
+ * retries with round-robin across sources, and applies exponential backoff between
+ * full cycles through all sources.
  */
 export class FileStoreTxCollection {
-  /** Map from tx hash to add context for txs queued for download. */
-  private pendingTxs = new Map<string, TxAddContext>();
+  /** Map from tx hash string to entry for all pending downloads. */
+  private entries = new Map<string, FileStoreTxEntry>();
 
-  /**
-   * 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. */
+  /** Worker promises for the shared worker pool. */
   private workers: Promise<void>[] = [];
 
-  /** Whether the collection has been started. */
-  private started = false;
+  /** Whether the worker pool is running. */
+  private running = false;
+
+  /** Signal used to wake sleeping workers when new entries arrive or stop is called. */
+  private wakeSignal: PromiseWithResolvers<void>;
 
   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'),
-  ) {}
+  ) {
+    this.wakeSignal = promiseWithResolvers<void>();
+  }
 
-  /** 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');
+  /** Starts the shared worker pool. */
+  public start(): void {
+    if (this.sources.length === 0) {
+      this.log.debug('No file store sources configured');
       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)));
+    this.running = true;
+    for (let i = 0; i < this.config.workerCount; i++) {
+      this.workers.push(this.workerLoop());
     }
-
-    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) {
-      return;
-    }
-    this.started = false;
-    this.downloadQueue.end();
+  /** Stops all workers and clears state. */
+  public async stop(): Promise<void> {
+    this.running = false;
+    this.wake();
     await Promise.all(this.workers);
     this.workers = [];
-    this.pendingTxs.clear();
-    this.foundTxHashes.clear();
+    this.entries.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);
+  /** Adds entries to the shared map and wakes workers. */
+  public startCollecting(txHashes: TxHash[], context: TxAddContext, deadline: Date): void {
+    if (this.sources.length === 0 || txHashes.length === 0) {
+      return;
+    }
+    if (+deadline <= this.dateProvider.now()) {
+      return;
     }
-  }
-
-  /** 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();
-  }
 
-  /** 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);
+      if (!this.entries.has(hashStr)) {
+        this.entries.set(hashStr, {
+          txHash: hashStr,
+          context,
+          deadline,
+          attempts: 0,
+          lastAttemptTime: 0,
+          nextSourceIndex: Math.floor(Math.random() * this.sources.length),
+        });
       }
     }
+    this.wake();
   }
 
-  /** Stop tracking txs that were found elsewhere. */
-  public foundTxs(txs: Tx[]) {
+  /** Removes entries for txs that have been found elsewhere. */
+  public foundTxs(txs: Tx[]): void {
     for (const tx of txs) {
-      const hashStr = tx.getTxHash().toString();
-      this.pendingTxs.delete(hashStr);
-      this.foundTxHashes.add(hashStr);
+      this.entries.delete(tx.getTxHash().toString());
     }
   }
 
-  /** 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);
+  /** Clears all pending entries. */
+  public clearPending(): void {
+    this.entries.clear();
   }
 
-  /** 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];
+  private async workerLoop(): Promise<void> {
+    while (this.running) {
+      const action = this.getNextAction();
+      if (action.type === 'sleep') {
+        await action.promise;
+        continue;
+      }
+
+      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',
             fileStore: source.getInfo(),
           },
-          context,
+          entry.context,
         );
-
         if (result.txs.length > 0) {
-          return;
+          this.entries.delete(entry.txHash);
         }
       } 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 });
+      }
+    }
+  }
+
+  /** Single-pass scan: removes expired entries, finds the best ready entry, or computes sleep time. */
+  private getNextAction(): { type: 'process'; entry: FileStoreTxEntry } | { type: 'sleep'; promise: Promise<void> } {
+    const now = this.dateProvider.now();
+    let best: FileStoreTxEntry | undefined;
+    let earliestReadyAt = Infinity;
+
+    for (const [key, entry] of this.entries) {
+      if (+entry.deadline <= now) {
+        this.entries.delete(key);
+        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;
       }
     }
 
-    this.log.trace(`Tx ${txHash} not found in any file store`);
+    if (best) {
+      return { type: 'process', entry: best };
+    }
+    if (earliestReadyAt < Infinity) {
+      return { type: 'sleep', promise: this.sleepOrWake(earliestReadyAt - now) };
+    }
+    return { type: 'sleep', promise: this.waitForWake() };
+  }
+
+  /** 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);
+  }
+
+  /** Resolves the current wake signal and creates a new one. */
+  private wake(): void {
+    this.wakeSignal.resolve();
+    this.wakeSignal = promiseWithResolvers<void>();
+  }
+
+  /** Waits until the wake signal is resolved. */
+  private async waitForWake(): Promise<void> {
+    await this.wakeSignal.promise;
+  }
+
+  /** Sleeps for the given duration or until the wake signal is resolved. */
+  private async sleepOrWake(ms: number): Promise<void> {
+    await Promise.race([sleep(ms), this.wakeSignal.promise]);
   }
 }