@aztec/p2p 0.0.1-commit.6230efd → 0.0.1-commit.6a729f7

package/src/client/p2p_client.ts

@@ -1,30 +1,29 @@
-import { GENESIS_BLOCK_HEADER_HASH, INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
+import { GENESIS_BLOCK_HEADER_HASH } from '@aztec/constants';
 import { BlockNumber, SlotNumber } from '@aztec/foundation/branded-types';
 import { createLogger } from '@aztec/foundation/log';
 import { DateProvider } from '@aztec/foundation/timer';
-import type { AztecAsyncKVStore, AztecAsyncMap, AztecAsyncSingleton } from '@aztec/kv-store';
-import type {
-  EthAddress,
-  L2BlockId,
-  L2BlockNew,
-  L2BlockSource,
+import type { AztecAsyncKVStore, AztecAsyncSingleton } from '@aztec/kv-store';
+import { L2TipsKVStore } from '@aztec/kv-store/stores';
+import {
+  type EthAddress,
+  type L2Block,
+  type L2BlockSource,
   L2BlockStream,
-  L2BlockStreamEvent,
-  L2Tips,
+  type L2BlockStreamEvent,
+  type L2Tips,
+  type L2TipsStore,
 } from '@aztec/stdlib/block';
 import type { ContractDataSource } from '@aztec/stdlib/contract';
 import { getTimestampForSlot } from '@aztec/stdlib/epoch-helpers';
 import { type PeerInfo, tryStop } from '@aztec/stdlib/interfaces/server';
-import { BlockAttestation, type BlockProposal, type P2PClientType } from '@aztec/stdlib/p2p';
-import type { Tx, TxHash } from '@aztec/stdlib/tx';
 import {
-  Attributes,
-  type TelemetryClient,
-  TraceableL2BlockStream,
-  WithTracer,
-  getTelemetryClient,
-  trackSpan,
-} from '@aztec/telemetry-client';
+  type BlockProposal,
+  CheckpointAttestation,
+  type CheckpointProposal,
+  type P2PClientType,
+} from '@aztec/stdlib/p2p';
+import type { Tx, TxHash } from '@aztec/stdlib/tx';
+import { Attributes, type TelemetryClient, WithTracer, getTelemetryClient, trackSpan } from '@aztec/telemetry-client';
 
 import type { PeerId } from '@libp2p/interface';
 import type { ENR } from '@nethermindeth/enr';
@@ -40,7 +39,7 @@ import {
   type ReqRespSubProtocolValidators,
 } from '../services/reqresp/interface.js';
 import { chunkTxHashesRequest } from '../services/reqresp/protocols/tx.js';
-import type { P2PBlockReceivedCallback, P2PService } from '../services/service.js';
+import type { P2PBlockReceivedCallback, P2PCheckpointReceivedCallback, P2PService } from '../services/service.js';
 import { TxCollection } from '../services/tx_collection/tx_collection.js';
 import { TxProvider } from '../services/tx_provider.js';
 import { type P2P, P2PClientState, type P2PSyncState } from './interface.js';
@@ -62,10 +61,7 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
   private provenBlockNumberAtStart = -1;
   private finalizedBlockNumberAtStart = -1;
 
-  private synchedBlockHashes: AztecAsyncMap<BlockNumber, string>;
-  private synchedLatestBlockNumber: AztecAsyncSingleton<BlockNumber>;
-  private synchedProvenBlockNumber: AztecAsyncSingleton<BlockNumber>;
-  private synchedFinalizedBlockNumber: AztecAsyncSingleton<BlockNumber>;
+  private l2Tips: L2TipsStore;
   private synchedLatestSlot: AztecAsyncSingleton<bigint>;
 
   private txPool: TxPool;
@@ -114,7 +110,8 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     );
 
     // Default to collecting all txs when we see a valid proposal
