# TODO Analysis Summary: py-libp2p Issues Overview

[acul71]

TODO Analysis Summary: py-libp2p Issues Overview

Last review: November 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 from Discussion #730 across 8 different modules, plus 5 additional TODOs identified in the expanded report, 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
  • Get Mux Return Type
  • Mplex Stream Muxer Issues
  • MplexStream Issues
  • Multiselect Type Consistency
  • MuxerMultistream Timeout
  • Pubsub Issues
  • Pubsub Missing Tests
  • Swarm Issues
  • Test Notify Issues
  • Transport Issues
  • Additional TODOs (Not in Original Discussion #730)
    • IPv6 Support
    • IPNS Implementation
    • Pubsub P6/P7 Penalties
    • TCP Nursery TODO
    • QUIC Type Fix
• 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 (1/4, 2/4 tracked)
Swarm Issues	Network Architecture	High	Expert	No	❌	⚠️ Open (PR #876 merged, but TODO remains)
Transport Issues	Transport Architecture	High	Expert	Yes	❌	⚠️ Open
MplexStream Issues	Stream Muxer Concurrency	High	Medium	No	❌	✅ Done (4/4 completed)
MuxerMultistream Timeout	Stream Muxer Reliability	High	Medium	No	❌	✅ RESOLVED - Timeout is configurable
BasicHost.get_addrs() p2p postfix	Host API Design	Medium	Medium	Yes	❌	⚠️ Open (no GitHub issue)
Pubsub Issues	Pubsub Performance	Medium	Medium	No	❌	⚠️ Partially resolved (2/3)
Pubsub Missing Tests	Pubsub Testing	Medium	Medium	No	❌	⚠️ Open (Issue #191 mentioned but not found)
Mplex Stream Muxer Issues	Stream Muxer Type Safety	Medium	Easy	No	✅	⚠️ Open (Issue #741 + PR #742)
Multiselect Type Consistency	Protocol Muxer Type Safety	Medium	Easy	No	✅	✅ Done in: #770
Get Mux Return Type	ABC Type Safety	Low	Easy	No	✅	⚠️ Open (Issue #736)
Test Notify Issues	Testing Test Coverage	Low	Easy	No	✅	✅ Done (Issue #825 closed)
IPv6 Support	Feature Gap	High	Medium-High	No	❌	⚠️ Open (not in Discussion #730)
IPNS Implementation	Planned Feature	High	Difficult	No	❌	⚠️ Open (not in Discussion #730)
Pubsub P6/P7 Penalties	Security Features	Medium	Medium	No	❌	⚠️ Open (not in Discussion #730)
TCP Nursery TODO	Design Question	Low	Easy	No	✅	⚠️ Open (not in Discussion #730)
QUIC Type Fix	Type Annotation	Low	Easy	No	✅	⚠️ Open (not in Discussion #730)

Detailed Issue Analysis

BasicHost.get_addrs() p2p postfix

Location: libp2p/host/basic_host.py:204

Type: API Design

Priority: Medium

Difficulty: Medium

Breaking Change: Yes

Discussion: GitHub Discussion #716

GitHub Tracking: ❌ No GitHub issue found - Needs to be created

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.

Current Status: ⚠️ OPEN - TODO comment still present at line 204

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. Create GitHub issue for API redesign discussion.

---

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 - PARTIALLY DONE (voucher generation implemented, signature still TODO at resources.py:119)
   • GitHub Tracking: ❌ No GitHub issue found - Needs to be created
2. ❌ Missing voucher and signature verification - OPEN (TODO at resources.py:215)
   • GitHub Tracking: ✅ Issue #697 + PR #698 (OPEN, active work)
3. ❌ Need for sophisticated relay selection - OPEN (TODO at transport.py:295)
   • GitHub Tracking: ✅ Issue #735 (OPEN)
4. ❌ Missing reservation storage and refresh mechanism - OPEN (TODO at transport.py:383)
   • GitHub Tracking: ❌ No GitHub issue found - Needs to be created

Current Status: ⚠️ WORK IN PROGRESS (1/4 resolved, 2/4 tracked on GitHub)

Impact:

• Production Risk: Not suitable for production use without fixes
• Security: Missing signature verification is a security concern

Recommendation: Address issues 2, 3, and 4 in order of priority.

---

Get Mux Return Type

Location: libp2p/abc.py:1799, libp2p/host/basic_host.py:194

Type: Type Safety

Priority: Low

Difficulty: Easy

Breaking Change: No

Discussion: GitHub Discussion #729

GitHub Tracking: ✅ Issue #736 (OPEN)

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

Current Status: ⚠️ OPEN - Still returns Multiselect instead of IMultiselectMuxer

Impact:

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

Recommendation: Update return type to IMultiselectMuxer in both interface and implementation. Tracked in Issue #736.

---

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

GitHub Tracking: ✅ Issue #741 + PR #742 (OPEN, active work)

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

1. ❌ Return type inconsistency in send_message() - OPEN (TODO at line 199)
2. ❌ Missing logging for unknown flags - OPEN (TODO at line 280)
3. ❌ Missing warning for unknown stream messages - OPEN (TODO at line 304)
4. ❌ Missing warning for data after stream close - OPEN (TODO at line 310)

Current Status: ⚠️ OPEN - All 4 issues still present, actively being addressed in PR #742

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

GitHub Tracking: ✅ Issue #984 (CLOSED - 2025-10-19)

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 - DONE (Implemented: set_deadline, set_read_deadline, set_write_deadline)

Current Status: ✅ DONE (4/4 completed)

Note: Issue #984 was closed as deadline functionality is now fully implemented. Issues #852 and #832 are outdated and should be closed.

Impact:

• Performance: Improved stream reliability
• Reliability: Better error handling and timeout support

Recommendation: All issues resolved. No further action needed.

---

Multiselect Type Consistency

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 and implementation.

Current Status: ✅ DONE - Resolved in PR #770

Impact:

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

Recommendation: Issue resolved. No further action needed.

---

MuxerMultistream Timeout

Location: libp2p/stream_muxer/muxer_multistream.py:55

Type: Configurability

Priority: High

Difficulty: Medium / Low

Breaking Change: No

Discussion: GitHub Discussion #725

Summary: Missing timeout configuration in MuxerMultistream.

Current Status: ✅ RESOLVED - Timeout is now configurable via negotiate_timeout parameter in __init__ (defaults to DEFAULT_NEGOTIATE_TIMEOUT = 5)

Impact:

• Positive: Configurable timeout improves flexibility
• Negative: None

Recommendation: Issue resolved. No further action needed.

---

Pubsub Issues

Location: libp2p/pubsub/

Type: Performance

Priority: Medium

Difficulty: Medium

Breaking Change: No

Discussion: GitHub Discussion #719

Summary: Missing GossipSub optimizations and type consistency:

1. ❌ Missing GossipSub sendRPC piggybacking - OPEN (TODO at gossipsub.py:337)
   • GitHub Tracking: ❌ No GitHub issue found - Needs to be created
2. ✅ Message ID type consistency - RESOLVED (Public get_message_id() method exists)
3. ⚠️ Async validator throttling - RESOLVED (Implemented with MAX_CONCURRENT_VALIDATORS = 10 and semaphore)

Current Status: ⚠️ PARTIALLY RESOLVED (2/3 resolved)

Impact:

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

Recommendation: Address remaining sendRPC piggybacking issue.

---

Pubsub Missing Tests

Location: tests/core/pubsub/test_pubsub.py:536

Type: Testing

Priority: Medium

Difficulty: Medium

Breaking Change: No

Discussion: GitHub Discussion #728

GitHub Tracking: ❌ Issue #191 mentioned in code but not found - Needs verification or new issue

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

Current Status: ⚠️ OPEN - TODO comment still present, tests not implemented

Impact:

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

Recommendation: Implement hybrid approach (direct + integration tests). Verify Issue #191 status or create new issue.

---

Swarm Issues

Location: libp2p/network/swarm.py:657

Type: Architecture

Priority: High

Difficulty: Expert

Breaking Change: No

Discussion: GitHub Discussion #717

GitHub Tracking: ✅ PR #876 (MERGED - 2025-09-01) - Some swarm issues addressed, but listener nursery TODO still present. Related: Issue #417, Issue #604

Summary: Listener nursery bounding issue.

Current Status: ⚠️ OPEN - TODO comment still present at line 657

Impact:

• Architecture: I/O agnostic API improvement needed
• Complexity: Requires API changes

Recommendation: Design API changes for I/O agnostic listener implementation. May be related to Issue #417 or #604.

---

Test Notify Issues

Location: tests/core/network/test_notify.py

Type: Testing

Priority: Low

Difficulty: Easy

Breaking Change: No

Discussion: GitHub Discussion #825

GitHub Tracking: ✅ Issue #825 (CLOSED - 2025-08-28)

Summary: Missing test coverage for notify functionality.

Current Status: ✅ DONE - Tests exist (test_notify, test_notify_with_closed_stream_and_listen_close, test_notify_edge_cases)

Impact:

• Positive: Better test coverage
• Negative: None

Recommendation: Issue resolved. No further action needed.

---

Transport Issues

Location: libp2p/transport/

Type: Transport Architecture

Priority: High

Difficulty: Expert

Breaking Change: Yes

Discussion: GitHub Discussion #717

Summary: Transport-related architectural improvements needed.

Current Status: ⚠️ OPEN - Needs investigation

Impact:

• Architecture: May require breaking changes
• Complexity: High

Recommendation: Further investigation needed to identify specific transport issues.

---

Additional TODOs (Not in Original Discussion #730)

These TODOs were identified in the expanded TODO report but are not part of the original Discussion #730 scope. They are included here for completeness.

IPv6 Support

Location: libp2p/utils/address_validation.py:67

Type: Feature Gap

Priority: High

Difficulty: Medium-High

Breaking Change: No

Summary: IPv6 support is temporarily disabled due to libp2p handshake issues. IPv6 connections fail during protocol negotiation (SecurityUpgradeFailure).

Current Status: ⚠️ OPEN - IPv6 code is commented out, needs re-enablement

Impact:

• Feature Gap: Significant limitation affecting network connectivity
• Modern Networking: IPv6 is increasingly important
• Interoperability: May affect compatibility with IPv6-only networks

Recommendation: Re-enable IPv6 support once security handshake and multiselect protocol issues are resolved. See downloads/2025-11-19-TODO.md for detailed implementation steps.

---

IPNS Implementation

Location: libp2p/kad_dht/kad_dht.py:254, 282, 290

Type: Planned Feature

Priority: High

Difficulty: Difficult

Breaking Change: No

Summary: IPNS (InterPlanetary Name System) support is planned but not implemented. Multiple TODOs indicate this is a planned feature that allows mutable pointers to content-addressed data.

Current Status: ⚠️ OPEN - Not implemented, 3 TODOs present

Impact:

• Feature Gap: Large feature not yet implemented
• Functionality: Enables mutable content addressing
• Complexity: Requires IPNS record structure, validator, and publishing/resolution

Recommendation: This is a large feature that should be tracked as a separate issue/PR, not just fixing TODOs. See downloads/2025-11-19-TODO.md for implementation approach.

---

Pubsub P6/P7 Penalties

Location: libp2p/pubsub/score.py:160

Type: Security Features

Priority: Medium

Difficulty: Medium

Breaking Change: No

Summary: GossipSub scoring system has penalties P1-P5 implemented, but P6 (Application-specific penalty) and P7 (IP colocation penalty) are documented but not implemented.

Current Status: ⚠️ OPEN - TODO comment present

Impact:

• Security: P7 helps prevent Sybil attacks from same IP ranges
• Flexibility: P6 allows application-specific scoring logic
• Completeness: Missing features from GossipSub spec

Recommendation: Implement when concrete use cases are identified. See downloads/2025-11-19-TODO.md for implementation details.

---

TCP Nursery TODO

Location: libp2p/transport/tcp/tcp.py:44

Type: Design Question

Priority: Low

Difficulty: Easy

Breaking Change: No

Summary: TODO questions whether nursery parameter is still needed in listen() method.

Current Status: ⚠️ OPEN - TODO present, but nursery is required by IListener interface

Impact:

• Design: Nursery is required by interface, TODO may be outdated
• Documentation: Should clarify why nursery is necessary

Recommendation: Remove TODO and add clarifying comment. The nursery is required by the IListener interface and is essential for managing async task lifecycle in trio.

---

QUIC Type Fix

Location: libp2p/transport/quic/exceptions.py:354

Type: Type Annotation

Priority: Low

Difficulty: Easy

Breaking Change: No

Summary: Type annotation has duplicate None in __exit__ method signature: type[BaseException] | None | None.

Current Status: ⚠️ OPEN - Simple typo in type annotation

Impact:

• Code Quality: Redundant type annotation
• Type Safety: Should be type[BaseException] | None

Recommendation: Simple fix - remove duplicate None. See downloads/2025-11-19-TODO.md for fix.

---

Good First Issues

These issues are suitable for new contributors:

1. Mplex Stream Muxer Issues - Type safety and logging improvements
2. Get Mux Return Type - Simple type annotation update
3. Multiselect Type Consistency - ✅ Already resolved

Expert Level Issues

These require deep understanding of the codebase:

1. Circuit v2 Relay Issues - Security-critical implementation
2. Swarm Issues - Architectural changes
3. Transport Issues - Breaking changes

Implementation Roadmap

Phase 1: High Priority Security (Expert)

• Circuit v2: Implement voucher and signature verification
• Circuit v2: Implement sophisticated relay selection
• Circuit v2: Implement reservation storage and refresh mechanism

Phase 2: High Priority Reliability (Medium)

• MplexStream: Deadline functionality ✅
• MuxerMultistream: Timeout configuration ✅

Phase 3: Medium Priority Improvements (Easy-Medium)

• Mplex Stream Muxer: Fix type inconsistencies and add logging
• Pubsub: Implement sendRPC piggybacking
• Pubsub: Add missing tests

Phase 4: Low Priority Cleanup (Easy)

• Get Mux Return Type: Update to IMultiselectMuxer
• BasicHost.get_addrs(): Consider API redesign
• QUIC Type Fix: Remove duplicate None in type annotation
• TCP Nursery TODO: Remove outdated TODO, add documentation

Phase 5: Additional High Priority Features (Not in Discussion #730)

• IPv6 Support: Re-enable IPv6 with feature flag
• IPNS Implementation: Large feature, track separately
• Pubsub P6/P7 Penalties: Implement when use cases identified

Risk Assessment

High Risk

• Circuit v2 Relay Issues: Security vulnerabilities, not production-ready
• Swarm Issues: Architectural changes may affect stability
• IPv6 Support: Feature gap affecting connectivity (not in Discussion # TODO Analysis Summary: py-libp2p Issues Overview #730)
• IPNS Implementation: Large feature requiring careful design (not in Discussion # TODO Analysis Summary: py-libp2p Issues Overview #730)

Medium Risk

• BasicHost.get_addrs(): Breaking change requires careful migration
• Transport Issues: Breaking changes need careful planning

Low Risk

• Type safety issues: Non-breaking, easy to implement
• Test additions: No risk to existing functionality

Conclusion

Summary of Status:

• ✅ Resolved: 5 issues (MplexStream deadlines, MuxerMultistream timeout, Multiselect types, Test notify, Message ID consistency, Async validator throttling)
• ⚠️ In Progress: 1 issue (Circuit v2 - 1/4 done)
• ❌ Open: 9 issues (from Discussion # TODO Analysis Summary: py-libp2p Issues Overview #730)
• 📋 Additional: 5 additional TODOs identified (IPv6, IPNS, P6/P7, TCP, QUIC)

Next Steps:

1. Prioritize Circuit v2 security issues
2. Address remaining Mplex logging issues
3. Implement Pubsub sendRPC piggybacking
4. Add missing Pubsub tests
5. Consider type safety improvements
6. Evaluate adding high-priority additional TODOs (IPv6, IPNS) to Discussion # TODO Analysis Summary: py-libp2p Issues Overview #730 scope

Last Updated: November 2025 (based on origin/main branch)

GitHub Tracking: See DISCUSSION_730_GITHUB_TRACKING.md for complete mapping of TODOs to GitHub issues and PRs.

Related Documentation: See downloads/2025-11-19-TODO.md for expanded TODO report with detailed context and solutions (42 total items, 18 active TODOs).

[dhuseby]

This is fantastic!! Thank you @acul71 🚀