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.

[Winter-Soren]

Added Discussion page #1297, which explains the differences among all Gossipsub versions, along with instructions on how to run these examples.

[Winter-Soren]

Hi @seetadev @pacrob @acul71 @sumanjeet0012 @yashksaini-coder
I would love to have your review and feedback on the PR. A guide on running these examples is added in #1297.

[yashksaini-coder]

Thanks for putting this together @Winter-Soren — the educational progression from v1.0 through v2.0 is genuinely useful and this has been missing from py-libp2p for a while. The per-version feature checklists and the companion discussion (#1297) are nice touches.

That said, I've flagged a few things that need attention before this can be merged. The big ones are: missing newsfragment (project policy blocker), heavy code duplication across the 6 example files, and the v2.0 example implying a standardized protocol that doesn't exist in the spec. Details inline below.

Also the commit history still needs squashing (21 commits with 9 merge commits) — the PR TODO has this unchecked too.

[yashksaini-coder]

This protocol ID /meshsub/2.0.0 doesn't exist in the libp2p spec — the official GossipSub spec only goes up to v1.2. py-libp2p has this constant internally but the example's docstring reads like v2.0 is a standardized thing with distinct features like "equivocation detection" and "eclipse attack protection via IP diversity", which are really just v1.4 features repackaged.

This will confuse users who look at the spec and can't find v2.0 anywhere. Can you either:

• Add a clear disclaimer at the top of the docstring: "Note: GossipSub 2.0 is an experimental/internal protocol version in py-libp2p, not part of the official libp2p specification"
• Or drop this file and end the progression at v1.4

What do you think?

[yashksaini-coder]

This entire method body (start, publish_message, receive_messages, connect_to_peer) is copy-pasted nearly identically across all 6 version files. Same for the Demo class (setup_network, start_network, _connect_nodes, _print_statistics, main). I diffed v1.0 against v1.1 and the method signatures are identical — only the GossipSub constructor args change.

That's roughly 200+ lines of boilerplate repeated 6 times. If anything in the demo infra needs fixing (say, the connection logic or nursery management), you'd have to patch all 6 files.

Would you consider extracting a shared BaseGossipsubNode + BaseGossipsubDemo that each version file subclasses? Each file would then only need to override the GossipSub config and the feature checklist printout — maybe 40-60 lines per version instead of 300-550. Happy to help sketch this out if useful.

[yashksaini-coder]

Minor: import multiaddr is inside the method body here and in connect_to_peer(). In the v1.3 and v1.4 examples it's imported at module level. Should be consistent — move it to the top with the other imports.

[yashksaini-coder]

time.time() in a trio async context can drift since trio has its own clock. Consider using trio.current_time() with relative deadline tracking, or just count iterations — it's more idiomatic for trio code.

[yashksaini-coder]

Looks like there's a missing space before "optional app score" — the string concatenation drops it:

"Features: Peer scoring (P1-P7), prune backoff, peer exchange (PX),"
"optional app score"

Should be "...PX), " with a trailing space, or ", optional app score".

[yashksaini-coder]

This test fix (sleep 0.1s → 2s for CI stability) makes sense but it's unrelated to the gossipsub examples. Would be cleaner as its own 1-line PR so it can land independently without waiting for the examples review to finish. Up to you though, not blocking on this.