The Two-Terminal Test
Fire up a JavaScript libp2p echo server and you see something like this:
Listener ready, listening on:
/ip4/127.0.0.1/tcp/10333/p2p/12D3KooW...
/ip4/192.168.136.148/tcp/10333/p2p/12D3KooW...
/ip4/10.149.6.41/tcp/10333/p2p/12D3KooW...
Three interfaces. Every way a peer could reach this node, spelled out. Now fire up the Python equivalent:
I am 16Uiu2HAmRxq...
echo-demo -d /ip4/192.168.136.148/tcp/33387/p2p/16Uiu2HAmRxq...
One address. Derived from a hardcoded wildcard. No loopback, no interface enumeration, no parity with the rest of the libp2p family. I set out to close that gap with PR #811 — and along the way uncovered a hidden bug that had been silently preventing multi-address listening for years.
Background
libp2p is a modular peer-to-peer networking framework that powers IPFS, Filecoin, and dozens of other decentralized systems. It uses multiaddr — a self-describing address format like /ip4/192.168.1.5/tcp/8080/p2p/QmPeerID — to represent network endpoints in a transport-agnostic way.
py-libp2p is the Python implementation of this stack. It's steadily moving toward production readiness, but its examples still carried a common shortcut: every single one hardcoded /ip4/0.0.0.0/tcp/{port} as its listen address. The "thin waist" — a networking term for the narrow IP layer through which all traffic flows — has utilities in the multiaddr library for expanding wildcards into concrete interface addresses. Nobody was using them.
The Problem
Issue #804 catalogued the damage. Fifteen examples, all with the same line:
listen_addr = multiaddr.Multiaddr(f"/ip4/0.0.0.0/tcp/{port}")
No interface discovery. No dynamic binding. No way for a peer to know which concrete addresses a node was reachable on. And because the examples are how new contributors learn the library, this hardcoded pattern was propagating into every project built on py-libp2p.
But the real surprise came during implementation. When I tried passing multiple listen addresses to the swarm, only the first one worked. The culprit was in swarm.listen():
for maddr in multiaddrs:
if str(maddr) in self.listeners:
- return True
+ success_count += 1
+ continue
An early return True on the first successful bind. The loop was there, but it never made it past iteration one. This bug had been invisible because nobody had ever passed more than one address.
Before PR #811: a hardcoded wildcard fed into a swarm that could only bind once.

The Solution
The fix came in three layers.
Layer 1: A new utility module. I created libp2p/utils/address_validation.py with four functions:
get_available_interfaces(port)— discovers all IPv4 network interfaces and returns multiaddrs for eachget_optimal_binding_address(port)— picks the best single address (prefers non-loopback)expand_wildcard_address(addr)— expands a0.0.0.0wildcard into concrete addressesfind_free_port()— a centralized port-finding utility (previously duplicated across examples)
Layer 2: The swarm fix. I replaced the early return with a counter that tracks successful binds across all addresses, returning True if at least one succeeded.
Layer 3: The echo migration. The echo example now calls get_available_interfaces(port) and passes the full list to host.run(listen_addrs=...):
listen_addr = get_available_interfaces(port)
# ...
async with host.run(listen_addrs=listen_addr):
print("Listener ready, listening on:\n")
peer_id = host.get_id().to_string()
for addr in listen_addr:
print(f"{addr}/p2p/{peer_id}")
The result matches what JavaScript libp2p users have always seen — every reachable interface, listed clearly.
The Graceful Fallback
The utility module doesn't blindly depend on thin waist support. At import time, it tries to load multiaddr.utils.get_thin_waist_addresses and get_network_addrs. If they're missing — older multiaddr versions, constrained environments — it sets _HAS_THIN_WAIST = False and falls back to conservative defaults like 127.0.0.1.
The fallback strategy ensures the code works even without thin waist support in the multiaddr library.

This means existing deployments won't break. The new code is strictly additive — if the thin waist helpers aren't available, you get the same behavior as before.
One thing I deliberately didn't do: IPv6. I discovered that py-libp2p's TCP transport calls maddr.value_for_protocol("ip4"), which throws a ProtocolLookupError on IPv6 multiaddrs. With ~40 files still carrying hardcoded IPv4 assumptions, enabling IPv6 would have blown the scope wide open. Instead, I wrote the IPv6 discovery code, commented it out, and marked it with a clear TODO. Ship what works; plan what's next.
Before & After
| Before | After | |
|---|---|---|
| Listen addresses | 1 (hardcoded 0.0.0.0) | All discovered IPv4 interfaces |
| Interface discovery | None | Dynamic via thin waist utilities |
| Swarm multi-listen | Broken (early return) | Fixed (iterates all addresses) |
| Loopback included | No | Always (ensures local dev works) |
| Output parity with JS | No | Yes |
| IPv6 | Not attempted | Discovered but disabled (TODO) |
| Backward compatibility | N/A | Full (graceful fallbacks) |
Lessons Learned
Feature work is the best bug finder. The swarm.listen() early-return bug had existed since the method was written. It never surfaced because no code path ever passed multiple addresses. The moment I tried to use the feature as designed, the bug became obvious. If your code has untested branches, writing a feature that exercises them is more effective than writing a test in isolation — you discover the bugs that matter in the context they'll actually appear.
Ship the working slice, not the perfect whole. IPv6 support was within reach — I had the discovery code written, the interfaces enumerated. But enabling it would have required changes across 40+ files in the transport layer, identify module, and mDNS. The pragmatic choice was to disable it with a clear TODO and keep the PR reviewable. A 572-line PR that ships is worth more than a 2000-line PR stuck in review.
Conclusion
PR #811 gives py-libp2p the ability to see its own network — a prerequisite for any serious P2P application. The echo example now shows every reachable interface, just like its JavaScript counterpart. A hidden swarm bug is fixed. And the groundwork is laid for IPv6 support and migration of the remaining 14 examples in Phase 4. Sometimes the most important infrastructure change is teaching a node to look around and say, "here's how you can reach me."
Resources
- PR #811 — Add Thin Waist address validation utilities
- Issue #804 — Add thin waist address validation to examples
- libp2p Addressing Concepts
- Multiaddr Specification
- py-libp2p Documentation
Related on libp2p.io: Addressing, Listening and Dialing.
If you would like to contribute, please connect with the libp2p maintainers.