✨ Feat: add Thin Waist address validation utilities and integrate into echo example

examples/advanced/network_discover.py

@@ -0,0 +1,63 @@
+"""
+Advanced demonstration of Thin Waist address handling.
+
+Run:
+    python -m examples.advanced.network_discovery
+"""
+
+from __future__ import annotations
+
+from multiaddr import Multiaddr
+
+try:
+    from libp2p.utils.address_validation import (
+        expand_wildcard_address,
+        get_available_interfaces,
+        get_optimal_binding_address,
+    )
+except ImportError:
+    # Fallbacks if utilities are missing
+    def get_available_interfaces(port: int, protocol: str = "tcp"):
+        return [Multiaddr(f"/ip4/0.0.0.0/{protocol}/{port}")]
+
+    def expand_wildcard_address(addr: Multiaddr, port: int | None = None):
+        if port is None:
+            return [addr]
+        addr_str = str(addr).rsplit("/", 1)[0]
+        return [Multiaddr(addr_str + f"/{port}")]
+
+    def get_optimal_binding_address(port: int, protocol: str = "tcp"):
+        return Multiaddr(f"/ip4/0.0.0.0/{protocol}/{port}")
+
+
+def main() -> None:
+    port = 8080
+    interfaces = get_available_interfaces(port)
+    print(f"Discovered interfaces for port {port}:")
+    for a in interfaces:
+        print(f"  - {a}")
+
+    wildcard_v4 = Multiaddr(f"/ip4/0.0.0.0/tcp/{port}")
+    expanded_v4 = expand_wildcard_address(wildcard_v4)
+    print("\nExpanded IPv4 wildcard:")
+    for a in expanded_v4:
+        print(f"  - {a}")
+
+    wildcard_v6 = Multiaddr(f"/ip6/::/tcp/{port}")
+    expanded_v6 = expand_wildcard_address(wildcard_v6)
+    print("\nExpanded IPv6 wildcard:")
+    for a in expanded_v6:
+        print(f"  - {a}")
+
+    print("\nOptimal binding address heuristic result:")
+    print(f"  -> {get_optimal_binding_address(port)}")
+
+    override_port = 9000
+    overridden = expand_wildcard_address(wildcard_v4, port=override_port)
+    print(f"\nPort override expansion to {override_port}:")
+    for a in overridden:
+        print(f"  - {a}")
+
+
+if __name__ == "__main__":
+    main()

examples/echo/echo.py

@@ -1,4 +1,7 @@
 import argparse
+import random
+import secrets
+import socket
 
 import multiaddr
 import trio
@@ -12,40 +15,61 @@
 from libp2p.custom_types import (
     TProtocol,
 )
+from libp2p.network.stream.exceptions import (
+    StreamEOF,
+)
 from libp2p.network.stream.net_stream import (
     INetStream,
 )
 from libp2p.peer.peerinfo import (
     info_from_p2p_addr,
 )
+from libp2p.utils.address_validation import (
+    get_available_interfaces,
+)
 
 PROTOCOL_ID = TProtocol("/echo/1.0.0")
 MAX_READ_LEN = 2**32 - 1
 
 
