Multiaddr

Multiaddr (short for "multi-address") is a self-describing, composable network address format that encodes multiple layers of network protocols into a single, future-proof string. Unlike traditional addresses like 192.168.1.1:8080, which imply TCP/IP, a Multiaddr explicitly declares its entire protocol stack—for example, /ip4/192.168.1.1/tcp/8080 for IPv4 over TCP, or /ip6/2001:db8::1/udp/4001/quic for IPv6 over QUIC. This explicit encoding ensures addresses remain unambiguous and interoperable across diverse and evolving network environments, a critical requirement for peer-to-peer systems like IPFS and libp2p.

The structure of a Multiaddr is built from a sequence of protocol codes and their corresponding values. Each component, like /ip4/ or /tcp/, is defined in a public table, allowing any system to parse the address step-by-step and understand exactly how to establish a connection. This composability allows for the seamless combination of transport protocols (e.g., TCP, QUIC, WebSockets), network layers (IPv4, IPv6), and application-level protocols (e.g., /p2p/ for peer IDs in libp2p). A key feature is the inclusion of cryptographic peer identities, as in /ip4/1.2.3.4/tcp/443/p2p/QmPeerID, which binds the network location to a specific node in a secure, verifiable way.

Multiaddr's primary use case is within the libp2p networking stack, where it serves as the fundamental addressing scheme for discovering and connecting to peers in a heterogeneous network. It solves the NAT traversal and multi-protocol support challenges inherent in decentralized systems by allowing a single peer to advertise multiple addresses (e.g., one for IPv4, one for IPv6, one for a WebSocket relay). Developers working with IPFS, Filecoin, or other libp2p-based projects will encounter Multiaddrs when configuring node listeners, parsing peer information from the DHT, or managing connection swarms. Its human-readable and machine-optimized binary representation make it a versatile tool for building resilient, protocol-agnostic network applications.

A Multiaddr (short for multi-address) is a convention for representing network addresses that combines multiple protocol layers—such as transport, network, and application protocols—into a single, human-readable string. Unlike traditional addresses like 192.168.1.1:80 or /dns4/example.com, a Multiaddr explicitly declares each protocol using predefined codes (e.g., /ip4, /tcp, /ws). This creates a composable and unambiguous address like /ip4/192.168.1.1/tcp/80 or /dns6/example.com/tcp/443/wss. The format's core innovation is its self-describing nature; any system can parse the address to understand exactly how to establish a connection without prior configuration or assumptions.

The structure follows a simple path-like syntax where each component is a protocol code and its value, separated by forward slashes. Common codes include /ip4 or /ip6 for the network layer, /tcp or /udp for transport, and /dns4 or /dns6 for domain resolution. For encrypted or overlay networks, protocols like /tls, /ws (WebSocket), or /p2p (for libp2p Peer IDs) can be appended. This allows a single Multiaddr to represent complex, multi-hop routes. For instance, /dns4/server.com/tcp/443/tls/ws/p2p/QmPeerID describes a connection to a specific peer over a secure WebSocket tunnel via a domain name.

Encoding and binary representation are critical to Multiaddr's efficiency in network communication. While the string format is human-readable, it is typically converted to a compact binary form for transmission. Each protocol code has a unique, registered number, and values are encoded according to their type (e.g., IPv4 addresses as 4 bytes, TCP ports as 2-byte integers). This binary representation, often prefixed with its length, allows for efficient parsing and is a foundational element for protocols within the libp2p stack, where it enables peer discovery and connection bootstrapping across heterogeneous networks.

The primary benefit of Multiaddr is network protocol agility and future-proofing. New transport protocols (e.g., QUIC, WebRTC) can be added by registering a new code without breaking existing address parsers. This is essential for decentralized systems like IPFS and libp2p that must operate across diverse environments—from browsers to data centers. It solves the network address translation (NAT) and firewall traversal problem by allowing peers to advertise multiple addresses (e.g., both a public IP and a relay address) in a standardized format, increasing the likelihood of a successful connection.

