@aztec/p2p 0.0.1-commit.0b941701 → 0.0.1-commit.134ed76

package/src/services/tx_collection/slow_tx_collection.ts

@@ -91,6 +91,7 @@ export class SlowTxCollection {
 
     for (const txHash of txHashes) {
       this.missingTxs.set(txHash.toString(), {
+        block,
         blockNumber: block.number,
         deadline: this.getDeadlineForSlot(block.header.getSlot()),
         readyForReqResp: this.nodes.length === 0, // If we have no nodes, we can start reqresp immediately
@@ -109,18 +110,26 @@ export class SlowTxCollection {
 
     // Gather all missing txs that are not in fast collection and request them from the node
     const missingTxs = this.getMissingTxsForSlowCollection();
-    const missingTxHashes = missingTxs.map(([txHash]) => txHash).map(TxHash.fromString);
-    if (missingTxHashes.length === 0) {
+    if (missingTxs.length === 0) {
       return;
     }
 
-    // Request in chunks to avoid hitting RPC limits
-    for (const batch of chunk(missingTxHashes, this.config.txCollectionNodeRpcMaxBatchSize)) {
-      await this.txCollectionSink.collect(txHashes => node.getTxsByHash(txHashes), batch, {
-        description: `node ${node.getInfo()}`,
-        node: node.getInfo(),
-        method: 'slow-node-rpc',
-      });
+    // Group by block so we pass the correct mined context to the sink
+    for (const entries of this.groupByBlock(missingTxs)) {
+      const block = entries[0][1].block;
+      const txHashes = entries.map(([txHash]) => TxHash.fromString(txHash));
+      for (const batch of chunk(txHashes, this.config.txCollectionNodeRpcMaxBatchSize)) {
+        await this.txCollectionSink.collect(
+          hashes => node.getTxsByHash(hashes),
+          batch,
+          {
+            description: `node ${node.getInfo()}`,
+            node: node.getInfo(),
+            method: 'slow-node-rpc',
+          },
+          { type: 'mined', block },
+        );
+      }
     }
 
     // Mark every tx that is still missing as ready for reqresp.
@@ -149,25 +158,30 @@ export class SlowTxCollection {
 
     const pinnedPeer = undefined;
     const timeoutMs = this.config.txCollectionSlowReqRespTimeoutMs;
-    const maxPeers = boundInclusive(Math.ceil(missingTxs.length / 3), 4, 16);
     const maxRetryAttempts = 3;
-    // Send a batch request via reqresp for the missing txs
-    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();
-      },
-      missingTxs.map(([txHash]) => TxHash.fromString(txHash)),
-      { description: 'slow reqresp', timeoutMs, method: 'slow-req-resp' },
-    );
+    // Group by block so we pass the correct mined context to the sink
+    for (const entries of this.groupByBlock(missingTxs)) {
+      const block = entries[0][1].block;
+      const txHashes = entries.map(([txHash]) => TxHash.fromString(txHash));
+      const maxPeers = boundInclusive(Math.ceil(txHashes.length / 3), 4, 16);
+      await this.txCollectionSink.collect(
+        async hashes => {
+          const txs = await this.reqResp.sendBatchRequest<ReqRespSubProtocol.TX>(
+            ReqRespSubProtocol.TX,
+            chunkTxHashesRequest(hashes),
+            pinnedPeer,
+            timeoutMs,
+            maxPeers,
+            maxRetryAttempts,
+          );
+          return txs.flat();
+        },
+        txHashes,
+        { description: 'slow reqresp', timeoutMs, method: 'slow-req-resp' },
+        { type: 'mined', block },
+      );
+    }
   }
 
   /** Retrieves all missing txs for the slow collection process. This is, all missing txs that are not part of a fast request. */
@@ -223,6 +237,21 @@ export class SlowTxCollection {
     }
   }
 
+  /** Groups missing tx entries by block number. */
+  private groupByBlock(entries: [string, MissingTxInfo][]): [string, MissingTxInfo][][] {
+    const groups = new Map<number, [string, MissingTxInfo][]>();
+    for (const entry of entries) {
+      const bn = +entry[1].blockNumber;
+      let group = groups.get(bn);
+      if (!group) {
+        group = [];
+        groups.set(bn, group);
+      }
+      group.push(entry);
+    }
+    return [...groups.values()];
+  }
+
   /** Computes the proof submission deadline for a given slot, a tx mined in this slot is no longer interesting after this deadline */
   private getDeadlineForSlot(slotNumber: SlotNumber): Date {
     const epoch = getEpochAtSlot(slotNumber, this.constants);

package/src/services/tx_collection/tx_collection.ts

@@ -2,6 +2,7 @@ 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';
+import { sleep } from '@aztec/foundation/sleep';
 import { DateProvider } from '@aztec/foundation/timer';
 import type { L2Block, L2BlockInfo } from '@aztec/stdlib/block';
 import type { L1RollupConstants } from '@aztec/stdlib/epoch-helpers';
@@ -11,18 +12,19 @@ import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-clien
 
 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 { TxPoolV2, TxPoolV2Events } from '../../mem_pools/tx_pool_v2/interfaces.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 { FileStoreTxCollection } from './file_store_tx_collection.js';
+import type { FileStoreTxSource } from './file_store_tx_source.js';
 import { SlowTxCollection } from './slow_tx_collection.js';
-import { TxCollectionSink } from './tx_collection_sink.js';
+import { type TxAddContext, TxCollectionSink } from './tx_collection_sink.js';
 import type { TxSource } from './tx_source.js';
 
-export type CollectionMethod = 'fast-req-resp' | 'fast-node-rpc' | 'slow-req-resp' | 'slow-node-rpc';
+export type CollectionMethod = 'fast-req-resp' | 'fast-node-rpc' | 'slow-req-resp' | 'slow-node-rpc' | 'file-store';
 
-export type MissingTxInfo = { blockNumber: BlockNumber; deadline: Date; readyForReqResp: boolean };
+export type MissingTxInfo = { block: L2Block; blockNumber: BlockNumber; deadline: Date; readyForReqResp: boolean };
 
 export type FastCollectionRequestInput =
   | { type: 'block'; block: L2Block }
@@ -54,6 +56,9 @@ export class TxCollection {
   /** Fast collection methods */
   protected readonly fastCollection: FastTxCollection;
 
+  /** File store collection */
+  protected readonly fileStoreCollection: FileStoreTxCollection;
+
   /** Loop for periodically reconciling found transactions from the tx pool in case we missed some */
   private readonly reconcileFoundTxsLoop: RunningPromise;
 
@@ -61,17 +66,24 @@ export class TxCollection {
   private readonly txCollectionSink: TxCollectionSink;
 
   /** Handler for the txs-added event from the tx pool */
-  protected readonly handleTxsAddedToPool: TxPoolEvents['txs-added'];
+  protected readonly handleTxsAddedToPool: TxPoolV2Events['txs-added'];
 
   /** Handler for the txs-added event from the tx collection sink */
-  protected readonly handleTxsFound: TxPoolEvents['txs-added'];
+  protected readonly handleTxsFound: TxPoolV2Events['txs-added'];
+
+  /** Whether the service has been started. */
+  private started = false;
+
+  /** Whether file store sources are configured. */
+  private readonly hasFileStoreSources: boolean;
 
   constructor(
-    private readonly reqResp: Pick<ReqRespInterface, 'sendBatchRequest'>,
+    private readonly p2pService: BatchTxRequesterLibP2PService,
     private readonly nodes: TxSource[],
     private readonly constants: L1RollupConstants,
-    private readonly txPool: TxPool,
+    private readonly txPool: TxPoolV2,
     private readonly config: TxCollectionConfig,
+    fileStoreSources: FileStoreTxSource[] = [],
     private readonly dateProvider: DateProvider = new DateProvider(),
     telemetryClient: TelemetryClient = getTelemetryClient(),
     private readonly log: Logger = createLogger('p2p:tx_collection_service'),
@@ -79,7 +91,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,
@@ -88,7 +100,7 @@ export class TxCollection {
     );
 
     this.slowCollection = new SlowTxCollection(
-      this.reqResp,
+      this.p2pService.reqResp,
       this.nodes,
       this.txCollectionSink,
       this.fastCollection,
@@ -98,18 +110,21 @@ export class TxCollection {
       this.log,
     );
 
+    this.hasFileStoreSources = fileStoreSources.length > 0;
+    this.fileStoreCollection = new FileStoreTxCollection(fileStoreSources, this.txCollectionSink, this.log);
+
     this.reconcileFoundTxsLoop = new RunningPromise(
       () => this.reconcileFoundTxsWithPool(),
       this.log,
       this.config.txCollectionReconcileIntervalMs,
     );
 
-    this.handleTxsFound = (args: Parameters<TxPoolEvents['txs-added']>[0]) => {
+    this.handleTxsFound = (args: Parameters<TxPoolV2Events['txs-added']>[0]) => {
       this.foundTxs(args.txs);
     };
     this.txCollectionSink.on('txs-added', this.handleTxsFound);
 
-    this.handleTxsAddedToPool = (args: Parameters<TxPoolEvents['txs-added']>[0]) => {
+    this.handleTxsAddedToPool = (args: Parameters<TxPoolV2Events['txs-added']>[0]) => {
       const { txs, source } = args;
       if (source !== 'tx-collection') {
         this.foundTxs(txs);
@@ -120,7 +135,9 @@ export class TxCollection {
 
   /** Starts all collection loops. */
   public start(): Promise<void> {
+    this.started = true;
     this.slowCollection.start();
+    this.fileStoreCollection.start();
     this.reconcileFoundTxsLoop.start();
 
     // TODO(palla/txs): Collect mined unproven tx hashes for txs we dont have in the pool and populate missingTxs on startup
@@ -129,7 +146,13 @@ export class TxCollection {
 
   /** Stops all activity. */
   public async stop() {
-    await Promise.all([this.slowCollection.stop(), this.fastCollection.stop(), this.reconcileFoundTxsLoop.stop()]);
+    this.started = false;
+    await Promise.all([
+      this.slowCollection.stop(),
+      this.fastCollection.stop(),
+      this.fileStoreCollection.stop(),
+      this.reconcileFoundTxsLoop.stop(),
+    ]);
 
     this.txPool.removeListener('txs-added', this.handleTxsAddedToPool);
     this.txCollectionSink.removeListener('txs-added', this.handleTxsFound);
@@ -147,7 +170,24 @@ export class TxCollection {
 
   /** Starts collecting the given tx hashes for the given L2Block in the slow loop */
   public startCollecting(block: L2Block, txHashes: TxHash[]) {
-    return this.slowCollection.startCollecting(block, txHashes);
+    this.slowCollection.startCollecting(block, txHashes);
+
+    // Delay file store collection to give P2P methods time to find txs first
+    if (this.hasFileStoreSources) {
+      const context: TxAddContext = { type: 'mined', block };
+      sleep(this.config.txCollectionFileStoreSlowDelayMs)
+        .then(() => {
+          if (this.started) {
+            // Only queue txs that are still missing after the delay
+            const stillMissing = new Set(this.slowCollection.getMissingTxHashes().map(h => h.toString()));
+            const remaining = txHashes.filter(h => stillMissing.has(h.toString()));
+            if (remaining.length > 0) {
+              this.fileStoreCollection.startCollecting(remaining, context);
+            }
+          }
+        })
+        .catch(err => this.log.error('Error in file store slow delay', err));
+    }
   }
 
   /** Collects the set of txs for the given block proposal as fast as possible */
@@ -175,13 +215,37 @@ export class TxCollection {
     txHashes: TxHash[] | string[],
     opts: { deadline: Date; pinnedPeer?: PeerId },
   ) {
+    const hashes = txHashes.map(h => (typeof h === 'string' ? TxHash.fromString(h) : h));
+
+    // Delay file store collection to give P2P methods time to find txs first
+    if (this.hasFileStoreSources) {
+      const context = this.getAddContextForInput(input);
+      sleep(this.config.txCollectionFileStoreFastDelayMs)
+        .then(() => {
+          if (this.started) {
+            this.fileStoreCollection.startCollecting(hashes, context);
+          }
+        })
+        .catch(err => this.log.error('Error in file store fast delay', err));
+    }
+
     return this.fastCollection.collectFastFor(input, txHashes, opts);
   }
 
+  /** Returns the TxAddContext for the given fast collection request input */
+  private getAddContextForInput(input: FastCollectionRequestInput): TxAddContext {
+    if (input.type === 'proposal') {
+      return { type: 'proposal', blockHeader: input.blockProposal.blockHeader };
+    } else {
+      return { type: 'mined', block: input.block };
+    }
+  }
+
   /** Mark the given txs as found. Stops collecting them. */
   private foundTxs(txs: Tx[]) {
     this.slowCollection.foundTxs(txs);
     this.fastCollection.foundTxs(txs);
+    this.fileStoreCollection.foundTxs(txs);
   }
 
   /**
@@ -191,6 +255,7 @@ export class TxCollection {
   public stopCollectingForBlocksUpTo(blockNumber: BlockNumber): void {
     this.slowCollection.stopCollectingForBlocksUpTo(blockNumber);
     this.fastCollection.stopCollectingForBlocksUpTo(blockNumber);
+    this.fileStoreCollection.clearPending();
   }
 
   /**
@@ -200,6 +265,7 @@ export class TxCollection {
   public stopCollectingForBlocksAfter(blockNumber: BlockNumber): void {
     this.slowCollection.stopCollectingForBlocksAfter(blockNumber);
     this.fastCollection.stopCollectingForBlocksAfter(blockNumber);
+    this.fileStoreCollection.clearPending();
   }
 
   /** Every now and then, check if the pool has received one of the txs we are looking for, just to catch any race conditions */

package/src/services/tx_collection/tx_collection_sink.ts

@@ -1,24 +1,28 @@
 import type { Logger } from '@aztec/foundation/log';
 import { elapsed } from '@aztec/foundation/timer';
 import type { TypedEventEmitter } from '@aztec/foundation/types';
-import { Tx, type TxHash } from '@aztec/stdlib/tx';
+import type { L2Block } from '@aztec/stdlib/block';
+import type { BlockHeader, Tx, TxHash } from '@aztec/stdlib/tx';
 import type { TelemetryClient } from '@aztec/telemetry-client';
 
 import EventEmitter from 'node:events';
 
-import type { TxPool, TxPoolEvents } from '../../mem_pools/tx_pool/tx_pool.js';
+import type { TxPoolV2, TxPoolV2Events } from '../../mem_pools/tx_pool_v2/interfaces.js';
 import { TxCollectionInstrumentation } from './instrumentation.js';
 import type { CollectionMethod } from './tx_collection.js';
 
+/** Context determining how collected txs should be added to the pool. */
+export type TxAddContext = { type: 'proposal'; blockHeader: BlockHeader } | { type: 'mined'; block: L2Block };
+
 /**
  * Executes collection requests from the fast and slow collection loops, and handles collected txs
  * by adding them to the tx pool and emitting events, as well as handling logging and metrics.
  */
-export class TxCollectionSink extends (EventEmitter as new () => TypedEventEmitter<TxPoolEvents>) {
+export class TxCollectionSink extends (EventEmitter as new () => TypedEventEmitter<TxPoolV2Events>) {
   private readonly instrumentation: TxCollectionInstrumentation;
 
   constructor(
-    private readonly txPool: TxPool,
+    private readonly txPool: TxPoolV2,
     telemetryClient: TelemetryClient,
     private readonly log: Logger,
   ) {
@@ -30,6 +34,7 @@ export class TxCollectionSink extends (EventEmitter as new () => TypedEventEmitt
     collectValidTxsFn: (txHashes: TxHash[]) => Promise<(Tx | undefined)[]>,
     requested: TxHash[],
     info: Record<string, any> & { description: string; method: CollectionMethod },
+    context: TxAddContext,
   ) {
     this.log.trace(`Requesting ${requested.length} txs via ${info.description}`, {
       ...info,
@@ -99,12 +104,13 @@ export class TxCollectionSink extends (EventEmitter as new () => TypedEventEmitt
       },
     );
 
-    return await this.foundTxs(validTxs, { ...info, duration });
+    return await this.foundTxs(validTxs, { ...info, duration }, context);
   }
 
   private async foundTxs(
     txs: Tx[],
     info: Record<string, any> & { description: string; method: CollectionMethod; duration: number },
+    context: TxAddContext,
   ) {
     // Report metrics for the collection
     this.instrumentation.increaseTxsFor(info.method, txs.length, info.duration);
@@ -112,9 +118,13 @@ export class TxCollectionSink extends (EventEmitter as new () => TypedEventEmitt
     // Mark txs as found in the slow missing txs set and all fast requests
     this.emit('txs-added', { txs });
 
-    // Add the txs to the tx pool (should not fail, but we catch it just in case)
+    // Add the txs to the tx pool using the appropriate method based on context
     try {
-      await this.txPool.addTxs(txs, { source: `tx-collection` });
+      if (context.type === 'mined') {
+        await this.txPool.addMinedTxs(txs, context.block.header, { source: 'tx-collection' });
+      } else {
+        await this.txPool.addProtectedTxs(txs, context.blockHeader, { source: 'tx-collection' });
+      }
     } catch (err) {
       this.log.error(`Error adding txs to the pool via ${info.description}`, err, {
         ...info,

package/src/services/tx_file_store/config.ts

@@ -0,0 +1,37 @@
+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;
+  /** 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://)',
+  },
+  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 { TxPoolV2 } from '../../mem_pools/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: (args: { txs: Tx[]; source?: string }) => void;
+
+  /** 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: TxPoolV2,
+    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: TxPoolV2,
+    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;
+  }
+}