Gossipsub Playground: Versioned Examples & Protocol Insights

[Winter-Soren]

This discussion page contains comprehensive examples showcasing the differences between Gossipsub protocol versions. Implemented at PR #1139

Overview

Py-libp2p has full protocol version support spanning:

• Gossipsub 1.0 (/meshsub/1.0.0) - Basic mesh-based pubsub
• Gossipsub 1.1 (/meshsub/1.1.0) - Added peer scoring and behavioral penalties
• Gossipsub 1.2 (/meshsub/1.2.0) - Added IDONTWANT message filtering
• Gossipsub 1.3 (/meshsub/1.3.0) - Extensions Control Message and Topic Observation
• Gossipsub 1.4 (/meshsub/1.4.0) - Rate limiting, GRAFT flood protection, and adaptive gossip
• Gossipsub 2.0 (/meshsub/2.0.0) - Enhanced security, adaptive gossip, and advanced peer scoring

Version comparison

Each version builds on the previous one. The summary table lists protocol id, example script (same directory as this README), and what that release adds. The feature matrix shows which major capabilities appear in which version.

Summary

Version	Protocol ID	Example script	What this version adds	Implementation (PR)
1.0	/meshsub/1.0.0	gossipsub_v1.0.py	Mesh pubsub, flooding, fanout; no peer scoring
1.1	/meshsub/1.1.0	gossipsub_v1.1.py	Peer scoring (P1–P7), behavioral penalties, prune backoff, peer exchange (PX)	#872
1.2	/meshsub/1.2.0	gossipsub_v1.2.py	IDONTWANT and message filtering (less redundant traffic)	#812
1.3	/meshsub/1.3.0	gossipsub_v1.3.py	Extensions control message; Topic Observation (IHAVE-only observers)	#1237
1.4	/meshsub/1.4.0	gossipsub_v1.4.py	IWANT/IHAVE rate limits, GRAFT flood protection, adaptive gossip factor, heartbeat adaptation	#1012
2.0	/meshsub/2.0.0	gossipsub_v2.0.py	Stronger security story (equivocation, eclipse, validation), scoring and adaptive gossip demos	#1066

Run scripts from the repository root as python examples/pubsub/gossipsub/<script>.py (see Examples).

Feature matrix

Capabilities accumulate down the column: a ✓ means that version includes the capability (and usually everything above it in earlier versions).

Capability	1.0	1.1	1.2	1.3	1.4	2.0
Mesh pubsub, fanout	✓	✓	✓	✓	✓	✓
Peer scoring (P1–P7), PX, prune backoff	—	✓	✓	✓	✓	✓
IDONTWANT / filtering	—	—	✓	✓	✓	✓
Extensions control + Topic Observation	—	—	—	✓	✓	✓
IWANT/IHAVE limits, GRAFT flood, adaptive gossip & heartbeat	—	—	—	—	✓	✓
Gossipsub 2.0 security emphasis (equivocation, eclipse, validation hooks, …)	—	—	—	—	—	✓

Examples

Run each command from the repository root of py-libp2p; paths are relative to that root.

1. Gossipsub 1.0 Demo (examples/pubsub/gossipsub/gossipsub_v1.0.py)

Basic mesh-based pubsub demo using Gossipsub 1.0 (/meshsub/1.0.0).

Features:

• Basic mesh-based pubsub
• Simple flooding for message dissemination
• Mesh topology maintenance
• Fanout behaviour: one node (node_0) is a fanout-only publisher: it publishes without subscribing, so messages are sent via fanout (a random set of topic subscribers) instead of mesh peers

Usage:

python examples/pubsub/gossipsub/gossipsub_v1.0.py --nodes 5 --duration 30

2. Gossipsub 1.1 Demo (examples/pubsub/gossipsub/gossipsub_v1.1.py)

Demonstrates Gossipsub 1.1 (/meshsub/1.1.0) with peer scoring and behavioral penalties.

Features:

• All Gossipsub 1.0 features
• Peer scoring with P1–P4 topic-scoped parameters
• Behavioral penalties (P5)
• P6 (application-specific score) and P7 (IP colocation factor / Behavioural Penalty)
• Prune backoff and peer exchange (PX) enabled
• Optional application score function (in real applications: staking, reputation, or role e.g. validator, full node)
• Honest vs. malicious publisher behaviour

