feat/920-add-gossipsub-2.0-support

[Winter-Soren]

What was wrong?

Issue #920

py-libp2p only supported Gossipsub 1.1, which limited its ability to handle adversarial network conditions and interoperate with modern libp2p implementations. The Python ecosystem was falling behind Go and JS implementations that already supported Gossipsub 2.0, exposing Python-based applications to:

• Security vulnerabilities: No peer scoring or behavioral penalties to mitigate spam, Sybil, and Eclipse attacks
• Unreliable message propagation: Fixed gossip parameters couldn't adapt to high-churn networks
• Interoperability issues: Inability to participate in modern libp2p pubsub networks
• Performance limitations: No validation caching or timeout mechanisms for message processing

How was it fixed?

This PR implements comprehensive Gossipsub 2.0 support by adding advanced peer scoring, adaptive gossip dissemination, enhanced security features, and improved message validation while maintaining full backward compatibility.

Summary of approach:

🔐 Enhanced Peer Scoring System

• Implemented P6 (Application-specific scoring) and P7 (IP colocation penalties)
• Added sophisticated decay mechanisms and behavioral pattern detection
• Enhanced opportunistic grafting with score-based peer selection
• Comprehensive peer cleanup and observability improvements

🌐 Adaptive Gossip Dissemination

• Network health monitoring and dynamic parameter adjustment
• Adaptive mesh degree bounds based on network conditions
• Intelligent gossip factor scaling for optimal message propagation
• Score-based mesh maintenance and peer replacement

🛡️ Security Enhancements

• Spam Protection: Configurable rate limiting per peer/topic
• Sybil Mitigation: IP colocation penalties and diversity enforcement
• Eclipse Attack Protection: Minimum IP diversity requirements in mesh
• Equivocation Detection: Penalties for peers sending conflicting messages

⚡ Enhanced Message Validation

• LRU validation cache with TTL for performance optimization
• Timeout support for async validators to prevent blocking
• Enhanced error reporting and failure result caching
• Background cleanup daemon for cache maintenance

🔄 Protocol Evolution

• Added /meshsub/2.0.0 protocol ID with full backward compatibility
• Graceful degradation when connecting to v1.1/v1.2 peers
• Enhanced protocol negotiation for seamless upgrades

Key Files Modified:

• libp2p/pubsub/gossipsub.py: Core Gossipsub 2.0 implementation
• libp2p/pubsub/score.py: Enhanced peer scoring with P6/P7 parameters
• libp2p/pubsub/pubsub.py: Validation caching and timeout mechanisms
• tests/core/pubsub/test_gossipsub_v2_0.py: Comprehensive v2.0 test suite
• tests/core/pubsub/test_validation_enhancements.py: Validation feature tests

To-Do

• Implement all Gossipsub 2.0 core features
• Add comprehensive unit and integration tests
• Ensure backward compatibility with v1.1/v1.2
• Follow existing code patterns and conventions
• Clean up commit history
• Add or update documentation related to these changes
• Add entry to the release notes

Benefits:

• 🔒 Enhanced Security: Protection against spam, Sybil, and Eclipse attacks
• 📈 Better Performance: Adaptive parameters and validation caching
• 🤝 Improved Interoperability: Compatible with Go/JS Gossipsub 2.0 implementations
• 🔄 Future-Ready: Foundation for advanced pubsub applications and research
• ⚡ Optimized Validation: Significant performance improvements through caching

This implementation brings py-libp2p to feature parity with other libp2p language implementations and provides a robust foundation for production systems requiring reliable pubsub behavior.

Cute Animal Picture

[seetadev]

@Winter-Soren : Great efforts, Soham. Thank you for raising the PR. I will review all the Gossipsub 2.0 features that have been implemented. Appreciate the contribution.

[pacrob]

Why this comment? And why not emitting a GRAFT message here?

[Winter-Soren]

Thank you @pacrob for flagging this, the comment was misleading. I've fixed this by:

1. Modified _improve_mesh_diversity() to return peers that need grafting instead of just adding them locally
2. Updated the heartbeat flow to collect these diversity peers and include them in the peers_to_graft dictionary
3. Now these peers properly receive GRAFT control messages through the existing _emit_control_msgs() mechanism

added fix in the commit 0398d1d

[pacrob]

This PR needs a newsfragment, but is otherwise good to merge.

[seetadev]

@Winter-Soren : This is excellent work — thank you for pushing this through. 🙌

Bringing full Gossipsub 2.0 support to py-libp2p is a major milestone and a big step toward parity with the Go and JS implementations. The scope and depth of this PR are very strong: peer scoring (including P6/P7), adaptive gossip, security hardening against spam/Sybil/Eclipse attacks, validation caching with timeouts, and careful backward compatibility with v1.1/v1.2 are all well thought out and clearly implemented. This meaningfully improves security, interoperability, and production readiness for Python-based libp2p applications.

@pacrob: Thank you for the thoughtful review, clear feedback, and for approving the PR. Appreciate your great support.

@Winter-Soren : Two small requests to help maximize the impact of this work along with adding the newsfragment for this PR:

• Could you open a discussion page (or short design note) outlining the implementation steps and design decisions, especially where py-libp2p diverges from Go/JS due to Python-specific considerations, if any? Wish if you could also share some design notes on your implementation and any spec additions/changes you would like to share.

• It would also be great to include a small, independent example/demo showcasing the differences between Gossipsub 1.1, 1.2, and 2.0, along with a standalone Gossipsub 2.0 demo highlighting peer scoring, adaptive gossip, and validation behavior.

Overall, this is a substantial contribution and sets a strong foundation for future pubsub and gossipsub work in py-libp2p. Fantastic work. 👏

[Winter-Soren]

@Winter-Soren : This is excellent work — thank you for pushing this through. 🙌

Bringing full Gossipsub 2.0 support to py-libp2p is a major milestone and a big step toward parity with the Go and JS implementations. The scope and depth of this PR are very strong: peer scoring (including P6/P7), adaptive gossip, security hardening against spam/Sybil/Eclipse attacks, validation caching with timeouts, and careful backward compatibility with v1.1/v1.2 are all well thought out and clearly implemented. This meaningfully improves security, interoperability, and production readiness for Python-based libp2p applications.

@pacrob: Thank you for the thoughtful review, clear feedback, and for approving the PR. Appreciate your great support.

@Winter-Soren : Two small requests to help maximize the impact of this work along with adding the newsfragment for this PR:

• Could you open a discussion page (or short design note) outlining the implementation steps and design decisions, especially where py-libp2p diverges from Go/JS due to Python-specific considerations, if any? Wish if you could also share some design notes on your implementation and any spec additions/changes you would like to share.
• It would also be great to include a small, independent example/demo showcasing the differences between Gossipsub 1.1, 1.2, and 2.0, along with a standalone Gossipsub 2.0 demo highlighting peer scoring, adaptive gossip, and validation behavior.

Overall, this is a substantial contribution and sets a strong foundation for future pubsub and gossipsub work in py-libp2p. Fantastic work. 👏

@seetadev Thank you so much for the positive feedback and recognition! I'm thrilled that the Gossipsub 2.0 implementation meets the project's standards and contributes meaningfully to py-libp2p's capabilities.

I'd be happy to work on both requests to maximize the impact:

1. Discussion Page / Design Document:
I'll create a comprehensive discussion page outlining:

• Implementation approach and key design decisions
• Python-specific considerations and how we adapted the Go/JS patterns
• Areas where py-libp2p diverges from other implementations (if any)
• Performance considerations and trade-offs made
• Future enhancement opportunities

2. Gossipsub Demo/Example:
I'll develop a standalone example showcasing:

• Side-by-side comparison of Gossipsub 1.1, 1.2, and 2.0 behavior
• Interactive demo highlighting peer scoring in action
• Adaptive gossip parameter adjustments under different network conditions
• Validation hooks and security features demonstration
• Performance metrics and network resilience comparisons