Feat: Add comprehensive IPv6 support to transport and network layers (libp2p#1132)

* feat: Add multiaddr utility functions for IPv4/IPv6 handling

* feat: Enhance IPv6 support by re-enabling address handling and updating utility functions

* feat: Enhance IPv6 support in tests by adding address parsing and validation

* feat: Add IPv6 address validation and default binding support

* feat: Improve IPv6 support in bind address tests with environment variable handling

* - Add IPv6 bind address support via `LIBP2P_BIND_V6` configuration option

* Fix validation messages for IPv4 and IPv6 address functions; add TODO for IPv6 test stability

Author: yashksaini-coder

docs/getting_started.rst

@@ -79,6 +79,36 @@ Now that you have configured a **Transport**, **Crypto** and **Stream Multiplexe
 .. literalinclude:: ../examples/doc-examples/example_running.py
    :language: python
 
+Bind address and IPv6
+^^^^^^^^^^^^^^^^^^^^^
+
+Default listen addresses are controlled by environment variables. Use ``LIBP2P_BIND`` for IPv4 (default ``127.0.0.1``) and ``LIBP2P_BIND_V6`` for IPv6 (default ``::1``). Invalid values fall back to these secure defaults.
+
+**IPv4 (LIBP2P_BIND):**
+
+.. code-block:: bash
+
+    # Listen on all IPv4 interfaces (e.g. for tests)
+    export LIBP2P_BIND=0.0.0.0
+    python your_script.py
+
+**IPv6 (LIBP2P_BIND_V6):**
+
+.. code-block:: bash
+
+    # Use default IPv6 loopback (::1)
+    python your_script.py
+
+    # Listen on all IPv6 interfaces (e.g. for tests or dual-stack)
+    export LIBP2P_BIND_V6=::
+    python your_script.py
+
+    # Custom IPv6 address
+    export LIBP2P_BIND_V6=fd00::1
+    python your_script.py
+
+Multiaddr formats for IPv6 include ``/ip6/::1/tcp/PORT`` and ``/ip6/::1/tcp/PORT/ws`` for WebSocket.
+
 Resource Management
 ^^^^^^^^^^^^^^^^^^^
 

docs/release_notes.rst

@@ -391,7 +391,7 @@ Internal Changes - for py-libp2p Contributors
   - 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) (`#811 <https://github.com/libp2p/py-libp2p/issues/811>`__)
+  - Temporarily disable IPv6 support due to libp2p handshake issues (re-enabled later; use ``LIBP2P_BIND_V6`` to configure IPv6 bind address) (`#811 <https://github.com/libp2p/py-libp2p/issues/811>`__)
 - The TODO IK patterns in Noise has been deprecated in specs: https://github.com/libp2p/specs/tree/master/noise#handshake-pattern (`#816 <https://github.com/libp2p/py-libp2p/issues/816>`__)
 - Remove the already completed TODO tasks in Peerstore:
   TODO: Set up an async task for periodic peer-store cleanup for expired addresses and records.

libp2p/network/swarm.py

@@ -54,6 +54,9 @@
 from libp2p.transport.upgrader import (
     TransportUpgrader,
 )