-    // This can be overridden by the validator client to attest, and it will call getTxsForBlockProposal on its own
+    // This can be overridden by the validator client to validate, and it will call getTxsForBlockProposal on its own
+    // Note: Validators do NOT attest to individual blocks - attestations are only for checkpoint proposals.
     // TODO(palla/txs): We should not trigger a request for txs on a proposal before fully validating it. We need to bring
     // validator-client code into here so we can validate a proposal is reasonable.
     this.registerBlockProposalHandler(async (block, sender) => {
@@ -123,21 +120,17 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
       const constants = this.txCollection.getConstants();
       const nextSlotTimestampSeconds = Number(getTimestampForSlot(SlotNumber(block.slotNumber + 1), constants));
       const deadline = new Date(nextSlotTimestampSeconds * 1000);
-      const parentBlock = await this.l2BlockSource.getBlockHeaderByArchive(block.payload.header.lastArchiveRoot);
+      const parentBlock = await this.l2BlockSource.getBlockHeaderByArchive(block.blockHeader.lastArchive.root);
       if (!parentBlock) {
         this.log.debug(`Cannot collect txs for proposal as parent block not found`);
-        return;
+        return false;
       }
       const blockNumber = BlockNumber(parentBlock.getBlockNumber() + 1);
       await this.txProvider.getTxsForBlockProposal(block, blockNumber, { pinnedPeer: sender, deadline });
-      return undefined;
+      return true;
     });
 
-    // REFACTOR: Try replacing these with an L2TipsStore
-    this.synchedBlockHashes = store.openMap('p2p_pool_block_hashes');
-    this.synchedLatestBlockNumber = store.openSingleton('p2p_pool_last_l2_block');
-    this.synchedProvenBlockNumber = store.openSingleton('p2p_pool_last_proven_l2_block');
-    this.synchedFinalizedBlockNumber = store.openSingleton('p2p_pool_last_finalized_l2_block');
+    this.l2Tips = new L2TipsKVStore(store, 'p2p_client');
     this.synchedLatestSlot = store.openSingleton('p2p_pool_last_l2_slot');
   }
 
@@ -163,7 +156,7 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
   }
 
   public getL2BlockHash(number: BlockNumber): Promise<string | undefined> {
-    return this.synchedBlockHashes.getAsync(number);
+    return this.l2Tips.getL2BlockHash(number);
   }
 
   public updateP2PConfig(config: Partial<P2PConfig>): Promise<void> {
@@ -172,85 +165,45 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     return Promise.resolve();
   }
 
