@aztec-labs/p2p 6.0.0-nightly.20260829

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

@@ -0,0 +1,265 @@
+import { median } from '@aztec-labs/foundation/collection';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { DateProvider } from '@aztec-labs/foundation/timer';
+import { PeerErrorSeverity } from '@aztec-labs/stdlib/p2p';
+import {
+  Attributes,
+  Metrics,
+  type TelemetryClient,
+  type UpDownCounter,
+  createUpDownCounterWithDefault,
+  getTelemetryClient,
+} from '@aztec-labs/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,
+  [PeerErrorSeverity.HighToleranceError]: 2,
+};
+
+export enum PeerScoreState {
+  Banned,
+  Disconnect,
+  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;
+const SCORE_CLEANUP_THRESHOLD = 0.1;
+
+/** An active ban: the score the peer held when banned, and the timestamp at which the ban lifts. */
+type BanRecord = { score: number; expiry: number };
+
+export class PeerScoring {
+  private logger = createLogger('p2p:peer-scoring');
+  private scores: Map<string, number> = new Map();
+  private lastUpdateTime: Map<string, number> = new Map();
+  private decayInterval = 1000 * 60; // 1 minute
+  private decayFactor = 0.9;
+  peerPenalties: { [key in PeerErrorSeverity]: number };
+
+  private peerStateCounter: UpDownCounter;
+
+  /** Active bans, keyed by peer id. Held in memory only, so they are cleared on restart. */
+  private bannedPeers: Map<string, BanRecord> = new Map();
+  /**
+   * How long a peer remains banned once its score crosses MIN_SCORE_BEFORE_BAN. While banned, the
+   * peer's ban score is returned by getScore regardless of decay, so it cannot recover its way out
+   * of the ban early. After the ban expires the live (decayed) score takes over again.
+   */
+  private readonly banDurationMs: number;
+
+  constructor(
+    config: P2PConfig,
+    telemetry: TelemetryClient = getTelemetryClient(),
+    private readonly dateProvider: DateProvider = new DateProvider(),
+  ) {
+    this.banDurationMs = config.peerBanDurationSeconds * 1000;
+    const orderedValues = config.peerPenaltyValues?.sort((a, b) => a - b);
+    this.peerPenalties = {
+      [PeerErrorSeverity.HighToleranceError]:
+        orderedValues?.[0] ?? DefaultPeerPenalties[PeerErrorSeverity.HighToleranceError],
+      [PeerErrorSeverity.MidToleranceError]:
+        orderedValues?.[1] ?? DefaultPeerPenalties[PeerErrorSeverity.MidToleranceError],
+      [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) {
+    const id = peerId.toString();
+    const penaltyValue = this.peerPenalties[penalty];
+    const newScore = this.updateScore(id, -penaltyValue);
+    this.logger.verbose(`Penalizing peer ${id} with ${penalty} (new score is ${newScore})`);
+    return newScore;
+  }
+
+  updateScore(peerId: string, scoreDelta: number): number {
+    const currentTime = this.dateProvider.now();
+    const lastUpdate = this.lastUpdateTime.get(peerId) || currentTime;
+    const timePassed = currentTime - lastUpdate;
+    const decayPeriods = Math.floor(timePassed / this.decayInterval);
+
+    let currentScore = this.scores.get(peerId) || 0;
+
+    // Apply decay
+    currentScore *= Math.pow(this.decayFactor, decayPeriods);
+
+    // Apply new score delta
+    currentScore += scoreDelta;
+
+    this.scores.set(peerId, currentScore);
+    this.lastUpdateTime.set(peerId, currentTime);
+
+    this.maybeBanPeer(peerId, currentScore);
+
+    return currentScore;
+  }
+
+  /**
+   * Records a ban for a peer whose score has crossed the ban threshold, with an expiry banDurationMs
+   * in the future. No-op if the score is above the threshold or the peer is already serving an active
+   * ban (an existing ban is not extended; the original window stands). A previously expired ban does
+   * not block a fresh one — getActiveBanScore prunes it first.
+   */
+  private maybeBanPeer(peerId: string, score: number): void {
+    if (score >= MIN_SCORE_BEFORE_BAN || this.getActiveBanScore(peerId) !== undefined) {
+      return;
+    }
+    const record: BanRecord = { score, expiry: this.dateProvider.now() + this.banDurationMs };
+    this.bannedPeers.set(peerId, record);
+    this.logger.verbose(`Banning peer ${peerId} until ${new Date(record.expiry).toISOString()}`, {
+      peerId,
+      score,
+      expiry: record.expiry,
+    });
+  }
+
+  decayAllScores(): void {
+    const currentTime = this.dateProvider.now();
+    for (const [peerId, lastUpdate] of this.lastUpdateTime.entries()) {
+      const timePassed = currentTime - lastUpdate;
+      const decayPeriods = Math.floor(timePassed / this.decayInterval);
+      if (decayPeriods > 0) {
+        let score = this.scores.get(peerId) || 0;
+        score *= Math.pow(this.decayFactor, decayPeriods);
+        if (Math.abs(score) < SCORE_CLEANUP_THRESHOLD) {
+          this.scores.delete(peerId);
+          this.lastUpdateTime.delete(peerId);
+        } else {
+          this.scores.set(peerId, score);
+          this.lastUpdateTime.set(peerId, currentTime);
+        }
+      }
+    }
+  }
+
+  /**
+   * Removes bans whose window has elapsed. Expired bans are otherwise only pruned lazily when their
+   * peer's score is next queried, so a banned peer that disconnects and is never queried again would
+   * linger in the map. Called periodically (per heartbeat) to bound the ban map's size.
+   */
+  pruneExpiredBans(): void {
+    const now = this.dateProvider.now();
+    const expired = [...this.bannedPeers.entries()].filter(([, ban]) => ban.expiry <= now).map(([peerId]) => peerId);
+    for (const peerId of expired) {
+      this.bannedPeers.delete(peerId);
+    }
+  }
+
+  /** Resets all peer scores. Useful for benchmarks to prevent cross-case contamination. */
+  resetAllScores(): void {
+    this.scores.clear();
+    this.lastUpdateTime.clear();
+    this.bannedPeers.clear();
+  }
+
+  removePeer(peerId: string): void {
+    this.scores.delete(peerId);
+    this.lastUpdateTime.delete(peerId);
+  }
+
+  /**
+   * The single source of truth for whether a peer is banned. Returns the ban score while the ban is
+   * active, or undefined if the peer is not banned. A ban that has expired is lazily lifted before
+   * returning undefined, so callers never see a stale ban.
+   */
+  private getActiveBanScore(peerId: string): number | undefined {
+    const ban = this.bannedPeers.get(peerId);
+    if (ban === undefined) {
+      return undefined;
+    }
+    if (ban.expiry > this.dateProvider.now()) {
+      return ban.score;
+    }
+    // Ban expired: lift it so the peer can recover.
+    this.bannedPeers.delete(peerId);
+    return undefined;
+  }
+
+  getScore(peerId: string): number {
+    // While a ban is active its ban score is returned regardless of how the live score has decayed,
+    // so the peer stays banned for the full duration.
+    return this.getActiveBanScore(peerId) ?? this.scores.get(peerId) ?? 0;
+  }
+
+  public getScoreState(peerId: string): PeerScoreState {
+    // A banned peer stays banned for the full ban duration regardless of score decay (see getScore /
+    // maybeBanPeer), rather than silently recovering once its decayed score is cleaned up.
+    const score = this.getScore(peerId);
+    if (score < MIN_SCORE_BEFORE_BAN) {
+      return PeerScoreState.Banned;
+    }
+    if (score < MIN_SCORE_BEFORE_DISCONNECT) {
+      return PeerScoreState.Disconnect;
+    }
+    return PeerScoreState.Healthy;
+  }
+
+  getStats(): { medianScore: number; healthyCount: number; disconnectCount: number; bannedCount: number } {
+    const stateCounts = { healthy: 0, disconnect: 0, banned: 0 };
+
+    // Include banned peers whose live score may have been decayed away but whose ban is still active.
+    const peerIds = new Set([...this.scores.keys(), ...this.bannedPeers.keys()]);
+    for (const peerId of peerIds) {
+      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,194 @@
+# 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_TXS | 10/s | 200/s | same |
+| TX | 10/s | 200/s | 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 |
+| `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_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) | handler |
+
+Conditional registration: BLOCK_TXS handler only registered when `config.disableTransactions` is false. Otherwise peers get `ERR_UNSUPPORTED_PROTOCOL`.
+
+**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.
+