py-multiaddr ↔ go-multiaddr Feature Parity Analysis #1364

sumanjeet0012 · 2026-07-04T20:48:31Z

sumanjeet0012
Jul 4, 2026
Maintainer

py-multiaddr Feature Parity Analysis

Date: 2026-07-05
Python version analyzed: py-multiaddr v0.2.0
Go version analyzed: go-multiaddr v0.16.1
Source: py-multiaddr · go-multiaddr

Executive Summary
Architecture Comparison
Feature-by-Feature Gap Analysis
- 3.1 Core Multiaddr Type
- 3.2 Component Model
- 3.3 Protocol Registry
- 3.4 Encapsulate / Decapsulate
- 3.5 Split / Join Utilities
- 3.6 Serialization (JSON / Binary / Text)
- 3.7 Collection Utilities (Filter, Contains, Unique)
- 3.8 Network Layer (net / manet)
- 3.9 IP Classification Utilities
- 3.10 Address Filtering
- 3.11 DNS Resolution
- 3.12 Pattern Matching (x/meg)
- 3.13 CLI Tool
- 3.14 Protocol Coverage
- 3.15 Error Handling
- 3.16 Testing
Feature Matrix Summary
Phased Roadmap
Appendix A – Protocol Coverage Detail
Appendix B – Python-Exclusive Features

Executive Summary

The Go reference implementation (go-multiaddr) is significantly more complete than the Python implementation (py-multiaddr). While Python has a solid foundation for parsing, encoding, and basic manipulation of multiaddrs, Go provides an entire network stack (net/manet), IP classification utilities, address filtering, pattern matching, and a CLI tool — none of which exist in Python.

Area	Status
Core parsing (string ↔ bytes)	✅ Parity achieved
Protocol registry	✅ Parity achieved (Python has extras)
Encapsulate / Decapsulate	✅ Parity achieved
Split / Join	⚠️ Partial (missing `SplitFirst`, `SplitLast`, `SplitFunc`)
Component model	❌ Go has rich `Component` type; Python treats as flat bytes
`Compare()` / ordering	❌ Missing
JSON / Binary / Text marshaling	❌ Missing
`Cast()` / `StringCast()`	❌ Missing
Collection utilities (`FilterAddrs`, `Contains`, `Unique`)	❌ Missing
Network layer (Dial, Listen, Conn, Listener)	❌ Entirely absent
`net.Addr` ↔ Multiaddr conversion	❌ Entirely absent
IP classification (IsPublicAddr, IsPrivateAddr, IsIPLoopback, etc.)	❌ Mostly absent
Address filtering (`Filters`)	❌ Missing
DNS resolution	✅ Python has async DNS resolver (Go lacks this)
Pattern matching (regex for multiaddrs)	❌ Missing
CLI tool	❌ Missing
Protocol `plaintextv2`	❌ Missing
Thin waist utilities	⚠️ Partial (Python has `get_thin_waist_addresses`)

Architecture Comparison

Go Architecture (Rich, Network-Integrated)

go-multiaddr/
├── multiaddr.go          # Multiaddr type ([]Component), Encapsulate, Decapsulate, Equal, Compare
├── component.go          # Component type with Bytes, String, Value, RawValue, Protocol, Marshal*
├── protocol.go           # Protocol struct, AddProtocol, ProtocolWithName/Code
├── protocols.go          # All protocol constants + init() registration (38 protocols)
├── codec.go              # stringToBytes, readComponent, readMultiaddr
├── transcoders.go        # Transcoder interface + all transcoders (IP4, IP6, P2P, Onion, etc.)
├── filter.go             # Filters struct (Accept/Deny IP ranges)
├── util.go               # Split, Join, Cast, StringCast, SplitFirst/Last/Func, ForEach
├── varint.go             # Varint helpers
├── doc.go                # Package documentation
├── net/                  # Network integration layer (manet)
│   ├── net.go            # Dial, Listen, Conn, Listener, PacketConn, InterfaceMultiaddrs
│   ├── convert.go        # FromNetAddr, ToNetAddr, DialArgs, FromIP, ToIP, MultiaddrToIPNet
│   ├── ip.go             # IsThinWaist, IsIPLoopback, IsIP6LinkLocal, IsIPUnspecified, etc.
│   ├── private.go        # IsPublicAddr, IsPrivateAddr, Private4/6, Unroutable4/6
│   ├── resolve.go        # ResolveUnspecifiedAddress/Addresses
│   ├── registry.go       # CodecMap for extensible net.Addr conversion
│   └── doc.go
├── multiaddr/
│   └── main.go           # CLI tool: parse multiaddr, output JSON component info
├── x/meg/                # "Megular Expressions" — regex for multiaddrs
│   ├── meg.go            # NFA-based pattern matching engine
│   └── sugar.go          # Convenient pattern construction DSL
├── matest/               # Test helpers
│   └── matest.go
└── version.json          # v0.16.1