-  public async getL2Tips(): Promise<L2Tips> {
-    const latestBlockNumber = await this.getSyncedLatestBlockNum();
-    let latestBlockHash: string | undefined;
-
-    const provenBlockNumber = await this.getSyncedProvenBlockNum();
-    let provenBlockHash: string | undefined;
-
-    const finalizedBlockNumber = await this.getSyncedFinalizedBlockNum();
-    let finalizedBlockHash: string | undefined;
-
-    if (latestBlockNumber > 0) {
-      latestBlockHash = await this.synchedBlockHashes.getAsync(latestBlockNumber);
-      if (typeof latestBlockHash === 'undefined') {
-        throw new Error(`Block hash for latest block ${latestBlockNumber} not found in p2p client`);
-      }
-    }
-
-    if (provenBlockNumber > 0) {
-      provenBlockHash = await this.synchedBlockHashes.getAsync(provenBlockNumber);
-      if (typeof provenBlockHash === 'undefined') {
-        throw new Error(`Block hash for proven block ${provenBlockNumber} not found in p2p client`);
-      }
-    }
-
-    if (finalizedBlockNumber > 0) {
-      finalizedBlockHash = await this.synchedBlockHashes.getAsync(finalizedBlockNumber);
-      if (typeof finalizedBlockHash === 'undefined') {
-        throw new Error(`Block hash for finalized block ${finalizedBlockNumber} not found in p2p client`);
-      }
-    }
-
-    const genesisHash = GENESIS_BLOCK_HEADER_HASH.toString();
-
-    return {
-      latest: { hash: latestBlockHash ?? genesisHash, number: latestBlockNumber },
-      proven: { hash: provenBlockHash ?? genesisHash, number: provenBlockNumber },
-      finalized: { hash: finalizedBlockHash ?? genesisHash, number: finalizedBlockNumber },
-    };
+  public getL2Tips(): Promise<L2Tips> {
+    return this.l2Tips.getL2Tips();
   }
 
   public async handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void> {
     this.log.debug(`Handling block stream event ${event.type}`);
+
     switch (event.type) {
       case 'blocks-added':
-        await this.handleLatestL2Blocks(event.blocks.map(b => b.block.toL2Block()));
+        await this.handleLatestL2Blocks(event.blocks);
         break;
       case 'chain-finalized': {
-        // TODO (alexg): I think we can prune the block hashes map here
-        await this.setBlockHash(event.block);
-        const from = BlockNumber((await this.getSyncedFinalizedBlockNum()) + 1);
+        const oldFinalizedBlockNum = await this.getSyncedFinalizedBlockNum();
+        const from = BlockNumber(oldFinalizedBlockNum + 1);
         const limit = event.block.number - from + 1;
         if (limit > 0) {
           const oldBlocks = await this.l2BlockSource.getBlocks(from, limit);
-          await this.handleFinalizedL2Blocks(oldBlocks.map(b => b.toL2Block()));
+          await this.handleFinalizedL2Blocks(oldBlocks);
         }
         break;
       }
-      case 'chain-proven': {
-        await this.setBlockHash(event.block);
+      case 'chain-proven':
         this.txCollection.stopCollectingForBlocksUpTo(event.block.number);
-        await this.synchedProvenBlockNumber.set(event.block.number);
         break;
-      }
       case 'chain-pruned':
-        await this.setBlockHash(event.block);
         this.txCollection.stopCollectingForBlocksAfter(event.block.number);
         await this.handlePruneL2Blocks(event.block.number);
         break;
+      case 'chain-checkpointed':
+        break;
       default: {
         const _: never = event;
         break;
       }
     }
-  }
 
-  private async setBlockHash(block: L2BlockId): Promise<void> {
-    if (block.hash !== undefined) {
-      await this.synchedBlockHashes.set(block.number, block.hash.toString());
-    }
+    // Pass the event through to our l2 tips store
+    await this.l2Tips.handleBlockStreamEvent(event);
+    await this.startServiceIfSynched();
   }
 
   #assertIsReady() {
@@ -274,9 +227,9 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
 
     // get the current latest block numbers
     const latestBlockNumbers = await this.l2BlockSource.getL2Tips();
-    this.latestBlockNumberAtStart = latestBlockNumbers.latest.number;
-    this.provenBlockNumberAtStart = latestBlockNumbers.proven.number;
-    this.finalizedBlockNumberAtStart = latestBlockNumbers.finalized.number;
+    this.latestBlockNumberAtStart = latestBlockNumbers.proposed.number;
+    this.provenBlockNumberAtStart = latestBlockNumbers.proven.block.number;
+    this.finalizedBlockNumberAtStart = latestBlockNumbers.finalized.block.number;
 
     const syncedLatestBlock = (await this.getSyncedLatestBlockNum()) + 1;
     const syncedProvenBlock = (await this.getSyncedProvenBlockNum()) + 1;
@@ -335,12 +288,10 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
   private initBlockStream(startingBlock?: BlockNumber) {
     if (!this.blockStream) {
       const { blockRequestBatchSize: batchSize, blockCheckIntervalMS: pollIntervalMS } = this.config;
-      this.blockStream = new TraceableL2BlockStream(
+      this.blockStream = new L2BlockStream(
         this.l2BlockSource,
         this,
         this,
-        this.telemetry.getTracer('P2PL2BlockStream'),
-        'P2PL2BlockStream',
         createLogger(`${this.log.module}:l2-block-stream`),
         { batchSize, pollIntervalMS, startingBlock },
       );
@@ -375,28 +326,44 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     [Attributes.BLOCK_ARCHIVE]: proposal.archive.toString(),
     [Attributes.P2P_ID]: (await proposal.p2pMessageLoggingIdentifier()).toString(),
   }))
-  public broadcastProposal(proposal: BlockProposal): Promise<void> {
+  public async broadcastProposal(proposal: BlockProposal): Promise<void> {
     this.log.verbose(`Broadcasting proposal for slot ${proposal.slotNumber} to peers`);
+    // Store our own proposal so we can respond to req/resp requests for it
+    await this.attestationPool.addBlockProposal(proposal);
     return this.p2pService.propagate(proposal);
   }
 
-  public async broadcastAttestations(attestations: BlockAttestation[]): Promise<void> {
-    this.log.verbose(`Broadcasting ${attestations.length} attestations to peers`);
-    await Promise.all(attestations.map(att => this.p2pService.propagate(att)));
+  @trackSpan('p2pClient.broadcastCheckpointProposal', async proposal => ({
+    [Attributes.SLOT_NUMBER]: proposal.slotNumber,
+    [Attributes.BLOCK_ARCHIVE]: proposal.archive.toString(),
+    [Attributes.P2P_ID]: (await proposal.p2pMessageLoggingIdentifier()).toString(),
+  }))
+  public async broadcastCheckpointProposal(proposal: CheckpointProposal): Promise<void> {
+    this.log.verbose(`Broadcasting checkpoint proposal for slot ${proposal.slotNumber} to peers`);
+    const blockProposal = proposal.getBlockProposal();
+    if (blockProposal) {
+      // Store our own last-block proposal so we can respond to req/resp requests for it.
+      await this.attestationPool.addBlockProposal(blockProposal);
+    }
+    return this.p2pService.propagate(proposal);
   }
 
-  public async getAttestationsForSlot(slot: SlotNumber, proposalId?: string): Promise<BlockAttestation[]> {
-    return await (proposalId
-      ? this.attestationPool.getAttestationsForSlotAndProposal(slot, proposalId)
-      : this.attestationPool.getAttestationsForSlot(slot));
+  public async broadcastCheckpointAttestations(attestations: CheckpointAttestation[]): Promise<void> {
+    this.log.verbose(`Broadcasting ${attestations.length} checkpoint attestations to peers`);
+    await Promise.all(attestations.map(att => this.p2pService.propagate(att)));
   }
 
-  public addAttestations(attestations: BlockAttestation[]): Promise<void> {
-    return this.attestationPool.addAttestations(attestations);
+  public async getCheckpointAttestationsForSlot(
+    slot: SlotNumber,
+    proposalId?: string,
+  ): Promise<CheckpointAttestation[]> {
+    return await (proposalId
+      ? this.attestationPool.getCheckpointAttestationsForSlotAndProposal(slot, proposalId)
+      : this.attestationPool.getCheckpointAttestationsForSlot(slot));
   }
 
-  public deleteAttestation(attestation: BlockAttestation): Promise<void> {
-    return this.attestationPool.deleteAttestations([attestation]);
+  public addCheckpointAttestations(attestations: CheckpointAttestation[]): Promise<void> {
+    return this.attestationPool.addCheckpointAttestations(attestations);
   }
 
   // REVIEW: https://github.com/AztecProtocol/aztec-packages/issues/7963
@@ -405,6 +372,10 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     this.p2pService.registerBlockReceivedCallback(handler);
   }
 
+  public registerCheckpointProposalHandler(handler: P2PCheckpointReceivedCallback): void {
+    this.p2pService.registerCheckpointReceivedCallback(handler);
+  }
+
   /**
    * Uses the batched Request Response protocol to request a set of transactions from the network.
    */
@@ -647,7 +618,8 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
    * @returns Block number of latest L2 Block we've synced with.
    */
   public async getSyncedLatestBlockNum(): Promise<BlockNumber> {
-    return (await this.synchedLatestBlockNumber.getAsync()) ?? BlockNumber(INITIAL_L2_BLOCK_NUM - 1);
+    const tips = await this.l2Tips.getL2Tips();
+    return tips.proposed.number;
   }
 
   /**
@@ -655,11 +627,13 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
    * @returns Block number of latest proven L2 Block we've synced with.
    */
   public async getSyncedProvenBlockNum(): Promise<BlockNumber> {
-    return (await this.synchedProvenBlockNumber.getAsync()) ?? BlockNumber(INITIAL_L2_BLOCK_NUM - 1);
+    const tips = await this.l2Tips.getL2Tips();
+    return tips.proven.block.number;
   }
 
   public async getSyncedFinalizedBlockNum(): Promise<BlockNumber> {
-    return (await this.synchedFinalizedBlockNumber.getAsync()) ?? BlockNumber(INITIAL_L2_BLOCK_NUM - 1);
+    const tips = await this.l2Tips.getL2Tips();
+    return tips.finalized.block.number;
   }
 
   /** Returns latest L2 slot for which we have seen an L2 block. */
@@ -692,7 +666,7 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
    * @param blocks - A list of existing blocks with txs that the P2P client needs to ensure the tx pool is reconciled with.
    * @returns Empty promise.
    */
-  private async markTxsAsMinedFromBlocks(blocks: L2BlockNew[]): Promise<void> {
+  private async markTxsAsMinedFromBlocks(blocks: L2Block[]): Promise<void> {
     for (const block of blocks) {
       const txHashes = block.body.txEffects.map(txEffect => txEffect.txHash);
       await this.txPool.markAsMined(txHashes, block.header);
@@ -704,7 +678,7 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
    * @param blocks - A list of existing blocks with txs that the P2P client needs to ensure the tx pool is reconciled with.
    * @returns Empty promise.
    */
-  private async handleLatestL2Blocks(blocks: L2BlockNew[]): Promise<void> {
+  private async handleLatestL2Blocks(blocks: L2Block[]): Promise<void> {
     if (!blocks.length) {
       return Promise.resolve();
     }
@@ -714,24 +688,12 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     await this.startCollectingMissingTxs(blocks);
 
     const lastBlock = blocks.at(-1)!;
-
-    await Promise.all(
-      blocks.map(async block =>
-        this.setBlockHash({
-          number: block.number,
-          hash: await block.hash().then(h => h.toString()),
-        }),
-      ),
-    );
-
-    await this.synchedLatestBlockNumber.set(lastBlock.number);
     await this.synchedLatestSlot.set(BigInt(lastBlock.header.getSlot()));
     this.log.verbose(`Synched to latest block ${lastBlock.number}`);
-    await this.startServiceIfSynched();
   }
 
   /** Request txs for unproven blocks so the prover node has more chances to get them. */
-  private async startCollectingMissingTxs(blocks: L2BlockNew[]): Promise<void> {
+  private async startCollectingMissingTxs(blocks: L2Block[]): Promise<void> {
     try {
       // TODO(#15435): If the archiver has lagged behind L1, the reported proven block number may
       // be much lower than the actual one, and it does not update until the pending chain is
@@ -764,7 +726,7 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
    * @param blocks - A list of finalized L2 blocks.
    * @returns Empty promise.
    */
-  private async handleFinalizedL2Blocks(blocks: L2BlockNew[]): Promise<void> {
+  private async handleFinalizedL2Blocks(blocks: L2Block[]): Promise<void> {
     if (!blocks.length) {
       return Promise.resolve();
     }
@@ -778,12 +740,9 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     await this.txPool.deleteTxs(txHashes, { permanently: true });
     await this.txPool.cleanupDeletedMinedTxs(lastBlockNum);
 
-    await this.attestationPool.deleteAttestationsOlderThan(lastBlockSlot);
+    await this.attestationPool.deleteCheckpointAttestationsOlderThan(lastBlockSlot);
 
-    await this.synchedFinalizedBlockNumber.set(lastBlockNum);
     this.log.debug(`Synched to finalized block ${lastBlockNum} at slot ${lastBlockSlot}`);
-
-    await this.startServiceIfSynched();
   }
 
   /**
@@ -831,18 +790,16 @@ export class P2PClient<T extends P2PClientType = P2PClientType.Full>
     } else {
       await this.txPool.markMinedAsPending(minedTxsFromReorg, latestBlock);
     }
-
-    await this.synchedLatestBlockNumber.set(latestBlock);
-    // no need to update block hashes, as they will be updated as new blocks are added
   }
 
   private async startServiceIfSynched() {
     if (this.currentState !== P2PClientState.SYNCHING) {
       return;
     }
-    const syncedFinalizedBlock = await this.getSyncedFinalizedBlockNum();
-    const syncedProvenBlock = await this.getSyncedProvenBlockNum();
-    const syncedLatestBlock = await this.getSyncedLatestBlockNum();
+    const tips = await this.l2Tips.getL2Tips();
+    const syncedFinalizedBlock = tips.finalized.block.number;
+    const syncedProvenBlock = tips.proven.block.number;
+    const syncedLatestBlock = tips.proposed.number;
 
     if (
       syncedLatestBlock >= this.latestBlockNumberAtStart &&

package/src/client/test/tx_proposal_collector/README.md

@@ -0,0 +1,227 @@
+# ProposalTxCollector Benchmarks
+
+This benchmark suite measures **how quickly a proposer node can fetch missing transactions from P2P peers** when building a block proposal. It compares two alternative transaction-collection implementations under several controlled "who-has-which-txs" distributions.
+
+## Purpose
+
+When proposing a block, the node may have a block proposal containing a list of `txHashes`, but may be **missing the full `Tx` objects** locally. The node must fetch those missing txs from peers via the P2P req/resp layer.
+
+This benchmark answers:
+
+- How long does it take to fetch **N missing txs** (N ∈ **{10, 50, 100, 500}**)?
+- How do different **peer availability patterns** affect performance?
+- Which collector strategy performs better under each pattern?
+
+The suite compares two collectors:
+
+- **`BatchTxRequesterCollector`** (collector type: `batch-requester`)
+- **`SendBatchRequestCollector`** (collector type: `send-batch-request`)
+
+## Architecture
+
+The benchmark runs a small simulated network on localhost:
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        Test Process (Driver)                        │
+│   p2p_client.proposal_tx_collector.bench.test.ts                    │
+│   ┌─────────────────────────────────────────────────────────────┐   │
+│   │            WorkerClientManager                              │   │
+│   │         (src/testbench/worker_client_manager.ts)            │   │
+│   └─────────────────────────────────────────────────────────────┘   │
+│                              │ IPC                                  │
+│         ┌────────────────────┼────────────────────┐                 │
+│         ▼                    ▼                    ▼                 │
+│   ┌───────────┐        ┌───────────┐        ┌───────────┐           │
+│   │ Worker 0  │◄──────►│ Worker 1  │◄──────►│ Worker N-1│           │
+│   │ (Collector│  P2P   │(Responder)│  P2P   │(Responder)│           │
+│   │  Node)    │        │           │        │           │           │
+│   │ TxPool:[] │        │ TxPool:   │        │ TxPool:   │           │
+│   │           │        │ [txs...]  │        │ [txs...]  │           │
+│   └───────────┘        └───────────┘        └───────────┘           │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+- **N worker processes** are spawned using Node's **`child_process.fork()`**
+- Each worker runs a "light" **`P2PClient.Full`** node (enough to exercise the real P2P req/resp machinery)
+- Workers communicate with the test process via **IPC messages** defined in `p2p_client_testbench_worker.ts`
+
+### Why multiple processes?
+
+Using separate OS processes makes the setup closer to real networking behavior (independent event loops, scheduling, IPC boundaries), and avoids many artifacts you'd get by running everything in one process.
+
+### Worker roles
+
+The network is intentionally asymmetric:
+
+- **Worker 0 is the collector/proposer node**
+  - Starts with an **empty tx pool** (`[]`)
+  - Is the only worker instructed to run the collector for each `BENCH_REQRESP` command
+- **Workers 1..N-1 are responder peers**
+  - Locally generate and filter txs according to the distribution pattern
+  - Respond to req/resp queries made by Worker 0's collector
+
+This models a proposer that has only `txHashes` in a proposal and must fetch the full tx bodies from the network.
+
+## Transaction Distribution Patterns
+
+Each benchmark case generates `missingTxCount` mock txs and assigns them to peers using one of these patterns:
+
+### `uniform`
+
+**Every responder peer has every transaction.**
+
+- Simulates the best-case: high replication / high gossip success
+- Expectation: collector should quickly succeed; differences mostly reflect collector overhead and batching strategy
+
+### `sparse`
+
+**Each transaction exists on only a small subset of peers.**
+
+Each responder is bucketed and holds txs whose index falls into its bucket or the "next" bucket (striped by tx index).
+
+- Simulates partial propagation, churn, or uneven mempool convergence
+- Expectation: collector must query multiple peers and cope with "misses"
+
+### `pinned-only`
+
+**Only a single "pinned" peer has the transactions; all other peers have none.**
+
+- Simulates "I know exactly who has the txs" (or a topology where one peer is the source of truth)
+- Useful to test whether "pinned peer" fast-paths work as intended
+
+> **Guardrail:** the pinned peer index must be within `(0, numberOfPeers)` (Worker 0 cannot be pinned).
+
+## Collectors Under Test
+
+### `BatchTxRequesterCollector` (`batch-requester`)
+
+```typescript
+new BatchTxRequesterCollector(p2pService, logger, new DateProvider())
+```
+
+Uses the P2P service plus internal logic to fetch missing txs, coordinating requests in a batched or staged way.
+
+### `SendBatchRequestCollector` (`send-batch-request`)
+
+```typescript
+const maxPeers = 10;
+const maxRetryAttempts = Math.max(peerIds.length, 3);
+new SendBatchRequestCollector(p2pService, maxPeers, maxRetryAttempts)
+```
+
+Explicitly caps the number of peers it will involve (`maxPeers`) and uses a retry budget derived from peer count.
+
+## Test Parameters
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `PEERS_PER_RUN` | 30 | Number of worker processes spawned |
+| `MISSING_TX_COUNTS` | 10, 50, 100, 500 | Number of missing transactions to fetch |
+| `TIMEOUT_MS` | 30,000 ms | Collector timeout per case |
+| `TEST_TIMEOUT_MS` | 600,000 ms | Overall Jest timeout (10 minutes) |
+
+## Running
+
+From the p2p package:
+
+```bash
+cd yarn-project/p2p
+yarn test src/client/test/tx_proposal_collector/p2p_client.proposal_tx_collector.bench.test.ts
+```
+
+Or from repo root:
+
+```bash
+yarn test p2p_client.proposal_tx_collector.bench.test.ts
+```
+
+The benchmark is intentionally long due to spawning many processes and running multiple cases.
+
+## Output Formats
+
+### Default: Markdown table to stdout
+
+If no env vars are set, the suite prints a table:
+
+```
+| Collector           | Distribution | Missing | Duration (ms) | Fetched | Success |
+|---------------------|--------------|---------|---------------|---------|---------|
+| batch-requester     | pinned-only  |      10 |           123 |      10 |   Yes   |
+| send-batch-request  | pinned-only  |      10 |           145 |      10 |   Yes   |
+```
+
+Plus a comparison summary stating which collector was faster per `(distribution, missing)` pair.
+
+### JSON metrics (for CI/dashboards)
+
+```bash
+BENCH_OUTPUT=/path/results.json yarn test ...
+```
+
+Writes JSON metrics like:
+- `ProposalTxCollector/<collector>/<distribution>/missing_<N>/duration` (ms)
+- `ProposalTxCollector/<collector>/<distribution>/missing_<N>/fetched` (txs)
+
+### Markdown file output
+
+```bash
+BENCH_OUTPUT_MD=/path/results.md yarn test ...
+```
+
+Writes the pretty table + summary to disk.
+
+## Interpreting Results
+
+For each case the benchmark records:
+
+- `durationMs`: wall-clock time spent inside the collector call
+- `fetchedCount`: how many txs were returned by the collector
+- `success`: `fetchedCount === missingTxCount`
+
+**Guidelines:**
+
+- **Always check `Success` first.** A faster run that fetched fewer txs is not a win.
+- Compare collectors **within the same distribution + missing count** only.
+- Expect `pinned-only` to highlight pinned-peer behavior (fast if pinned peer is used effectively; slow if the algorithm wastes time sampling other peers).
+- Expect `sparse` to be the most "network-like" stress case, since many peers won't have each requested tx.
+
+## Determinism / Noise Reduction
+
+Inside each worker, the benchmark intentionally reduces variability:
+
+- **Unlimited rate limits** are installed so the req/resp rate limiter doesn't dominate results
+- **Deterministic tx generation** ensures all workers see the same tx set without large IPC payloads
+
+This makes the benchmark better for *comparing collectors* (A vs B), but it is **not** a perfect model of production networking conditions.
+
+## Limitations
+
+This benchmark does **not** measure:
+
+- Real internet latency, NAT traversal, or adversarial peers (everything runs on localhost)
+- End-to-end proposer behavior beyond tx fetching (block construction, proving, etc.)
+- Gossip-based mempool convergence—tx availability is injected directly into each worker's in-memory tx pool
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `p2p_client.proposal_tx_collector.bench.test.ts` | Test suite (cases, distributions, output formatting) |
+| `proposal_tx_collector_worker.ts` | Collector-specific worker implementation |
+| `proposal_tx_collector_worker_protocol.ts` | IPC message types and serialization |
+| `src/testbench/worker_client_manager.ts` | Worker process manager (forking, IPC, orchestration) |
+| `src/testbench/p2p_client_testbench_worker.ts` | General testbench worker implementation |
+| `src/test-helpers/testbench-utils.ts` | Shared mocks and utilities (InMemoryTxPool, InMemoryAttestationPool, etc.) |
+
+## Implementation Notes
+
+- Workers run TypeScript via `ts-node/esm` unless a compiled JS worker exists at `dest/testbench/p2p_client_testbench_worker.js`
+- Request/response rate limits are overridden so the benchmark is not throttled
+- Workers generate txs locally from a shared seed to avoid sending large tx payloads over IPC
+
+## Practical Tips
+
+- Run on an otherwise idle machine; CPU scheduling noise matters when spawning 30 node processes
+- If you see intermittent failures, increase `TIMEOUT_MS` or reduce `PEERS_PER_RUN` for local iteration
+- Use `BENCH_OUTPUT` in CI to track performance regressions over time