@aztec/p2p 0.0.1-commit.9b94fc1 → 0.0.1-commit.9d2bcf6d

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 ProposalTxCollectorType = 'new' | 'old';
 
 export type TxCollectionConfig = {
   /** How long to wait before starting reqresp for fast collection  */
@@ -22,6 +29,8 @@ 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 proposal tx collection */
+  txCollectionProposalTxCollectorType: ProposalTxCollectorType;
 };
 
 export const txCollectionConfigMappings: ConfigMappingsType<TxCollectionConfig> = {
@@ -81,4 +90,9 @@ export const txCollectionConfigMappings: ConfigMappingsType<TxCollectionConfig>
     description: 'Maximum number of transactions to request from a node in a single batch',
     ...numberConfigHelper(MAX_RPC_TXS_LEN),
   },
+  txCollectionProposalTxCollectorType: {
+    env: 'TX_COLLECTION_PROPOSAL_TX_COLLECTOR_TYPE',
+    description: 'Which collector implementation to use for proposal tx collection (new or old)',
+    ...enumConfigHelper(['new', 'old'] as const, 'new'),
+  },
 };

package/src/services/tx_collection/fast_tx_collection.ts

@@ -1,3 +1,4 @@
+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';
@@ -11,9 +12,16 @@ import { type Tx, TxHash } from '@aztec/stdlib/tx';
 
 import type { PeerId } from '@libp2p/interface';
 
-import { type ReqRespInterface, ReqRespSubProtocol } from '../reqresp/interface.js';
+import type { BatchTxRequesterConfig } from '../reqresp/batch-tx-requester/config.js';
+import type { BatchTxRequesterLibP2PService } from '../reqresp/batch-tx-requester/interface.js';
+import { ReqRespSubProtocol } from '../reqresp/interface.js';
 import { chunkTxHashesRequest } from '../reqresp/protocols/tx.js';
 import type { TxCollectionConfig } from './config.js';
+import {
+  BatchTxRequesterCollector,
+  type ProposalTxCollector,
+  SendBatchRequestCollector,
+} from './proposal_tx_collector.js';
 import type { FastCollectionRequest, FastCollectionRequestInput } from './tx_collection.js';
 import type { TxCollectionSink } from './tx_collection_sink.js';
 import type { TxSource } from './tx_source.js';
@@ -21,15 +29,25 @@ 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 proposalTxCollector: ProposalTxCollector;
 
   constructor(
-    private reqResp: Pick<ReqRespInterface, 'sendBatchRequest'>,
+    private p2pService: BatchTxRequesterLibP2PService,
     private nodes: TxSource[],
     private txCollectionSink: TxCollectionSink,
     private config: TxCollectionConfig,
     private dateProvider: DateProvider = new DateProvider(),
     private log: Logger = createLogger('p2p:tx_collection_service'),
-  ) {}
+    proposalTxCollector?: ProposalTxCollector,
+  ) {
+    const batchTxRequesterConfig = this.config as Partial<BatchTxRequesterConfig>;
+    const proposalCollectorType = this.config.txCollectionProposalTxCollectorType;
+    this.proposalTxCollector =
+      proposalTxCollector ??
+      (proposalCollectorType === '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`)));
@@ -260,16 +278,22 @@ 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.proposalTxCollector.collectTxs(txHashes, request.blockProposal, pinnedPeer, timeoutMs);
+          } else if (request.type === 'block') {
+            const txs = await this.p2pService.reqResp.sendBatchRequest<ReqRespSubProtocol.TX>(
+              ReqRespSubProtocol.TX,
+              chunkTxHashesRequest(txHashes),
+              pinnedPeer,
+              timeoutMs,
+              maxPeers,
+              maxRetryAttempts,
+            );
+
+            return txs.flat();
+          } 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 },
@@ -316,7 +340,7 @@ export class FastTxCollection {
    * Stop collecting all txs for blocks less than or requal to the block number specified.
    * To be called when we no longer care about gathering txs up to a certain block, eg when they become proven or finalized.
    */
-  public stopCollectingForBlocksUpTo(blockNumber: number): void {
+  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}`));
@@ -329,7 +353,7 @@ export class FastTxCollection {
    * Stop collecting all txs for blocks greater than the block number specified.
    * To be called when there is a chain prune and previously mined txs are no longer relevant.
    */
-  public stopCollectingForBlocksAfter(blockNumber: number): void {
+  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}`));