Python Architecture (Solid Core, No Network Layer)

py-multiaddr/
├── multiaddr/
│   ├── __init__.py          # Exports Multiaddr class
│   ├── multiaddr.py         # Multiaddr class (Mapping interface), encap/decap, split, resolve
│   ├── protocols.py         # Protocol class, ProtocolRegistry, 39 protocols, P_* constants
│   ├── transforms.py        # string_to_bytes, bytes_to_string, string_iter, bytes_iter
│   ├── exceptions.py        # Rich exception hierarchy
│   ├── utils.py             # get_thin_waist_addresses, get_network_addrs, get_multiaddr_options
│   ├── codecs/              # Individual codec implementations
│   │   ├── __init__.py      # CodecBase, codec_by_name, NoneCodec
│   │   ├── ip4.py, ip6.py, domain.py, uint16be.py, utf8.py
│   │   ├── onion.py, onion3.py, garlic32.py, garlic64.py
│   │   ├── cid.py, fspath.py, http_path.py, certhash.py
│   │   ├── ipcidr.py, memory.py
│   │   └── ...
│   └── resolvers/           # DNS resolution (async via Trio)
│       ├── __init__.py
│       ├── base.py          # Resolver protocol
│       ├── dns.py           # DNSResolver (/dns, /dns4, /dns6, /dnsaddr)
│       └── util.py
├── examples/                # Usage examples (12+ example files)
├── tests/                   # Test suite (5 test files)
└── pyproject.toml

Feature-by-Feature Gap Analysis

3.1 Core Multiaddr Type

Feature	Go	Python	Gap?
Construct from string	✅ `NewMultiaddr(s)`	✅ `Multiaddr(s)`	No
Construct from bytes	✅ `NewMultiaddrBytes(b)`	✅ `Multiaddr(b)`	No
Construct from Multiaddr	✅ (slice copy)	✅ `Multiaddr(other_ma)`	No
String representation	✅ `.String()`	✅ `str(ma)`	No
Byte representation	✅ `.Bytes()`	✅ `.to_bytes()` / `bytes(ma)`	No
Equality	✅ `.Equal(m2)`	✅ `ma1 == ma2`	No
Hashable	✅ (via bytes)	✅ `__hash__`	No
Ordering / Compare	✅ `.Compare(o) int`	❌	YES
Protocols list	✅ `.Protocols() []Protocol`	✅ `.protocols()` → `MultiAddrKeys`	No
Value for protocol	✅ `.ValueForProtocol(code)`	✅ `.value_for_protocol(proto)` / `ma[proto]`	No
Length (component count)	✅ `len(m)` (native slice)	✅ `len(ma)`	No
Iteration	✅ `for _, c := range m`	✅ `for proto in ma`	No
Mapping interface (keys/values/items)	❌	✅ `MultiAddrKeys`, `MultiAddrItems`, `MultiAddrValues`	No (Python extra)
Empty multiaddr	✅ Returns `nil` + error	✅ Allows empty `Multiaddr("")`	Design difference

3.2 Component Model

Feature	Go	Python	Gap?
`Component` type	✅ Dedicated struct	❌ No equivalent	YES
`Component.Bytes()`	✅	❌	YES
`Component.String()`	✅	❌	YES
`Component.Value()`	✅ (string)	❌	YES
`Component.RawValue()`	✅ (raw bytes)	❌	YES
`Component.Protocol()`	✅	❌	YES
`Component.Code()`	✅	❌	YES
`Component.Equal()` / `Compare()`	✅	❌	YES
`NewComponent(protocol, value)`	✅	❌	YES
Component MarshalJSON/Binary/Text	✅	❌	YES
Component Encapsulate/Decapsulate	✅	❌	YES

Key insight: Go's Multiaddr is []Component — a typed slice of individually accessible and manipulable components. Python's Multiaddr stores raw bytes and lazily parses them on each access. This is a fundamental architectural difference.

3.3 Protocol Registry

Feature	Go	Python	Gap?
`Protocol` struct	✅ (Name, Code, VCode, Size, Path, Transcoder)	✅ (code, name, codec)	No
`ProtocolWithName(s)`	✅	✅ `protocol_with_name(name)`	No
`ProtocolWithCode(c)`	✅	✅ `protocol_with_code(code)`	No
`ProtocolsWithString(s)`	✅	✅ `protocols_with_string(s)`	No
`AddProtocol(p)`	✅ (global)	✅ `registry.add(proto)`	No
Registry locking	❌ (always open)	✅ `registry.lock()`	No (Python extra)
Registry copy	❌	✅ `registry.copy(unlock=True)`	No (Python extra)
Alias names	⚠️ Hardcoded (`"ipfs"` → `"p2p"`)	✅ `add_alias_name()`	No (Python extra)
Alias codes	❌	✅ `add_alias_code()`	No (Python extra)
Protocol validation on add	✅ (Size/Transcoder consistency)	❌	YES (minor)

