@aztec/p2p 0.0.1-commit.e61ad554 → 0.0.1-commit.f146247c

package/src/services/libp2p/libp2p_service.ts

@@ -6,7 +6,6 @@ import { type Logger, createLibp2pComponentLogger, createLogger } from '@aztec/f
 import { RunningPromise } from '@aztec/foundation/running-promise';
 import { Timer } from '@aztec/foundation/timer';
 import type { AztecAsyncKVStore } from '@aztec/kv-store';
-import { getVKTreeRoot } from '@aztec/noir-protocol-circuits-types/vk-tree';
 import { protocolContractsHash } from '@aztec/protocol-contracts';
 import type { EthAddress, L2Block, L2BlockSource } from '@aztec/stdlib/block';
 import type { ContractDataSource } from '@aztec/stdlib/contract';
@@ -67,18 +66,15 @@ import {
   CheckpointAttestationValidator,
   CheckpointProposalValidator,
   FishermanAttestationValidator,
-  SizeTxValidator,
 } from '../../msg_validators/index.js';
 import { MessageSeenValidator } from '../../msg_validators/msg_seen_validator/msg_seen_validator.js';
 import { getDefaultAllowedSetupFunctions } from '../../msg_validators/tx_validator/allowed_public_setup.js';
-import { type MessageValidator, createTxMessageValidators } from '../../msg_validators/tx_validator/factory.js';
 import {
-  AggregateTxValidator,
-  DataTxValidator,
-  DoubleSpendTxValidator,
-  MetadataTxValidator,
-  TxProofValidator,
-} from '../../msg_validators/tx_validator/index.js';
+  type MessageValidator,
+  createTxMessageValidators,
+  createTxReqRespValidator,
+} from '../../msg_validators/tx_validator/factory.js';
+import { DoubleSpendTxValidator } from '../../msg_validators/tx_validator/index.js';
 import { GossipSubEvent } from '../../types/index.js';
 import { type PubSubLibp2p, convertToMultiaddr } from '../../util.js';
 import { getVersions } from '../../versioning.js';
@@ -89,10 +85,12 @@ import { gossipScoreThresholds } from '../gossipsub/scoring.js';
 import type { PeerManagerInterface } from '../peer-manager/interface.js';
 import { PeerManager } from '../peer-manager/peer_manager.js';
 import { PeerScoring } from '../peer-manager/peer_scoring.js';
+import type { BatchTxRequesterLibP2PService } from '../reqresp/batch-tx-requester/interface.js';
 import type { P2PReqRespConfig } from '../reqresp/config.js';
 import {
   DEFAULT_SUB_PROTOCOL_VALIDATORS,
   type ReqRespInterface,
+  type ReqRespResponse,
   ReqRespSubProtocol,
   type ReqRespSubProtocolHandler,
   type ReqRespSubProtocolHandlers,
@@ -286,14 +284,14 @@ export class LibP2PService<T extends P2PClientType = P2PClientType.Full> extends
 
     const datastore = new AztecDatastore(peerStore);
 
-    const otelMetricsAdapter = new OtelMetricsAdapter(telemetry);
+    const otelMetricsAdapter = new OtelMetricsAdapter(telemetry, logger.getBindings());
 
     const peerDiscoveryService = new DiscV5Service(
       peerId,
       config,
       packageVersion,
       telemetry,
-      createLogger(`${logger.module}:discv5_service`),
+      createLogger(`${logger.module}:discv5_service`, logger.getBindings()),
     );
 
     // Seed libp2p's bootstrap discovery with private and trusted peers
@@ -454,7 +452,7 @@ export class LibP2PService<T extends P2PClientType = P2PClientType.Full> extends
           connectionManager: components.connectionManager,
         }),
       },
-      logger: createLibp2pComponentLogger(logger.module),
+      logger: createLibp2pComponentLogger(logger.module, logger.getBindings()),
     });
 
     const peerScoring = new PeerScoring(config, telemetry);
@@ -642,6 +640,15 @@ export class LibP2PService<T extends P2PClientType = P2PClientType.Full> extends
     return this.reqresp.sendBatchRequest(protocol, requests, pinnedPeerId);
   }
 
