Multiformats / Multiaddr

⚠️️ (Note: this page is a work in progress; please improve it here) ⚠️️

Self-describing network addresses

Multiaddr is a format for encoding addresses from various well-established network protocols. It is useful to write applications that future-proof their use of addresses, and allow multiple transport protocols and addresses to coexist.

Network Protocol Ossification

The current network addressing scheme in the internet IS NOT self-describing. Addresses of the following forms leave much to interpretation and side-band context. The assumptions they make cause applications to also make those assumptions, which causes lots of “this type of address”-specific code. The network addresses and their protocols rust into place, and cannot be displaced by future protocols because the addressing prevents change.

For example, consider:

127.0.0.1:9090   # ip4. is this TCP? or UDP? or something else?
[::1]:3217       # ip6. is this TCP? or UDP? or something else?

http://127.0.0.1/baz.jpg
http://foo.com/bar/baz.jpg
//foo.com:1234
 # use DNS, to resolve to either ip4 or ip6, but definitely use
 # tcp after. or maybe quic... >.<
 # these default to TCP port :80.

Instead, when addresses are fully qualified, we can build applications that will work with network protocols of the future, and do not accidentally ossify the stack.

/ip4/127.0.0.1/udp/9090/quic
/ip6/::1/tcp/3217
/ip4/127.0.0.1/tcp/80/http/baz.jpg
/dns4/foo.com/tcp/80/http/bar/baz.jpg
/dns6/foo.com/tcp/443/https

Multiaddr Format

A multiaddr value is a recursive (TLV)+ (type-length-value repeating) encoding. It has two forms:

The human-readable version:

Human-readable encoding (psuedo regex)

(/<addr-protocol-str-code>/<addr-value>)+
protocol code as a string
the address itself (human readable)
the pattern repeats, protocols encapsulate other protocols

The binary-packed version:

Binary-packed encoding (psuedo regex)

(<addr-protocol-code><addr-value>)+
protocol code as a varint
the address value itself (binary)
the pattern repeats, protocols encapsulate other protocols

For Example

(TODO)

Implementations

These implementations are available:

Examples

TODO

F.A.Q.

TODO

About

Specification

We will be submitting an RFC to the IETF. It will be worked on at the multiaddr repo.

Credits

The Multiaddr format was invented by @jbenet, and refined by the IPFS Team. It is now maintained by the Multiformats community. The Multiaddr implementations are written by a variety of authors, whose hard work has made future-proofing and upgrading hash functions much easier. Thank you!

Open Source

The Multiaddr format (this documentation and the specification) is Open Source software, licensed under the MIT License and patent-free. The multiaddr implementations listed here are also Open Source software. Please contribute to make them great! Your bug reports, new features, and documentation improvements will benefit everyone.

Part of the Multiformats Project

Multiaddr is part of the Multiformats Project, a collection of protocols which aim to future-proof systems, today. Check out the other multiformats. It is also maintained and sponsored by Protocol Labs.

Multiformats