Usage:

python examples/pubsub/gossipsub/gossipsub_v1.1.py --nodes 5 --duration 30

3. Gossipsub 1.2 Demo (examples/pubsub/gossipsub/gossipsub_v1.2.py)

Demonstrates Gossipsub 1.2 (/meshsub/1.2.0) with IDONTWANT message filtering.

Features:

• All Gossipsub 1.1 features
• IDONTWANT messages and message filtering
• Reduced redundant traffic in denser meshes

Usage:

python examples/pubsub/gossipsub/gossipsub_v1.2.py --nodes 5 --duration 30

4. Gossipsub 1.3 Demo (examples/pubsub/gossipsub/gossipsub_v1.3.py)

Demonstrates GossipSub 1.3 (/meshsub/1.3.0) with the Extensions Control Message
mechanism and the Topic Observation extension.

Features:

• All GossipSub 1.2 features (IDONTWANT, peer scoring)
• Extensions Control Message: sent exactly once in the first message per peer
• At-most-once enforcement: duplicate Extensions from a peer triggers a score penalty
• Topic Observation: observer nodes receive IHAVE presence notifications without
  full message payloads
• Protocol gating: extension fields are only attached when /meshsub/1.3.0 is negotiated

Node roles in the demo:

Role	Behaviour
publisher	Subscribes and publishes messages every 2 seconds
subscriber	Subscribes and reads full message payloads
observer	Uses Topic Observation (IHAVE-only); no full subscription

At the halfway point one observer sends UNOBSERVE to stop receiving notifications,
demonstrating the full OBSERVE → IHAVE → UNOBSERVE lifecycle.

Usage:

python examples/pubsub/gossipsub/gossipsub_v1.3.py --nodes 6 --duration 40
python examples/pubsub/gossipsub/gossipsub_v1.3.py --nodes 6 --duration 40 --verbose

5. Gossipsub 1.4 Demo (examples/pubsub/gossipsub/gossipsub_v1.4.py)

Demonstrates GossipSub 1.4 (/meshsub/1.4.0) with enhanced rate limiting, GRAFT flood
protection, and adaptive gossip parameter tuning.

Features:

• All GossipSub 1.3 features (Extensions Control Message, Topic Observation)
• IWANT request rate limiting per peer – prevents IWANT spam storms; excess requests
  trigger a penalize_iwant_spam score deduction
• IHAVE message rate limiting per peer per topic – caps IHAVE floods;
  excess triggers penalize_ihave_spam
• GRAFT flood protection – a peer that sends GRAFT too soon after receiving PRUNE
  is penalised via penalize_graft_flood and immediately re-pruned
• Adaptive gossip factor – the gossip spread factor scales with a multi-metric
  network health score (connectivity, peer scores, delivery rate, mesh stability, churn)
• Opportunistic grafting threshold adaptation – in poor health the threshold
  is lowered so high-quality peers are grafted more aggressively
• Heartbeat interval adaptation – under critical health the heartbeat is
  accelerated for faster mesh recovery
• Extended scoring (P5-P7) gated to /meshsub/1.4.0

Node roles in the demo:

Role	Behaviour
honest	Subscribes and publishes at a normal cadence
validator	Subscribes and reads messages; no publishing
spammer	Bursts rapid messages to trigger IWANT / IHAVE rate-limiting paths
observer	Uses Topic Observation (IHAVE-only, inherited from v1.3)

At t = duration/4 the spammer fires a burst of 12 messages in rapid succession to
demonstrate rate-limit enforcement. At t = duration/2 one observer sends UNOBSERVE.

Usage:

python examples/pubsub/gossipsub/gossipsub_v1.4.py --nodes 6 --duration 40
python examples/pubsub/gossipsub/gossipsub_v1.4.py --nodes 6 --duration 40 --verbose

6. Gossipsub 2.0 Demo (examples/pubsub/gossipsub/gossipsub_v2.0.py)

