@libp2p/gossipsub 14.1.1-6059227cb

package/src/score/compute-score.ts

@@ -0,0 +1,98 @@
+import type { PeerScoreParams } from './peer-score-params.js'
+import type { PeerStats } from './peer-stats.js'
+
+export function computeScore (
+  peer: string,
+  pstats: PeerStats,
+  params: PeerScoreParams,
+  peerIPs: Map<string, Set<string>>
+): number {
+  let score = 0
+
+  // topic stores
+  Object.entries(pstats.topics).forEach(([topic, tstats]) => {
+    // the topic parameters
+    const topicParams = params.topics[topic]
+    if (topicParams === undefined) {
+      // we are not scoring this topic
+      return
+    }
+
+    let topicScore = 0
+
+    // P1: time in Mesh
+    if (tstats.inMesh) {
+      let p1 = tstats.meshTime / topicParams.timeInMeshQuantum
+      if (p1 > topicParams.timeInMeshCap) {
+        p1 = topicParams.timeInMeshCap
+      }
+      topicScore += p1 * topicParams.timeInMeshWeight
+    }
+
+    // P2: first message deliveries
+    let p2 = tstats.firstMessageDeliveries
+    if (p2 > topicParams.firstMessageDeliveriesCap) {
+      p2 = topicParams.firstMessageDeliveriesCap
+    }
+    topicScore += p2 * topicParams.firstMessageDeliveriesWeight
+
+    // P3: mesh message deliveries
+    if (
+      tstats.meshMessageDeliveriesActive &&
+      tstats.meshMessageDeliveries < topicParams.meshMessageDeliveriesThreshold
+    ) {
+      const deficit = topicParams.meshMessageDeliveriesThreshold - tstats.meshMessageDeliveries
+      const p3 = deficit * deficit
+      topicScore += p3 * topicParams.meshMessageDeliveriesWeight
+    }
+
+    // P3b:
+    // NOTE: the weight of P3b is negative (validated in validateTopicScoreParams) so this detracts
+    const p3b = tstats.meshFailurePenalty
+    topicScore += p3b * topicParams.meshFailurePenaltyWeight
+
+    // P4: invalid messages
+    // NOTE: the weight of P4 is negative (validated in validateTopicScoreParams) so this detracts
+    const p4 = tstats.invalidMessageDeliveries * tstats.invalidMessageDeliveries
+    topicScore += p4 * topicParams.invalidMessageDeliveriesWeight
+
+    // update score, mixing with topic weight
+    score += topicScore * topicParams.topicWeight
+  })
+
+  // apply the topic score cap, if any
+  if (params.topicScoreCap > 0 && score > params.topicScoreCap) {
+    score = params.topicScoreCap
+  }
+
+  // P5: application-specific score
+  const p5 = params.appSpecificScore(peer)
+  score += p5 * params.appSpecificWeight
+
+  // P6: IP colocation factor
+  pstats.knownIPs.forEach((ip) => {
+    if (params.IPColocationFactorWhitelist.has(ip)) {
+      return
+    }
+
+    // P6 has a cliff (IPColocationFactorThreshold)
+    // It's only applied if at least that many peers are connected to us from that source IP addr.
+    // It is quadratic, and the weight is negative (validated in validatePeerScoreParams)
+    const peersInIP = peerIPs.get(ip)
+    const numPeersInIP = (peersInIP != null) ? peersInIP.size : 0
+    if (numPeersInIP > params.IPColocationFactorThreshold) {
+      const surplus = numPeersInIP - params.IPColocationFactorThreshold
+      const p6 = surplus * surplus
+      score += p6 * params.IPColocationFactorWeight
+    }
+  })
+
+  // P7: behavioural pattern penalty
+  if (pstats.behaviourPenalty > params.behaviourPenaltyThreshold) {
+    const excess = pstats.behaviourPenalty - params.behaviourPenaltyThreshold
+    const p7 = excess * excess
+    score += p7 * params.behaviourPenaltyWeight
+  }
+
+  return score
+}

package/src/score/index.ts

