# TODO Analysis Summary: py-libp2p Issues Overview

[acul71]

TODO Analysis Summary: py-libp2p Issues Overview

Last review: August 2025

Executive Summary

This document provides a comprehensive overview of all TODO and FIXME issues analyzed in the py-libp2p codebase. The analysis covers 15 major issues across 8 different modules, ranging from simple type fixes to complex architectural improvements.

---

Table of Contents

• Executive Summary
• Issue Categorization Table
• Detailed Issue Analysis
  • BasicHost.get_addrs() p2p postfix
  • Circuit v2 Relay Issues ⚠️ 2/4 RESOLVED
  • Get Mux Return Type
  • Mplex Stream Muxer Issues
  • MplexStream Issues ⚠️ 3/4 RESOLVED
  • Multiselect Type Consistency ✅ Done in: FIXME: Make TProtocol Optional[TProtocol] to keep types consistent #770
  • MuxerMultistream Timeout Current Status: ⚠️ PARTIALLY RESOLVED
  • Pubsub Issues
  • Pubsub Missing Tests
  • Swarm Issues ⚠️ Work in progress
  • Test Notify Issues ✅ Done
  • Transport Issues
• Good First Issues
• Expert Level Issues
• Implementation Roadmap
• Risk Assessment
• Conclusion

Issue Categorization Table

Sorted by Priority (High → Medium → Low) then by Difficulty (Expert → Medium → Easy)

Issue	Module	Type	Priority	Difficulty	Breaking Change	Good First Issue	STATUS
Circuit v2 Relay Issues	Relay	Security	High	Expert	No	❌	⚠️ Work in progress (2/4) in PR #698
Swarm Issues	Network	Architecture	High	Expert	No	❌	⚠️ Work in progress (0/1) in PR #876
Transport Issues	Transport	Architecture	High	Expert	Yes	❌	⚠️(1/2)
MplexStream Issues	Stream Muxer	Concurrency	High	Medium	No	❌	Can be assigned (3/4 completed)
MuxerMultistream Timeout	Stream Muxer	Reliability	High	Medium	No	❌	Can be assigned
BasicHost.get_addrs() p2p postfix	Host	API Design	Medium	Medium	Yes	❌	Reviewing Status (Wait for updates)
Pubsub Issues	Pubsub	Performance	Medium	Medium	No	❌	Can be assigned
Pubsub Missing Tests	Pubsub	Testing	Medium	Medium	No	❌	Reviewing Status (Waiting for feedback)
Mplex Stream Muxer Issues	Stream Muxer	Type Safety	Medium	Easy	No	✅	⚠️ open PR here #742
Multiselect Type Consistency	Protocol Muxer	Type Safety	Medium	Easy	No	✅	✅ Done in: #770
Get Mux Return Type	ABC	Type Safety	Low	Easy	No	✅	Antrikshgwal should open a issue/PR soon
Test Notify Issues	Testing	Test Coverage	Low	Easy	No	✅	✅ Done in #825

---

Detailed Issue Analysis

BasicHost.get_addrs() p2p postfix

Location: libp2p/host/basic_host.py:140
Type: API Design
Priority: Medium
Difficulty: Medium
Breaking Change: Yes
Discussion: GitHub Discussion #716

Summary: The get_addrs() method currently adds /p2p/{peer_id} postfix to transport addresses, but the TODO suggests this should be removed for cleaner separation of concerns.

Impact:

• Positive: Cleaner API, better separation of concerns
• Negative: Breaking change affecting all code that expects p2p addresses

Recommendation: Implement Option B (add new method) for backward compatibility.

---

Circuit v2 Relay Issues

Location: libp2p/relay/circuit_v2/
Type: Security
Priority: High
Difficulty: Expert
Breaking Change: No
Discussion: GitHub Discussion #720

Summary: Four critical security issues in circuit v2 relay implementation:

1. Missing signature generation for production DONE
2. Missing voucher and signature verification DONE
3. Need for sophisticated relay selection
4. Missing reservation storage and refresh mechanism

Impact:

• Production Risk: Not suitable for production use without fixes

Recommendation: Address issue 4 and then issue 3

---

