@aztec/p2p 0.0.0-test.0 → 0.0.1-commit.001888fc

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

@@ -1,11 +1,34 @@
 import { median } from '@aztec/foundation/collection';
 import { createLogger } from '@aztec/foundation/log';
 import { PeerErrorSeverity } from '@aztec/stdlib/p2p';
+import {
+  Attributes,
+  Metrics,
+  type TelemetryClient,
+  type UpDownCounter,
+  createUpDownCounterWithDefault,
+  getTelemetryClient,
+} from '@aztec/telemetry-client';
 
 import type { PeerId } from '@libp2p/interface';
 
 import type { P2PConfig } from '../../config.js';
 
+/**
+ * Application-level peer penalties.
+ *
+ * These scores are multiplied by appSpecificWeight (10) when contributing to gossipsub score.
+ * The values are designed to align with gossipsub thresholds:
+ *
+ * - LowToleranceError (50): 1 error → app score -50 → gossipsub -500 → gossipThreshold
+ * - MidToleranceError (10): 5 errors → app score -50 → gossipsub -500 → gossipThreshold
+ * - HighToleranceError (2): 25 errors → app score -50 → gossipsub -500 → gossipThreshold
+ *
+ * Examples of each severity:
+ * - LowToleranceError: Invalid messages, deserialization errors, manipulation attempts
+ * - MidToleranceError: Hash mismatches, protocol violations
+ * - HighToleranceError: Rate limit exceeded, failed responses, transient errors
+ */
 const DefaultPeerPenalties = {
   [PeerErrorSeverity.LowToleranceError]: 50,
   [PeerErrorSeverity.MidToleranceError]: 10,
@@ -18,6 +41,16 @@ export enum PeerScoreState {
   Healthy,
 }
 
+/**
+ * Score thresholds for peer states.
+ *
+ * These values align with gossipsub thresholds when multiplied by appSpecificWeight (10):
+ * - MIN_SCORE_BEFORE_DISCONNECT (-50) × 10 = -500 = gossipThreshold
+ * - MIN_SCORE_BEFORE_BAN (-100) × 10 = -1000 = publishThreshold
+ *
+ * This ensures that when a peer is disconnected at the application level,
+ * they also stop receiving gossip, and when banned, they cannot publish.
+ */
 // TODO: move into config / constants
 const MIN_SCORE_BEFORE_BAN = -100;
 const MIN_SCORE_BEFORE_DISCONNECT = -50;
@@ -30,7 +63,9 @@ export class PeerScoring {
   private decayFactor = 0.9;
   peerPenalties: { [key in PeerErrorSeverity]: number };
 
-  constructor(config: P2PConfig) {
+  private peerStateCounter: UpDownCounter;
+
+  constructor(config: P2PConfig, telemetry: TelemetryClient = getTelemetryClient()) {
     const orderedValues = config.peerPenaltyValues?.sort((a, b) => a - b);
     this.peerPenalties = {
       [PeerErrorSeverity.HighToleranceError]:
@@ -40,6 +75,12 @@ export class PeerScoring {
       [PeerErrorSeverity.LowToleranceError]:
         orderedValues?.[2] ?? DefaultPeerPenalties[PeerErrorSeverity.LowToleranceError],
     };
+
+    const meter = telemetry.getMeter('PeerScoring');
+
+    this.peerStateCounter = createUpDownCounterWithDefault(meter, Metrics.P2P_PEER_STATE_COUNT, {
+      [Attributes.P2P_PEER_SCORE_STATE]: ['Healthy', 'Disconnect', 'Banned'],
+    });
   }
 
   public penalizePeer(peerId: PeerId, penalty: PeerErrorSeverity) {
@@ -99,7 +140,33 @@ export class PeerScoring {
     return PeerScoreState.Healthy;
   }
 
-  getStats(): { medianScore: number } {
-    return { medianScore: median(Array.from(this.scores.values())) ?? 0 };
+  getStats(): { medianScore: number; healthyCount: number; disconnectCount: number; bannedCount: number } {
+    const stateCounts = { healthy: 0, disconnect: 0, banned: 0 };
+
+    for (const peerId of this.scores.keys()) {
+      const state = this.getScoreState(peerId);
+      switch (state) {
+        case PeerScoreState.Healthy:
+          stateCounts.healthy++;
+          break;
+        case PeerScoreState.Disconnect:
+          stateCounts.disconnect++;
+          break;
+        case PeerScoreState.Banned:
+          stateCounts.banned++;
+          break;
+      }
+    }
+
+    this.peerStateCounter.add(stateCounts.healthy, { [Attributes.P2P_PEER_SCORE_STATE]: 'Healthy' });
+    this.peerStateCounter.add(stateCounts.disconnect, { [Attributes.P2P_PEER_SCORE_STATE]: 'Disconnect' });
+    this.peerStateCounter.add(stateCounts.banned, { [Attributes.P2P_PEER_SCORE_STATE]: 'Banned' });
+
+    return {
+      medianScore: median(Array.from(this.scores.values())) ?? 0,
+      healthyCount: stateCounts.healthy,
+      disconnectCount: stateCounts.disconnect,
+      bannedCount: stateCounts.banned,
+    };
   }
 }

package/src/services/reqresp/README.md

@@ -0,0 +1,229 @@
+# ReqResp Protocols
+
+This module implements libp2p request-response protocols for the Aztec P2P network. All protocols share common transport-level validation (rate limiting, timeouts, Snappy decompression, error penalties) with protocol-specific logic layered on top.
+
+## Common Transport Validation
+
+### Rate Limiting (Responder Side)
+
+Applied before the protocol handler runs.
+
+| Protocol | Peer Limit | Global Limit | File |
+|----------|-----------|-------------|------|
+| PING | 5/s | 10/s | `rate-limiter/rate_limits.ts` |
+| STATUS | 5/s | 10/s | same |
+| AUTH | 5/s | 10/s | same |
+| GOODBYE | 5/s | 10/s | same |
+| BLOCK | 2/s | 5/s | same |
+| BLOCK_TXS | 10/s | 200/s | same |
+| TX | (see rate limits file) | (see rate limits file) | same |
+
+- Per-peer limit exceeded: `HighToleranceError` penalty + `RATE_LIMIT_EXCEEDED` status. Penalty fires inside `RequestResponseRateLimiter.allow()`, not the stream handler.
+- Global limit exceeded: `RATE_LIMIT_EXCEEDED` status only (no peer penalty).
+
+### Response Status Byte (Requester Side)
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| First chunk must be exactly 1 byte | `ReqRespStatusError(UNKNOWN)` | `status.ts` |
+| Byte must be valid `ReqRespStatus` enum (0-4, 126, 127) | `ReqRespStatusError(UNKNOWN)` | same |
+
+Note: `prettyPrintReqRespStatus` is missing a `NOT_FOUND` case (minor logging bug).
+
+### Snappy Decompression (Requester Side)
+
+Per-protocol size limits checked via preamble before decompression.
+
+### Timeouts (Requester Side)
+
+| Timeout | Default | Penalty |
+|---------|---------|---------|
+| Individual request | 10s | HighToleranceError |
+| Dial | 5s | HighToleranceError |
+
+### Error Penalty Categorization (Requester Side)
+
+| Error Type | Severity |
+|------------|----------|
+| GOODBYE subprotocol errors | None |
+| `CollectiveReqRespTimeoutError` / `InvalidResponseError` | None |
+| `AbortError` / connection close / muxer closed | None |
+| `ECONNRESET` / `EPIPE` / `ECONNREFUSED` / `ERR_UNEXPECTED_EOF` | HighToleranceError |
+| `ERR_UNSUPPORTED_PROTOCOL` | HighToleranceError |
+| `IndividualReqRespTimeoutError` / `TimeoutError` | HighToleranceError |
+| Catch-all | HighToleranceError |
+
+### Request Error Penalty (Responder Side)
+
+| Error Type | Severity |
+|------------|----------|
+| `BADLY_FORMED_REQUEST` | LowToleranceError |
+| All others | None |
+
+### Notes
+
+- Request payloads are NOT snappy-compressed (asymmetric: only responses use snappy).
+
+---
+
+## Handshake Protocols
+
+### Connection-Level Gating (Before Any Handshake)
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| Deny inbound connection from IP/peerId with too many failed auth handshakes | Connection denied | `libp2p_service.ts` |
+| Threshold: `p2pMaxFailedAuthAttemptsAllowed` (default 3) | Tracked per peerId AND per IP | `peer_manager.ts` |
+| Failed auth entries expire after 1 hour | Peer can reconnect; no escalating penalty for repeat offenders | same |
+
+### Handshake Trigger Logic (`peer:connect`)
+
+1. `p2pDisableStatusHandshake` = true: no handshake
+2. `p2pAllowOnlyValidators` = false: STATUS handshake
+3. Peer is protected (trusted/private/preferred): STATUS handshake
+4. Otherwise: AUTH handshake (superset of STATUS)
+
+Config constraint: `p2pDisableStatusHandshake && p2pAllowOnlyValidators` is disallowed.
+
+### STATUS Protocol (`/aztec/req/status/1.0.0`)
+
+**Requester side** (`peer_manager.ts`):
+
+| Rule | Consequence |
+|------|-------------|
+| Response status must be SUCCESS | Peer scheduled for disconnect |
+| `compressedComponentsVersion` must match | Peer scheduled for disconnect |
+| Any exception | Peer scheduled for disconnect |
+
+`StatusMessage.validate()` currently only checks `compressedComponentsVersion`. Fields `latestBlockNumber`, `latestBlockHash`, `finalizedBlockNumber` are NOT validated (TODO in code).
+
+**Responder side**: no validation of incoming request content (always responds with own status). This means the requester leaks its blockchain state to any peer before validation.
+
+**Deserialization bounds**: `MAX_VERSION_STRING_LENGTH` = 64 bytes, `MAX_BLOCK_HASH_STRING_LENGTH` = 128 bytes. Expected response size: 1 KB.
+
+### AUTH Protocol (`/aztec/req/auth/1.0.0`)
+
+**Requester side** (`peer_manager.ts`):
+
+| # | Rule | Consequence |
+|---|------|-------------|
+| 1 | Response status is SUCCESS | `markAuthHandshakeFailed` + disconnect |
+| 2 | `compressedComponentsVersion` match | `markAuthHandshakeFailed` + disconnect |
+| 3 | Valid ECDSA signature recovery from challenge response | `markAuthHandshakeFailed` + disconnect |
+| 4 | Recovered address is a registered validator | `markAuthHandshakeFailed` + disconnect |
+| 5 | Validator address not already authenticated to different peerId | Silent return (no disconnect, no failure marking -- peer stays connected but unauthenticated) |
+| 6 | Any exception | `markAuthHandshakeFailed` + disconnect |
+
+Challenge: random `Fr`, payload = `keccak256("Aztec Validator Challenge:" + challenge)`, signed with `eth_sign` style. Challenge is NOT bound to peer identity (transport encryption via Noise is the binding layer).
+
+On success: peer added to authenticated maps, prior failures cleared (including IP-based ones -- shared-IP peers benefit from a legitimate validator's success).
+
+**Responder side** (`validator-client/src/validator.ts` + `peer_manager.ts`):
+
+| # | Rule | Consequence |
+|---|------|-------------|
+| 1 | Peer must be protected (`shouldTrustWithIdentity` in `peer_manager.ts`) | Returns empty buffer (SUCCESS status + empty payload -> requester gets parse error -> `markAuthHandshakeFailed`) |
+| 2 | Node must have registered validator address | Returns empty buffer (same consequence) |
+
+**Unauthenticated peer gossip**: when `p2pAllowOnlyValidators` is true, unauthenticated peers get `appSpecificScore = -Infinity`, completely excluding them from all gossip.
+
+### PING Protocol (`/aztec/req/ping/1.0.0`)
+
+No validation on either side. Responder returns `Buffer.from('pong')`. Expected response: 1 KB.
+
+### GOODBYE Protocol (`/aztec/req/goodbye/1.0.0`)
+
+**Responder**: buffer must be 1 byte (defaults to `UNKNOWN` on invalid length). Goodbye reason byte is NOT validated against the enum -- any byte 0-255 accepted. Peer scheduled for disconnect regardless of reason.
+
+**Requester**: response errors are never penalized (GOODBYE subprotocol exempt from error categorization).
+
+### Periodic Re-validation
+
+| Rule | Interval | File |
+|------|----------|------|
+| Authenticated validators re-checked against current validator set | Every heartbeat (`peerCheckIntervalMS`) | `peer_manager.ts` |
+| If validator address no longer registered, auth entry removed | Same | same |
+
+Protected peers (private/trusted/preferred) are always considered "authenticated" without AUTH handshake.
+
+---
+
+## Block Data Protocols
+
+### BLOCK Protocol (`/aztec/req/block/1.0.0`)
+
+**Server side**:
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| Request must parse as `Fr` | `BADLY_FORMED_REQUEST` + LowToleranceError | `protocols/block.ts` |
+| Block lookup throws | `INTERNAL_ERROR` status | same |
+| Block not found | SUCCESS + empty buffer (design choice; no `NOT_FOUND` status used) | same |
+
+**Requester side** (Snappy limit: 3 MB):
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| Response block number must match requested | LowToleranceError; rejected | `libp2p_service.ts` (`validateRequestedBlock`) |
+| Local block must exist for hash verification | Rejected (no penalty) | same |
+| Response block hash must equal local block hash | MidToleranceError; rejected | same |
+
+**Limitation**: the local-block requirement means BLOCK req/resp is unusable for initial P2P-only sync (before L1 sync provides local copies for verification). A TODO in the code acknowledges this.
+
+### BLOCK_TXS Protocol (`/aztec/req/block_txs/1.0.0`)
+
+**Server side**:
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| Request must parse as `BlockTxsRequest` (Fr + TxHashArray + BitVector) | `BADLY_FORMED_REQUEST` + LowToleranceError | `protocols/block_txs/block_txs_handler.ts` |
+| BitVector length: non-negative and <= `MAX_TXS_PER_BLOCK` (65536) | Deserialization throws -> `BADLY_FORMED_REQUEST` | `protocols/block_txs/bitvector.ts` |
+| Archive root not found and no explicit txHashes | `NOT_FOUND` status | handler |
+| Internal error during lookup | Unhandled exception -> stream abort (no `INTERNAL_ERROR` status, unlike BLOCK) | handler |
+
+Conditional registration: BLOCK_TXS handler only registered when `config.disableTransactions` is false. Otherwise peers get `ERR_UNSUPPORTED_PROTOCOL`.
+
+**Requester side via `sendBatchRequest`** (Snappy limit: `max(N, 1) * 512 + 1` KB):
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| Archive root must match request | MidToleranceError | `libp2p_service.ts` (`validateRequestedBlockTxs`) |
+| BitVector length must match request | MidToleranceError | same |
+| No duplicate tx hashes | MidToleranceError | same |
+| Tx count within bounds | MidToleranceError | same |
+| Local block proposal must exist for archive root | Rejected (no penalty) | same |
+| All tx hashes must be in proposal's tx list at allowed indices | LowToleranceError | same |
+| Txs in strictly increasing index order | LowToleranceError | same |
+| Each tx passes well-formedness (Metadata [4 fields], Size, Data, Proof) | LowToleranceError | same |
+
+**Requester side via `BatchTxRequester`** (separate validation path):
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| Non-SUCCESS status: `FAILURE`/`UNKNOWN` | HighToleranceError + "bad peer" tracking | `batch-tx-requester/batch_tx_requester.ts` |
+| `RATE_LIMIT_EXCEEDED` | Peer marked rate-limited (cooldown) | same |
+| `NOT_FOUND` / `BADLY_FORMED_REQUEST` / `INTERNAL_ERROR` | Falls through silently (no penalty) | same |
+| Each tx validated (Metadata + Size + Data + Proof) | LowToleranceError per invalid tx; valid txs from same response still accepted | same |
+| Archive root match + non-empty txIndices | No penalty on mismatch; peer not promoted to "smart" | same |
+
+**Double penalty on transport errors**: when `BatchTxRequester` encounters a transport error (e.g., ECONNRESET), both `sendRequestToPeer`'s internal handler and the `BatchTxRequester`'s catch block penalize the peer, resulting in double HighToleranceError.
+
+See [BatchTxRequester README](batch-tx-requester/README.md) for the full architecture (peer classification, worker model, wire protocol).
+
+### TX Protocol (`/aztec/req/tx/1.0.0`)
+
+**Server side**:
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| Request must parse as `TxHashArray` | `BADLY_FORMED_REQUEST` + LowToleranceError | `protocols/tx.ts` |
+
+**Requester side** (validator registered at startup, not the default noop):
+
+| Rule | Consequence | File |
+|------|-------------|------|
+| Each returned tx hash must be in the requested set | MidToleranceError | `libp2p_service.ts` (`validateRequestedTxs`) |
+| Each tx passes well-formedness (Metadata + Size + Data + Proof) | LowToleranceError | same |
+
+Snappy limit: `max(N, 1) * 512 + 1` KB.
+

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 lacks some of the referenced transactions. It serves two pathways: (1) block proposals, where validators need all transactions to attest, and (2) block proving, where provers need all transactions to generate proofs.
+
+## Overview
+
+When a validator receives a block proposal or a prover needs to prove a block, they must have all transactions. 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 deadline.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      Block Proposal or Block 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
+  blockTxsSource,       // BlockTxsSource - the proposal or block we need txs for
+  pinnedPeer,           // PeerId | undefined - peer expected to have the txs
+  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: proposals/proving │   │  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' and 'block' 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                    │
+└─────────────────────────────────────────────────────────────────────────────┘
+```