ipv6 error: MultiAddr '/ip6/::1/tcp/0' does not contain protocol ip4

[TimSC]

Summary

When I try to create peers that communicate over ipv6 I get an error using libp2p 0.5.0:

    |   File "/home/tim/dev/p2ptest/env/lib/python3.12/site-packages/libp2p/transport/tcp/tcp.py", line 91, in listen
    |     ip4_host_str = maddr.value_for_protocol("ip4")
    |                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |   File "/home/tim/dev/p2ptest/env/lib/python3.12/site-packages/multiaddr/multiaddr.py", line 293, in value_for_protocol
    |     raise exceptions.ProtocolLookupError(proto, str(self))
    | multiaddr.exceptions.ProtocolLookupError: MultiAddr '/ip6/::1/tcp/0' does not contain protocol Protocol(code=4, name='ip4', codec='ip4')

My minimal example:

import argparse

import trio
import multiaddr

from libp2p import (
    InsecureTransport,
    PLAINTEXT_PROTOCOL_ID,
    TProtocol,
    create_new_ed25519_key_pair,
    new_host,
)
from libp2p.peer.peerinfo import info_from_p2p_addr
from libp2p.peer.peerstore import PeerStore
from libp2p.tools.async_service import background_trio_service


def make_plaintext_host(listen_addrs=None):
    key_pair = create_new_ed25519_key_pair()
    peerstore = PeerStore()
    sec_opt = {
        TProtocol(PLAINTEXT_PROTOCOL_ID): InsecureTransport(
            key_pair, peerstore=peerstore
        )
    }
    return new_host(
        key_pair=key_pair,
        sec_opt=sec_opt,
        peerstore_opt=peerstore,
        listen_addrs=listen_addrs,
    )


async def main(use_ipv4: bool):
    if use_ipv4:
        listen_addr = multiaddr.Multiaddr("/ip4/127.0.0.1/tcp/0")
    else:
        listen_addr = multiaddr.Multiaddr("/ip6/::1/tcp/0")

    server = make_plaintext_host([listen_addr])
    client = make_plaintext_host()

    async with server.run([listen_addr]):
        async with background_trio_service(client.get_network()):
            await trio.sleep(0.1)
            server_addrs = server.get_addrs()
            print("server addrs:", server_addrs)

            target = info_from_p2p_addr(server_addrs[0])
            await client.connect(target)
            print("connected to server over plaintext")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="Minimal libp2p plaintext repro using IPv6 or IPv4."
    )
    parser.add_argument(
        "--ipv4",
        action="store_true",
        help="Use IPv4 (default is IPv6).",
    )
    args = parser.parse_args()

    trio.run(main, args.ipv4)

If I patch around this problem, I hit another error:

failed to upgrade security for peer 12D3KooWAUtLVoYPSPdTjxYpANDeD3MKzECeQvWfhCLP12WqEkvA: failed to negotiate the secure protocol

Expected behavior

To run without errors

Actual behavior

Errors logs are above

Relevant log output

Errors are above

Possible Solution

None yet

Environment

Python version:
3.12.3 (main, Nov  6 2025, 13:44:16) [GCC 13.3.0]

Operating System: Linux-6.14.0-37-generic-x86_64-with-glibc2.39