+def find_free_port():
+    """Find a free port on localhost."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("", 0))  # Bind to a free port provided by the OS
+        return s.getsockname()[1]
+
+
 async def _echo_stream_handler(stream: INetStream) -> None:
-    # Wait until EOF
-    msg = await stream.read(MAX_READ_LEN)
-    await stream.write(msg)
-    await stream.close()
+    try:
+        peer_id = stream.muxed_conn.peer_id
+        print(f"Received connection from {peer_id}")
+        # Wait until EOF
+        msg = await stream.read(MAX_READ_LEN)
+        print(f"Echoing message: {msg.decode('utf-8')}")
+        await stream.write(msg)
+    except StreamEOF:
+        print("Stream closed by remote peer.")
+    except Exception as e:
+        print(f"Error in echo handler: {e}")
+    finally:
+        await stream.close()
 
 
 async def run(port: int, destination: str, seed: int | None = None) -> None:
-    listen_addr = multiaddr.Multiaddr(f"/ip4/0.0.0.0/tcp/{port}")
+    # CHANGED: previously hardcoded 0.0.0.0
+    if port <= 0:
+        port = find_free_port()
+    listen_addr = get_available_interfaces(port)
 
     if seed:
-        import random
-
         random.seed(seed)
         secret_number = random.getrandbits(32 * 8)
         secret = secret_number.to_bytes(length=32, byteorder="big")
     else:
-        import secrets
-
         secret = secrets.token_bytes(32)
 
     host = new_host(key_pair=create_new_key_pair(secret))
-    async with host.run(listen_addrs=[listen_addr]), trio.open_nursery() as nursery:
+    async with host.run(listen_addrs=listen_addr), trio.open_nursery() as nursery:
         # Start the peer-store cleanup task
         nursery.start_soon(host.get_peerstore().start_cleanup_task, 60)
 
@@ -54,10 +78,15 @@ async def run(port: int, destination: str, seed: int | None = None) -> None:
         if not destination:  # its the server
             host.set_stream_handler(PROTOCOL_ID, _echo_stream_handler)
 
+            # Print all listen addresses with peer ID (JS parity)
+            print("Listener ready, listening on:\n")
+            peer_id = host.get_id().to_string()
+            for addr in listen_addr:
+                print(f"{addr}/p2p/{peer_id}")
+
             print(
-                "Run this from the same folder in another console:\n\n"
-                f"echo-demo "
-                f"-d {host.get_addrs()[0]}\n"
+                "\nRun this from the same folder in another console:\n\n"
+                f"echo-demo -d {host.get_addrs()[0]}\n"
             )
             print("Waiting for incoming connections...")
             await trio.sleep_forever()

libp2p/network/swarm.py

@@ -249,9 +249,11 @@ async def listen(self, *multiaddrs: Multiaddr) -> bool:
         # We need to wait until `self.listener_nursery` is created.
         await self.event_listener_nursery_created.wait()
 
+        success_count = 0
         for maddr in multiaddrs:
             if str(maddr) in self.listeners:
-                return True
+                success_count += 1
+                continue
 
             async def conn_handler(
                 read_write_closer: ReadWriteCloser, maddr: Multiaddr = maddr
@@ -302,13 +304,14 @@ async def conn_handler(
                 # Call notifiers since event occurred
                 await self.notify_listen(maddr)
 
-                return True
+                success_count += 1
+                logger.debug("successfully started listening on: %s", maddr)
             except OSError:
                 # Failed. Continue looping.
                 logger.debug("fail to listen on: %s", maddr)
 
-        # No maddr succeeded
-        return False
+        # Return true if at least one address succeeded
+        return success_count > 0
 
     async def close(self) -> None:
         """

libp2p/utils/__init__.py

@@ -15,6 +15,12 @@
     get_agent_version,
 )
 
+from libp2p.utils.address_validation import (
+    get_available_interfaces,
+    get_optimal_binding_address,
+    expand_wildcard_address,
+)
+
 __all__ = [
     "decode_uvarint_from_stream",
     "encode_delim",
@@ -26,4 +32,7 @@
     "decode_varint_from_bytes",
     "decode_varint_with_size",
     "read_length_prefixed_protobuf",
+    "get_available_interfaces",
+    "get_optimal_binding_address",
+    "expand_wildcard_address",
 ]