Demonstrates Gossipsub 2.0 (/meshsub/2.0.0) with adaptive gossip and advanced security features.

Features:

Peer Scoring Visualization

• Real-time Score Display: Shows peer scores (P1-P7 parameters) updating in real-time
• Score Component Breakdown: Visualizes individual scoring components
• Behavioral Penalties: Demonstrates how misbehavior affects peer scores
• IP Colocation Penalties: Shows P7 penalties for peers from same IP ranges
• Application Scoring: Demonstrates P6 custom application-defined scoring

Adaptive Gossip Demonstration

• Network Health Monitoring: Displays network health score calculation
• Dynamic Parameter Adjustment: Shows how gossip parameters adapt to network conditions
• Mesh Quality Maintenance: Visualizes mesh degree adjustments
• Opportunistic Grafting: Demonstrates score-based peer selection

Security Features

• Spam Protection: Shows rate limiting in action
• Eclipse Attack Protection: Demonstrates IP diversity enforcement
• Equivocation Detection: Shows detection and penalties for duplicate messages
• Message Validation: Demonstrates validation hooks and caching

Usage:

python examples/pubsub/gossipsub/gossipsub_v2.0.py --nodes 5 --duration 60

Protocol Version Differences

Gossipsub 1.0 (/meshsub/1.0.0)

• Basic mesh-based pubsub protocol
• Simple flooding for message dissemination
• Fanout: publishers that are not in the mesh for a topic send to a random set of topic subscribers (fanout peers)
• No peer scoring or advanced security features
• Suitable for trusted networks with low adversarial activity

Gossipsub 1.1 (/meshsub/1.1.0)

• Added Peer Scoring: P1-P4 topic-scoped parameters
  • P1: Time in mesh
  • P2: First message deliveries
  • P3: Mesh message deliveries
  • P4: Invalid messages penalty
• Behavioral Penalties: P5 global behavior penalty
• P6 (Application-specific score) and P7 (IP colocation factor)
• Prune backoff and peer exchange (PX) enabled
• Optional application score function (e.g. staking/reputation, validator/full node role)
• Signed Peer Records: Enhanced peer exchange with signed records
• Better resilience against basic attacks

Gossipsub 1.2 (/meshsub/1.2.0)

• IDONTWANT Messages: Peers can signal they don't want specific messages
• Message Filtering: Reduces redundant message transmission
• Improved Efficiency: Lower bandwidth usage in dense networks
• All v1.1 features included

Gossipsub 1.3 (/meshsub/1.3.0)

• Extensions Control Message: carried in the first RPC on a stream, at most once per peer
• Misbehaviour Scoring: duplicate Extensions messages trigger scorer.penalize_behavior
• Topic Observation: start_observing_topic / stop_observing_topic API; observers
  receive IHAVE notifications immediately on publish without fetching full payloads
• Protocol Gating: extension fields are injected only when the negotiated protocol
  is /meshsub/1.3.0 or later
• Forward Compatibility: unknown extension fields are silently ignored by decoders
• All v1.2 features included

Gossipsub 1.4 (/meshsub/1.4.0)

• IWANT Rate Limiting: caps IWANT requests per peer per second; excess triggers
  penalize_iwant_spam score deduction
• IHAVE Rate Limiting: caps IHAVE messages per peer per topic per second; excess
  triggers penalize_ihave_spam
• GRAFT Flood Protection: peers that re-GRAFT before the backoff window expires
  receive penalize_graft_flood and are immediately re-pruned
• Adaptive Gossip Factor: gossip spread factor (gossip_factor) scales dynamically
  based on a composite network health score (mesh connectivity, peer scores, delivery
  rate, mesh stability, and connection churn)
• Opportunistic Grafting Threshold Adaptation: lower threshold in poor health
  promotes more aggressive peer selection for mesh repair
• Heartbeat Interval Adaptation: heartbeat interval shrinks under critical health
  for faster mesh recovery, expanding again once health improves
• Extended Scoring (P5-P7) Gate: supports_protocol_feature(peer, "extended_scoring")
  returns True only for /meshsub/1.4.0
• All v1.3 features included

Gossipsub 2.0 (/meshsub/2.0.0)

