eg/1130-add-gossipsub-comparison-and-standalone-examples

[Winter-Soren]

Implements comprehensive examples showcasing Gossipsub protocol evolution (v1.0-v2.0) with interactive demonstrations of peer scoring, adaptive gossip, and security features.

What was wrong?

Issue #1130

The py-libp2p did not have comprehensive examples demonstrating the differences between Gossipsub protocol versions and showcasing the advanced features of Gossipsub 2.0.

How was it fixed?

Created a complete example suite in examples/pubsub/gossipsub/ with three main components:

1. Multi-Version Comparison Demo (version_comparison.py)

• Side-by-side testing of Gossipsub v1.0, v1.1, v1.2, and v2.0
• Four realistic scenarios: normal operation, high churn, spam attacks, network partitions
• Performance metrics comparison (delivery rates, latency, security effectiveness)
• JSON output for analysis and visualization

2. Gossipsub 2.0 Feature Showcase (v2_showcase.py)

• Interactive demonstrations of advanced v2.0 features
• Real-time peer scoring visualization (P1-P7 parameters)
• Adaptive gossip monitoring with network health metrics
• Security features demo with spam protection and rate limiting
• Multiple node roles: honest, spammer, eclipse_attacker, validator

3. Convenient Runner Script (run_examples.py)

• Automated test execution with progress reporting
• Quick comparison across all scenarios
• File management and cleanup utilities
• Comprehensive help system

Key Technical Fixes:

• Proper trio nursery management for concurrent network simulation
• Robust peer connection logic with ring topology
• Timeout handling and graceful cancellation
• Comprehensive error handling and logging

To-Do

• Clean up commit history
• Add or update documentation related to these changes
• Add entry to the release notes

Cute Animal Picture

[IronJam11]

Missing:
[v1.0]

• fanout behaviour not shown in v1.0

[v1.1]

• ⁠p6 and p7 (IP Colocation Factor, Behavioural Penalty)
  ⁠- enabling prune backoff and peer exchange
  ⁠- ”can” add application score function (in real applications, this could be based on staking/reputation in a blockchain, role in the network (validator, full node,...)

@Winter-Soren @seetadev

[Winter-Soren]

Missing: [v1.0]

• fanout behaviour not shown in v1.0

[v1.1]

• ⁠p6 and p7 (IP Colocation Factor, Behavioural Penalty)
  ⁠- enabling prune backoff and peer exchange
  ⁠- ”can” add application score function (in real applications, this could be based on staking/reputation in a blockchain, role in the network (validator, full node,...)

@Winter-Soren @seetadev

Hey @IronJam11,

Thank you for flagging this!
I have incorporated the missing features into the Gossipsub 1.0 and Gossipsub 1.1 examples.

1. v1.0 demo: Shows node_0 as a fanout-only publisher (no subscription, 3 messages sent, 0 received), with other nodes receiving via fanout. The summary explicitly lists the fanout behavior.

2. v1.1 demo: Runs with P1–P7, prune backoff, PX, and an optional app score, all described in the banner and final feature list. Honest vs. malicious behavior stats are printed as expected.

Fanout (v1.0) and P6/P7 + PX + prune backoff + app score (v1.1) are now covered.

[seetadev]

@Winter-Soren , @IronJam11 : Hi friends. Appreciate the efforts. The PR does an excellent job of making the evolution of Gossipsub (v1.0 → v2.0) tangible through well-structured, runnable examples, something that has been missing in py-libp2p for a while. The multi-version comparison, scenario-based simulations (churn, spam, partitions), and especially the interactive v2.0 showcase with peer scoring and adaptive gossip provide real educational and debugging value for both new and experienced contributors.

It’s also great to see the feedback loop handled so well, fanout behavior in v1.0 and the inclusion of P6/P7, PX, prune backoff, and optional app scoring in v1.1 really strengthen the completeness and accuracy of the examples. The attention to concurrency (trio nursery management), error handling, and metrics output makes this not just illustrative but practically usable.

I’m aligned with the approach to scope this PR to all versions except v1.3 and take that up separately to avoid blocking the release. This is in a very good state to land once the final check clears, would be great to get this merged ahead of the upcoming release.