⚠️️ (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.
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
A multiaddr value is a recursive (TLV)+
(type-length-value repeating) encoding. It has two forms:
/ip4/127.0.0.1/udp/4023/quic
(this is the repeating part).
/
) (eg. /quic
and /ip4/127.0.0.1
)<addr-protocol-str-code>
is a string code identifying the network protocol. The table of protocols is configurable. The default table is the multicodec table.<addr-value>
is the network address value, in natural string form.Human-readable encoding (psuedo regex)
(/<addr-protocol-str-code>
/<addr-value>)
+
<addr-protocol-code>
is a variable integer identifying the network protocol. The table of protocols is configurable. The default table is the multicodec table.<addr-value>
is the network address value, of length L
.
Binary-packed encoding (psuedo regex)
(<addr-protocol-code>
<addr-value>)
+
For Example
(TODO)
These implementations are available:
TODO
TODO
We will be submitting an RFC to the IETF. It will be worked on at the multiaddr repo.
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!
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.
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.