• Enhanced Peer Scoring: P6 (application-specific) and P7 (IP colocation) parameters
• Adaptive Gossip: Dynamic parameter adjustment based on network health
• Advanced Security Features:
  • Spam protection with rate limiting
  • Eclipse attack protection via IP diversity
  • Equivocation detection
  • Enhanced message validation
• Network Health Monitoring: Continuous assessment of network conditions
• Opportunistic Grafting: Score-based peer selection for mesh optimization

Peer Scoring Parameters (P1-P7)

Topic-Scoped Parameters (P1-P4)

• P1 (Time in Mesh): Rewards peers for staying in the mesh longer
• P2 (First Message Deliveries): Rewards peers for delivering messages first
• P3 (Mesh Message Deliveries): Rewards peers for consistent message delivery
• P4 (Invalid Messages): Penalizes peers for sending invalid messages

Global Parameters (P5-P7)

• P5 (Behavior Penalty): General behavioral penalty for misbehavior
• P6 (Application Score): Custom application-defined scoring
• P7 (IP Colocation): Penalizes multiple peers from same IP address

Security Features in Gossipsub 2.0

Spam Protection

• Rate limiting per peer per topic
• Configurable message rate thresholds
• Automatic penalty application for rate limit violations

Eclipse Attack Protection

• Minimum IP diversity requirements in mesh
• Penalties for excessive peers from same IP range
• Mesh diversity monitoring and enforcement

Equivocation Detection

• Detection of duplicate messages with same sequence number
• Penalties for peers sending conflicting messages
• Message deduplication and validation

Message Validation

• Configurable validation hooks
• Validation result caching
• Integration with peer scoring system

Running the Examples

Basic Usage

# From the repository root of py-libp2p
python examples/pubsub/gossipsub/gossipsub_v1.0.py --nodes 5 --duration 30
python examples/pubsub/gossipsub/gossipsub_v1.1.py --nodes 5 --duration 30
python examples/pubsub/gossipsub/gossipsub_v1.2.py --nodes 5 --duration 30
python examples/pubsub/gossipsub/gossipsub_v1.3.py --nodes 6 --duration 40
python examples/pubsub/gossipsub/gossipsub_v1.4.py --nodes 6 --duration 40
python examples/pubsub/gossipsub/gossipsub_v2.0.py --nodes 5 --duration 60

Understanding the Output

The per-version demos print statistics summarising:

• Messages Sent/Received per node
• Roles (honest, malicious, spammer, validator) and their behaviour
• Feature Highlights for the corresponding protocol version (for example, IDONTWANT support in v1.2, security and adaptive gossip in v2.0)

Network Topologies

All demos create realistic network topologies:

• Mesh Connectivity: Each node connects to 3-4 peers
• Realistic Latency: Simulated network delays
• Diverse Roles: Honest peers, spammers, validators, attackers
• Dynamic Behavior: Peer churn, network partitions, attacks

Customization

Adding Custom Scenarios

To add new test scenarios to the per-version demos:

async def _run_custom_scenario(self, duration: int):
    """Your custom scenario implementation"""
    # Implement custom network behavior
    pass

# Register in run_scenario method
elif scenario == "custom":
    await self._run_custom_scenario(duration)

Custom Scoring Functions

To implement custom application scoring:

def custom_app_score(peer_id: ID) -> float:
    """Custom application-specific scoring logic"""
    # Implement your scoring logic
    return score

# Use in ScoreParams
score_params = ScoreParams(
    app_specific_score_fn=custom_app_score,
    p6_appl_slack_weight=0.5
)

Custom Validation

To add custom message validation:

def custom_validator(message) -> bool:
    """Custom message validation logic"""
    # Implement validation rules
    return is_valid

# Use in node setup
node._validate_message = custom_validator

Troubleshooting

Common Issues

1. Port Conflicts: If you get port binding errors, the examples will automatically find free ports
2. Connection Failures: Ensure firewall allows local connections on the used ports
3. High CPU Usage: Reduce the number of nodes or increase sleep intervals for testing
4. Memory Usage: Large networks may consume significant memory; monitor usage