Get Mux Return Type

Current Status: ✅ Done in: #770
Location: libp2p/abc.py:1131
Type: Type Safety
Priority: Low
Difficulty: Easy
Breaking Change: No
Discussion: GitHub Discussion #729

Summary: The get_mux() method returns Any but should return IMultiselectMuxer for proper type safety.

Impact:

• Positive: Better type safety, IDE support, documentation
• Negative: Minimal

Recommendation: Implement Option A (interface-based approach).

---

Mplex Stream Muxer Issues

Location: libp2p/stream_muxer/mplex/mplex.py
Type: Type Safety
Priority: Medium
Difficulty: Easy
Breaking Change: No
Discussion: GitHub Discussion #722

Summary: Four type consistency and logging issues in mplex implementation:

1. Return type inconsistency in send_message()
2. Missing logging for unknown flags
3. Missing warning for unknown stream messages
4. Missing warning for data after stream close

Impact:

• Positive: Better type safety, improved debugging
• Negative: Minimal

Recommendation: Address all four issues for better code quality.

---

MplexStream Issues

Location: libp2p/stream_muxer/mplex/mplex_stream.py
Type: Concurrency
Priority: High
Difficulty: Medium
Breaking Change: No
Discussion: GitHub Discussion #723

Summary: Four concurrency and error handling issues:

1. Missing read/write locks for message interleaving DONE
2. Missing error handling with timeout in close DONE
3. Missing error handling for send_message failures DONE
4. Missing deadline functionality

Impact:

• Performance: May affect stream reliability

Recommendation: Implement Missing deadline functionality

---

Multiselect Type Consistency ✅ Done in: #770

Location: libp2p/protocol_muxer/multiselect.py:48
Type: Type Safety
Priority: Medium
Difficulty: Easy
Breaking Change: No
Discussion: GitHub Discussion #718

Summary: Type inconsistency between interface (TProtocol | None) and implementation (TProtocol).

Impact:

• Positive: Type consistency, better static analysis
• Negative: Minimal

Recommendation: Implement Option A (make return type optional).

---

MuxerMultistream Timeout

Location: libp2p/stream_muxer/muxer_multistream.py:34
Type: Configurability
Priority: Low
Difficulty: Medium / Low
Breaking Change: No
Discussion: GitHub Discussion #725

Summary: Missing timeout configuration in MuxerMultistream (hard coded 5 secs)

---

Noise Security Issues

Location: libp2p/security/noise/
Type: Interoperability
Priority: High
Difficulty: Expert
Breaking Change: Yes
Discussion: GitHub Discussion #721

Summary: Two interoperability issues with Go implementation:

