Add Support for mDNS-Based Local Peer Discovery in py-libp2p

[seetadev]

This proposal outlines how we can introduce Multicast DNS (mDNS)-based peer discovery into py-libp2p, aligned with the behavior of go-libp2p and js-libp2p.

Module Structure & Responsibilities

We propose creating a dedicated module, libp2p.discovery.mdns, with the following internal components:

libp2p/
└── discovery/
    └── mdns/
        ├── broadcaster.py  # Registers local peer via mDNS
        ├── listener.py     # Listens for mDNS broadcasts from other peers
        └── __init__.py

Each component would manage distinct responsibilities:

1. Broadcaster

   • Advertises the local peer's presence on the network using the _p2p._udp.local service name.
   • Uses a TXT record to encode the local peer ID:
     Example: id=QmPeerID123...

2. Listener

   • Listens on 224.0.0.251:5353 for mDNS responses.
   • Parses valid mDNS responses to extract PeerInfo for peers discovered on the same LAN.
   • Emits these to the libp2p Swarm/Host layer for dialing.

3. Integration Layer

   • Provides an API surface for enabling/disabling mDNS.
   • Hooks into Swarm or Host to trigger connection attempts when peers are discovered.

---

🛠️ How it Works (Expected Flow)

• On startup, if mdns is enabled:

  • mdns_broadcaster advertises the peer using Zeroconf (or equivalent).
  • mdns_listener listens for peer advertisements.

• When a peer is found:

  • A PeerInfo object is emitted.
  • If supported, Swarm auto-dials the discovered peer or adds it to its peerstore.