package/src/services/tx_collection/index.ts

@@ -1,2 +1,7 @@
 export { TxCollection, type FastCollectionRequestInput } from './tx_collection.js';
 export { type TxSource, createNodeRpcTxSources, NodeRpcTxSource } from './tx_source.js';
+export {
+  type ProposalTxCollector,
+  BatchTxRequesterCollector,
+  SendBatchRequestCollector,
+} from './proposal_tx_collector.js';

package/src/services/tx_collection/instrumentation.ts

@@ -4,7 +4,7 @@ import {
   Metrics,
   type TelemetryClient,
   type UpDownCounter,
-  ValueType,
+  createUpDownCounterWithDefault,
 } from '@aztec/telemetry-client';
 
 import type { CollectionMethod } from './tx_collection.js';
@@ -17,21 +17,13 @@ export class TxCollectionInstrumentation {
   constructor(client: TelemetryClient, name: string) {
     const meter = client.getMeter(name);
 
-    this.txsCollected = meter.createUpDownCounter(Metrics.TX_COLLECTOR_COUNT, {
-      description: 'The number of txs collected',
+    this.txsCollected = createUpDownCounterWithDefault(meter, Metrics.TX_COLLECTOR_COUNT, {
+      [Attributes.TX_COLLECTION_METHOD]: ['fast-req-resp', 'fast-node-rpc', 'slow-req-resp', 'slow-node-rpc'],
     });
 
-    this.collectionDurationPerTx = meter.createHistogram(Metrics.TX_COLLECTOR_DURATION_PER_TX, {
-      unit: 'ms',
-      description: 'Average duration per tx of an individual tx collection request',
-      valueType: ValueType.INT,
-    });
+    this.collectionDurationPerTx = meter.createHistogram(Metrics.TX_COLLECTOR_DURATION_PER_TX);
 
-    this.collectionDurationPerRequest = meter.createHistogram(Metrics.TX_COLLECTOR_DURATION_PER_REQUEST, {
-      unit: 'ms',
-      description: 'Total duration of an individual tx collection request',
-      valueType: ValueType.INT,
-    });
+    this.collectionDurationPerRequest = meter.createHistogram(Metrics.TX_COLLECTOR_DURATION_PER_REQUEST);
   }
 
   increaseTxsFor(what: CollectionMethod, count: number, duration: number) {

package/src/services/tx_collection/proposal_tx_collector.ts

@@ -0,0 +1,114 @@
+import type { Logger } from '@aztec/foundation/log';
+import type { DateProvider } from '@aztec/foundation/timer';
+import type { BlockProposal } from '@aztec/stdlib/p2p';
+import type { Tx, TxHash } from '@aztec/stdlib/tx';
+
+import type { PeerId } from '@libp2p/interface';
+
+import { BatchTxRequester } from '../reqresp/batch-tx-requester/batch_tx_requester.js';
+import type { BatchTxRequesterConfig } from '../reqresp/batch-tx-requester/config.js';
+import type { BatchTxRequesterLibP2PService } from '../reqresp/batch-tx-requester/interface.js';
+import type { IBatchRequestTxValidator } from '../reqresp/batch-tx-requester/tx_validator.js';
+import { ReqRespSubProtocol } from '../reqresp/interface.js';
+import { chunkTxHashesRequest } from '../reqresp/protocols/tx.js';
+
+/**
+ * Strategy interface for collecting transactions for block proposals.
+ * Allows swapping between different tx collection implementations for benchmarking.
+ */
+export interface ProposalTxCollector {
+  /**
+   * Collect transactions for a block proposal.
+   * @param txHashes - The transaction hashes to collect
+   * @param blockProposal - The block proposal containing the transactions
+   * @param pinnedPeer - Optional peer that sent the proposal (expected to have all txs)
+   * @param timeoutMs - Timeout in milliseconds
+   * @returns The collected transactions
+   */
+  collectTxs(
+    txHashes: TxHash[],
+    blockProposal: BlockProposal,
+    pinnedPeer: PeerId | undefined,
+    timeoutMs: number,
+  ): Promise<Tx[]>;
+}
+
+/**
+ * Collects transactions using the BatchTxRequester implementation.
+ * This uses a smart/dumb peer strategy with parallel workers.
+ */
+export class BatchTxRequesterCollector implements ProposalTxCollector {
+  constructor(
+    private p2pService: BatchTxRequesterLibP2PService,
+    private log: Logger,
+    private dateProvider: DateProvider,
+    private txValidator?: IBatchRequestTxValidator,
+    private batchTxRequesterConfig?: Partial<BatchTxRequesterConfig>,
+  ) {}
+
+  async collectTxs(
+    txHashes: TxHash[],
+    blockProposal: BlockProposal,
+    pinnedPeer: PeerId | undefined,
+    timeoutMs: number,
+  ): Promise<Tx[]> {
+    const {
+      batchTxRequesterSmartParallelWorkerCount: smartParallelWorkerCount,
+      batchTxRequesterDumbParallelWorkerCount: dumbParallelWorkerCount,
+      batchTxRequesterTxBatchSize: txBatchSize,
+      batchTxRequesterBadPeerThreshold: badPeerThreshold,
+    } = this.batchTxRequesterConfig ?? {};
+
+    const batchRequester = new BatchTxRequester(
+      txHashes,
+      blockProposal,
+      pinnedPeer,
+      timeoutMs,
+      this.p2pService,
+      this.log,
+      this.dateProvider,
+      {
+        smartParallelWorkerCount,
+        dumbParallelWorkerCount,
+        txBatchSize,
+        badPeerThreshold,
+        txValidator: this.txValidator,
+      },
+    );
+
+    return await BatchTxRequester.collectAllTxs(batchRequester.run());
+  }
+}
+
+const DEFAULT_MAX_PEERS = 10;
+const DEFAULT_MAX_RETRY_ATTEMPTS = 3;
+
+/**
+ * Collects transactions using the sendBatchRequest implementation from ReqResp.
+ * This is the original implementation that balances requests across peers.
+ */
+export class SendBatchRequestCollector implements ProposalTxCollector {
+  constructor(
+    private p2pService: BatchTxRequesterLibP2PService,
+    private maxPeers: number = DEFAULT_MAX_PEERS,
+    private maxRetryAttempts: number = DEFAULT_MAX_RETRY_ATTEMPTS,
+  ) {}
+
+  async collectTxs(
+    txHashes: TxHash[],
+    _blockProposal: BlockProposal,
+    pinnedPeer: PeerId | undefined,
+    timeoutMs: number,
+  ): Promise<Tx[]> {
+    const txs = await this.p2pService.reqResp.sendBatchRequest<ReqRespSubProtocol.TX>(
+      ReqRespSubProtocol.TX,
+      chunkTxHashesRequest(txHashes),
+      pinnedPeer,
+      timeoutMs,
+      this.maxPeers,
+      this.maxRetryAttempts,
+    );
+
+    return txs.flat();
+  }
+}

package/src/services/tx_collection/slow_tx_collection.ts

@@ -1,4 +1,4 @@
-import { EpochNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import { BlockNumber, EpochNumber, SlotNumber } from '@aztec/foundation/branded-types';
 import { chunk } from '@aztec/foundation/collection';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import { boundInclusive } from '@aztec/foundation/number';
@@ -203,7 +203,7 @@ export class SlowTxCollection {
    * Stop collecting all txs for blocks less than or requal to the block number specified.
    * To be called when we no longer care about gathering txs up to a certain block, eg when they become proven or finalized.
    */
-  public stopCollectingForBlocksUpTo(blockNumber: number): void {
+  public stopCollectingForBlocksUpTo(blockNumber: BlockNumber): void {
     for (const [txHash, info] of this.missingTxs.entries()) {
       if (info.blockNumber <= blockNumber) {
         this.missingTxs.delete(txHash);
@@ -215,7 +215,7 @@ export class SlowTxCollection {
    * Stop collecting all txs for blocks greater than the block number specified.
    * To be called when there is a chain prune and previously mined txs are no longer relevant.
    */
-  public stopCollectingForBlocksAfter(blockNumber: number): void {
+  public stopCollectingForBlocksAfter(blockNumber: BlockNumber): void {
     for (const [txHash, info] of this.missingTxs.entries()) {
       if (info.blockNumber > blockNumber) {
         this.missingTxs.delete(txHash);

package/src/services/tx_collection/tx_collection.ts

@@ -1,3 +1,4 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
 import { compactArray } from '@aztec/foundation/collection';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import { type PromiseWithResolvers, RunningPromise } from '@aztec/foundation/promise';
@@ -12,7 +13,7 @@ import type { PeerId } from '@libp2p/interface';
 
 import type { TxPool } from '../../mem_pools/index.js';
 import type { TxPoolEvents } from '../../mem_pools/tx_pool/tx_pool.js';
-import type { ReqRespInterface } from '../reqresp/interface.js';
+import type { BatchTxRequesterLibP2PService } from '../reqresp/batch-tx-requester/interface.js';
 import type { TxCollectionConfig } from './config.js';
 import { FastTxCollection } from './fast_tx_collection.js';
 import { SlowTxCollection } from './slow_tx_collection.js';
@@ -21,11 +22,11 @@ import type { TxSource } from './tx_source.js';
 
 export type CollectionMethod = 'fast-req-resp' | 'fast-node-rpc' | 'slow-req-resp' | 'slow-node-rpc';
 
-export type MissingTxInfo = { blockNumber: number; deadline: Date; readyForReqResp: boolean };
+export type MissingTxInfo = { blockNumber: BlockNumber; deadline: Date; readyForReqResp: boolean };
 
 export type FastCollectionRequestInput =
   | { type: 'block'; block: L2Block }
-  | { type: 'proposal'; blockProposal: BlockProposal; blockNumber: number };
+  | { type: 'proposal'; blockProposal: BlockProposal; blockNumber: BlockNumber };
 
 export type FastCollectionRequest = FastCollectionRequestInput & {
   missingTxHashes: Set<string>;
@@ -66,7 +67,7 @@ export class TxCollection {
   protected readonly handleTxsFound: TxPoolEvents['txs-added'];
 
   constructor(
-    private readonly reqResp: Pick<ReqRespInterface, 'sendBatchRequest'>,
+    private readonly p2pService: BatchTxRequesterLibP2PService,
     private readonly nodes: TxSource[],
     private readonly constants: L1RollupConstants,
     private readonly txPool: TxPool,
@@ -78,7 +79,7 @@ export class TxCollection {
     this.txCollectionSink = new TxCollectionSink(this.txPool, telemetryClient, this.log);
 
     this.fastCollection = new FastTxCollection(
-      this.reqResp,
+      this.p2pService,
       this.nodes,
       this.txCollectionSink,
       this.config,
@@ -87,7 +88,7 @@ export class TxCollection {
     );
 
     this.slowCollection = new SlowTxCollection(
-      this.reqResp,
+      this.p2pService.reqResp,
       this.nodes,
       this.txCollectionSink,
       this.fastCollection,
@@ -152,7 +153,7 @@ export class TxCollection {
   /** Collects the set of txs for the given block proposal as fast as possible */
   public collectFastForProposal(
     blockProposal: BlockProposal,
-    blockNumber: number,
+    blockNumber: BlockNumber,
     txHashes: TxHash[] | string[],
     opts: { deadline: Date; pinnedPeer?: PeerId },
   ) {
@@ -187,7 +188,7 @@ export class TxCollection {
    * Stop collecting all txs for blocks less than or requal to the block number specified.
    * To be called when we no longer care about gathering txs up to a certain block, eg when they become proven or finalized.
    */
-  public stopCollectingForBlocksUpTo(blockNumber: number): void {
+  public stopCollectingForBlocksUpTo(blockNumber: BlockNumber): void {
     this.slowCollection.stopCollectingForBlocksUpTo(blockNumber);
     this.fastCollection.stopCollectingForBlocksUpTo(blockNumber);
   }
@@ -196,7 +197,7 @@ export class TxCollection {
    * Stop collecting all txs for blocks greater than the block number specified.
    * To be called when there is a chain prune and previously mined txs are no longer relevant.
    */
-  public stopCollectingForBlocksAfter(blockNumber: number): void {
+  public stopCollectingForBlocksAfter(blockNumber: BlockNumber): void {
     this.slowCollection.stopCollectingForBlocksAfter(blockNumber);
     this.fastCollection.stopCollectingForBlocksAfter(blockNumber);
   }

package/src/services/tx_file_store/config.ts

@@ -0,0 +1,43 @@
+import { type ConfigMappingsType, booleanConfigHelper, numberConfigHelper } from '@aztec/foundation/config';
+
+/**
+ * Configuration for the TxFileStore service.
+ */
+export type TxFileStoreConfig = {
+  /** URL for uploading txs to file storage (s3://, gs://, file://) */
+  txFileStoreUrl?: string;
+  /** URL for downloading txs from file storage */
+  txFileStoreDownloadUrl?: string;
+  /** Max concurrent uploads */
+  txFileStoreUploadConcurrency: number;
+  /** Max queue size to prevent unbounded memory growth */
+  txFileStoreMaxQueueSize: number;
+  /** Enable tx file store upload */
+  txFileStoreEnabled: boolean;
+};
+
+export const txFileStoreConfigMappings: ConfigMappingsType<TxFileStoreConfig> = {
+  txFileStoreUrl: {
+    env: 'TX_FILE_STORE_URL',
+    description: 'URL for uploading txs to file storage (s3://, gs://, file://)',
+  },
+  txFileStoreDownloadUrl: {
+    env: 'TX_FILE_STORE_DOWNLOAD_URL',
+    description: 'URL for downloading txs from file storage',
+  },
+  txFileStoreUploadConcurrency: {
+    env: 'TX_FILE_STORE_UPLOAD_CONCURRENCY',
+    description: 'Maximum number of concurrent tx uploads',
+    ...numberConfigHelper(10),
+  },
+  txFileStoreMaxQueueSize: {
+    env: 'TX_FILE_STORE_MAX_QUEUE_SIZE',
+    description: 'Maximum queue size for pending uploads (oldest dropped when exceeded)',
+    ...numberConfigHelper(1000),
+  },
+  txFileStoreEnabled: {
+    env: 'TX_FILE_STORE_ENABLED',
+    description: 'Enable uploading transactions to file storage',
+    ...booleanConfigHelper(false),
+  },
+};

package/src/services/tx_file_store/index.ts

@@ -0,0 +1,3 @@
+export { TxFileStore } from './tx_file_store.js';
+export { TxFileStoreInstrumentation } from './instrumentation.js';
+export { type TxFileStoreConfig, txFileStoreConfigMappings } from './config.js';

package/src/services/tx_file_store/instrumentation.ts

@@ -0,0 +1,36 @@
+import { type Gauge, type Histogram, Metrics, type TelemetryClient, type UpDownCounter } from '@aztec/telemetry-client';
+
+/** Instrumentation for the TxFileStore service. */
+export class TxFileStoreInstrumentation {
+  private uploadsSuccess: UpDownCounter;
+  private uploadsFailed: UpDownCounter;
+  private uploadsSkipped: UpDownCounter;
+  private uploadDuration: Histogram;
+  private queueSize: Gauge;
+
+  constructor(client: TelemetryClient, name: string) {
+    const meter = client.getMeter(name);
+    this.uploadsSuccess = meter.createUpDownCounter(Metrics.TX_FILE_STORE_UPLOADS_SUCCESS);
+    this.uploadsFailed = meter.createUpDownCounter(Metrics.TX_FILE_STORE_UPLOADS_FAILED);
+    this.uploadsSkipped = meter.createUpDownCounter(Metrics.TX_FILE_STORE_UPLOADS_SKIPPED);
+    this.uploadDuration = meter.createHistogram(Metrics.TX_FILE_STORE_UPLOAD_DURATION);
+    this.queueSize = meter.createGauge(Metrics.TX_FILE_STORE_QUEUE_SIZE);
+  }
+
+  recordUploadSuccess(durationMs: number) {
+    this.uploadsSuccess.add(1);
+    this.uploadDuration.record(durationMs);
+  }
+
+  recordUploadFailed() {
+    this.uploadsFailed.add(1);
+  }
+
+  recordUploadSkipped() {
+    this.uploadsSkipped.add(1);
+  }
+
+  recordQueueSize(size: number) {
+    this.queueSize.record(size);
+  }
+}

package/src/services/tx_file_store/tx_file_store.ts

@@ -0,0 +1,173 @@
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import { RunningPromise } from '@aztec/foundation/promise';
+import { makeBackoff, retry } from '@aztec/foundation/retry';
+import { Timer } from '@aztec/foundation/timer';
+import { type FileStore, createFileStore } from '@aztec/stdlib/file-store';
+import type { Tx } from '@aztec/stdlib/tx';
+import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-client';
+
+import type { TxPool, TxPoolEvents } from '../../mem_pools/tx_pool/index.js';
+import type { TxFileStoreConfig } from './config.js';
+import { TxFileStoreInstrumentation } from './instrumentation.js';
+
+/**
+ * Uploads validated transactions to a file store as a fallback retrieval mechanism.
+ * Listens to TxPool txs-added events and uploads txs asynchronously with bounded concurrency.
+ */
+export class TxFileStore {
+  private uploadQueue: Tx[] = [];
+  private activeUploads = 0;
+  private readonly queueProcessor: RunningPromise;
+  private readonly handleTxsAdded: TxPoolEvents['txs-added'];
+
+  /** Recently uploaded tx hashes for deduplication. */
+  private recentUploads: Set<string> = new Set();
+  private recentUploadsOrder: string[] = [];
+  private readonly maxRecentUploads = 1000;
+
+  private constructor(
+    private readonly fileStore: FileStore,
+    private readonly txPool: TxPool,
+    private readonly config: TxFileStoreConfig,
+    private readonly instrumentation: TxFileStoreInstrumentation,
+    private readonly log: Logger,
+  ) {
+    this.handleTxsAdded = (args: { txs: Tx[]; source?: string }) => {
+      this.enqueueTxs(args.txs);
+    };
+    this.queueProcessor = new RunningPromise(() => this.processQueueBatch(), this.log, 100);
+  }
+
+  /**
+   * Creates and initializes the file store.
+   * @param txPool - The transaction pool to listen to.
+   * @param config - The file store configuration.
+   * @param log - Optional logger.
+   * @param telemetry - Optional telemetry client.
+   * @param fileStoreOverride - Optional FileStore for testing (bypasses createFileStore).
+   * @returns The file store instance, or undefined if not configured/enabled.
+   */
+  static async create(
+    txPool: TxPool,
+    config: TxFileStoreConfig,
+    log: Logger = createLogger('p2p:tx_file_store'),
+    telemetry: TelemetryClient = getTelemetryClient(),
+    fileStoreOverride?: FileStore,
+  ): Promise<TxFileStore | undefined> {
+    if (!config.txFileStoreEnabled) {
+      log.debug('Tx file store is disabled');
+      return undefined;
+    }
+
+    if (!config.txFileStoreUrl) {
+      log.warn('Tx file store is enabled but URL is not configured');
+      return undefined;
+    }
+
+    const fileStore = fileStoreOverride ?? (await createFileStore(config.txFileStoreUrl, log));
+    if (!fileStore) {
+      log.warn('Failed to create file store for tx file store');
+      return undefined;
+    }
+
+    const instrumentation = new TxFileStoreInstrumentation(telemetry, 'TxFileStore');
+    log.info('Created tx file store', { url: config.txFileStoreUrl });
+    return new TxFileStore(fileStore, txPool, config, instrumentation, log);
+  }
+
+  /** Starts listening to TxPool events and uploading txs. */
+  public start(): void {
+    this.queueProcessor.start();
+    this.txPool.on('txs-added', this.handleTxsAdded);
+    this.log.info('Started tx file store', {
+      concurrency: this.config.txFileStoreUploadConcurrency,
+      maxQueueSize: this.config.txFileStoreMaxQueueSize,
+    });
+  }
+
+  /** Stops listening and waits for pending uploads to complete. */
+  public async stop(): Promise<void> {
+    this.txPool.removeListener('txs-added', this.handleTxsAdded);
+    await this.queueProcessor.stop();
+    this.log.info('Stopped tx file store');
+  }
+
+  private enqueueTxs(txs: Tx[]): void {
+    this.uploadQueue.push(...txs);
+
+    // Enforce max queue size by dropping oldest entries
+    const overflow = this.uploadQueue.length - this.config.txFileStoreMaxQueueSize;
+    if (overflow > 0) {
+      this.log.warn(`Upload queue overflow, dropping ${overflow} oldest txs`);
+      this.uploadQueue.splice(0, overflow);
+    }
+
+    this.instrumentation.recordQueueSize(this.uploadQueue.length);
+
+    // Immediately start uploading txs
+    void this.queueProcessor.trigger();
+  }
+
+  private async processQueueBatch(): Promise<void> {
+    const batch = this.uploadQueue.splice(0, this.config.txFileStoreUploadConcurrency);
+    this.instrumentation.recordQueueSize(this.uploadQueue.length);
+
+    this.activeUploads += batch.length;
+    try {
+      await Promise.all(batch.map(tx => this.uploadTx(tx)));
+    } finally {
+      this.activeUploads -= batch.length;
+    }
+  }
+
+  private async uploadTx(tx: Tx): Promise<void> {
+    const txHash = tx.getTxHash().toString();
+    const path = `txs/${txHash}.bin`;
+    const timer = new Timer();
+
+    if (this.recentUploads.has(txHash)) {
+      return;
+    }
+
+    try {
+      this.recentUploads.add(txHash);
+      this.recentUploadsOrder.push(txHash);
+
+      if (this.recentUploadsOrder.length > this.maxRecentUploads) {
+        // delete old entries in recentUploads
+        for (const txHashToRemove of this.recentUploadsOrder.splice(
+          0,
+          this.recentUploadsOrder.length - this.maxRecentUploads,
+        )) {
+          this.recentUploads.delete(txHashToRemove);
+        }
+      }
+
+      await retry(
+        () => this.fileStore.save(path, tx.toBuffer(), { compress: false }),
+        `Uploading tx ${txHash}`,
+        makeBackoff([0.1, 0.5, 2]),
+        this.log,
+        true, // failSilently - don't log errors during retries
+      );
+      const durationMs = Math.trunc(timer.ms());
+      this.log.debug(`Uploaded tx to file store`, { txHash, path, durationMs });
+      this.instrumentation.recordUploadSuccess(durationMs);
+    } catch (err) {
+      this.log.warn(`Failed to upload tx to file store after retries`, { txHash, error: err });
+      this.instrumentation.recordUploadFailed();
+    }
+  }
+
+  /** Waits for all queued and in-flight uploads to complete. For testing. */
+  public async flush(): Promise<void> {
+    while (this.uploadQueue.length > 0 || this.activeUploads > 0) {
+      await this.queueProcessor.trigger();
+    }
+  }
+
+  /** Returns the number of pending uploads (queued + in-flight). */
+  public getPendingUploadCount(): number {
+    return this.uploadQueue.length + this.activeUploads;
+  }
+}