@aztec/p2p 0.0.1-commit.c2595eba → 0.0.1-commit.c2eed6949

package/src/services/tx_collection/file_store_tx_collection.ts

@@ -0,0 +1,202 @@
+import { type Logger, createLogger } from '@aztec/foundation/log';
+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';
+
+/** 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.
+ * 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 string to entry for all pending downloads. */
+  private entries = new Map<string, FileStoreTxEntry>();
+
+  /** Worker promises for the shared worker pool. */
+  private workers: Promise<void>[] = [];
+
+  /** 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 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 shared worker pool. */
+  public start(): void {
+    if (this.sources.length === 0) {
+      this.log.debug('No file store sources configured');
+      return;
+    }
+    this.running = true;
+    for (let i = 0; i < this.config.workerCount; i++) {
+      this.workers.push(this.workerLoop());
+    }
+  }
+
+  /** Stops all workers and clears state. */
+  public async stop(): Promise<void> {
+    this.running = false;
+    this.wake();
+    await Promise.all(this.workers);
+    this.workers = [];
+    this.entries.clear();
+  }
+
+  /** 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;
+    }
+
+    for (const txHash of txHashes) {
+      const hashStr = txHash.toString();
+      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();
+  }
+
+  /** Removes entries for txs that have been found elsewhere. */
+  public foundTxs(txs: Tx[]): void {
+    for (const tx of txs) {
+      this.entries.delete(tx.getTxHash().toString());
+    }
+  }
+
+  /** Clears all pending entries. */
+  public clearPending(): void {
+    this.entries.clear();
+  }
+
+  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(
+          () => source.getTxsByHash([TxHash.fromString(entry.txHash)]),
+          [entry.txHash],
+          {
+            description: `file-store ${source.getInfo()}`,
+            method: 'file-store',
+            fileStore: source.getInfo(),
+          },
+          entry.context,
+        );
+        if (result.txs.length > 0) {
+          this.entries.delete(entry.txHash);
+        }
+      } catch (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;
+      }
+    }
+
+    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]);
+  }
+}

package/src/services/tx_collection/file_store_tx_source.ts

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

package/src/services/tx_collection/index.ts

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

package/src/services/tx_collection/instrumentation.ts

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

package/src/services/tx_collection/proposal_tx_collector.ts

@@ -1,7 +1,6 @@
 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 Tx, TxHash } from '@aztec/stdlib/tx';
 
 import type { PeerId } from '@libp2p/interface';
 
@@ -9,27 +8,25 @@ import { BatchTxRequester } from '../reqresp/batch-tx-requester/batch_tx_request
 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';
+import { type BlockTxsSource, ReqRespSubProtocol, chunkTxHashesRequest } from '../reqresp/index.js';
+import type { IRequestTracker } from './request_tracker.js';
 
 /**
- * Strategy interface for collecting transactions for block proposals.
+ * Strategy interface for collecting missing transactions for a block or proposal.
  * Allows swapping between different tx collection implementations for benchmarking.
  */
-export interface ProposalTxCollector {
+export interface MissingTxsCollector {
   /**
-   * 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
+   * Collect missing transactions for a block or proposal.
+   * @param requestTracker - The missing transactions tracker
+   * @param blockTxsSource - The block or proposal containing the transactions
+   * @param pinnedPeer - Optional peer expected to have the transactions
    * @returns The collected transactions
    */
   collectTxs(
-    txHashes: TxHash[],
-    blockProposal: BlockProposal,
+    requestTracker: IRequestTracker,
+    blockTxsSource: BlockTxsSource,
     pinnedPeer: PeerId | undefined,
-    timeoutMs: number,
   ): Promise<Tx[]>;
 }
 
@@ -37,7 +34,7 @@ export interface ProposalTxCollector {
  * Collects transactions using the BatchTxRequester implementation.
  * This uses a smart/dumb peer strategy with parallel workers.
  */
-export class BatchTxRequesterCollector implements ProposalTxCollector {
+export class BatchTxRequesterCollector implements MissingTxsCollector {
   constructor(
     private p2pService: BatchTxRequesterLibP2PService,
     private log: Logger,
@@ -47,10 +44,9 @@ export class BatchTxRequesterCollector implements ProposalTxCollector {
   ) {}
 
   async collectTxs(
-    txHashes: TxHash[],
-    blockProposal: BlockProposal,
+    requestTracker: IRequestTracker,
+    blockTxsSource: BlockTxsSource,
     pinnedPeer: PeerId | undefined,
-    timeoutMs: number,
   ): Promise<Tx[]> {
     const {
       batchTxRequesterSmartParallelWorkerCount: smartParallelWorkerCount,
@@ -60,10 +56,9 @@ export class BatchTxRequesterCollector implements ProposalTxCollector {
     } = this.batchTxRequesterConfig ?? {};
 
     const batchRequester = new BatchTxRequester(
-      txHashes,
-      blockProposal,
+      requestTracker,
+      blockTxsSource,
       pinnedPeer,
-      timeoutMs,
       this.p2pService,
       this.log,
       this.dateProvider,
@@ -87,7 +82,7 @@ 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 {
+export class SendBatchRequestCollector implements MissingTxsCollector {
   constructor(
     private p2pService: BatchTxRequesterLibP2PService,
     private maxPeers: number = DEFAULT_MAX_PEERS,
@@ -95,16 +90,15 @@ export class SendBatchRequestCollector implements ProposalTxCollector {
   ) {}
 
   async collectTxs(
-    txHashes: TxHash[],
-    _blockProposal: BlockProposal,
+    requestTracker: IRequestTracker,
+    _blockTxsSource: BlockTxsSource,
     pinnedPeer: PeerId | undefined,
-    timeoutMs: number,
   ): Promise<Tx[]> {
     const txs = await this.p2pService.reqResp.sendBatchRequest<ReqRespSubProtocol.TX>(
       ReqRespSubProtocol.TX,
-      chunkTxHashesRequest(txHashes),
+      chunkTxHashesRequest(Array.from(requestTracker.missingTxHashes).map(TxHash.fromString)),
       pinnedPeer,
-      timeoutMs,
+      requestTracker.timeoutMs,
       this.maxPeers,
       this.maxRetryAttempts,
     );

package/src/services/tx_collection/request_tracker.ts

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