+from libp2p.utils.multiaddr_utils import (
+    extract_ip_from_multiaddr,
+)
 
 from ..exceptions import (
     MultiError,
@@ -347,11 +350,7 @@ async def _dial_addr_single_attempt(self, addr: Multiaddr, peer_id: ID) -> INetC
         pre_scope = None
         if self._resource_manager is not None:
             try:
-                ep = None
-                try:
-                    ep = addr.value_for_protocol("ip4")
-                except Exception:
-                    ep = None
+                ep = extract_ip_from_multiaddr(addr)
                 pre_scope = self._resource_manager.open_connection(None, endpoint_ip=ep)
                 if pre_scope is None:
                     raise SwarmException("Connection denied by resource manager")

libp2p/tools/constants.py

@@ -25,7 +25,7 @@
 
 def _validate_ipv4_address(address: str) -> str:
     """
-    Validate that the given address is a valid IPv4 address.
+    Validate that a given address is a valid IPv4 address.
 
     Args:
         address: The IP address string to validate
@@ -35,12 +35,30 @@ def _validate_ipv4_address(address: str) -> str:
 
     """
     try:
-        # Validate that it's a valid IPv4 address
+        # Validate that the given address is a valid IPv4 address
         ipaddress.IPv4Address(address)
         return address
     except (ipaddress.AddressValueError, ValueError):
-        # If invalid, return the secure default
-        return "127.0.0.1"
+        return "127.0.0.1"  # If invalid, return to the secure default
+
+
+def _validate_ipv6_address(address: str) -> str:
+    """
+    Validate that a given address is a valid IPv6 address.
+
+    Args:
+        address: The IP address string to validate
+
+    Returns:
+        The validated IPv6 address, or "::1" if invalid
+
+    """
+    try:
+        # Validate that the given address is a valid IPv6 address
+        ipaddress.IPv6Address(address)
+        return address
+    except (ipaddress.AddressValueError, ValueError):
+        return "::1"  # If invalid, return to the secure default
 
 
 # Default bind address configuration with environment variable override
@@ -50,6 +68,13 @@ def _validate_ipv4_address(address: str) -> str:
 DEFAULT_BIND_ADDRESS = _validate_ipv4_address(os.getenv("LIBP2P_BIND", "127.0.0.1"))
 LISTEN_MADDR = multiaddr.Multiaddr(f"/ip4/{DEFAULT_BIND_ADDRESS}/tcp/0")
 
+# IPv6 default bind address configuration with environment variable override
+# DEFAULT_BIND_ADDRESS_V6 defaults to "::1" (secure) but can be overridden
+# via LIBP2P_BIND_V6 environment variable (e.g., "::" for tests)
+# Invalid IPv6 addresses will fallback to "::1"
+DEFAULT_BIND_ADDRESS_V6 = _validate_ipv6_address(os.getenv("LIBP2P_BIND_V6", "::1"))
+LISTEN_MADDR_V6 = multiaddr.Multiaddr(f"/ip6/{DEFAULT_BIND_ADDRESS_V6}/tcp/0")
+
 
 FLOODSUB_PROTOCOL_ID = floodsub.PROTOCOL_ID
 GOSSIPSUB_PROTOCOL_ID = gossipsub.PROTOCOL_ID

libp2p/transport/tcp/tcp.py

@@ -30,6 +30,10 @@
 from libp2p.transport.exceptions import (
     OpenConnectionError,
 )
+from libp2p.utils.multiaddr_utils import (
+    extract_ip_from_multiaddr,
+    multiaddr_from_socket,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -88,15 +92,15 @@ async def handler(stream: trio.SocketStream) -> None:
             )
             return False
 
-        ip4_host_str = maddr.value_for_protocol("ip4")
-        # For trio.serve_tcp, ip4_host_str (as host argument) can be None,
+        host_str = extract_ip_from_multiaddr(maddr)
+        # For trio.serve_tcp, host_str (as host argument) can be None,
         # which typically means listen on all available interfaces.
 
         started_listeners = await nursery.start(
             serve_tcp,
             handler,
             tcp_port,
-            ip4_host_str,
+            host_str,
         )
 
         if started_listeners is None:
@@ -138,7 +142,7 @@ async def dial(self, maddr: Multiaddr) -> IRawConnection:
         :return: `RawConnection` if successful
         :raise OpenConnectionError: raised when failed to open connection
         """
-        host_str = maddr.value_for_protocol("ip4")
+        host_str = extract_ip_from_multiaddr(maddr)
         port_str = maddr.value_for_protocol("tcp")
 
         if host_str is None:
@@ -194,5 +198,4 @@ def create_listener(self, handler_function: THandler) -> TCPListener:
 
 
 def _multiaddr_from_socket(socket: trio.socket.SocketType) -> Multiaddr:
-    ip, port = socket.getsockname()
-    return Multiaddr(f"/ip4/{ip}/tcp/{port}")
+    return multiaddr_from_socket(socket)

libp2p/utils/address_validation.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import ipaddress
 import socket
 
 from multiaddr import Multiaddr
@@ -23,13 +24,55 @@ def _safe_get_network_addrs(ip_version: int) -> list[str]:
         return []
 
 
-def find_free_port() -> int:
-    """Find a free port on localhost."""
-    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+def find_free_port(ip_version: int = 4) -> int:
+    """
+    Find a free port on localhost.
+
+    :param ip_version: IP version (4 for IPv4, 6 for IPv6)
+    :return: Available port number
+    """
+    family = socket.AF_INET6 if ip_version == 6 else socket.AF_INET
+    with socket.socket(family, socket.SOCK_STREAM) as s:
         s.bind(("", 0))  # Bind to a free port provided by the OS
         return s.getsockname()[1]
 
 
+def _validate_ipv4_address(address: str) -> str:
+    """
+    Validate that a given address is a valid IPv4 address.
+
+    Args:
+        address: The IP address string to validate
+
+    Returns:
+        The validated IPv4 address, or "127.0.0.1" if invalid
+
+    """
+    try:
+        ipaddress.IPv4Address(address)
+        return address
+    except (ipaddress.AddressValueError, ValueError):
+        return "127.0.0.1"
+
+
+def _validate_ipv6_address(address: str) -> str:
+    """
+    Validate that a given address is a valid IPv6 address.
+
+    Args:
+        address: The IP address string to validate
+
+    Returns:
+        The validated IPv6 address, or "::1" if invalid
+
+    """
+    try:
+        ipaddress.IPv6Address(address)
+        return address
+    except (ipaddress.AddressValueError, ValueError):
+        return "::1"
+
+
 def _safe_expand(addr: Multiaddr, port: int | None = None) -> list[Multiaddr]:
     """
     Internal safe expansion wrapper. Returns a list of Multiaddr objects.
@@ -64,23 +107,16 @@ def get_available_interfaces(port: int, protocol: str = "tcp") -> list[Multiaddr
     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):
-    #     if ip not in seen_v6:  # Avoid duplicates
-    #         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}"))
+    seen_v6: set[str] = set()
+    for ip in _safe_get_network_addrs(6):
+        if ip not in seen_v6:  # Avoid duplicates
+            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:
@@ -105,27 +141,34 @@ def expand_wildcard_address(
     return expanded
 
 
-def get_wildcard_address(port: int, protocol: str = "tcp") -> Multiaddr:
+def get_wildcard_address(
+    port: int, protocol: str = "tcp", ip_version: int = 4
+) -> Multiaddr:
     """
-    Get wildcard address (0.0.0.0) when explicitly needed.
+    Get wildcard address (0.0.0.0 or ::) when explicitly needed.
 
     This function provides access to wildcard binding as a feature when
     explicitly required, preserving the ability to bind to all interfaces.
 
     :param port: Port number.
     :param protocol: Transport protocol.
-    :return: A Multiaddr with wildcard binding (0.0.0.0).
+    :param ip_version: IP version (4 for 0.0.0.0, 6 for ::).
+    :return: A Multiaddr with wildcard binding (0.0.0.0 or ::).
     """
-    return Multiaddr(f"/ip4/0.0.0.0/{protocol}/{port}")
+    if ip_version == 6:
+        return Multiaddr(f"/ip6/::/{protocol}/{port}")
+    else:
+        return Multiaddr(f"/ip4/0.0.0.0/{protocol}/{port}")
 
 
 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
+    - Prefer non-loopback IPv6
+    - Then non-loopback IPv4
+    - Then loopback IPv6
+    - Then loopback IPv4
+    - Fallback to wildcard IPv4
 
     :param port: Port number.
     :param protocol: Transport protocol.
@@ -137,14 +180,17 @@ 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 "/ip6/" in str(c) and is_non_loopback(c):
+            return c
     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):
+        if "/ip6/::1" in str(c):
             return c
     for c in candidates:
-        if "/ip4/127." in str(c) or "/ip6/::1" in str(c):
+        if "/ip4/127." in str(c):
             return c
 
     # As a final fallback, produce a loopback address