@@ -0,0 +1,3 @@
+export * from './peer-score-params.js'
+export * from './peer-score-thresholds.js'
+export * from './peer-score.js'

package/src/score/message-deliveries.ts

@@ -0,0 +1,95 @@
+import Denque from 'denque'
+import { TimeCacheDuration } from '../constants.js'
+
+export enum DeliveryRecordStatus {
+  /**
+   * we don't know (yet) if the message is valid
+   */
+  unknown,
+  /**
+   * we know the message is valid
+   */
+  valid,
+  /**
+   * we know the message is invalid
+   */
+  invalid,
+  /**
+   * we were instructed by the validator to ignore the message
+   */
+  ignored
+}
+
+export interface DeliveryRecord {
+  status: DeliveryRecordStatus
+  firstSeenTsMs: number
+  validated: number
+  peers: Set<string>
+}
+
+interface DeliveryQueueEntry {
+  msgId: string
+  expire: number
+}
+
+/**
+ * Map of canonical message ID to DeliveryRecord
+ *
+ * Maintains an internal queue for efficient gc of old messages
+ */
+export class MessageDeliveries {
+  private readonly records: Map<string, DeliveryRecord>
+  public queue: Denque<DeliveryQueueEntry>
+
+  constructor () {
+    this.records = new Map()
+    this.queue = new Denque()
+  }
+
+  getRecord (msgIdStr: string): DeliveryRecord | undefined {
+    return this.records.get(msgIdStr)
+  }
+
+  ensureRecord (msgIdStr: string): DeliveryRecord {
+    let drec = this.records.get(msgIdStr)
+    if (drec != null) {
+      return drec
+    }
+
+    // record doesn't exist yet
+    // create record
+    drec = {
+      status: DeliveryRecordStatus.unknown,
+      firstSeenTsMs: Date.now(),
+      validated: 0,
+      peers: new Set()
+    }
+    this.records.set(msgIdStr, drec)
+
+    // and add msgId to the queue
+    const entry: DeliveryQueueEntry = {
+      msgId: msgIdStr,
+      expire: Date.now() + TimeCacheDuration
+    }
+    this.queue.push(entry)
+
+    return drec
+  }
+
+  gc (): void {
+    const now = Date.now()
+    // queue is sorted by expiry time
+    // remove expired messages, remove from queue until first un-expired message found
+    let head = this.queue.peekFront()
+    while ((head != null) && head.expire < now) {
+      this.records.delete(head.msgId)
+      this.queue.shift()
+      head = this.queue.peekFront()
+    }
+  }
+
+  clear (): void {
+    this.records.clear()
+    this.queue.clear()
+  }
+}

package/src/score/peer-score-params.ts