3.4 Encapsulate / Decapsulate

Feature	Go	Python	Gap?
`Encapsulate(other)`	✅	✅ `encapsulate(other)`	No
`Decapsulate(right)`	✅ (removes last match + everything after)	✅ `decapsulate(addr)` (string-based rindex)	⚠️ Different semantics
`DecapsulateCode(code)`	❌	✅ `decapsulate_code(code)`	No (Python extra)
Join multiple	✅ `Join(ms...)` variadic	✅ `Multiaddr.join(*addrs)`	No

Note: Go's Decapsulate does component-by-component comparison; Python uses string rindex. This can produce different results in edge cases (e.g., when the same protocol appears multiple times).

3.5 Split / Join Utilities

Feature	Go	Python	Gap?
`Split(m)` → components	✅ Returns `[]Component`	✅ `split(maxsplit)` returns `list[Multiaddr]`	No
`SplitFirst(m)` → (Component, Multiaddr)	✅	❌	YES
`SplitLast(m)` → (Multiaddr, Component)	✅	❌	YES
`SplitFunc(m, cb)` → (Multiaddr, Multiaddr)	✅	❌	YES
`ForEach(m, cb)`	✅	❌ (use `for` loop)	YES
`Cast(b)` (panic on error)	✅	❌	YES
`StringCast(s)` (panic on error)	✅	❌	YES

3.6 Serialization (JSON / Binary / Text)

Feature	Go	Python	Gap?
`MarshalJSON` / `UnmarshalJSON`	✅	❌	YES
`MarshalBinary` / `UnmarshalBinary`	✅	❌	YES
`MarshalText` / `UnmarshalText`	✅	❌	YES

Go's Multiaddr can be directly serialized/deserialized via encoding/json, encoding/binary, and encoding.TextMarshaler. Python has none of these interfaces.

3.7 Collection Utilities (Filter, Contains, Unique)

Feature	Go	Python	Gap?
`FilterAddrs(addrs, ...filters)`	✅	❌	YES
`Contains(addrs, addr)`	✅	❌	YES
`Unique(addrs)`	✅ (in-place dedup)	❌	YES

3.8 Network Layer (`net` / `manet`)

This is the largest gap between the two implementations. Go's net sub-package provides a complete network integration layer.

Feature	Go `manet`	Python	Gap?
`Dial(remote)` → `Conn`	✅	❌	YES
`DialContext(ctx, remote)` → `Conn`	✅	❌	YES
`Listen(laddr)` → `Listener`	✅	❌	YES
`ListenPacket(laddr)` → `PacketConn`	✅	❌	YES
`Conn` interface (LocalMultiaddr, RemoteMultiaddr)	✅	❌	YES
`Listener` interface (Accept, Close, Multiaddr)	✅	❌	YES
`PacketConn` interface	✅	❌	YES
`Dialer` struct	✅	❌	YES
`WrapNetConn(nconn)`	✅	❌	YES
`WrapNetListener(nl)`	✅	❌	YES
`WrapPacketConn(pc)`	✅	❌	YES
`NetListener(l)` → `net.Listener`	✅	❌	YES
`InterfaceMultiaddrs()`	✅	❌	YES
`AddrMatch(match, addrs)`	✅	❌	YES
`FromNetAddr(a)` → Multiaddr	✅	❌	YES
`ToNetAddr(ma)` → `net.Addr`	✅	❌	YES
`FromIP(ip)` → Multiaddr	✅	❌	YES
`ToIP(ma)` → `net.IP`	✅	❌	YES
`FromIPAndZone(ip, zone)`	✅	❌	YES
`DialArgs(ma)` → (network, address)	✅	❌	YES
*`MultiaddrToIPNet(ma)` → `net.IPNet`**	✅	❌	YES
`CodecMap` (extensible conversion registry)	✅	❌	YES
`RegisterFromNetAddr` / `RegisterToNetAddr`	✅	❌	YES

3.9 IP Classification Utilities

Feature	Go	Python	Gap?
`IsThinWaist(ma)`	✅	❌ (has `get_thin_waist_addresses`)	YES
`IsIPLoopback(ma)`	✅	❌	YES
`IsIP6LinkLocal(ma)`	✅	⚠️ `is_link_local_ip()` (string-based, in utils.py)	YES (not on Multiaddr)
`IsIPUnspecified(ma)`	✅	⚠️ `is_wildcard()` (string-based)	YES (not on Multiaddr)
`IsNAT64IPv4ConvertedIPv6Addr(ma)`	✅	❌	YES
`IsPublicAddr(ma)`	✅	❌	YES
`IsPrivateAddr(ma)`	✅	❌	YES
Well-known constants (`IP4Loopback`, `IP6Loopback`, `IP4Unspecified`, etc.)	✅	❌	YES
Private/Unroutable CIDR lists	✅ `Private4/6`, `Unroutable4/6`	❌	YES

