@aztec/p2p 0.0.1-commit.f295ac2 → 0.0.1-commit.f8ca9b2f3

package/src/services/gossipsub/topic_score_params.ts

@@ -0,0 +1,451 @@
+import { TopicType, createTopicString } from '@aztec/stdlib/p2p';
+import { calculateMaxBlocksPerSlot } from '@aztec/stdlib/timetable';
+
+import { createTopicScoreParams } from '@chainsafe/libp2p-gossipsub/score';
+
+/**
+ * Network parameters needed to compute topic-specific gossipsub scoring parameters.
+ */
+export type TopicScoringNetworkParams = {
+  /** L2 slot duration in milliseconds */
+  slotDurationMs: number;
+  /** Gossipsub heartbeat interval in milliseconds */
+  heartbeatIntervalMs: number;
+  /** Target committee size (number of validators expected to attest per slot) */
+  targetCommitteeSize: number;
+  /** Duration per block in milliseconds when building multiple blocks per slot. If undefined, single block mode. */
+  blockDurationMs?: number;
+};
+
+/**
+ * Calculates the number of blocks per slot based on timing parameters.
+ * Uses the shared calculation from @aztec/stdlib/timetable.
+ *
+ * @param slotDurationMs - L2 slot duration in milliseconds
+ * @param blockDurationMs - Duration per block in milliseconds (undefined = single block mode)
+ * @returns Number of blocks per slot
+ */
+export function calculateBlocksPerSlot(slotDurationMs: number, blockDurationMs: number | undefined): number {
+  return calculateMaxBlocksPerSlot(slotDurationMs / 1000, blockDurationMs ? blockDurationMs / 1000 : undefined);
+}
+
+/**
+ * Determines the decay window in slots based on expected message frequency.
+ * Low-frequency topics need longer decay windows to accumulate meaningful counter values.
+ *
+ * @param expectedMessagesPerSlot - Expected messages per slot for this topic
+ * @returns Number of slots over which the counter should decay to ~1%
+ */
+export function getDecayWindowSlots(expectedMessagesPerSlot: number): number {
+  if (expectedMessagesPerSlot <= 1) {
+    return 5; // Low frequency: decay over 5 slots
+  } else if (expectedMessagesPerSlot <= 10) {
+    return 3; // Medium frequency: decay over 3 slots
+  } else {
+    return 2; // High frequency: decay over 2 slots
+  }
+}
+
+/**
+ * Computes the decay factor for exponential decay over a given window.
+ * After `heartbeatsInWindow` heartbeats, the counter decays to ~1% of its original value.
+ *
+ * @param heartbeatIntervalMs - Gossipsub heartbeat interval in milliseconds
+ * @param slotDurationMs - L2 slot duration in milliseconds
+ * @param decayWindowSlots - Number of slots over which to decay
+ * @returns Decay factor (0 < decay < 1), applied each heartbeat
+ */
+export function computeDecay(heartbeatIntervalMs: number, slotDurationMs: number, decayWindowSlots: number): number {
+  const heartbeatsPerSlot = slotDurationMs / heartbeatIntervalMs;
+  const heartbeatsInWindow = heartbeatsPerSlot * decayWindowSlots;
+
+  // Decay to 1% over the window: decay^heartbeatsInWindow = 0.01
+  // decay = 0.01^(1/heartbeatsInWindow)
+  return Math.pow(0.01, 1 / heartbeatsInWindow);
+}
+
+/**
+ * Computes the steady-state convergence value for a decaying counter.
+ * If messages arrive at a constant rate and decay is applied each heartbeat,
+ * the counter converges to: rate / (1 - decay)
+ *
+ * @param messagesPerHeartbeat - Expected messages per heartbeat
+ * @param decay - Decay factor applied each heartbeat
+ * @returns Convergence value (steady-state counter value)
+ */
+export function computeConvergence(messagesPerHeartbeat: number, decay: number): number {
+  return messagesPerHeartbeat / (1 - decay);
+}
+
+/**
+ * Computes a conservative threshold for mesh message deliveries.
+ * The threshold should be low enough to avoid penalizing honest peers with normal variance.
+ *
+ * @param convergence - Steady-state counter value
+ * @param conservativeFactor - Fraction of convergence to use as threshold (e.g., 0.3)
+ * @returns Threshold value
+ */
+export function computeThreshold(convergence: number, conservativeFactor: number): number {
+  return convergence * conservativeFactor;
+}
+
+/**
+ * Gets the expected messages per slot for a given topic type.
+ *
+ * @param topicType - The topic type
+ * @param targetCommitteeSize - Target committee size
+ * @param blocksPerSlot - Number of blocks per slot
+ * @returns Expected messages per slot, or undefined if unpredictable
+ */
+export function getExpectedMessagesPerSlot(
+  topicType: TopicType,
+  targetCommitteeSize: number,
+  blocksPerSlot: number,
+): number | undefined {
+  switch (topicType) {
+    case TopicType.tx:
+      // Transactions are unpredictable - disable mesh message delivery scoring
+      return undefined;
+
+    case TopicType.block_proposal:
+      // In MBPS mode, N-1 block proposals per slot (last one bundled with checkpoint)
+      // In single block mode (blocksPerSlot=1), this is 0
+      return Math.max(0, blocksPerSlot - 1);
+
+    case TopicType.checkpoint_proposal:
+      // Exactly 1 checkpoint proposal per slot
+      return 1;
+
+    case TopicType.checkpoint_attestation:
+      // Each committee member sends one attestation per slot
+      return targetCommitteeSize;
+
+    default:
+      return undefined;
+  }
+}
+
+/** Conservative factor for threshold calculation (30% of convergence) */
+const CONSERVATIVE_FACTOR = 0.3;
+
+/** Number of slots over which invalid message penalty decays */
+const INVALID_DECAY_WINDOW_SLOTS = 4;
+
+/** Weight for invalid message deliveries penalty */
+const INVALID_MESSAGE_WEIGHT = -20;
+
+/** Mesh message deliveries window in milliseconds (5 seconds - balanced for TypeScript runtime) */
+const MESH_DELIVERIES_WINDOW_MS = 5000;
+
+/**
+ * Multiplier for activation time to provide extra grace period during network bootstrap.
+ * The activation timer starts from mesh join time, not from first message received.
+ * During bootstrap, peers may join before messages start flowing, so we need extra time.
+ */
+const ACTIVATION_MULTIPLIER = 5;
+
+// ============================================================================
+// P1 (timeInMesh) Configuration
+// ============================================================================
+// P1 rewards peers for time spent in the mesh. Following Lodestar's approach,
+// we normalize the score so that max P1 = MAX_P1_SCORE after P1_CAP_TIME_SECONDS.
+//
+// Formula: P1 = min(timeInMesh / quantum, cap) * weight
+// - quantum = slotDurationMs (one increment per slot worth of time)
+// - cap = P1_CAP_TIME_SECONDS / slotSeconds (number of slots to reach cap)
+// - weight = MAX_P1_SCORE / cap
+//
+// This ensures: max P1 = cap * weight = MAX_P1_SCORE
+
+/** Maximum P1 score contribution per topic */
+export const MAX_P1_SCORE = 8;
+
+/** Time in seconds to reach P1 cap (1 hour) */
+const P1_CAP_TIME_SECONDS = 3600;
+
+// ============================================================================
+// P2 (firstMessageDeliveries) Configuration
+// ============================================================================
+// P2 rewards peers who deliver messages first. We normalize so max P2 = MAX_P2_SCORE.
+// P2 uses a decaying counter, so we set the cap based on convergence and scale the weight.
+//
+// Formula: P2 = min(firstMessageDeliveries, cap) * weight
+// - cap = convergence value for first deliveries
+// - weight = MAX_P2_SCORE / cap
+
+/** Maximum P2 score contribution per topic */
+export const MAX_P2_SCORE = 25;
+
+/** Decay window for first message deliveries in slots (fast decay) */
+const P2_DECAY_WINDOW_SLOTS = 2;
+
+// ============================================================================
+// P3 (meshMessageDeliveries) Configuration
+// ============================================================================
+// P3 penalizes peers who under-deliver messages. For a peer to be pruned from
+// the mesh, their topic score must be negative: P1 + P2 + P3 < 0
+//
+// Therefore, P3 max penalty must exceed (P1 + P2) to cause pruning:
+//   |P3| > P1 + P2
+//   |P3| > 8 + 25 = 33
+//
+// We set P3 max = -34 per topic (slightly more than P1+P2) to ensure pruning.
+// With 3 topics having P3 enabled, total P3b after pruning = -102.
+//
+// With appSpecificWeight=10, ~20 HighTolerance errors (-40 app score) plus max P3b (-102)
+// would cross gossipThreshold (-500). This keeps non-contributors from being disconnected
+// unless they also accrue app-level penalties.
+//
+// The weight formula ensures max penalty equals MAX_P3_PENALTY_PER_TOPIC:
+//   weight = MAX_P3_PENALTY_PER_TOPIC / threshold²
+//   When deficit = threshold: penalty = threshold² * weight = MAX_P3_PENALTY_PER_TOPIC
+
+/** Maximum P3 penalty per topic (must exceed P1 + P2 to cause pruning) */
+export const MAX_P3_PENALTY_PER_TOPIC = -(MAX_P1_SCORE + MAX_P2_SCORE + 1); // -34
+
+/** Number of topics with P3 enabled in MBPS mode (block_proposal + checkpoint_proposal + checkpoint_attestation) */
+export const NUM_P3_ENABLED_TOPICS = 3;
+
+/** Total maximum P3b penalty across all topics after pruning in MBPS mode */
+export const TOTAL_MAX_P3B_PENALTY = MAX_P3_PENALTY_PER_TOPIC * NUM_P3_ENABLED_TOPICS; // -102
+
+/**
+ * Factory class for creating gossipsub topic scoring parameters.
+ * Computes shared values once and reuses them across all topics.
+ */
+export class TopicScoreParamsFactory {
+  /** Number of blocks per slot based on timetable configuration */
+  public readonly blocksPerSlot: number;
+
+  /** Decay factor for invalid message penalties (P4) */
+  public readonly invalidDecay: number;
+
+  /** Number of heartbeats per slot */
+  public readonly heartbeatsPerSlot: number;
+
+  /** P1: Time in mesh quantum (slot duration in ms - score increases by ~1 per slot) */
+  public readonly timeInMeshQuantum: number;
+
+  /** P1: Time in mesh cap (number of slots to reach max score) */
+  public readonly timeInMeshCap: number;
+
+  /** P1: Time in mesh weight (normalized so max P1 = MAX_P1_SCORE) */
+  public readonly timeInMeshWeight: number;
+
+  /** P2: First message deliveries decay factor */
+  public readonly firstMessageDeliveriesDecay: number;
+
+  /** P2: First message deliveries cap (convergence-based) */
+  public readonly firstMessageDeliveriesCap: number;
+
+  /** P2: First message deliveries weight (normalized so max P2 = MAX_P2_SCORE) */
+  public readonly firstMessageDeliveriesWeight: number;
+
+  /** Base parameters common to all topics */
+  private readonly baseParams: {
+    topicWeight: number;
+    invalidMessageDeliveriesWeight: number;
+    invalidMessageDeliveriesDecay: number;
+    // P1: timeInMesh
+    timeInMeshQuantum: number;
+    timeInMeshCap: number;
+    timeInMeshWeight: number;
+    // P2: firstMessageDeliveries
+    firstMessageDeliveriesDecay: number;
+    firstMessageDeliveriesCap: number;
+    firstMessageDeliveriesWeight: number;
+  };
+
+  constructor(private readonly params: TopicScoringNetworkParams) {
+    const { slotDurationMs, heartbeatIntervalMs, blockDurationMs } = params;
+
+    // Compute values that are the same for all topics
+    this.blocksPerSlot = calculateBlocksPerSlot(slotDurationMs, blockDurationMs);
+    this.heartbeatsPerSlot = slotDurationMs / heartbeatIntervalMs;
+    this.invalidDecay = computeDecay(heartbeatIntervalMs, slotDurationMs, INVALID_DECAY_WINDOW_SLOTS);
+
+    // P1: timeInMesh - Lodestar style slot-based normalization
+    // quantum = slot duration, so score increases by ~1 per slot of mesh membership
+    // cap = number of slots in P1_CAP_TIME_SECONDS (1 hour)
+    // weight = MAX_P1_SCORE / cap, so max P1 = cap * weight = MAX_P1_SCORE
+    const slotDurationSeconds = slotDurationMs / 1000;
+    this.timeInMeshQuantum = slotDurationMs;
+    this.timeInMeshCap = P1_CAP_TIME_SECONDS / slotDurationSeconds;
+    this.timeInMeshWeight = MAX_P1_SCORE / this.timeInMeshCap;
+
+    // P2: firstMessageDeliveries - convergence-based cap with normalized weight
+    // Uses fast decay (2 slots) so it rewards recent first deliveries
+    // cap = convergence at 1 first delivery per heartbeat (theoretical max rate)
+    // weight = MAX_P2_SCORE / cap, so max P2 = cap * weight = MAX_P2_SCORE
+    this.firstMessageDeliveriesDecay = computeDecay(heartbeatIntervalMs, slotDurationMs, P2_DECAY_WINDOW_SLOTS);
+    // Convergence for 1 message per heartbeat (generous estimate for first deliveries)
+    this.firstMessageDeliveriesCap = computeConvergence(1, this.firstMessageDeliveriesDecay);
+    this.firstMessageDeliveriesWeight = MAX_P2_SCORE / this.firstMessageDeliveriesCap;
+
+    // Base params are identical for all topics
+    this.baseParams = {
+      topicWeight: 1,
+      invalidMessageDeliveriesWeight: INVALID_MESSAGE_WEIGHT,
+      invalidMessageDeliveriesDecay: this.invalidDecay,
+      // P1: timeInMesh (same for all topics)
+      timeInMeshQuantum: this.timeInMeshQuantum,
+      timeInMeshCap: this.timeInMeshCap,
+      timeInMeshWeight: this.timeInMeshWeight,
+      // P2: firstMessageDeliveries (same for all topics)
+      firstMessageDeliveriesDecay: this.firstMessageDeliveriesDecay,
+      firstMessageDeliveriesCap: this.firstMessageDeliveriesCap,
+      firstMessageDeliveriesWeight: this.firstMessageDeliveriesWeight,
+    };
+  }
+
+  /**
+   * Creates scoring parameters for topics with unpredictable or zero message rates.
+   * Disables P1, P2, P3, and P3b to avoid unbalanced positive score accumulation.
+   *
+   * Rationale: If P1/P2 were enabled without P3, the topic would contribute free
+   * positive scores that could offset penalties from other topics, preventing
+   * proper mesh pruning of non-contributing peers.
+   */
+  private createDisabledP3Params(): ReturnType<typeof createTopicScoreParams> {
+    return createTopicScoreParams({
+      topicWeight: 1,
+      // P1: timeInMesh - disabled (no free positive scores)
+      timeInMeshQuantum: 1,
+      timeInMeshCap: 0,
+      timeInMeshWeight: 0,
+      // P2: firstMessageDeliveries - disabled
+      firstMessageDeliveriesDecay: 0.5,
+      firstMessageDeliveriesCap: 0,
+      firstMessageDeliveriesWeight: 0,
+      // P3: meshMessageDeliveries - disabled
+      meshMessageDeliveriesWeight: 0,
+      meshMessageDeliveriesDecay: 0.5,
+      meshMessageDeliveriesThreshold: 0,
+      meshMessageDeliveriesWindow: 0,
+      meshMessageDeliveriesActivation: 0,
+      meshMessageDeliveriesCap: 0,
+      // P3b: meshFailurePenalty - disabled
+      meshFailurePenaltyWeight: 0,
+      meshFailurePenaltyDecay: 0.5,
+      // P4: invalidMessageDeliveries - still enabled for attack detection
+      invalidMessageDeliveriesWeight: INVALID_MESSAGE_WEIGHT,
+      invalidMessageDeliveriesDecay: this.invalidDecay,
+    });
+  }
+
+  /**
+   * Creates scoring parameters for topics with predictable message rates.
+   * Enables P1, P2, P3, and P3b for balanced scoring.
+   *
+   * The scoring is designed so that:
+   * - P1 + P2 max = 8 + 25 = 33 (positive rewards for good behavior)
+   * - P3 max = -34 (penalty exceeds P1+P2 to ensure pruning of non-contributors)
+   * - After pruning: P1 resets, P2 decays, P3b persists with slow decay
+   *
+   * @param expectedPerSlot - Expected messages per slot
+   */
+  private createEnabledP3Params(expectedPerSlot: number): ReturnType<typeof createTopicScoreParams> {
+    const { slotDurationMs, heartbeatIntervalMs } = this.params;
+
+    // Calculate decay based on message frequency
+    const decayWindowSlots = getDecayWindowSlots(expectedPerSlot);
+    const decay = computeDecay(heartbeatIntervalMs, slotDurationMs, decayWindowSlots);
+
+    // Calculate convergence and threshold
+    const messagesPerHeartbeat = expectedPerSlot / this.heartbeatsPerSlot;
+    const convergence = computeConvergence(messagesPerHeartbeat, decay);
+    const threshold = computeThreshold(convergence, CONSERVATIVE_FACTOR);
+
+    // Cap factor: higher for high-volume topics
+    const capFactor = expectedPerSlot > 10 ? 8 : 4;
+
+    // P3 Weight: scaled so max penalty = MAX_P3_PENALTY_PER_TOPIC (-34)
+    // When deficit = threshold (peer delivers nothing):
+    //   penalty = deficit² × weight = threshold² × (MAX_P3_PENALTY_PER_TOPIC / threshold²) = MAX_P3_PENALTY_PER_TOPIC
+    const meshDeliveriesWeight = threshold > 0 ? MAX_P3_PENALTY_PER_TOPIC / (threshold * threshold) : 0;
+
+    // Activation time: use the decay window multiplied by ACTIVATION_MULTIPLIER for extra grace
+    // during network bootstrap. The timer starts from mesh join time, not from first message,
+    // so peers joining before messages flow need extra time to accumulate counter values.
+    const activationMs = slotDurationMs * decayWindowSlots * ACTIVATION_MULTIPLIER;
+
+    return createTopicScoreParams({
+      ...this.baseParams,
+      // P3: meshMessageDeliveries
+      meshMessageDeliveriesWeight: meshDeliveriesWeight,
+      meshMessageDeliveriesDecay: decay,
+      meshMessageDeliveriesThreshold: threshold,
+      meshMessageDeliveriesWindow: MESH_DELIVERIES_WINDOW_MS,
+      meshMessageDeliveriesActivation: activationMs,
+      meshMessageDeliveriesCap: Math.max(threshold * capFactor, 2),
+      // P3b: meshFailurePenalty (same weight and decay as P3)
+      meshFailurePenaltyWeight: meshDeliveriesWeight,
+      meshFailurePenaltyDecay: decay,
+    });
+  }
+
+  /**
+   * Creates topic score parameters for a specific topic type.
+   *
+   * @param topicType - The topic type
+   * @returns TopicScoreParams for the topic
+   */
+  createForTopic(topicType: TopicType): ReturnType<typeof createTopicScoreParams> {
+    const expectedPerSlot = getExpectedMessagesPerSlot(topicType, this.params.targetCommitteeSize, this.blocksPerSlot);
+
+    // For unpredictable topics (tx) or topics with 0 expected messages, disable P3/P3b
+    if (expectedPerSlot === undefined || expectedPerSlot === 0) {
+      return this.createDisabledP3Params();
+    }
+
+    return this.createEnabledP3Params(expectedPerSlot);
+  }
+
+  /**
+   * Creates all topic score parameters for gossipsub configuration.
+   *
+   * @param protocolVersion - Protocol version string for topic naming
+   * @returns Record mapping topic strings to their score parameters
+   */
+  createAll(protocolVersion: string): Record<string, ReturnType<typeof createTopicScoreParams>> {
+    const topics: Record<string, ReturnType<typeof createTopicScoreParams>> = {};
+
+    for (const topicType of Object.values(TopicType)) {
+      const topicString = createTopicString(topicType, protocolVersion);
+      topics[topicString] = this.createForTopic(topicType);
+    }
+
+    return topics;
+  }
+}
+
+/**
+ * Creates topic score parameters for a specific topic type.
+ * Convenience function that creates a factory internally.
+ *
+ * @param topicType - The topic type
+ * @param params - Network parameters for scoring calculation
+ * @returns TopicScoreParams for the topic
+ */
+export function createTopicScoreParamsForTopic(
+  topicType: TopicType,
+  params: TopicScoringNetworkParams,
+): ReturnType<typeof createTopicScoreParams> {
+  const factory = new TopicScoreParamsFactory(params);
+  return factory.createForTopic(topicType);
+}
+
+/**
+ * Creates all topic score parameters for gossipsub configuration.
+ *
+ * @param protocolVersion - Protocol version string for topic naming
+ * @param params - Network parameters for scoring calculation
+ * @returns Record mapping topic strings to their score parameters
+ */
+export function createAllTopicScoreParams(
+  protocolVersion: string,
+  params: TopicScoringNetworkParams,
+): Record<string, ReturnType<typeof createTopicScoreParams>> {
+  const factory = new TopicScoreParamsFactory(params);
+  return factory.createAll(protocolVersion);
+}