+  public sendRequestToPeer(
+    peerId: PeerId,
+    subProtocol: ReqRespSubProtocol,
+    payload: Buffer,
+    dialTimeout?: number,
+  ): Promise<ReqRespResponse> {
+    return this.reqresp.sendRequestToPeer(peerId, subProtocol, payload, dialTimeout);
+  }
+
   /**
    * Get the ENR of the node
    * @returns The ENR of the node
@@ -1207,7 +1214,7 @@ export class LibP2PService<T extends P2PClientType = P2PClientType.Full> extends
    * @returns True if the requested block transactions are valid, false otherwise.
    */
   @trackSpan('Libp2pService.validateRequestedBlockTxs', request => ({
-    [Attributes.BLOCK_HASH]: request.blockHash.toString(),
+    [Attributes.BLOCK_ARCHIVE]: request.archiveRoot.toString(),
   }))
   private async validateRequestedBlockTxs(
     request: BlockTxsRequest,
@@ -1217,10 +1224,10 @@ export class LibP2PService<T extends P2PClientType = P2PClientType.Full> extends
     const requestedTxValidator = this.createRequestedTxValidator();
 
     try {
-      if (!response.blockHash.equals(request.blockHash)) {
+      if (!response.archiveRoot.equals(request.archiveRoot)) {
         this.peerManager.penalizePeer(peerId, PeerErrorSeverity.MidToleranceError);
         throw new ValidationError(
-          `Received block txs for unexpected block: expected ${request.blockHash.toString()}, got ${response.blockHash.toString()}`,
+          `Received block txs for unexpected archive root: expected ${request.archiveRoot.toString()}, got ${response.archiveRoot.toString()}`,
         );
       }
 
@@ -1250,7 +1257,7 @@ export class LibP2PService<T extends P2PClientType = P2PClientType.Full> extends
       }
 
       // Given proposal (should have locally), ensure returned txs are valid subset and match request indices
-      const proposal = await this.mempools.attestationPool.getBlockProposal(request.blockHash.toString());
+      const proposal = await this.mempools.attestationPool.getBlockProposal(request.archiveRoot.toString());
       if (proposal) {
         // Build intersected indices
         const intersectIdx = request.txIndices.getTrueIndices().filter(i => response.txIndices.isSet(i));
@@ -1270,7 +1277,7 @@ export class LibP2PService<T extends P2PClientType = P2PClientType.Full> extends
       } else {
         // No local proposal, cannot check the membership/order of the returned txs
         this.logger.warn(
-          `Block proposal not found for block hash ${request.blockHash.toString()}; cannot validate membership/order of returned txs`,
+          `Block proposal not found for archive root ${request.archiveRoot.toString()}; cannot validate membership/order of returned txs`,
         );
         return false;
       }
@@ -1309,7 +1316,7 @@ export class LibP2PService<T extends P2PClientType = P2PClientType.Full> extends
     const requested = new Set(requestedTxHash.map(h => h.toString()));
     const requestedTxValidator = this.createRequestedTxValidator();
 
-    //TODO: (mralj) - this is somewhat naive implementation, if single tx is invlid we consider the whole response invalid.
+    //TODO: (mralj) - this is somewhat naive implementation, if single tx is invalid we consider the whole response invalid.
     // I think we should still extract the valid txs and return them, so that we can still use the response.
     try {
       await Promise.all(responseTx.map(tx => this.validateRequestedTx(tx, peerId, requestedTxValidator, requested)));
@@ -1372,28 +1379,8 @@ export class LibP2PService<T extends P2PClientType = P2PClientType.Full> extends
     }
   }
 
-  private createRequestedTxValidator(): TxValidator {
-    return new AggregateTxValidator(
-      new DataTxValidator(),
-      new SizeTxValidator(),
-      new MetadataTxValidator({
-        l1ChainId: new Fr(this.config.l1ChainId),
-        rollupVersion: new Fr(this.config.rollupVersion),
-        protocolContractsHash,
-        vkTreeRoot: getVKTreeRoot(),
-      }),
-      new TxProofValidator(this.proofVerifier),
-    );
-  }
-
   private async validateRequestedTx(tx: Tx, peerId: PeerId, txValidator: TxValidator, requested?: Set<`0x${string}`>) {
     const penalize = (severity: PeerErrorSeverity) => this.peerManager.penalizePeer(peerId, severity);
-
-    if (!(await tx.validateTxHash())) {
-      penalize(PeerErrorSeverity.MidToleranceError);
-      throw new ValidationError(`Received tx with invalid hash ${tx.getTxHash().toString()}.`);
-    }
-
     if (requested && !requested.has(tx.getTxHash().toString())) {
       penalize(PeerErrorSeverity.MidToleranceError);
       throw new ValidationError(`Received tx with hash ${tx.getTxHash().toString()} that was not requested.`);
@@ -1406,6 +1393,13 @@ export class LibP2PService<T extends P2PClientType = P2PClientType.Full> extends
     }
   }
 
+  private createRequestedTxValidator(): TxValidator {
+    return createTxReqRespValidator(this.proofVerifier, {
+      l1ChainId: this.config.l1ChainId,
+      rollupVersion: this.config.rollupVersion,
+    });
+  }
+
   @trackSpan('Libp2pService.validatePropagatedTx', tx => ({
     [Attributes.TX_HASH]: tx.getTxHash().toString(),
   }))
@@ -1448,6 +1442,22 @@ export class LibP2PService<T extends P2PClientType = P2PClientType.Full> extends
     return gasFees;
   }
 