3.10 Address Filtering

Feature	Go	Python	Gap?
`Filters` struct	✅	❌	YES
`NewFilters()`	✅	❌	YES
`AddFilter(ipnet, action)`	✅ (Accept/Deny)	❌	YES
`RemoveLiteral(ipnet)`	✅	❌	YES
`AddrBlocked(ma)`	✅	❌	YES
`ActionForFilter(ipnet)`	✅	❌	YES
`FiltersForAction(action)`	✅	❌	YES
`DefaultAction`	✅	❌	YES

3.11 DNS Resolution

Feature	Go	Python	Gap?
DNS resolver for `/dns`, `/dns4`, `/dns6`	❌ (external packages)	✅ `DNSResolver`	No (Python extra)
DNSADDR TXT record resolution	❌ (external packages)	✅ `DNSResolver._resolve_dnsaddr()`	No (Python extra)
Async resolution	❌	✅ (via Trio)	No (Python extra)
Recursive resolution with depth limit	❌	✅ `MAX_RECURSIVE_DEPTH = 32`	No (Python extra)
Peer ID preservation	❌	✅	No (Python extra)
Cancellation support	❌	✅ (Trio cancel scopes)	No (Python extra)
`ResolveUnspecifiedAddress` (expand wildcards)	✅	⚠️ `get_thin_waist_addresses()` (different approach)	Different