1. Message prefix behavior inconsistency FIXED
2. Missing static key storage for IK pattern (JS, and GO implementation don't have this) DEPRECATED Removed TODO

Recommendation: Investigate Go implementation and align behavior.

---

Pubsub Issues

Location: libp2p/pubsub/
Type: Performance
Priority: Medium
Difficulty: Medium
Breaking Change: No
Discussion: GitHub Discussion #719

Summary:

1. Missing GossipSub sendRPC piggybacking ⚠️ PARTIALLY IMPLEMENTED
2. Message ID type consistency ❌ CRITICAL ISSUE
3. Message ID parsing improvement ❌ CRITICAL ISSUE
4. Async validator throttling ⚠️ PARTIALLY IMPLEMENTED

Impact:

• Positive: Better performance, type safety
• Negative: Minimal

Recommendation: Address CRITICAL ISSUEs.

---

Pubsub Missing Tests

Location: tests/core/pubsub/test_pubsub.py:393
Type: Testing
Priority: Medium
Difficulty: Medium
Breaking Change: No
Discussion: GitHub Discussion #728

Summary: Missing tests for test_stream_handler and test_handle_peer_queue that need alignment with Go implementation.

Impact:

• Positive: Better test coverage, Go compatibility
• Negative: Minimal

Recommendation: Implement hybrid approach (direct + integration tests).

---

Swarm Issues

Location: libp2p/network/swarm.py
Type: Architecture
Priority: High
Difficulty: Expert
Breaking Change: No
Discussion: GitHub Discussion #717

Summary: Two architectural issues:

1. Connection and peer_id 1-1 mapping limitation
2. Listener nursery I/O agnostic API issue Should be dismissed

Impact:

• Critical: Limited fault tolerance, framework coupling
• Architecture: Major design improvements needed

Recommendation: Implement Option A (multiple connections per peer) for fault tolerance.

---

Test Notify Issues DONE

Location: tests/core/network/test_notify.py
Type: Test Coverage
Priority: Low
Difficulty: Easy
Breaking Change: No
Discussion: GitHub Discussion #724

Summary: Missing tests for closed_stream and listen_close methods that are not implemented in swarm.

Impact:

• Positive: Better test coverage
• Negative: Minimal

Recommendation: Implement basic test structure first.

---

Transport Issues

Location: libp2p/transport/
Type: Architecture
Priority: High (Issue 1) / Low (Issue 2)
Difficulty: Expert (Issue 1) / Beginner (Issue 2)
Breaking Change: Yes (Issue 1) / No (Issue 2)
Discussion: GitHub Discussion #726

Summary: Two architectural issues:

1. TCPListener nursery dependency - Poor design choice violating Trio's structured concurrency principles Too complex
2. upgrade_listener function purpose - Fix in fix: remove unused upgrade_listener function (Issue 2 from #726) #884

Impact:

• Issue 1: 7 files need updates, breaking change requiring coordinated updates
• Issue 2: 1 file needs update, simple removal of unused code

Recommendations:

• Issue 1: Implement Option A (create nursery internally) for better design and cleaner API
• Issue 2: Remove the empty upgrade_listener function entirely

---

Good First Issues

For New Contributors

1. Get Mux Return Type - Simple type annotation fix
2. Mplex Stream Muxer Issues - Type safety and logging improvements
   . Test Notify Issues - Adding missing tests DONE

Benefits for New Contributors

• Low Risk: No breaking changes
• Clear Scope: Well-defined tasks
• Learning Value: Good introduction to codebase
• Quick Wins: Can be completed in a few hours
• Mentoring Opportunity: Good for pair programming

---

Expert Level Issues

For Experienced Contributors

1. Circuit v2 Relay Issues - Complex security implementation
   2. Noise Security Issues - Protocol interoperability
2. Swarm Issues - Major architectural changes
3. Transport Issues - Framework abstraction

Requirements for Expert Issues

• Deep Understanding: Protocol specifications and security
• Architecture Skills: Major design decisions
• Testing Expertise: Complex integration testing
• Breaking Changes: Careful migration planning

---

Implementation Roadmap

Phase 1: Quick Wins (1-2 weeks)

1. Fix get_mux return type
2. Add basic test notify tests
3. Fix mplex stream muxer issues

Phase 2: Important Improvements (2-4 weeks)

1. Implement muxer timeout
2. Fix mplexstream concurrency issues
3. Address pubsub performance issues
4. Add pubsub missing tests
5. Consider basichost.get_addrs() changes

Phase 3: Major Architecture (1-2 months)

1. Address swarm issues
2. Fix transport issues
3. Implement circuit v2 security

---

Risk Assessment

Low Risk Issues

• Type annotation fixes
• Error message improvements
• Test additions
• Logging improvements

Medium Risk Issues

• Performance optimizations
• API improvements (with backward compatibility)
• Concurrency fixes

High Risk Issues

• Breaking changes
• Security implementations
• Major architectural changes
• Protocol interoperability fixes

---

Conclusion

The py-libp2p codebase has a good mix of issues suitable for contributors at all levels. The high-priority security and reliability issues should be addressed first, followed by the medium-priority improvements. The low-priority issues provide excellent opportunities for new contributors to get familiar with the codebase.

Key Recommendations:

1. Start with good first issues for new contributors
2. Address security issues before production use
3. Plan breaking changes carefully with migration paths
4. Maintain backward compatibility where possible
5. Focus on reliability and performance improvements

This analysis provides a roadmap for systematic improvement of the py-libp2p codebase while maintaining stability and encouraging community contribution.

[dhuseby]

This is fantastic!! Thank you @acul71 🚀