package/src/services/index.ts

@@ -3,4 +3,5 @@ export * from './libp2p/libp2p_service.js';
 export * from './tx_provider.js';
 export * from './dummy_service.js';
 export * from './reqresp/index.js';
+export * from './tx_file_store/index.js';
 export * from './tx_collection/index.js';

package/src/services/libp2p/instrumentation.ts

@@ -8,6 +8,7 @@ import {
   type ObservableGauge,
   type TelemetryClient,
   type UpDownCounter,
+  createUpDownCounterWithDefault,
 } from '@aztec/telemetry-client';
 
 import { type RecordableHistogram, createHistogram } from 'node:perf_hooks';
@@ -29,11 +30,23 @@ export class P2PInstrumentation {
 
     this.messageValidationDuration = meter.createHistogram(Metrics.P2P_GOSSIP_MESSAGE_VALIDATION_DURATION);
 
-    this.messagePrevalidationCount = meter.createUpDownCounter(Metrics.P2P_GOSSIP_MESSAGE_PREVALIDATION_COUNT);
+    this.messagePrevalidationCount = createUpDownCounterWithDefault(
+      meter,
+      Metrics.P2P_GOSSIP_MESSAGE_PREVALIDATION_COUNT,
+      {
+        [Attributes.TOPIC_NAME]: [
+          TopicType.tx,
+          TopicType.block_proposal,
+          TopicType.checkpoint_proposal,
+          TopicType.checkpoint_attestation,
+        ],
+        [Attributes.OK]: [true, false],
+      },
+    );
 
     this.messageLatency = meter.createHistogram(Metrics.P2P_GOSSIP_MESSAGE_LATENCY);
 
-    this.txReceivedCount = meter.createUpDownCounter(Metrics.P2P_GOSSIP_TX_RECEIVED_COUNT);
+    this.txReceivedCount = createUpDownCounterWithDefault(meter, Metrics.P2P_GOSSIP_TX_RECEIVED_COUNT);
 
     this.aggLatencyMetrics = {
       avg: meter.createObservableGauge(Metrics.P2P_GOSSIP_AGG_MESSAGE_LATENCY_AVG),