Key insight: Python is ahead of Go in DNS resolution. Go delegates this to external packages (e.g., go-libp2p's DNS resolver). Python has a full async DNS resolver built-in.

3.12 Pattern Matching (`x/meg`)

Feature	Go	Python	Gap?
"Megular Expressions" (regex for multiaddrs)	✅	❌	YES
Thompson NFA matching engine	✅	❌	YES
`Pattern`, `MatchState`, `Matchable` types	✅	❌	YES
Sugar DSL for pattern construction	✅	❌	YES
`Multiaddr.Match(patterns...)`	✅	❌	YES
Capture groups	✅	❌	YES

3.13 CLI Tool

Feature	Go	Python	Gap?
CLI binary	✅ `multiaddr`	❌	YES
Parse string multiaddr	✅	❌	YES
Parse hex bytes (`0x...`)	✅	❌	YES
JSON output with component details	✅ (string, packed, value, rawValue, protocol, codec, uvarint, lengthPrefix)	❌	YES

3.14 Protocol Coverage

Protocol	Code	Go	Python	Notes
ip4	0x04	✅	✅
tcp	0x06	✅	✅
udp	0x0111	✅	✅
dccp	0x21	✅	✅
ip6	0x29	✅	✅
ip6zone	0x2A	✅	✅
ipcidr	0x2B	✅	✅
dns	0x35	✅	✅
dns4	0x36	✅	✅
dns6	0x37	✅	✅
dnsaddr	0x38	✅	✅
sctp	0x84	✅	✅
udt	0x012D	✅	✅
utp	0x012E	✅	✅
p2p-circuit	0x0122	✅	✅
p2p-webrtc-star	0x0113	✅	✅
p2p-webrtc-direct	0x0114	✅	✅
p2p	0x01A5	✅	✅
onion	0x01BC	✅	✅
onion3	0x01BD	✅	✅
garlic64	0x01BE	✅	✅
garlic32	0x01BF	✅	✅
quic	0x01CC	✅	✅
quic-v1	0x01CD	✅	✅
webtransport	0x01D1	✅	✅
certhash	0x01D2	✅	✅
http	0x01E0	✅	✅
http-path	0x01E1	✅	✅
https	0x01BB	✅	✅
tls	0x01C0	✅	✅
sni	0x01C1	✅	✅
noise	0x01C6	✅	✅
ws	0x01DD	✅	✅
wss	0x01DE	✅	✅
unix	0x0190	✅	✅
webrtc-direct	0x0118	✅	✅
webrtc	0x0119	✅	✅
memory	0x0309	✅	✅
plaintextv2	0x706C61	✅	❌	Python missing
p2p-websocket-star	0x01DF	✅	✅

3.15 Error Handling

Go Error	Python Equivalent	Gap?
`fmt.Errorf("failed to parse multiaddr...")`	`StringParseError`	No
`fmt.Errorf("no protocol with code...")`	`BinaryParseError`	No
`ErrProtocolNotFound`	`ProtocolLookupError`	No
`fmt.Errorf("protocol by the name...already exists")`	`ProtocolExistsError`	No
—	`ProtocolRegistryLocked`	Python extra
—	`ProtocolNotFoundError`	Python extra
—	`ResolutionError` / `RecursionLimitError`	Python extra
—	`MultiaddrError` (base)	Python extra

Python has a richer exception hierarchy.

3.16 Testing

Feature	Go	Python	Gap?
Core encode/decode tests	✅	✅	No
Protocol registry tests	✅	✅	No
Component tests	✅	N/A (no Component type)	N/A
Filter tests	✅	N/A	N/A
Net convert tests	✅	N/A	N/A
Net private IP tests	✅	N/A	N/A
Net resolve tests	✅	N/A	N/A
Net registry tests	✅	N/A	N/A
MEG pattern tests	✅	N/A	N/A
Benchmark tests	✅	❌	YES
DNS resolver tests	N/A (external)	✅	No (Python extra)
Thin waist tests	N/A (external)	✅	No (Python extra)
Transform tests	N/A	✅	No (Python extra)

Feature Matrix Summary

#	Feature	Priority	Status
1	`Component` type (individual address part)	High	❌ Missing
2	`NewComponent(protocol, value)`	High	❌ Missing
3	`Multiaddr.Compare()` (ordering)	Medium	❌ Missing
4	`MarshalJSON` / `UnmarshalJSON`	High	❌ Missing
5	`MarshalBinary` / `UnmarshalBinary`	Medium	❌ Missing
6	`MarshalText` / `UnmarshalText`	Medium	❌ Missing
7	`Cast(b)` / `StringCast(s)` (panic-on-error)	Low	❌ Missing
8	`SplitFirst(m)` / `SplitLast(m)` / `SplitFunc(m, cb)`	Medium	❌ Missing
9	`ForEach(m, cb)`	Low	❌ Missing
10	`FilterAddrs(addrs, ...filters)`	Medium	❌ Missing
11	`Contains(addrs, addr)`	Low	❌ Missing
12	`Unique(addrs)` (deduplicate)	Low	❌ Missing
13	Network: `Dial`, `Listen`, `Conn`, `Listener`	High	❌ Entirely absent
14	Network: `FromNetAddr` / `ToNetAddr`	High	❌ Entirely absent
15	Network: `FromIP` / `ToIP`	High	❌ Missing
16	Network: `DialArgs(ma)`	High	❌ Missing
17	Network: `InterfaceMultiaddrs()`	Medium	❌ Missing
18	Network: `CodecMap` (extensible registry)	Medium	❌ Missing
19	IP: `IsThinWaist(ma)`	Medium	❌ Missing
20	IP: `IsIPLoopback(ma)`	Medium	❌ Missing
21	IP: `IsIPUnspecified(ma)`	Medium	❌ Missing
22	IP: `IsPublicAddr(ma)` / `IsPrivateAddr(ma)`	High	❌ Missing
23	IP: `IsIP6LinkLocal(ma)`	Medium	❌ Missing
24	IP: `IsNAT64IPv4ConvertedIPv6Addr(ma)`	Low	❌ Missing
25	IP: Well-known constants (`IP4Loopback`, etc.)	Medium	❌ Missing
26	IP: Private/Unroutable CIDR lists	Medium	❌ Missing
27	`Filters` (Accept/Deny IP ranges)	Medium	❌ Missing
28	Pattern matching (`x/meg` regex for multiaddrs)	Low	❌ Missing
29	CLI tool	Low	❌ Missing
30	Protocol `plaintextv2`	Low	❌ Missing
31	`MultiaddrToIPNet(ma)`	Medium	❌ Missing
32	`ResolveUnspecifiedAddress(es)`	Medium	⚠️ Different approach

Phased Roadmap

Phase 1 – Core API Gaps & Serialization

Goal: Add the most impactful missing core APIs and serialization support.

Estimated effort: 2–3 weeks

1.1 Add `Component` class

Create a Component type that represents a single protocol + value pair:

class Component:
    """A single multiaddr component (protocol + value)."""
    __slots__ = ("_bytes", "_protocol", "_value_start")
    
    def __init__(self, protocol: str, value: str = ""): ...
    
    @property
    def protocol(self) -> Protocol: ...
    @property
    def code(self) -> int: ...
    @property
    def value(self) -> str: ...
    @property
    def raw_value(self) -> bytes: ...
    
    def to_bytes(self) -> bytes: ...
    def __str__(self) -> str: ...
    def __eq__(self, other) -> bool: ...
    def __hash__(self) -> int: ...

1.2 Refactor `Multiaddr` as `list[Component]`

Optionally, refactor the internal representation from bytes to list[Component] (matching Go's []Component). This would enable efficient component-level access. Alternatively, add lazy component parsing.

1.3 Add `Compare()` method

def compare(self, other: "Multiaddr") -> int:
    """Compare two multiaddrs for ordering. Returns -1, 0, or 1."""

1.4 Add JSON/Binary/Text serialization

import json

class Multiaddr:
    def to_json(self) -> str:
        return json.dumps(str(self))
    
    @classmethod
    def from_json(cls, data: str) -> "Multiaddr":
        return cls(json.loads(data))

1.5 Add `SplitFirst`, `SplitLast`, `SplitFunc`

def split_first(self) -> tuple[Component | None, "Multiaddr | None"]: ...
def split_last(self) -> tuple["Multiaddr | None", Component | None]: ...
def split_func(self, cb: Callable[[Component], bool]) -> tuple["Multiaddr", "Multiaddr"]: ...

1.6 Add `Cast()` and `StringCast()`

@classmethod
def cast(cls, b: bytes) -> "Multiaddr":
    """Parse bytes, raising ValueError on failure (like Go's Cast)."""
    return cls(b)  # Already raises on invalid

@classmethod
def string_cast(cls, s: str) -> "Multiaddr":
    """Parse string, raising ValueError on failure."""
    return cls(s)

1.7 Add `plaintextv2` protocol

P_PLAINTEXTV2 = 0x706C61
# In PROTOCOLS list:
Protocol(P_PLAINTEXTV2, "plaintextv2", None),

Phase 2 – Network Layer (`manet` equivalent)

Goal: Create a multiaddr.net sub-package providing Python equivalents of Go's manet.

Estimated effort: 3–4 weeks

2.1 Create `multiaddr/net/init.py`

# multiaddr/net/
├── __init__.py       # Public API
├── convert.py        # from_net_addr, to_net_addr, dial_args, from_ip, to_ip
├── ip.py             # is_thin_waist, is_ip_loopback, is_ip_unspecified, etc.
├── private.py        # is_public_addr, is_private_addr, PRIVATE4/6, UNROUTABLE4/6
├── resolve.py        # resolve_unspecified_address(es)
└── registry.py       # CodecMap for extensible conversions

2.2 Implement `dial_args(ma) → (network, address)`

def dial_args(ma: Multiaddr) -> tuple[str, str]:
    """Convert a multiaddr to (network, address) suitable for socket.connect().
    
    >>> dial_args(Multiaddr("/ip4/1.2.3.4/tcp/80"))
    ('tcp4', '1.2.3.4:80')
    """

2.3 Implement `from_ip(ip) → Multiaddr` and `to_ip(ma) → ipaddress.IPv4Address | IPv6Address`

Using Python's ipaddress stdlib module.

2.4 Implement `from_net_addr(addr) → Multiaddr` and `to_net_addr(ma) → socket address`

2.5 Implement IP classification functions

def is_thin_waist(ma: Multiaddr) -> bool: ...
def is_ip_loopback(ma: Multiaddr) -> bool: ...
def is_ip_unspecified(ma: Multiaddr) -> bool: ...
def is_ip6_link_local(ma: Multiaddr) -> bool: ...
def is_public_addr(ma: Multiaddr) -> bool: ...
def is_private_addr(ma: Multiaddr) -> bool: ...
def is_nat64_ipv4_converted_ipv6_addr(ma: Multiaddr) -> bool: ...

2.6 Implement well-known constants

IP4_LOOPBACK = Multiaddr("/ip4/127.0.0.1")
IP6_LOOPBACK = Multiaddr("/ip6/::1")
IP4_UNSPECIFIED = Multiaddr("/ip4/0.0.0.0")
IP6_UNSPECIFIED = Multiaddr("/ip6/::")

PRIVATE4 = [...]   # ipaddress.IPv4Network list
PRIVATE6 = [...]   # ipaddress.IPv6Network list
UNROUTABLE4 = [...]
UNROUTABLE6 = [...]

2.7 Implement `interface_multiaddrs() → list[Multiaddr]`

Using psutil (already a dependency) or socket.if_nameindex().

2.8 Implement Dial/Listen wrappers (optional, lower priority)

async def dial(remote: Multiaddr) -> "MultiaddrConn": ...
async def listen(laddr: Multiaddr) -> "MultiaddrListener": ...

Using Python's asyncio or trio for async networking.

Phase 3 – IP Classification & Filtering

Goal: Add address filtering (Accept/Deny) and enhance IP classification.

Estimated effort: 1–2 weeks

3.1 Implement `Filters` class

class Action(Enum):
    ACCEPT = 1
    DENY = 2

class Filters:
    def __init__(self, default_action: Action = Action.ACCEPT): ...
    def add_filter(self, ipnet: ipaddress.IPv4Network | IPv6Network, action: Action): ...
    def remove_literal(self, ipnet) -> bool: ...
    def addr_blocked(self, ma: Multiaddr) -> bool: ...
    def action_for_filter(self, ipnet) -> Action | None: ...
    def filters_for_action(self, action: Action) -> list: ...

3.2 Add collection utilities

def filter_addrs(addrs: list[Multiaddr], *filters: Callable[[Multiaddr], bool]) -> list[Multiaddr]: ...
def contains(addrs: list[Multiaddr], addr: Multiaddr) -> bool: ...
def unique(addrs: list[Multiaddr]) -> list[Multiaddr]: ...

3.3 Add `multiaddr_to_ipnet(ma)`

def multiaddr_to_ipnet(ma: Multiaddr) -> ipaddress.IPv4Network | IPv6Network | None: ...

3.4 Add `resolve_unspecified_addresses()`

def resolve_unspecified_addresses(
    unspec_addrs: list[Multiaddr],
    iface_addrs: list[Multiaddr] | None = None,
) -> list[Multiaddr]: ...

Phase 4 – Pattern Matching, CLI & Polish

Goal: Add advanced features and tooling.

Estimated effort: 2–3 weeks

4.1 Implement pattern matching (`meg` equivalent)

Create a multiaddr.patterns module with regex-like matching for multiaddr components:

from multiaddr.patterns import Pattern, match

# Match any /ip4/*/tcp/* address
pattern = Pattern.ip4.any().tcp.any()
result = match(pattern, Multiaddr("/ip4/1.2.3.4/tcp/80"))

This is lower priority since it's in Go's experimental x/meg package.

4.2 Implement CLI tool

# multiaddr/cli.py
def main():
    """Parse a multiaddr and output component details as JSON."""
    parser = argparse.ArgumentParser(description="Parse and inspect multiaddrs")
    parser.add_argument("addr", help="Multiaddr string or hex bytes (0x...)")
    args = parser.parse_args()
    ...

Register as console script:

[project.scripts]
multiaddr = "multiaddr.cli:main"

4.3 Add `ForEach` utility

def for_each(ma: Multiaddr, cb: Callable[[Component], bool]) -> None:
    """Walk over components. Return False from cb to stop."""

4.4 Add `addr_match(match, addrs)`

def addr_match(match: Multiaddr, addrs: list[Multiaddr]) -> list[Multiaddr]:
    """Return addrs that have the same protocol stack as match."""

4.5 Add benchmark suite

Using pytest-benchmark:

@pytest.mark.benchmark
def test_bench_parse_string(benchmark): ...

@pytest.mark.benchmark
def test_bench_parse_bytes(benchmark): ...

@pytest.mark.benchmark
def test_bench_to_string(benchmark): ...

Appendix A – Protocol Coverage Detail

Both implementations support 38 protocols. The only difference:

Protocol	Go	Python
`plaintextv2` (0x706C61)	✅	❌

Python has an additional P_P2P_WEBSOCKET_STAR constant defined but Go also supports it via p2p-websocket-star.

Both implementations support the ipfs → p2p alias.

Appendix B – Python-Exclusive Features

These features exist in Python but not in Go:

Feature	Description
Mapping interface	`Multiaddr` implements `collections.abc.Mapping` with `.keys()`, `.values()`, `.items()`
`ProtocolRegistry` with locking	`lock()`, `copy(unlock=True)`, `add_alias_name()`, `add_alias_code()`
DNS Resolver	Full async DNS resolution for `/dns`, `/dns4`, `/dns6`, `/dnsaddr` with recursive resolution, peer ID preservation, and cancellation
`decapsulate_code(code)`	Remove last occurrence of protocol by code
`get_peer_id()`	Extract peer ID from multiaddr (handles circuit relay)
`resolve()` async method	Built-in DNS resolution
`get_thin_waist_addresses()`	Expand wildcard addresses using `psutil`
`get_multiaddr_options()`	Extract family/host/transport/port dict
Rich exception hierarchy	`StringParseError`, `BinaryParseError`, `ProtocolLookupError`, `ProtocolExistsError`, `ProtocolRegistryLocked`, `ResolutionError`, `RecursionLimitError`
`split(maxsplit)` parameter	Configurable max splits
12+ example files	Comprehensive usage examples

Summary Timeline

Phase	Focus	Effort	Key Deliverables
Phase 1	Core API & Serialization	2–3 weeks	`Component` type, `Compare()`, JSON marshaling, `SplitFirst`/`SplitLast`/`SplitFunc`, `plaintextv2`
Phase 2	Network Layer	3–4 weeks	`multiaddr.net` package: `dial_args`, `from_ip`/`to_ip`, `from_net_addr`/`to_net_addr`, IP classification, `interface_multiaddrs()`
Phase 3	Filtering & Collections	1–2 weeks	`Filters` class, `filter_addrs`, `contains`, `unique`, `multiaddr_to_ipnet`, private/public CIDR lists
Phase 4	Pattern Matching, CLI & Polish	2–3 weeks	`multiaddr.patterns`, CLI tool, `ForEach`, `addr_match`, benchmarks

Total estimated effort: 8–12 weeks

The highest-impact gap is the network layer (Phase 2) — Go's manet package is used extensively throughout the libp2p ecosystem for Dial/Listen operations and IP classification. The Component type (Phase 1) is the second priority since it enables efficient component-level manipulation that Go users take for granted.

Python's DNS resolver and async resolution are genuine advantages that should be preserved and documented as differentiators.

Navigation Menu

Repository navigation

py-multiaddr ↔ go-multiaddr Feature Parity Analysis #1364

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

py-multiaddr ↔ go-multiaddr Feature Parity Analysis #1364

Uh oh!

sumanjeet0012 Jul 4, 2026 Maintainer

py-multiaddr Feature Parity Analysis

Table of Contents

Executive Summary

Architecture Comparison

Go Architecture (Rich, Network-Integrated)

Python Architecture (Solid Core, No Network Layer)

Feature-by-Feature Gap Analysis

3.1 Core Multiaddr Type

3.2 Component Model

3.3 Protocol Registry

3.4 Encapsulate / Decapsulate

3.5 Split / Join Utilities

3.6 Serialization (JSON / Binary / Text)

3.7 Collection Utilities (Filter, Contains, Unique)

3.8 Network Layer (net / manet)

3.9 IP Classification Utilities

3.10 Address Filtering

3.11 DNS Resolution

3.12 Pattern Matching (x/meg)

3.13 CLI Tool

3.14 Protocol Coverage

3.15 Error Handling

3.16 Testing

Feature Matrix Summary

Phased Roadmap

Phase 1 – Core API Gaps & Serialization

1.1 Add Component class

1.2 Refactor Multiaddr as list[Component]

1.3 Add Compare() method

1.4 Add JSON/Binary/Text serialization

1.5 Add SplitFirst, SplitLast, SplitFunc

1.6 Add Cast() and StringCast()

1.7 Add plaintextv2 protocol

Phase 2 – Network Layer (manet equivalent)

2.1 Create multiaddr/net/__init__.py

2.2 Implement dial_args(ma) → (network, address)

2.3 Implement from_ip(ip) → Multiaddr and to_ip(ma) → ipaddress.IPv4Address | IPv6Address

2.4 Implement from_net_addr(addr) → Multiaddr and to_net_addr(ma) → socket address

2.5 Implement IP classification functions

2.6 Implement well-known constants

2.7 Implement interface_multiaddrs() → list[Multiaddr]

2.8 Implement Dial/Listen wrappers (optional, lower priority)

Phase 3 – IP Classification & Filtering

3.1 Implement Filters class

3.2 Add collection utilities

3.3 Add multiaddr_to_ipnet(ma)

3.4 Add resolve_unspecified_addresses()

Phase 4 – Pattern Matching, CLI & Polish

4.1 Implement pattern matching (meg equivalent)

4.2 Implement CLI tool

4.3 Add ForEach utility

4.4 Add addr_match(match, addrs)

4.5 Add benchmark suite

Appendix A – Protocol Coverage Detail

Appendix B – Python-Exclusive Features

Summary Timeline

Replies: 0 comments

sumanjeet0012
Jul 4, 2026
Maintainer

3.8 Network Layer (`net` / `manet`)

3.12 Pattern Matching (`x/meg`)

1.1 Add `Component` class

1.2 Refactor `Multiaddr` as `list[Component]`

1.3 Add `Compare()` method

1.5 Add `SplitFirst`, `SplitLast`, `SplitFunc`

1.6 Add `Cast()` and `StringCast()`

1.7 Add `plaintextv2` protocol

Phase 2 – Network Layer (`manet` equivalent)

2.1 Create `multiaddr/net/init.py`

2.2 Implement `dial_args(ma) → (network, address)`

2.3 Implement `from_ip(ip) → Multiaddr` and `to_ip(ma) → ipaddress.IPv4Address | IPv6Address`

2.4 Implement `from_net_addr(addr) → Multiaddr` and `to_net_addr(ma) → socket address`

2.7 Implement `interface_multiaddrs() → list[Multiaddr]`

3.1 Implement `Filters` class

3.3 Add `multiaddr_to_ipnet(ma)`

3.4 Add `resolve_unspecified_addresses()`

4.1 Implement pattern matching (`meg` equivalent)

4.3 Add `ForEach` utility

4.4 Add `addr_match(match, addrs)`