Debug Mode

Enable verbose logging for detailed information:

python examples/pubsub/gossipsub/gossipsub_v1.0.py --verbose ...
python examples/pubsub/gossipsub/gossipsub_v1.1.py --verbose ...
python examples/pubsub/gossipsub/gossipsub_v1.2.py --verbose ...
python examples/pubsub/gossipsub/gossipsub_v1.3.py --verbose ...
python examples/pubsub/gossipsub/gossipsub_v1.4.py --verbose ...
python examples/pubsub/gossipsub/gossipsub_v2.0.py --verbose ...

References

• Gossipsub v1.1 Specification
• Gossipsub v1.2 Specification
• Gossipsub v1.3 Specification
• Topic Observation proposal (ethresearch)
• Gossipsub v1.4 Specification
• Gossipsub v2.0 Specification

[seetadev]

@Winter-Soren: This is an excellent and highly valuable contribution, thank you for putting this together so comprehensively.

The progression across Gossipsub versions is presented with strong clarity, and the combination of executable examples + feature matrix + protocol evolution narrative makes this especially impactful for both new contributors and experienced maintainers. The way each version incrementally builds on the previous one (from basic mesh pubsub to adaptive gossip and security in 2.0) is easy to follow, and the inclusion of realistic node roles (spammer, validator, observer, etc.) significantly improves the learning and testing experience.

Next Steps: Protocol Research on Gossipsub

Building on this, there are several high-impact directions we should prioritize:

1. Formalizing Network Health & Adaptive Gossip

• Define and document the network health score function more rigorously.

• Explore:

  • Stability vs responsiveness trade-offs in adaptive gossip factor
  • Impact of heartbeat adaptation under churn

• Goal: move toward a spec-aligned, tunable model that can be benchmarked across implementations.

2. Peer Scoring Calibration & Attack Resistance

• Systematically evaluate P1–P7 under adversarial scenarios:

  • Eclipse attacks (IP colocation / Sybil clusters)
  • Spam + gray failures (low-quality but non-malicious peers)
  • Strategic peers gaming P2/P3 rewards

• Introduce:

  • Parameter sweep experiments
  • Sensitivity analysis for scoring weights

• Goal: publish recommended default scoring profiles for different network types (permissioned, open, high-churn, etc.)

3. Cross-Implementation Interop Testing

• Validate behavior against other libp2p implementations:

  • go-libp2p
  • js-libp2p

• Focus areas:

  • Protocol negotiation across versions (/meshsub/1.x vs 2.0)
  • Extension handling (v1.3+)
  • Score propagation and pruning behavior

• Goal: ensure py-libp2p is fully interoperable and spec-compliant.

4. Large-Scale Simulation & Visualization

• Integrate with tools like NetViz-style simulation pipelines:

  • Feed topology + events → visualize mesh evolution, score changes, gossip spread

• Run:

  • High-node-count simulations (100–1000 nodes)
  • Partition + recovery scenarios

• Goal: produce research-grade insights + visual artifacts for protocol behavior.

5. Message Validation & Application-Aware Gossip

• Expand on P6 (application scoring):

  • Validator-based networks (e.g., block propagation)
  • Reputation/stake-weighted gossip

• Study:

  • Trade-offs between fast propagation vs strict validation

• Goal: define patterns for application-specific Gossipsub profiles.

---

6. Security Hardening (Toward Gossipsub 2.x+)

• Deepen exploration of:

  • Equivocation detection effectiveness
  • Mesh diversity guarantees
  • Attack recovery latency

• Add:

  • Fault injection scenarios (Byzantine peers, delayed delivery, collusion)

• Goal: evolve toward a formally analyzed adversarial model.

7. Documentation → Spec Feedback Loop

• Use these examples to:

  • Identify ambiguities or gaps in the current Gossipsub specs
  • Propose clarifications upstream

• Potential output:

  • “Gossipsub Explained via Executable Models” doc

• Goal: position this work as both implementation + spec companion.

If we sequence this well, this work can evolve from examples into a full-fledged Gossipsub research and testing framework, which would be a major contribution not just to py-libp2p, but to the broader libp2p ecosystem.