@@ -0,0 +1,316 @@
+import { InvalidPeerScoreParamsError } from '../errors.js'
+
+// This file defines PeerScoreParams and TopicScoreParams interfaces
+// as well as constructors, default constructors, and validation functions
+// for these interfaces
+
+export interface PeerScoreParams {
+  /**
+   * Score parameters per topic.
+   */
+  topics: Record<string, TopicScoreParams>
+
+  /**
+   * Aggregate topic score cap; this limits the total contribution of topics towards a positive
+   * score. It must be positive (or 0 for no cap).
+   */
+  topicScoreCap: number
+
+  /**
+   * P5: Application-specific peer scoring
+   */
+  appSpecificScore(p: string): number
+  appSpecificWeight: number
+
+  /**
+   * P6: IP-colocation factor.
+   * The parameter has an associated counter which counts the number of peers with the same IP.
+   * If the number of peers in the same IP exceeds IPColocationFactorThreshold, then the value
+   * is the square of the difference, ie (PeersInSameIP - IPColocationThreshold)^2.
+   * If the number of peers in the same IP is less than the threshold, then the value is 0.
+   * The weight of the parameter MUST be negative, unless you want to disable for testing.
+   * Note: In order to simulate many IPs in a managable manner when testing, you can set the weight to 0
+   * thus disabling the IP colocation penalty.
+   */
+  IPColocationFactorWeight: number
+  IPColocationFactorThreshold: number
+  IPColocationFactorWhitelist: Set<string>
+
+  /**
+   * P7: behavioural pattern penalties.
+   * This parameter has an associated counter which tracks misbehaviour as detected by the
+   * router. The router currently applies penalties for the following behaviors:
+   * - attempting to re-graft before the prune backoff time has elapsed.
+   * - not following up in IWANT requests for messages advertised with IHAVE.
+   *
+   * The value of the parameter is the square of the counter, which decays with  BehaviourPenaltyDecay.
+   * The weight of the parameter MUST be negative (or zero to disable).
+   */
+  behaviourPenaltyWeight: number
+  behaviourPenaltyThreshold: number
+  behaviourPenaltyDecay: number
+
+  /**
+   * the decay interval for parameter counters.
+   */
+  decayInterval: number
+
+  /**
+   * counter value below which it is considered 0.
+   */
+  decayToZero: number
+
+  /**
+   * time to remember counters for a disconnected peer.
+   */
+  retainScore: number
+}
+
+export interface TopicScoreParams {
+  /**
+   * The weight of the topic.
+   */
+  topicWeight: number
+
+  /**
+   * P1: time in the mesh
+   * This is the time the peer has ben grafted in the mesh.
+   * The value of the parameter is the time/TimeInMeshQuantum, capped by TimeInMeshCap
+   * The weight of the parameter MUST be positive (or zero to disable).
+   */
+  timeInMeshWeight: number
+  timeInMeshQuantum: number
+  timeInMeshCap: number
+
+  /**
+   * P2: first message deliveries
+   * This is the number of message deliveries in the topic.
+   * The value of the parameter is a counter, decaying with FirstMessageDeliveriesDecay, and capped
+   * by FirstMessageDeliveriesCap.
+   * The weight of the parameter MUST be positive (or zero to disable).
+   */
+  firstMessageDeliveriesWeight: number
+  firstMessageDeliveriesDecay: number
+  firstMessageDeliveriesCap: number
+
+  /**
+   * P3: mesh message deliveries
+   * This is the number of message deliveries in the mesh, within the MeshMessageDeliveriesWindow of
+   * message validation; deliveries during validation also count and are retroactively applied
+   * when validation succeeds.
+   * This window accounts for the minimum time before a hostile mesh peer trying to game the score
+   * could replay back a valid message we just sent them.
+   * It effectively tracks first and near-first deliveries, ie a message seen from a mesh peer
+   * before we have forwarded it to them.
+   * The parameter has an associated counter, decaying with MeshMessageDeliveriesDecay.
+   * If the counter exceeds the threshold, its value is 0.
+   * If the counter is below the MeshMessageDeliveriesThreshold, the value is the square of
+   * the deficit, ie (MessageDeliveriesThreshold - counter)^2
+   * The penalty is only activated after MeshMessageDeliveriesActivation time in the mesh.
+   * The weight of the parameter MUST be negative (or zero to disable).
+   */
+  meshMessageDeliveriesWeight: number
+  meshMessageDeliveriesDecay: number
+  meshMessageDeliveriesCap: number
+  meshMessageDeliveriesThreshold: number
+  meshMessageDeliveriesWindow: number
+  meshMessageDeliveriesActivation: number
+
+  /**
+   * P3b: sticky mesh propagation failures
+   * This is a sticky penalty that applies when a peer gets pruned from the mesh with an active
+   * mesh message delivery penalty.
+   * The weight of the parameter MUST be negative (or zero to disable)
+   */
+  meshFailurePenaltyWeight: number
+  meshFailurePenaltyDecay: number
+
+  /**
+   * P4: invalid messages
+   * This is the number of invalid messages in the topic.
+   * The value of the parameter is the square of the counter, decaying with
+   * InvalidMessageDeliveriesDecay.
+   * The weight of the parameter MUST be negative (or zero to disable).
+   */
+  invalidMessageDeliveriesWeight: number
+  invalidMessageDeliveriesDecay: number
+}
+
+export const defaultPeerScoreParams: PeerScoreParams = {
+  topics: {},
+  topicScoreCap: 10.0,
+  appSpecificScore: () => 0.0,
+  appSpecificWeight: 10.0,
+  IPColocationFactorWeight: -5.0,
+  IPColocationFactorThreshold: 10.0,
+  IPColocationFactorWhitelist: new Set(),
+  behaviourPenaltyWeight: -10.0,
+  behaviourPenaltyThreshold: 0.0,
+  behaviourPenaltyDecay: 0.2,
+  decayInterval: 1000.0,
+  decayToZero: 0.1,
+  retainScore: 3600 * 1000
+}
+
+export const defaultTopicScoreParams: TopicScoreParams = {
+  topicWeight: 0.5,
+  timeInMeshWeight: 1,
+  timeInMeshQuantum: 1,
+  timeInMeshCap: 3600,
+
+  firstMessageDeliveriesWeight: 1,
+  firstMessageDeliveriesDecay: 0.5,
+  firstMessageDeliveriesCap: 2000,
+
+  meshMessageDeliveriesWeight: -1,
+  meshMessageDeliveriesDecay: 0.5,
+  meshMessageDeliveriesCap: 100,
+  meshMessageDeliveriesThreshold: 20,
+  meshMessageDeliveriesWindow: 10,
+  meshMessageDeliveriesActivation: 5000,
+
+  meshFailurePenaltyWeight: -1,
+  meshFailurePenaltyDecay: 0.5,
+
+  invalidMessageDeliveriesWeight: -1,
+  invalidMessageDeliveriesDecay: 0.3
+}
+
+export function createPeerScoreParams (p: Partial<PeerScoreParams> = {}): PeerScoreParams {
+  return {
+    ...defaultPeerScoreParams,
+    ...p,
+    topics: (p.topics != null)
+      ? Object.entries(p.topics).reduce<Record<string, TopicScoreParams>>((topics, [topic, topicScoreParams]) => {
+        topics[topic] = createTopicScoreParams(topicScoreParams)
+        return topics
+      }, {})
+      : {}
+  }
+}
+
+export function createTopicScoreParams (p: Partial<TopicScoreParams> = {}): TopicScoreParams {
+  return {
+    ...defaultTopicScoreParams,
+    ...p
+  }
+}
+
+// peer score parameter validation
+export function validatePeerScoreParams (p: PeerScoreParams): void {
+  for (const [topic, params] of Object.entries(p.topics)) {
+    try {
+      validateTopicScoreParams(params)
+    } catch (e) {
+      throw new InvalidPeerScoreParamsError(`invalid score parameters for topic ${topic}: ${(e as Error).message}`)
+    }
+  }
+
+  // check that the topic score is 0 or something positive
+  if (p.topicScoreCap < 0) {
+    throw new InvalidPeerScoreParamsError('invalid topic score cap; must be positive (or 0 for no cap)')
+  }
+
+  // check that we have an app specific score; the weight can be anything (but expected positive)
+  if (p.appSpecificScore === null || p.appSpecificScore === undefined) {
+    throw new InvalidPeerScoreParamsError('missing application specific score function')
+  }
+
+  // check the IP colocation factor
+  if (p.IPColocationFactorWeight > 0) {
+    throw new InvalidPeerScoreParamsError('invalid IPColocationFactorWeight; must be negative (or 0 to disable)')
+  }
+  if (p.IPColocationFactorWeight !== 0 && p.IPColocationFactorThreshold < 1) {
+    throw new InvalidPeerScoreParamsError('invalid IPColocationFactorThreshold; must be at least 1')
+  }
+
+  // check the behaviour penalty
+  if (p.behaviourPenaltyWeight > 0) {
+    throw new InvalidPeerScoreParamsError('invalid BehaviourPenaltyWeight; must be negative (or 0 to disable)')
+  }
+  if (p.behaviourPenaltyWeight !== 0 && (p.behaviourPenaltyDecay <= 0 || p.behaviourPenaltyDecay >= 1)) {
+    throw new InvalidPeerScoreParamsError('invalid BehaviourPenaltyDecay; must be between 0 and 1')
+  }
+
+  // check the decay parameters
+  if (p.decayInterval < 1000) {
+    throw new InvalidPeerScoreParamsError('invalid DecayInterval; must be at least 1s')
+  }
+  if (p.decayToZero <= 0 || p.decayToZero >= 1) {
+    throw new InvalidPeerScoreParamsError('invalid DecayToZero; must be between 0 and 1')
+  }
+
+  // no need to check the score retention; a value of 0 means that we don't retain scores
+}
+
+// eslint-disable-next-line complexity
+export function validateTopicScoreParams (p: TopicScoreParams): void {
+  // make sure we have a sane topic weight
+  if (p.topicWeight < 0) {
+    throw new InvalidPeerScoreParamsError('invalid topic weight; must be >= 0')
+  }
+
+  // check P1
+  if (p.timeInMeshQuantum === 0) {
+    throw new InvalidPeerScoreParamsError('invalid TimeInMeshQuantum; must be non zero')
+  }
+  if (p.timeInMeshWeight < 0) {
+    throw new InvalidPeerScoreParamsError('invalid TimeInMeshWeight; must be positive (or 0 to disable)')
+  }
+  if (p.timeInMeshWeight !== 0 && p.timeInMeshQuantum <= 0) {
+    throw new InvalidPeerScoreParamsError('invalid TimeInMeshQuantum; must be positive')
+  }
+  if (p.timeInMeshWeight !== 0 && p.timeInMeshCap <= 0) {
+    throw new InvalidPeerScoreParamsError('invalid TimeInMeshCap; must be positive')
+  }
+
+  // check P2
+  if (p.firstMessageDeliveriesWeight < 0) {
+    throw new InvalidPeerScoreParamsError('invallid FirstMessageDeliveriesWeight; must be positive (or 0 to disable)')
+  }
+  if (
+    p.firstMessageDeliveriesWeight !== 0 &&
+    (p.firstMessageDeliveriesDecay <= 0 || p.firstMessageDeliveriesDecay >= 1)
+  ) {
+    throw new InvalidPeerScoreParamsError('invalid FirstMessageDeliveriesDecay; must be between 0 and 1')
+  }
+  if (p.firstMessageDeliveriesWeight !== 0 && p.firstMessageDeliveriesCap <= 0) {
+    throw new InvalidPeerScoreParamsError('invalid FirstMessageDeliveriesCap; must be positive')
+  }
+
+  // check P3
+  if (p.meshMessageDeliveriesWeight > 0) {
+    throw new InvalidPeerScoreParamsError('invalid MeshMessageDeliveriesWeight; must be negative (or 0 to disable)')
+  }
+  if (p.meshMessageDeliveriesWeight !== 0 && (p.meshMessageDeliveriesDecay <= 0 || p.meshMessageDeliveriesDecay >= 1)) {
+    throw new InvalidPeerScoreParamsError('invalid MeshMessageDeliveriesDecay; must be between 0 and 1')
+  }
+  if (p.meshMessageDeliveriesWeight !== 0 && p.meshMessageDeliveriesCap <= 0) {
+    throw new InvalidPeerScoreParamsError('invalid MeshMessageDeliveriesCap; must be positive')
+  }
+  if (p.meshMessageDeliveriesWeight !== 0 && p.meshMessageDeliveriesThreshold <= 0) {
+    throw new InvalidPeerScoreParamsError('invalid MeshMessageDeliveriesThreshold; must be positive')
+  }
+  if (p.meshMessageDeliveriesWindow < 0) {
+    throw new InvalidPeerScoreParamsError('invalid MeshMessageDeliveriesWindow; must be non-negative')
+  }
+  if (p.meshMessageDeliveriesWeight !== 0 && p.meshMessageDeliveriesActivation < 1000) {
+    throw new InvalidPeerScoreParamsError('invalid MeshMessageDeliveriesActivation; must be at least 1s')
+  }
+
+  // check P3b
+  if (p.meshFailurePenaltyWeight > 0) {
+    throw new InvalidPeerScoreParamsError('invalid MeshFailurePenaltyWeight; must be negative (or 0 to disable)')
+  }
+  if (p.meshFailurePenaltyWeight !== 0 && (p.meshFailurePenaltyDecay <= 0 || p.meshFailurePenaltyDecay >= 1)) {
+    throw new InvalidPeerScoreParamsError('invalid MeshFailurePenaltyDecay; must be between 0 and 1')
+  }
+
+  // check P4
+  if (p.invalidMessageDeliveriesWeight > 0) {
+    throw new InvalidPeerScoreParamsError('invalid InvalidMessageDeliveriesWeight; must be negative (or 0 to disable)')
+  }
+  if (p.invalidMessageDeliveriesDecay <= 0 || p.invalidMessageDeliveriesDecay >= 1) {
+    throw new InvalidPeerScoreParamsError('invalid InvalidMessageDeliveriesDecay; must be between 0 and 1')
+  }
+}