python -m pip freeze result:
aioquic==1.3.0
annotated-types==0.7.0
async-generator==1.10
attrs==25.4.0
base58==2.1.1
blake3==1.0.8
certifi==2025.11.12
cffi==2.0.0
coincurve==21.0.0
cryptography==46.0.3
cytoolz==1.1.0
dnspython==2.8.0
eth-hash==0.7.1
eth-typing==5.2.1
eth-utils==5.3.1
fastecdsa==2.3.2
grpcio==1.76.0
h11==0.16.0
idna==3.11
ifaddr==0.2.0
importlib_metadata==8.7.1
libp2p==0.5.0
lru-dict==1.4.1
miniupnpc==2.3.3
mmh3==5.2.0
morphys==1.0
multiaddr==0.0.11
mypy-protobuf==4.0.0
mypy_extensions==1.1.0
netaddr==1.3.0
noiseprotocol==0.3.1
outcome==1.3.0.post0
packaging==25.0
protobuf==6.33.2
psutil==7.2.0
py-cid==0.4.0
py-multibase==2.0.0
py-multicodec==1.0.0
py-multihash==3.0.0
pyasn1==0.6.1
pyasn1_modules==0.4.2
pycparser==2.23
pycryptodome==3.23.0
pydantic==2.12.5
pydantic_core==2.41.5
pylsqpack==0.3.23
PyNaCl==1.6.1
pyOpenSSL==25.3.0
python-baseconv==1.2.2
rpcudp==5.0.1
service-identity==24.2.0
six==1.17.0
sniffio==1.3.1
sortedcontainers==2.4.0
toolz==1.1.0
trio==0.32.0
trio-typing==0.10.0
trio-websocket==0.12.2
types-protobuf==6.32.1.20251210
typing-inspection==0.4.2
typing_extensions==4.15.0
u-msgpack-python==2.8.0
varint==1.0.2
wsproto==1.3.2
zeroconf==0.147.3
zipp==3.23.0

Would you like to work on fixing this bug ?

Yes

[seetadev]

Hi Tim — thank you very much for the detailed report and for the excellent minimal repro. This is a really helpful issue, and we appreciate the time you took to write it up so clearly.

You’re absolutely right: the current TCP transport path is implicitly assuming an ip4 multiaddr and fails when presented with a pure IPv6 address like /ip6/::1/tcp/0. That’s a real bug, and your traceback pinpoints the problem area very clearly. The follow-up error you’re seeing after patching around it (during security protocol negotiation) is also valuable signal and suggests there may be more than one IPv6-related assumption in the stack.

We’re definitely interested in fixing this, and yes — we’d be happy to work on it.

CCing py-libp2p contributors, who will collaborate with you and help resolve the issue: @acul71 , @sumanjeet0012 , @yashksaini-coder and @Winter-Soren

A few initial notes on next steps, just to keep things transparent:

• The immediate issue in tcp.listen() should be addressed by correctly handling ip6 multiaddrs (instead of unconditionally calling value_for_protocol("ip4")).
• We’ll also need to validate the downstream behavior around peer address selection and security negotiation to make sure IPv6 paths are exercised correctly end-to-end.
• Your repro is perfect for adding a regression test once we have a fix in place.

If you’re interested in contributing directly, we’d be very happy to collaborate — even a draft PR or exploratory patch would be more than welcome, and we can help iterate on it together. Otherwise, we’ll take this up and keep you posted with progress and findings.

Thanks again for reporting this and for confirming your interest in working on the fix. This kind of issue report genuinely helps improve py-libp2p for everyone.

Looking forward to collaborating on this 👍

[acul71]

Hello @TimSC, thanks for submitting this issue and willing to work to fix this bug.
I've opened a new discussion page so to make conversation there and keep messages in this PR shorter for easy review.
tag me if you need feedback.
Ciao Luca

IPv6 Support Implementation Plan

Summary of work needed to fix IPv6 support in py-libp2p (Issue #1111):

Critical fixes:

1. TCP Transport (libp2p/transport/tcp/tcp.py) — Replace hardcoded IPv4 lookups with IPv4/IPv6 helper function
2. Swarm Resource Manager (libp2p/network/swarm.py) — Fix endpoint tracking to support IPv6

Medium priority:
3. Re-enable IPv6 in address validation utilities
4. Standardize WebSocket transport IPv6 handling

Implementation approach:

• Create shared helper functions for IP extraction (QUIC transport already implements this pattern)
• Follow QUIC transport as reference implementation
• Maintain backward compatibility with IPv4

Full analysis and implementation details:
👉 GitHub Discussion #1113

The discussion includes file-by-file analysis, code examples, test requirements, and a phased implementation strategy.

[TimSC]

Thanks for taking a look at this. I'll try to help out but this looks like it needs a decent amount of work!