libp2p/utils/address_validation.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from multiaddr import Multiaddr
+
+try:
+    from multiaddr.utils import (  # type: ignore
+        get_network_addrs,
+        get_thin_waist_addresses,
+    )
+
+    _HAS_THIN_WAIST = True
+except ImportError:  # pragma: no cover - only executed in older environments
+    _HAS_THIN_WAIST = False
+    get_thin_waist_addresses = None  # type: ignore
+    get_network_addrs = None  # type: ignore
+
+
+def _safe_get_network_addrs(ip_version: int) -> list[str]:
+    """
+    Internal safe wrapper. Returns a list of IP addresses for the requested IP version.
+    Falls back to minimal defaults when Thin Waist helpers are missing.
+
+    :param ip_version: 4 or 6
+    """
+    if _HAS_THIN_WAIST and get_network_addrs:
+        try:
+            return get_network_addrs(ip_version) or []
+        except Exception:  # pragma: no cover - defensive
+            return []
+    # Fallback behavior (very conservative)
+    if ip_version == 4:
+        return ["127.0.0.1"]
+    if ip_version == 6:
+        return ["::1"]
+    return []
+
+
+def _safe_expand(addr: Multiaddr, port: int | None = None) -> list[Multiaddr]:
+    """
+    Internal safe expansion wrapper. Returns a list of Multiaddr objects.
+    If Thin Waist isn't available, returns [addr] (identity).
+    """
+    if _HAS_THIN_WAIST and get_thin_waist_addresses:
+        try:
+            if port is not None:
+                return get_thin_waist_addresses(addr, port=port) or []
+            return get_thin_waist_addresses(addr) or []
+        except Exception:  # pragma: no cover - defensive
+            return [addr]
+    return [addr]
+
+
+def get_available_interfaces(port: int, protocol: str = "tcp") -> list[Multiaddr]:
+    """
+    Discover available network interfaces (IPv4 + IPv6 if supported) for binding.
+
+    :param port: Port number to bind to.
+    :param protocol: Transport protocol (e.g., "tcp" or "udp").
+    :return: List of Multiaddr objects representing candidate interface addresses.
+    """
+    addrs: list[Multiaddr] = []
+
+    # IPv4 enumeration
+    seen_v4: set[str] = set()
+
+    for ip in _safe_get_network_addrs(4):
+        seen_v4.add(ip)
+        addrs.append(Multiaddr(f"/ip4/{ip}/{protocol}/{port}"))
+
+    # Ensure IPv4 loopback is always included when IPv4 interfaces are discovered
+    if seen_v4 and "127.0.0.1" not in seen_v4:
+        addrs.append(Multiaddr(f"/ip4/127.0.0.1/{protocol}/{port}"))
+
+    # TODO: IPv6 support temporarily disabled due to libp2p handshake issues
+    # IPv6 connections fail during protocol negotiation (SecurityUpgradeFailure)
+    # Re-enable IPv6 support once the following issues are resolved:
+    # - libp2p security handshake over IPv6
+    # - multiselect protocol over IPv6
+    # - connection establishment over IPv6
+    #
+    # seen_v6: set[str] = set()
+    # for ip in _safe_get_network_addrs(6):
+    #     seen_v6.add(ip)
+    #     addrs.append(Multiaddr(f"/ip6/{ip}/{protocol}/{port}"))
+    #
+    # # Always include IPv6 loopback for testing purposes when IPv6 is available
+    # # This ensures IPv6 functionality can be tested even without global IPv6 addresses
+    # if "::1" not in seen_v6:
+    #     addrs.append(Multiaddr(f"/ip6/::1/{protocol}/{port}"))
+
+    # Fallback if nothing discovered
+    if not addrs:
+        addrs.append(Multiaddr(f"/ip4/0.0.0.0/{protocol}/{port}"))
+
+    return addrs
+
+
+def expand_wildcard_address(
+    addr: Multiaddr, port: int | None = None
+) -> list[Multiaddr]:
+    """
+    Expand a wildcard (e.g. /ip4/0.0.0.0/tcp/0) into all concrete interfaces.
+
+    :param addr: Multiaddr to expand.
+    :param port: Optional override for port selection.
+    :return: List of concrete Multiaddr instances.
+    """
+    expanded = _safe_expand(addr, port=port)
+    if not expanded:  # Safety fallback
+        return [addr]
+    return expanded
+
+
+def get_optimal_binding_address(port: int, protocol: str = "tcp") -> Multiaddr:
+    """
+    Choose an optimal address for an example to bind to:
+    - Prefer non-loopback IPv4
+    - Then non-loopback IPv6
+    - Fallback to loopback
+    - Fallback to wildcard
+
+    :param port: Port number.
+    :param protocol: Transport protocol.
+    :return: A single Multiaddr chosen heuristically.
+    """
+    candidates = get_available_interfaces(port, protocol)
+
+    def is_non_loopback(ma: Multiaddr) -> bool:
+        s = str(ma)
+        return not ("/ip4/127." in s or "/ip6/::1" in s)
+
+    for c in candidates:
+        if "/ip4/" in str(c) and is_non_loopback(c):
+            return c
+    for c in candidates:
+        if "/ip6/" in str(c) and is_non_loopback(c):
+            return c
+    for c in candidates:
+        if "/ip4/127." in str(c) or "/ip6/::1" in str(c):
+            return c
+
+    # As a final fallback, produce a wildcard
+    return Multiaddr(f"/ip4/0.0.0.0/{protocol}/{port}")
+
+
+__all__ = [
+    "get_available_interfaces",
+    "get_optimal_binding_address",
+    "expand_wildcard_address",
+]

newsfragments/811.internal.rst

@@ -0,0 +1,7 @@
+Add Thin Waist address validation utilities and integrate into echo example
+
+- Add ``libp2p/utils/address_validation.py`` with dynamic interface discovery
+- Implement ``get_available_interfaces()``, ``get_optimal_binding_address()``, and ``expand_wildcard_address()``
+- Update echo example to use dynamic address discovery instead of hardcoded wildcard
+- Add safe fallbacks for environments lacking Thin Waist support
+- Temporarily disable IPv6 support due to libp2p handshake issues (TODO: re-enable when resolved)

newsfragments/863.bugfix.rst

@@ -0,0 +1,5 @@
+Fix multi-address listening bug in swarm.listen()
+
+- Fix early return in swarm.listen() that prevented listening on all addresses
+- Add comprehensive tests for multi-address listening functionality
+- Ensure all available interfaces are properly bound and connectable