package/src/score/peer-score-thresholds.ts

@@ -0,0 +1,70 @@
+import { InvalidPeerScoreThresholdsError } from '../errors.js'
+
+// This file defines PeerScoreThresholds interface
+// as well as a constructor, default constructor, and validation function
+// for this interface
+
+export interface PeerScoreThresholds {
+  /**
+   * gossipThreshold is the score threshold below which gossip propagation is supressed;
+   * should be negative.
+   */
+  gossipThreshold: number
+
+  /**
+   * publishThreshold is the score threshold below which we shouldn't publish when using flood
+   * publishing (also applies to fanout and floodsub peers); should be negative and <= GossipThreshold.
+   */
+  publishThreshold: number
+
+  /**
+   * graylistThreshold is the score threshold below which message processing is supressed altogether,
+   * implementing an effective graylist according to peer score; should be negative and <= PublisThreshold.
+   */
+  graylistThreshold: number
+
+  /**
+   * acceptPXThreshold is the score threshold below which PX will be ignored; this should be positive
+   * and limited to scores attainable by bootstrappers and other trusted nodes.
+   */
+  acceptPXThreshold: number
+
+  /**
+   * opportunisticGraftThreshold is the median mesh score threshold before triggering opportunistic
+   * grafting; this should have a small positive value.
+   */
+  opportunisticGraftThreshold: number
+}
+
+export const defaultPeerScoreThresholds: PeerScoreThresholds = {
+  gossipThreshold: -10,
+  publishThreshold: -50,
+  graylistThreshold: -80,
+  acceptPXThreshold: 10,
+  opportunisticGraftThreshold: 20
+}
+
+export function createPeerScoreThresholds (p: Partial<PeerScoreThresholds> = {}): PeerScoreThresholds {
+  return {
+    ...defaultPeerScoreThresholds,
+    ...p
+  }
+}
+
+export function validatePeerScoreThresholds (p: PeerScoreThresholds): void {
+  if (p.gossipThreshold > 0) {
+    throw new InvalidPeerScoreThresholdsError('invalid gossip threshold; it must be <= 0')
+  }
+  if (p.publishThreshold > 0 || p.publishThreshold > p.gossipThreshold) {
+    throw new InvalidPeerScoreThresholdsError('invalid publish threshold; it must be <= 0 and <= gossip threshold')
+  }
+  if (p.graylistThreshold > 0 || p.graylistThreshold > p.publishThreshold) {
+    throw new InvalidPeerScoreThresholdsError('invalid graylist threshold; it must be <= 0 and <= publish threshold')
+  }
+  if (p.acceptPXThreshold < 0) {
+    throw new InvalidPeerScoreThresholdsError('invalid accept PX threshold; it must be >= 0')
+  }
+  if (p.opportunisticGraftThreshold < 0) {
+    throw new InvalidPeerScoreThresholdsError('invalid opportunistic grafting threshold; it must be >= 0')
+  }
+}