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

package/src/services/reqresp/reqresp.ts

@@ -36,6 +36,7 @@ import {
   type ReqRespSubProtocolValidators,
   type SubProtocolMap,
   responseFromBuffer,
+  subProtocolSizeCalculators,
 } from './interface.js';
 import { ReqRespMetrics } from './metrics.js';
 import {
@@ -111,6 +112,13 @@ export class ReqResp implements ReqRespInterface {
     return this.metrics.tracer;
   }
 
+  /**
+   * Get the connection sampler instance
+   */
+  getConnectionSampler(): Pick<ConnectionSampler, 'getPeerListSortedByConnectionCountAsc'> {
+    return this.connectionSampler;
+  }
+
   /**
    * Start the reqresp service
    */
@@ -212,6 +220,14 @@ export class ReqResp implements ReqRespInterface {
     const responseValidator = this.subProtocolValidators[subProtocol] ?? DEFAULT_SUB_PROTOCOL_VALIDATORS[subProtocol];
     const responses: InstanceType<SubProtocolMap[SubProtocol]['response']>[] = new Array(requests.length);
     const requestBuffers = requests.map(req => req.toBuffer());
+    const isEmptyResponse = (value: unknown): boolean => {
+      // Some responses serialize to a non-empty buffer even when they contain no items (e.g., empty TxArray).
+      if (!value || typeof value !== 'object') {
+        return false;
+      }
+      const length = (value as { length?: number }).length;
+      return typeof length === 'number' && length === 0;
+    };
 
     const requestFunction = async (signal: AbortSignal) => {
       // Track which requests still need to be processed
@@ -252,7 +268,9 @@ export class ReqResp implements ReqRespInterface {
         for (const requestIndex of pendingRequestIndices) {
           const peer = batchSampler.getPeerForRequest(requestIndex);
           if (!peer) {
-            break;
+            // No peer available for this specific index (all peers exhausted for it)
+            // Skip this index for now - it stays in pendingRequestIndices for retry
+            continue;
           }
           const peerAsString = peer.toString();
           if (!requestBatches.has(peerAsString)) {
@@ -271,6 +289,12 @@ export class ReqResp implements ReqRespInterface {
           });
         }
 
+        // If no requests could be assigned (all peers exhausted for all indices), exit early
+        if (requestBatches.size === 0) {
+          this.logger.warn('No peers available for any pending request indices, stopping batch request');
+          break;
+        }
+
         // Make parallel requests for each peer's batch
         // A batch entry will look something like this:
         // PeerId0: [0, 1, 2, 3]
@@ -282,38 +306,61 @@ export class ReqResp implements ReqRespInterface {
         const batchResults = await Promise.all(
           Array.from(requestBatches.entries()).map(async ([peerAsString, { peerId: peer, indices }]) => {
             try {
+              const markIndexFailed = (index: number) => batchSampler.markPeerFailedForIndex(peer, index);
               // Requests all going to the same peer are sent synchronously
               const peerResults: { index: number; response: InstanceType<SubProtocolMap[SubProtocol]['response']> }[] =
                 [];
+              let shouldReplacePeer = false;
+              const handleFailure = (status: ReqRespStatus, index: number) => {
+                this.logger.warn(
+                  `Request to peer ${peerAsString} failed with status ${prettyPrintReqRespStatus(status)}`,
+                );
+                markIndexFailed(index);
+                return status === ReqRespStatus.RATE_LIMIT_EXCEEDED;
+              };
+
               for (const index of indices) {
-                this.logger.trace(`Sending request ${index} to peer ${peerAsString}`);
+                this.logger.info(`Sending request ${index} to peer ${peerAsString}`);
                 const response = await this.sendRequestToPeer(peer, subProtocol, requestBuffers[index]);
 
                 // Check the status of the response buffer
                 if (response.status !== ReqRespStatus.SUCCESS) {
-                  this.logger.debug(
-                    `Request to peer ${peerAsString} failed with status ${prettyPrintReqRespStatus(response.status)}`,
-                  );
-
-                  // If we hit a rate limit or some failure, we remove the peer and return the results,
-                  // they will be split among remaining peers and the new sampled peer
-                  batchSampler.removePeerAndReplace(peer);
-                  return { peer, results: peerResults };
+                  shouldReplacePeer = handleFailure(response.status, index);
+                  if (shouldReplacePeer) {
+                    break;
+                  }
+                  continue;
                 }
 
-                if (response && response.data.length > 0) {
-                  const object = responseFromBuffer(subProtocol, response.data);
-                  const isValid = await responseValidator(requests[index], object, peer);
+                if (response.data.length === 0) {
+                  markIndexFailed(index);
+                  continue;
+                }
 
-                  if (isValid) {
-                    peerResults.push({ index, response: object });
-                  }
+                const object = responseFromBuffer(subProtocol, response.data);
+                if (isEmptyResponse(object)) {
+                  markIndexFailed(index);
+                  continue;
                 }
+
+                const isValid = await responseValidator(requests[index], object, peer);
+                if (!isValid) {
+                  markIndexFailed(index);
+                  continue;
+                }
+
+                peerResults.push({ index, response: object });
+              }
+
+              // If peer had a hard failure (rate limit), replace it for future iterations
+              if (shouldReplacePeer) {
+                this.logger.warn(`Peer ${peerAsString} hit a hard failure, removing from sampler`);
+                batchSampler.removePeerAndReplace(peer);
               }
 
               return { peer, results: peerResults };
             } catch (error) {
-              this.logger.debug(`Failed batch request to peer ${peerAsString}:`, error);
+              this.logger.warn(`Failed batch request to peer ${peerAsString}:`, error);
               batchSampler.removePeerAndReplace(peer);
               return { peer, results: [] };
             }
@@ -334,7 +381,7 @@ export class ReqResp implements ReqRespInterface {
       }
 
       if (retryAttempts >= maxRetryAttempts) {
-        this.logger.debug(`Max retry attempts ${maxRetryAttempts} reached for batch request`);
+        this.logger.warn(`Max retry attempts ${maxRetryAttempts} reached for batch request`);
       }
 
       return responses;
@@ -347,7 +394,7 @@ export class ReqResp implements ReqRespInterface {
         () => new CollectiveReqRespTimeoutError(),
       );
     } catch (e: any) {
-      this.logger.debug(`${e.message} | subProtocol: ${subProtocol}`);
+      this.logger.warn(`${e.message} | subProtocol: ${subProtocol}`);
       return [];
     }
   }
@@ -391,6 +438,9 @@ export class ReqResp implements ReqRespInterface {
     try {
       this.metrics.recordRequestSent(subProtocol);
 
+      // Calculate expected response size based on the request payload
+      const expectedSizeKb = subProtocolSizeCalculators[subProtocol](payload);
+
       this.logger.trace(`Sending request to peer ${peerId.toString()} on sub protocol ${subProtocol}`);
       stream = await this.connectionSampler.dialProtocol(peerId, subProtocol, dialTimeout);
       this.logger.trace(
@@ -398,17 +448,21 @@ export class ReqResp implements ReqRespInterface {
       );
 
       const timeoutErr = new IndividualReqRespTimeoutError();
+      // Create a wrapper to pass the expected size to readMessage
+      const readMessageWithSizeLimit = (source: AsyncIterable<Uint8ArrayList>) =>
+        this.readMessage(source, expectedSizeKb);
       const [_, resp] = await executeTimeout(
         signal =>
           Promise.all([
             pipeline([payload], stream!.sink, { signal }),
-            pipeline(stream!.source, this.readMessage.bind(this), { signal }),
+            pipeline(stream!.source, readMessageWithSizeLimit, { signal }),
           ]),
         this.individualRequestTimeoutMs,
         () => timeoutErr,
       );
       return resp;
     } catch (e: any) {
+      this.logger.warn(`SUBPROTOCOL: ${subProtocol}\n`, e);
       // On error we immediately abort the stream, this is preferred way,
       // because it signals to the sender that error happened, whereas
       // closing the stream only closes our side and is much slower
@@ -463,8 +517,11 @@ export class ReqResp implements ReqRespInterface {
    * The message is split into two components
    * - The first chunk should contain a control byte, indicating the status of the response see `ReqRespStatus`
    * - The second chunk should contain the response data
+   *
+   * @param source - The async iterable source of data chunks
+   * @param maxSizeKb - Optional maximum expected size in KB for the decompressed response
    */
-  private async readMessage(source: AsyncIterable<Uint8ArrayList>): Promise<ReqRespResponse> {
+  private async readMessage(source: AsyncIterable<Uint8ArrayList>, maxSizeKb?: number): Promise<ReqRespResponse> {
     let status: ReqRespStatus | undefined;
     const chunks: Uint8Array[] = [];
 
@@ -489,7 +546,7 @@ export class ReqResp implements ReqRespInterface {
       }
 
       const messageData = Buffer.concat(chunks);
-      const message: Buffer = this.snappyTransform.inboundTransformData(messageData);
+      const message: Buffer = this.snappyTransform.inboundTransformData(messageData, undefined, maxSizeKb);
 
       return {
         status: status ?? ReqRespStatus.UNKNOWN,

package/src/services/service.ts

@@ -1,12 +1,14 @@
+import type { SlotNumber } from '@aztec/foundation/branded-types';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import type { PeerInfo } from '@aztec/stdlib/interfaces/server';
-import type { BlockAttestation, BlockProposal, Gossipable } from '@aztec/stdlib/p2p';
+import type { BlockProposal, CheckpointAttestation, CheckpointProposalCore, Gossipable } from '@aztec/stdlib/p2p';
 import type { Tx } from '@aztec/stdlib/tx';
 
 import type { PeerId } from '@libp2p/interface';
 import type { ENR } from '@nethermindeth/enr';
 import type EventEmitter from 'events';
 
+import type { BatchTxRequesterLibP2PService } from './reqresp/batch-tx-requester/interface.js';
 import type { P2PReqRespConfig } from './reqresp/config.js';
 import type { StatusMessage } from './reqresp/index.js';
 import type {
@@ -22,13 +24,52 @@ export enum PeerDiscoveryState {
   STOPPED = 'stopped',
 }
 
-export type P2PBlockReceivedCallback = (
-  block: BlockProposal,
+/**
+ * Callback for when a block proposal is received.
+ * Validators validate but DO NOT attest to individual blocks - attestations are only for checkpoints.
+ * @returns true if the proposal is valid, false otherwise
+ */
+export type P2PBlockReceivedCallback = (block: BlockProposal, sender: PeerId) => Promise<boolean>;
+
+/**
+ * Callback for when a checkpoint proposal is received.
+ * The checkpoint proposal is passed as CheckpointProposalCore (without lastBlock) since
+ * the lastBlock is extracted and stored separately as a BlockProposal, and the block
+ * callback is invoked and awaited before this checkpoint callback.
+ */
+export type P2PCheckpointReceivedCallback = (
+  checkpoint: CheckpointProposalCore,
   sender: PeerId,
-) => Promise<BlockAttestation[] | undefined>;
+) => Promise<CheckpointAttestation[] | undefined>;
 
 export type AuthReceivedCallback = (peerId: PeerId, authRequest: AuthRequest) => Promise<AuthResponse | undefined>;
 
+/** Minimal info passed to the duplicate proposal callback. */
+export type DuplicateProposalInfo = {
+  slot: SlotNumber;
+  proposer: EthAddress;
+  type: 'checkpoint' | 'block';
+};
+
+/**
+ * Callback for when a duplicate proposal is detected (equivocation).
+ * Invoked on the first duplicate (when count goes from 1 to 2).
+ */
+export type P2PDuplicateProposalCallback = (info: DuplicateProposalInfo) => void;
+
+/** Minimal info passed to the duplicate attestation callback. */
+export type DuplicateAttestationInfo = {
+  slot: SlotNumber;
+  attester: EthAddress;
+};
+
+/**
+ * Callback for when a duplicate attestation is detected (equivocation).
+ * A validator signing attestations for different proposals at the same slot.
+ * Invoked on the first duplicate (when count goes from 1 to 2).
+ */
+export type P2PDuplicateAttestationCallback = (info: DuplicateAttestationInfo) => void;
+
 /**
  * The interface for a P2P service implementation.
  */
@@ -70,6 +111,21 @@ export interface P2PService {
   // Leaky abstraction: fix https://github.com/AztecProtocol/aztec-packages/issues/7963
   registerBlockReceivedCallback(callback: P2PBlockReceivedCallback): void;
 
+  registerCheckpointReceivedCallback(callback: P2PCheckpointReceivedCallback): void;
+
+  /**
+   * Registers a callback invoked when a duplicate proposal is detected (equivocation).
+   * The callback is triggered on the first duplicate (when count goes from 1 to 2).
+   */
+  registerDuplicateProposalCallback(callback: P2PDuplicateProposalCallback): void;
+
+  /**
+   * Registers a callback invoked when a duplicate attestation is detected (equivocation).
+   * A validator signing attestations for different proposals at the same slot.
+   * The callback is triggered on the first duplicate (when count goes from 1 to 2).
+   */
+  registerDuplicateAttestationCallback(callback: P2PDuplicateAttestationCallback): void;
+
   getEnr(): ENR | undefined;
 
   getPeers(includePending?: boolean): PeerInfo[];
@@ -88,6 +144,9 @@ export interface P2PService {
 
   /** If node running this P2P stack is validator, passes in validator address to P2P layer */
   registerThisValidatorAddresses(address: EthAddress[]): void;
+
+  /** Get BatchTxRequester service dependencies */
+  getBatchTxRequesterService(): BatchTxRequesterLibP2PService;
 }
 
 /**

package/src/services/tx_collection/config.ts

@@ -1,5 +1,12 @@
-import { type ConfigMappingsType, booleanConfigHelper, numberConfigHelper } from '@aztec/foundation/config';
-import { MAX_RPC_TXS_LEN } from '@aztec/stdlib/interfaces/server';
+import {
+  type ConfigMappingsType,
+  booleanConfigHelper,
+  enumConfigHelper,
+  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  */
@@ -22,6 +29,14 @@ 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 */
+  txCollectionFileStoreFastDelayMs: number;
 };
 
 export const txCollectionConfigMappings: ConfigMappingsType<TxCollectionConfig> = {
@@ -81,4 +96,29 @@ 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',
+    parseEnv: (val: string) =>
+      val
+        .split(',')
+        .map(url => url.trim())
+        .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',
+    ...numberConfigHelper(2_000),
+  },
 };

package/src/services/tx_collection/fast_tx_collection.ts

@@ -2,7 +2,6 @@ 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 { boundInclusive } from '@aztec/foundation/number';
 import { promiseWithResolvers } from '@aztec/foundation/promise';
 import { sleep } from '@aztec/foundation/sleep';
 import { DateProvider, elapsed } from '@aztec/foundation/timer';
@@ -12,25 +11,40 @@ import { type Tx, TxHash } from '@aztec/stdlib/tx';
 
 import type { PeerId } from '@libp2p/interface';
 
-import { type ReqRespInterface, ReqRespSubProtocol } from '../reqresp/interface.js';
-import { chunkTxHashesRequest } from '../reqresp/protocols/tx.js';
+import type { BatchTxRequesterConfig } from '../reqresp/batch-tx-requester/config.js';
+import type { BatchTxRequesterLibP2PService } from '../reqresp/batch-tx-requester/interface.js';
 import type { TxCollectionConfig } from './config.js';
+import {
+  BatchTxRequesterCollector,
+  type MissingTxsCollector,
+  SendBatchRequestCollector,
+} from './proposal_tx_collector.js';
 import type { FastCollectionRequest, FastCollectionRequestInput } from './tx_collection.js';
-import type { TxCollectionSink } from './tx_collection_sink.js';
+import type { TxAddContext, TxCollectionSink } from './tx_collection_sink.js';
 import type { TxSource } from './tx_source.js';
 
 export class FastTxCollection {
   // eslint-disable-next-line aztec-custom/no-non-primitive-in-collections
   protected requests: Set<FastCollectionRequest> = new Set();
+  private missingTxsCollector: MissingTxsCollector;
 
   constructor(
-    private reqResp: Pick<ReqRespInterface, 'sendBatchRequest'>,
+    p2pService: BatchTxRequesterLibP2PService,
     private nodes: TxSource[],
     private txCollectionSink: TxCollectionSink,
     private config: TxCollectionConfig,
     private dateProvider: DateProvider = new DateProvider(),
     private log: Logger = createLogger('p2p:tx_collection_service'),
-  ) {}
+    missingTxsCollector?: MissingTxsCollector,
+  ) {
+    const batchTxRequesterConfig = this.config as Partial<BatchTxRequesterConfig>;
+    const missingTxsCollectorType = this.config.txCollectionMissingTxsCollectorType;
+    this.missingTxsCollector =
+      missingTxsCollector ??
+      (missingTxsCollectorType === 'old'
+        ? new SendBatchRequestCollector(p2pService)
+        : new BatchTxRequesterCollector(p2pService, log, dateProvider, undefined, batchTxRequesterConfig));
+  }
 
   public async stop() {
     this.requests.forEach(request => request.promise.reject(new AbortError(`Stopped collection service`)));
@@ -63,7 +77,7 @@ export class FastTxCollection {
     // 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>();
-    setTimeout(() => promise.reject(new TimeoutError(`Timed out while collecting txs`)), timeout);
+    const timeoutTimer = setTimeout(() => promise.reject(new TimeoutError(`Timed out while collecting txs`)), timeout);
 
     const request: FastCollectionRequest = {
       ...input,
@@ -75,6 +89,7 @@ export class FastTxCollection {
     };
 
     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}`,
@@ -220,6 +235,7 @@ export class FastTxCollection {
             method: 'fast-node-rpc',
             ...request.blockInfo,
           },
+          this.getAddContext(request),
         );
 
         // Clear from the active requests the txs we just requested
@@ -241,8 +257,6 @@ export class FastTxCollection {
   private async collectFastViaReqResp(request: FastCollectionRequest, opts: { pinnedPeer?: PeerId }) {
     const timeoutMs = +request.deadline - this.dateProvider.now();
     const pinnedPeer = opts.pinnedPeer;
-    const maxPeers = boundInclusive(Math.ceil(request.missingTxHashes.size / 2), 8, 32);
-    const maxRetryAttempts = 5;
     const blockInfo = request.blockInfo;
     const slotNumber = blockInfo.slotNumber;
     if (timeoutMs < 100) {
@@ -261,19 +275,21 @@ export class FastTxCollection {
     try {
       await this.txCollectionSink.collect(
         async txHashes => {
-          const txs = await this.reqResp.sendBatchRequest<ReqRespSubProtocol.TX>(
-            ReqRespSubProtocol.TX,
-            chunkTxHashesRequest(txHashes),
-            pinnedPeer,
-            timeoutMs,
-            maxPeers,
-            maxRetryAttempts,
-          );
-
-          return txs.flat();
+          if (request.type === 'proposal') {
+            return await this.missingTxsCollector.collectTxs(txHashes, request.blockProposal, pinnedPeer, timeoutMs);
+          } 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);
+          } else {
+            throw new Error(`Unknown request type: ${(request as any).type}`);
+          }
         },
         Array.from(request.missingTxHashes).map(txHash => TxHash.fromString(txHash)),
         { 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, {
@@ -283,6 +299,15 @@ export class FastTxCollection {
     }
   }
 
+  /** Returns the TxAddContext for the given request, used by the sink to add txs to the pool correctly. */
+  private getAddContext(request: FastCollectionRequest): TxAddContext {
+    if (request.type === 'proposal') {
+      return { type: 'proposal', blockHeader: request.blockProposal.blockHeader };
+    } else {
+      return { type: 'mined', block: request.block };
+    }
+  }
+
   /**
    * Handle txs by marking them as found for the requests that are waiting for them, and resolves the request if all its txs have been found.
    * Called internally and from the main tx collection manager whenever the tx pool emits a tx-added event.

package/src/services/tx_collection/file_store_tx_collection.ts

@@ -0,0 +1,152 @@
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import { FifoMemoryQueue } from '@aztec/foundation/queue';
+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
+
+/**
+ * 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.
+ */
+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 txCollectionSink: TxCollectionSink,
+    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');
+      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.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();
+    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();
+  }
+
+  /** 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);
+      }
+    }
+  }
+
+  /** 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];
+
+      try {
+        const result = await this.txCollectionSink.collect(
+          hashes => source.getTxsByHash(hashes),
+          [txHash],
+          {
+            description: `file-store ${source.getInfo()}`,
+            method: 'file-store',
+            fileStore: source.getInfo(),
+          },
+          context,
+        );
+
+        if (result.txs.length > 0) {
+          return;
+        }
+      } catch (err) {
+        this.log.trace(`Failed to download tx ${txHash} from ${source.getInfo()}`, { err });
+      }
+    }
+
+    this.log.trace(`Tx ${txHash} not found in any file store`);
+  }
+}