Dependency Suggestion: [zeroconf](https://github.com/jstasiak/python-zeroconf) Python Library

We suggest using zeroconf, a well-supported Python library with support for:

• Multicast broadcast and listening
• TXT record parsing
• Cross-platform support (Linux/macOS/Windows)

The library is used in projects like Home Assistant, which shows it handles real-world, high-performance discovery.

Configuration Options

Add a new config object or flags to enable/disable mDNS:

Host(..., enable_mdns=True)

Advanced options could include:

• Service name override (for scoped discovery)
• Peer ID filtering
• Interval control for rebroadcasts

---

Testing Plan

1. Unit Tests

   • TXT record parsing
   • PeerInfo extraction
   • Service registration lifecycle

2. Integration Tests

   • Simulate two libp2p hosts on the same subnet
   • Validate discovery and peerstore updates

We can leverage pytest fixtures to spin up hosts in subprocesses on local ports.

Example Usage (Preview)

from libp2p import new_node

node = await new_node(enable_mdns=True)

@node.on_peer_discovered
def on_new_peer(peer_info):
    print(f"Discovered peer: {peer_info.peer_id}")
    await node.connect(peer_info)

🔍 Open Questions for Discussion

1. Where should peer discovery events be surfaced?

   • Should Host expose a listener pattern or use async callbacks?
   • How should we handle multiple discovery mechanisms (mDNS, DHT, etc.) consistently?

2. How do we ensure safety and scoping?

   • Should we support namespaces for service names to avoid collisions on shared networks?

3. Do we want to align broadcast intervals with go/js defaults?

   • Example: js-libp2p re-broadcasts every 10 seconds.

4. Should we emit events even if the peer is already known (i.e., for heartbeats)?

Why This Is a Good Fit for py-libp2p

• Improves feature parity with Go and JS libp2p.
• Enables new use cases (local collaboration, demos, P2P offline apps).
• Provides easier onboarding for developers experimenting with libp2p in Python.
• Aligns with libp2p’s modular discovery framework and specs.

[sumanjeet0012]

mDNS Discovery Implementation Progress Update

🚀 Current Status

Hey @seetadev I've been working on implementing mDNS-based peer discovery for py-libp2p as outlined in issue #633. Here's the current status of my implementation:

✅ What's Working:

1. Broadcasting is fully functional

   • Peers can successfully advertise themselves on the local network using the _p2p._udp.local. service type
   • Proper TXT records containing peer IDs are being broadcast
   • Service registration and lifecycle management working correctly

2. Listening/Discovery is working

   • The listener successfully discovers other peers on the network
   • PeerInfo objects are properly extracted from discovered services
   • Service info parsing logic implemented

3. Zeroconf Integration

   • Using the zeroconf library as suggested for cross-platform mDNS support
   • Handles service registration, discovery, and cleanup properly

🔧 Current Implementation Structure:

Following the proposed module structure from the discussion:

libp2p/discovery/mdns/
├── broadcaster.py    # ✅ Complete - handles service registration
├── listener.py       # ✅ Complete - discovers peers and extracts PeerInfo  
├── mdns.py          # ✅ Complete - main MDNSDiscovery class
└── utils.py         # ✅ Complete - helper functions

🤔 Where I Need Guidance - Event System:

This is where I could use some input . Currently, I have the discovery logic working, but I'm looking for guidance on the best practices for emitting events with peer info as payload.

Specific questions:

Event System Architecture:

• Should we create a dedicated libp2p.discovery.events module for discovery events?
• Or integrate with an existing event system in py-libp2p?
• Is there a preferred event emitter pattern already used in the codebase?
• Or should I use some external libraries.

🧪 Testing Status:

Still needed:

• Unit tests for core logic components
• Integration tests for multi-peer scenarios

This feature is very close to completion - just need to nail down the event system design! 🚀

Looking forward to your feedback and guidance on the event system implementation!

[seetadev]

mDNS Discovery Implementation Progress Update

🚀 Current Status

Hey @seetadev I've been working on implementing mDNS-based peer discovery for py-libp2p as outlined in issue #633. Here's the current status of my implementation:

@sumanjeet0012 : Great work—this is a solid implementation update and a huge step forward for peer discovery in py-libp2p. Thanks for the detailed breakdown; very easy to follow.

✅ Implementation Review

• Broadcasting + Listening:
  Excellent that both components are fully functional. Service registration using _p2p._udp.local. and correct handling of TXT records with peer IDs checks all the core requirements. Good call on using zeroconf—it’s the right abstraction for cross-platform support.

• Module Structure:
  The directory layout under libp2p/discovery/mdns/ is clean and aligns well with modular design. Keeping broadcaster.py, listener.py, and mdns.py decoupled this way makes future testing and extension (e.g., adding DNS-SD, Bluetooth LE, etc.) more straightforward.

---

🧩 Event System – Technical Recommendation

You're right to pause here. For peer discovery to be usable across other parts of the stack (like Swarm, DHT, etc.), a proper event interface is critical.

Suggested Direction:

• Create a dedicated libp2p.discovery.events module
  This keeps discovery-related signaling isolated and scalable.

• Use an internal async callback/event pattern
  We don’t need to bring in an external library here—an async handler pattern or asyncio.Queue-based pub/sub model should suffice.

Reference Design:

class MDNSDiscovery:
    def __init__(self):
        self._peer_discovered_handlers: List[Callable[[PeerInfo], Awaitable[None]]] = []

    def on_peer_discovered(self, handler: Callable[[PeerInfo], Awaitable[None]]):
        self._peer_discovered_handlers.append(handler)

    async def _emit_peer_discovered(self, peer_info: PeerInfo):
        for handler in self._peer_discovered_handlers:
            await handler(peer_info)

This is minimal but extensible and keeps the peer discovery interface asynchronous and composable.

You can look at how Pubsub or Swarm handles internal events (e.g., peer connections, message delivery) for consistency.

🧪 Testing

Once the event system is in place, integration tests with multiple peer instances on a local network will be the priority. For unit testing, we can use unittest.mock to stub out zeroconf.ServiceBrowser and simulate discovery responses.

Let me know if you want help sketching out the test harness. We’ll also want to validate behavior under peer churn and duplicate discovery cases.

✅ Next Steps

• Proceed with building the event system under libp2p.discovery.events
• Implement the callback registration/emission as above
• Once events are flowing, we can integrate with Swarm for full local peer autodiscovery

This is excellent work and moving us toward a much-needed capability in py-libp2p. Thanks again for pushing this forward—happy to review the PR once the event layer is in place.

[sumanjeet0012]

@seetadev The Multicast DNS is ready for review.
I have uploaded the developer documentation and demo file for the same.

Developer documentation: https://drive.google.com/file/d/104byHM3iOi9AeDeK_W0Jb1BIOXo6bvNF/view?usp=drive_link
Demo Video: https://drive.google.com/file/d/1JZ4_6iZJwJvohETa2GxP1-udQ2kbWAAP/view?usp=sharing