In practice, a node in a peer-to-peer network will typically have multiple Multiaddrs. A developer uses a library like go-multiaddr or js-multiaddr to construct, parse, and manipulate these addresses. When a peer discovers another, it receives a list of its Multiaddrs and attempts to dial each in turn until a connection is established. This multi-address approach is why libp2p peers can seamlessly connect over WebSockets in a browser, TCP on a local network, and QUIC on the public internet, all using the same core addressing scheme.

A Multiaddr (multi-address) is a future-proof, composable network address format designed for heterogeneous networks. It is a convention for encoding multiple layers of addressing into a single, human-readable and machine-optimized string. The core principle is that addresses are represented as a stack of protocol-code and value pairs, such as /ip4/192.168.1.1/tcp/443 or /dns6/example.com/tcp/80/ws. This structure allows applications to handle addresses agnostic of the underlying network layers, from IP addresses to overlay protocols like libp2p or Tor.

In practice, libraries like go-multiaddr (Go) or multiaddr (JavaScript) provide the tools to work with these addresses programmatically. A typical workflow involves parsing a string into a structured Multiaddr object, encapsulating or decapsulating protocol layers (e.g., adding a transport protocol), and extracting specific components like the IP or port. For instance, you can programmatically upgrade a base IP address to use WebSockets or QUIC by appending the appropriate protocol codes, enabling dynamic network stack configuration.

The following pseudocode illustrates common operations:

codeCopy
// Create a Multiaddr from a string
addr = Multiaddr('/ip4/127.0.0.1/tcp/8080')
// Decapsulate the TCP layer to get the IP layer
ipAddr = addr.decapsulate('tcp') // -> '/ip4/127.0.0.1'
// Encapsulate to add a WebSocket layer
wsAddr = addr.encapsulate('/ws') // -> '/ip4/127.0.0.1/tcp/8080/ws'
// Get the human-readable string representation
console.log(wsAddr.toString())

This composability is fundamental for peer-to-peer systems where connection paths may involve NAT traversal, relays, or encrypted channels, each represented as an additional protocol layer in the address.

Key use cases for Multiaddr in development include peer discovery in libp2p, where a peer's address may include multiple transport options, and network abstraction in decentralized applications. By using Multiaddr, developers write transport-agnostic code; the same connection logic can handle a direct TCP connection, a WebSocket connection through a browser, or a circuit relay connection via a p2p-circuit address. This eliminates the need for separate code paths for IPv4, IPv6, or DNS-based addresses.

When implementing, it's crucial to handle the binary serialization format for efficient network transmission, alongside the standard string format. The code must also validate addresses to ensure protocol codes are used in a valid order (e.g., an IP layer must come before a TCP layer). Libraries manage this validation, raising errors for malformed addresses. This rigorous structure prevents ambiguity and ensures interoperability across different implementations in the decentralized ecosystem.

The name Multiaddr is a contraction of "multi-address," which precisely describes its function: a single, future-proof address format capable of encoding multiple network protocols and addresses. It was created to solve a fundamental problem in peer-to-peer (P2P) systems like libp2p, where nodes need to communicate over diverse transports—such as TCP/IP, WebSockets, or QUIC—and may have multiple public endpoints (IPv4, IPv6, Tor). Before Multiaddr, managing these combinations required complex, ad-hoc serialization, making network code brittle and hard to compose.

The specification was formally developed within the libp2p project, a core component of the IPFS (InterPlanetary File System) ecosystem. Its creation was driven by the need for a self-describing network address that could be easily parsed by machines and understood by humans. The syntax, resembling a path-like structure (e.g., /ip4/192.168.1.1/tcp/443), was inspired by the composability of URLs and Unix filesystem paths, allowing protocols and their arguments to be chained together deterministically. This design enables systems to negotiate connections without prior configuration about supported transports.

The historical significance of Multiaddr lies in its role as a foundational abstraction layer for the decentralized web. By decoupling application logic from specific network layers, it facilitated the creation of transport-agnostic P2P applications. Its adoption beyond libp2p, in projects like Ethereum and various blockchain clients, underscores its utility as a universal networking primitive. The evolution of the standard continues, with ongoing proposals to support new protocols like QUIC and WebTransport, ensuring it remains the canonical way to represent network addresses in an increasingly multi-transport internet.