+  /**
+   * Get the BatchTxRequesterLibP2PService dependencies for creating BatchTxRequester instances
+   */
+  public getBatchTxRequesterService(): BatchTxRequesterLibP2PService {
+    return {
+      reqResp: this.reqresp,
+      connectionSampler: this.reqresp.getConnectionSampler(),
+      txValidatorConfig: {
+        l1ChainId: this.config.l1ChainId,
+        rollupVersion: this.config.rollupVersion,
+        proofVerifier: this.proofVerifier,
+      },
+      peerScoring: this.peerManager,
+    };
+  }
+
   public async validate(txs: Tx[]): Promise<void> {
     const currentBlockNumber = await this.archiver.getBlockNumber();
 
@@ -1498,6 +1508,7 @@ export class LibP2PService<T extends P2PClientType = P2PClientType.Full> extends
       this.proofVerifier,
       !this.config.disableTransactions,
       allowedInSetup,
+      this.logger.getBindings(),
     );
   }
 
@@ -1551,15 +1562,18 @@ export class LibP2PService<T extends P2PClientType = P2PClientType.Full> extends
       return PeerErrorSeverity.HighToleranceError;
     }
 
-    const snapshotValidator = new DoubleSpendTxValidator({
-      nullifiersExist: async (nullifiers: Buffer[]) => {
-        const merkleTree = this.worldStateSynchronizer.getSnapshot(
-          BlockNumber(blockNumber - this.config.doubleSpendSeverePeerPenaltyWindow),
-        );
-        const indices = await merkleTree.findLeafIndices(MerkleTreeId.NULLIFIER_TREE, nullifiers);
-        return indices.map(index => index !== undefined);
+    const snapshotValidator = new DoubleSpendTxValidator(
+      {
+        nullifiersExist: async (nullifiers: Buffer[]) => {
+          const merkleTree = this.worldStateSynchronizer.getSnapshot(
+            BlockNumber(blockNumber - this.config.doubleSpendSeverePeerPenaltyWindow),
+          );
+          const indices = await merkleTree.findLeafIndices(MerkleTreeId.NULLIFIER_TREE, nullifiers);
+          return indices.map(index => index !== undefined);
+        },
       },
-    });
+      this.logger.getBindings(),
+    );
 
     const validSnapshot = await snapshotValidator.validateTx(tx);
     if (validSnapshot.result !== 'valid') {

package/src/services/peer-manager/metrics.ts

@@ -6,12 +6,13 @@ import {
   type TelemetryClient,
   type Tracer,
   type UpDownCounter,
+  createUpDownCounterWithDefault,
   getTelemetryClient,
 } from '@aztec/telemetry-client';
 
 import type { PeerId } from '@libp2p/interface';
 
-import { type GoodByeReason, prettyGoodbyeReason } from '../reqresp/protocols/index.js';
+import { GoodByeReason, prettyGoodbyeReason } from '../reqresp/protocols/index.js';
 
 export class PeerManagerMetrics {
   private sentGoodbyes: UpDownCounter;
@@ -31,10 +32,26 @@ export class PeerManagerMetrics {
     this.tracer = telemetryClient.getTracer(name);
 
     const meter = telemetryClient.getMeter(name);
-    this.sentGoodbyes = meter.createUpDownCounter(Metrics.PEER_MANAGER_GOODBYES_SENT);
-    this.receivedGoodbyes = meter.createUpDownCounter(Metrics.PEER_MANAGER_GOODBYES_RECEIVED);
+    const goodbyeReasonAttrs = {
+      [Attributes.P2P_GOODBYE_REASON]: [
+        prettyGoodbyeReason(GoodByeReason.SHUTDOWN),
+        prettyGoodbyeReason(GoodByeReason.MAX_PEERS),
+        prettyGoodbyeReason(GoodByeReason.LOW_SCORE),
+        prettyGoodbyeReason(GoodByeReason.BANNED),
+        prettyGoodbyeReason(GoodByeReason.WRONG_NETWORK),
+        prettyGoodbyeReason(GoodByeReason.UNKNOWN),
+      ],
+    };
+    this.sentGoodbyes = createUpDownCounterWithDefault(meter, Metrics.PEER_MANAGER_GOODBYES_SENT, goodbyeReasonAttrs);
+    this.receivedGoodbyes = createUpDownCounterWithDefault(
+      meter,
+      Metrics.PEER_MANAGER_GOODBYES_RECEIVED,
+      goodbyeReasonAttrs,
+    );
     this.peerCount = meter.createGauge(Metrics.PEER_MANAGER_PEER_COUNT);
-    this.lowScoreDisconnects = meter.createUpDownCounter(Metrics.PEER_MANAGER_LOW_SCORE_DISCONNECTS);
+    this.lowScoreDisconnects = createUpDownCounterWithDefault(meter, Metrics.PEER_MANAGER_LOW_SCORE_DISCONNECTS, {
+      [Attributes.P2P_PEER_SCORE_STATE]: ['Banned', 'Disconnect'],
+    });
     this.peerConnectionDuration = meter.createHistogram(Metrics.PEER_MANAGER_PEER_CONNECTION_DURATION);
   }
 

package/src/services/peer-manager/peer_scoring.ts

@@ -6,6 +6,7 @@ import {
   Metrics,
   type TelemetryClient,
   type UpDownCounter,
+  createUpDownCounterWithDefault,
   getTelemetryClient,
 } from '@aztec/telemetry-client';
 
@@ -52,7 +53,9 @@ export class PeerScoring {
 
     const meter = telemetry.getMeter('PeerScoring');
 
-    this.peerStateCounter = meter.createUpDownCounter(Metrics.P2P_PEER_STATE_COUNT);
+    this.peerStateCounter = createUpDownCounterWithDefault(meter, Metrics.P2P_PEER_STATE_COUNT, {
+      [Attributes.P2P_PEER_SCORE_STATE]: ['Healthy', 'Disconnect', 'Banned'],
+    });
   }
 
   public penalizePeer(peerId: PeerId, penalty: PeerErrorSeverity) {

package/src/services/reqresp/batch-tx-requester/README.md

@@ -0,0 +1,305 @@
+# BatchTxRequester
+
+The `BatchTxRequester` is a specialized P2P service that aggressively fetches missing transactions from peers when a node receives a block proposal but lacks some of the referenced transactions. This is critical for validators who need all transactions to attest to a proposal.
+
+## Overview
+
+When a validator receives a block proposal, they must verify all transactions in the block. If some transactions are missing from the local mempool (e.g., due to gossip delays), the `BatchTxRequester` kicks in to fetch them via direct peer-to-peer requests before the attestation deadline.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           Block Proposal Received                           │
+│                     (contains hashes of N transactions)                     │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+                    ┌─────────────────────────────────┐
+                    │   Check local mempool for txs   │
+                    └─────────────────────────────────┘
+                                      │
+                    ┌─────────────────┴─────────────────┐
+                    │                                   │
+                    ▼                                   ▼
+          ┌─────────────────┐                 ┌─────────────────┐
+          │   All txs found │                 │  Missing M txs  │
+          │   → Attest now  │                 │                 │
+          └─────────────────┘                 └─────────────────┘
+                                                       │
+                                                       ▼
+                                    ┌───────────────────────────────┐
+                                    │      BatchTxRequester.run()   │
+                                    │   Fetch missing txs until     │
+                                    │   deadline or all collected   │
+                                    └───────────────────────────────┘
+```
+
+## Architecture
+
+### Peer Classification
+
+The requester classifies peers into three categories to optimize fetching:
+
+```
+                              ┌─────────────────────────────┐
+                              │        All Known Peers      │
+                              └─────────────────────────────┘
+                                           │
+              ┌────────────────────────────┼────────────────────────────┐
+              │                            │                            │
+              ▼                            ▼                            ▼
+    ┌─────────────────┐          ┌─────────────────┐          ┌─────────────────┐
+    │   Pinned Peer   │          │   Dumb Peers    │          │   Smart Peers   │
+    │                 │          │                 │          │                 │
+    │ The peer who    │          │ Peers we query  │          │ Peers that have │
+    │ sent us the     │          │ blindly - we    │          │ told us which   │
+    │ block proposal. │          │ don't know what │          │ txs they have   │
+    │ Should have ALL │          │ txs they have.  │          │ via BitVector   │
+    │ transactions.   │          │                 │          │ responses.      │
+    └─────────────────┘          └─────────────────┘          └─────────────────┘
+           │                            │                            │
+           │                            │                            │
+           ▼                            ▼                            ▼
+    ┌─────────────────┐          ┌─────────────────┐          ┌─────────────────┐
+    │ Queried in      │          │ Queried with    │          │ Queried with    │
+    │ dedicated loop, │          │ full tx hashes  │          │ BitVector only  │
+    │ prioritizes     │          │ (peer may not   │          │ (peer has the   │
+    │ least-requested │          │ have proposal)  │          │ block proposal) │
+    │ transactions    │          │                 │          │                 │
+    └─────────────────┘          └─────────────────┘          └─────────────────┘
+```
+
+### Blind Phase → Smart Phase Transition
+
+Peers transition from "dumb" to "smart" when they respond with a valid `BlockTxsResponse` containing:
+1. A matching `archiveRoot`
+2. A non-empty `txIndices` BitVector indicating which transactions they have
+3. At least one transaction we're still missing
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                              BLIND PHASE                                     │
+│  ┌────────────────────────────────────────────────────────────────────────┐  │
+│  │  Initial State: All peers are "dumb" (except pinned peer)              │  │
+│  │                                                                        │  │
+│  │  Request: [archiveRoot, txHashes (full list), txIndices (BitVector)]   │  │
+│  │           └─ Include full hashes because peer may not have proposal    │  │
+│  │                                                                        │  │
+│  │  Response: [archiveRoot, txs[], txIndices (what peer has)]             │  │
+│  │            └─ Tells us exactly which txs this peer can provide         │  │
+│  └────────────────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      │ Peer responds with valid txIndices
+                                      │ AND has txs we're missing
+                                      ▼
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                              SMART PHASE                                     │
+│  ┌────────────────────────────────────────────────────────────────────────┐  │
+│  │  Peer promoted to "smart" - we know exactly what they have             │  │
+│  │                                                                        │  │
+│  │  Request: [archiveRoot, txIndices (BitVector only)]                    │  │
+│  │           └─ No need for full hashes, peer has the proposal            │  │
+│  │                                                                        │  │
+│  │  Response: [archiveRoot, txs[], txIndices (updated availability)]      │  │
+│  │            └─ May have received more txs since last response           │  │
+│  └────────────────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Concurrent Worker Architecture
+
+The `BatchTxRequester` runs three types of workers concurrently:
+
+```
+                         ┌─────────────────────────────────────┐
+                         │         BatchTxRequester.run()      │
+                         │                                     │
+                         │  ┌─────────────────────────────┐    │
+                         │  │    txQueue (FifoMemoryQueue)│◄───┼──── Yields Tx objects
+                         │  └─────────────────────────────┘    │     to caller
+                         └─────────────────────────────────────┘
+                                          ▲
+                                          │ put(tx)
+           ┌──────────────────────────────┼────────────────────────────┐
+           │                              │                            │
+           │                              │                            │
+┌──────────┴──────────┐       ┌───────────┴─────────┐       ┌──────────┴──────────┐
+│ pinnedPeerRequester │       │    dumbRequester    │       │   smartRequester    │
+│                     │       │                     │       │                     │
+│ Single dedicated    │       │ N parallel workers  │       │ M parallel workers  │
+│ loop for pinned     │       │ (default: 10)       │       │ (default: 10)       │
+│ peer                │       │                     │       │                     │
+│                     │       │ Round-robin through │       │ Wait on semaphore   │
+│ Prioritizes txs     │       │ available dumb      │       │ until peers become  │
+│ that have been      │       │ peers               │       │ smart               │
+│ requested least     │       │                     │       │                     │
+└─────────────────────┘       └─────────────────────┘       └─────────────────────┘
+           │                              │                              │
+           └──────────────────────────────┼──────────────────────────────┘
+                                          │
+                                          ▼
+                              ┌───────────────────────┐
+                              │    requestTxBatch()   │
+                              │                       │
+                              │  sendRequestToPeer()  │
+                              │  via libp2p ReqResp   │
+                              └───────────────────────┘
+```
+
+## Wire Protocol
+
+### BlockTxsRequest
+
+```typescript
+class BlockTxsRequest {
+  archiveRoot: Fr;         // Archive root after the proposed block is applied
+  txHashes: TxHashArray;   // Full tx hashes (for dumb peers without proposal)
+  txIndices: BitVector;    // Which txs from proposal we're requesting (1 = want)
+}
+```
+
+### BlockTxsResponse
+
+```typescript
+class BlockTxsResponse {
+  archiveRoot: Fr;         // Echo back the proposal archive root
+  txs: TxArray;            // Actual transaction data
+  txIndices: BitVector;    // Which txs the peer has available (1 = have)
+}
+```
+
+The `BitVector` is a compact representation where each bit corresponds to a transaction index in the block proposal. This allows efficient capability advertisement without repeating full hashes.
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `batch_tx_requester.ts` | Main orchestrator with worker loops |
+| `missing_txs.ts` | Tracks metadata for each missing tx (request count, in-flight status, which peers have it) |
+| `peer_collection.ts` | Manages peer classification (dumb/smart/bad) and rate limiting |
+| `interface.ts` | Type definitions for dependencies |
+| `../protocols/block_txs/` | Wire protocol definitions (`BlockTxsRequest`, `BlockTxsResponse`, `BitVector`) |
+
+## Stopping Conditions
+
+The `BatchTxRequester` stops when any of these conditions are met:
+
+1. **All transactions fetched** - Success!
+2. **Deadline exceeded** - Timeout configured by caller
+3. **Abort signal** - External cancellation
+4. **No transactions to fetch** - Nothing was missing
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `batchTxRequesterSmartParallelWorkerCount` | 10 | Max concurrent requests to smart peers |
+| `batchTxRequesterDumbParallelWorkerCount` | 10 | Max concurrent requests to dumb peers |
+| `batchTxRequesterTxBatchSize` | 8 | Max transactions per request |
+| `batchTxRequesterBadPeerThreshold` | 2 | Penalties before marking peer as bad (see > threshold logic) |
+| `RATE_LIMIT_EXCEEDED_PEER_CACHE_TTL` | 1000ms | Cooldown after rate limit hit |
+
+## Error Handling
+
+### Peer States
+
+- **Bad Peer**: After `batchTxRequesterBadPeerThreshold` penalties, peer is excluded from queries
+- **Bad Peer Penalties**: A penalty is applied on `FAILURE`/`UNKNOWN` responses or when transaction validation fails
+- **Rate Limited**: On `RATE_LIMIT_EXCEEDED` response, peer is temporarily excluded
+- **Redemption**: A peer is removed from the bad set only after a successful response with all transactions valid (this clears the penalty counter)
+- **Peer Scoring**: Each penalty is forwarded to the injected `peerScoring` service with a severity
+
+### Failure Recovery
+
+```
+Request to peer fails
+        │
+        ├── RATE_LIMIT_EXCEEDED → Mark peer rate-limited, sleep, retry later
+        │
+        ├── FAILURE/UNKNOWN → Penalise peer (severity), increment penalty counter
+        │                     │
+        │                     ├── Counter < threshold → Continue querying
+        │                     │
+        │                     └── Counter ≥ threshold → Exclude peer
+        │
+        └── SUCCESS → Process response, if all transactions are valid clear penalties
+```
+
+## Usage Example
+
+```typescript
+const requester = new BatchTxRequester(
+  missingTxHashes,      // TxHash[] - what we need
+  blockProposal,        // BlockProposal - the proposal we're attesting to
+  pinnedPeer,           // PeerId | undefined - who sent us the proposal
+  timeoutMs,            // number - how long to try
+  p2pService,           // BatchTxRequesterLibP2PService
+);
+
+// Async generator yields transactions as they arrive
+for await (const tx of requester.run()) {
+  // Process each transaction as it's fetched and validated
+  mempool.addTx(tx);
+}
+
+// Or collect all at once
+const txs = await BatchTxRequester.collectAllTxs(requester.run());
+```
+
+## Integration with Broader Codebase
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                                P2PClient                                    │
+│                                                                             │
+│  Receives block proposals via gossipsub                                     │
+│  Triggers transaction collection when needed                                │
+└───────────────────────────────────┬─────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              TxCollection                                   │
+│                                                                             │
+│  Coordinates Fast and Slow collection strategies                            │
+│  Manages lifecycle of collection requests                                   │
+└───────────────────┬─────────────────────────────────┬───────────────────────┘
+                    │                                 │
+                    ▼                                 ▼
+┌───────────────────────────────────┐   ┌─────────────────────────────────────┐
+│        FastTxCollection           │   │         SlowTxCollection            │
+│                                   │   │                                     │
+│  Time-critical: attestations      │   │  Background: unproven blocks        │
+│                                   │   │                                     │
+│  1. Try RPC nodes first (fast)    │   │  Periodic polling of RPC nodes      │
+│  2. Fall back to BatchTxRequester │   │  and peers for missing txs          │
+│                                   │   │                                     │
+└───────────────────┬───────────────┘   └─────────────────────────────────────┘
+                    │
+                    │ For 'proposal' requests
+                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           BatchTxRequester                                  │
+│                                                                             │
+│  Aggressive parallel fetching from multiple peers                           │
+│  Uses BLOCK_TXS sub-protocol for efficient batching                         │
+└───────────────────┬─────────────────────────────────────────────────────────┘
+                    │
+                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         ReqResp (libp2p)                                    │
+│                                                                             │
+│  Low-level stream management                                                │
+│  sendRequestToPeer() → opens stream → sends request → awaits response       │
+└───────────────────┬─────────────────────────────────────────────────────────┘
+                    │
+                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    reqRespBlockTxsHandler (on peer)                         │
+│                                                                             │
+│  1. Parse BlockTxsRequest                                                   │
+│  2. Look up block proposal in AttestationPool                               │
+│  3. Check TxPool for available transactions                                 │
+│  4. Build BitVector of available tx indices                                 │
+│  5. Return BlockTxsResponse with txs + availability info                    │
+└─────────────────────────────────────────────────────────────────────────────┘
+```