diff --git a/README.md b/README.md index 8f15bc8..c62e3cc 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # multiaddr +Composable and future-proof network addresses + [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](https://protocol.ai) [![](https://img.shields.io/badge/project-multiformats-blue.svg?style=flat-square)](https://github.com/multiformats/multiformats) [![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](https://webchat.freenode.net/?channels=%23ipfs) [![](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) -> Composable and future-proof network addresses - - [Introduction](#introduction) - [Use cases](#use-cases) - [Encapsulation based on context](#encapsulation-based-on-context) @@ -110,22 +110,40 @@ TODO: specify the decoding (string to byte-array) procedure See [protocols.csv](protocols.csv) for a list of protocol codes and names, and [protocols/](protocols/) for specifications of the currently supported protocols. -TODO: most of these are way underspecified - -- /ip4, /ip6 -- /ipcidr -- /dns4, /dns6 +- [/ip4](protocols/IP4.md) +- [/tcp](protocols/TCP.md) +- [/ipfs](protocols/IPFS.md) +- [/ipns](protocols/IPNS.md) +- [/dccp](protocols/DCCP.md) +- [/ip6](protocols/IP6.md) +- [/ip6zone](protocols/IP6ZONE.md) +- [/ip6cidr](protocols/IP6CIDR.md) +- [/dns](protocols/DNS.md) +- [/dns4](protocols/DNS4.md) +- [/dns6](protocols/DNS6.md) - [/dnsaddr](protocols/DNSADDR.md) -- /tcp -- /udp -- /utp -- /tls -- /ws, /wss -- /ipfs -- /p2p-circuit -- /p2p-webrtc-star, /p2p-webrtc-direct -- /p2p-websocket-star -- /onion +- [/sctp](protocols/SCTP.md) +- [/udp](protocols/UDP.md) +- [/webrtc](protocols/WEBRTC.md) +- [/udt](protocols/UDT.md) +- [/utp](protocols/UTP.md) +- [/unix](protocols/UNIX.md) +- [/thread](protocols/THREAD.md) +- [/p2p](protocols/P2P.md) +- [/https](protocols/HTTPS.md) +- [/onion](protocols/ONION.md) +- [/onion3](protocols/ONION3.md) +- [/garlic64](protocols/GARLIC64.md) +- [/garlic32](protocols/GARLIC32.md) +- [/tls](protocols/TLS.md) +- [/noise](protocols/NOISE.md) +- [/quic](protocols/QUIC.md) +- [/webtransport](protocols/WEBTRANSPORT.md) +- [/certhash](protocols/CERTHASH.md) +- [/ws](protocols/WS.md) +- [/wss](protocols/WSS.md) +- [/http](protocols/HTTP.md) +- [/memory](protocols/MEMORY.md) ## Implementations diff --git a/protocols.csv b/protocols.csv index 70f5504..38ac541 100644 --- a/protocols.csv +++ b/protocols.csv @@ -1,21 +1,29 @@ code, size, name, comment 4, 32, ip4, 6, 16, tcp, -273, 16, udp, 33, 16, dccp, 41, 128, ip6, 42, V, ip6zone, rfc4007 IPv6 zone -43, 8, ipcidr, CIDR mask for IP addresses +43, 8, ipcidr, [NOT REGISTERED AS MULTICODEC] CIDR mask for IP addresses 53, V, dns, domain name resolvable to both IPv6 and IPv4 addresses 54, V, dns4, domain name resolvable only to IPv4 addresses 55, V, dns6, domain name resolvable only to IPv6 addresses 56, V, dnsaddr, 132, 16, sctp, +227, V, ipfs, IPFS; holding a CID +229, V ipns, IPNS; holding a CID +273, 16, udp, +275, 0, p2p-webrtc-star, +276, 0, p2p-webrtc-direct, +277, 0, p2p-stardust, +280, 0, webrtc, ICE-lite webrtc transport +290, 0, p2p-circuit, 301, 0, udt, 302, 0, utp, 400, V, unix, -421, V, p2p, preferred over /ipfs -421, V, ipfs, backwards compatibility; equivalent to /p2p +406, ?, thread, Textile Thread +421, V, p2p, P2P; holding a PeerId +443, 0, https, Deprecated alias for /tls/http 444, 96, onion, 445, 296, onion3, 446, V, garlic64, @@ -25,14 +33,8 @@ code, size, name, comment 460, 0, quic, 465, 0, webtransport, 466, V, certhash, -480, 0, http, HyperText Transfer Protocol -443, 0, https, Deprecated alias for /tls/http 477, 0, ws, WebSockets 478, 0, wss, Deprecated alias for /tls/ws 479, 0, p2p-websocket-star, -277, 0, p2p-stardust, -275, 0, p2p-webrtc-star, -276, 0, p2p-webrtc-direct, -280, 0, webrtc, ICE-lite webrtc transport -290, 0, p2p-circuit, -777, V, memory, in memory transport for self-dialing and testing; arbitrary +480, 0, http, HyperText Transfer Protocol +777, V, memory, [NOT REGISTERED AS MULTICODEC] in memory transport for self-dialing and testing; arbitrary \ No newline at end of file diff --git a/protocols/DCCP.md b/protocols/DCCP.md new file mode 100644 index 0000000..9a0593a --- /dev/null +++ b/protocols/DCCP.md @@ -0,0 +1,17 @@ +# `dccp` + +`dccp` is a protocol that defines which DCCP port should be used. + +## Representation Format + +### Human-readable + +TODO + +### Binary + +TODO + +## Binary Size + +16 bits (Implicit) \ No newline at end of file diff --git a/protocols/DNS.md b/protocols/DNS.md new file mode 100644 index 0000000..703b110 --- /dev/null +++ b/protocols/DNS.md @@ -0,0 +1,21 @@ +# `dns` + +`dns` is a protocol that defines which domain name should be used. + +## Representation Format + +### Human-readable + +The human-readable format of the `dns` protocol uses the well-known textual representation: + + example.com + +TODO: Consider also supporting with trailing dot. + +### Binary + +TODO: Consider binary format. Is it a string prefixed by an unsigned varint or should the FQDN encoding be used, where every label is prefixed and the last label has zero length? + +## Binary Size + +Unknown \ No newline at end of file diff --git a/protocols/DNS4.md b/protocols/DNS4.md new file mode 100644 index 0000000..47e524f --- /dev/null +++ b/protocols/DNS4.md @@ -0,0 +1,21 @@ +# `dns4` + +`dns4` is a protocol that defines which domain name should be used, but only by resolving it to IPv4 addresses. + +## Representation Format + +### Human-readable + +The human-readable format of the `dns4` protocol uses the well-known textual representation: + + example.com + +TODO: Consider also supporting with trailing dot. + +### Binary + +TODO: Consider binary format. Is it a string prefixed by an unsigned varint or should the FQDN encoding be used, where every label is prefixed and the last label has zero length? + +## Binary Size + +Unknown \ No newline at end of file diff --git a/protocols/DNS6.md b/protocols/DNS6.md new file mode 100644 index 0000000..7ba8636 --- /dev/null +++ b/protocols/DNS6.md @@ -0,0 +1,21 @@ +# `dns6` + +`dns6` is a protocol that defines which domain name should be used, but only by resolving it to IPv6 addresses. + +## Representation Format + +### Human-readable + +The human-readable format of the `dns6` protocol uses the well-known textual representation: + + example.com + +TODO: Consider also supporting with trailing dot. + +### Binary + +TODO: Consider binary format. Is it a string prefixed by an unsigned varint or should the FQDN encoding be used, where every label is prefixed and the last label has zero length? + +## Binary Size + +Unknown \ No newline at end of file diff --git a/protocols/DNSADDR.md b/protocols/DNSADDR.md index 115e1f8..ce7d2ce 100644 --- a/protocols/DNSADDR.md +++ b/protocols/DNSADDR.md @@ -1,6 +1,6 @@ # `dnsaddr` -`dnsaddr` is a protocol that instructs the resolver to lookup multiaddr(s) in DNS TXT records for the domain name in it's value section. +`dnsaddr` is a protocol that instructs the resolver to lookup multiaddrs in DNS TXT records for the domain name in it's value section. To resolve a `dnsaddr` multiaddr, the domain name in the value section must first be prefixed with `_dnsaddr.`. Then a DNS query to lookup TXT records for the domain must be made. There may be multiple DNS TXT records for the domain. Valid `dnsaddr` TXT records begin with `dnsaddr=`, followed by a single multiaddr. Recursive lookups are allowed. diff --git a/protocols/HTTP.md b/protocols/HTTP.md new file mode 100644 index 0000000..901dd6f --- /dev/null +++ b/protocols/HTTP.md @@ -0,0 +1,17 @@ +# `http` + +`http` is a protocol that defines to use HTTP. + +## Representation Format + +### Human-readable + +None + +### Binary + +None + +## Binary Size + +None \ No newline at end of file diff --git a/protocols/HTTPS.md b/protocols/HTTPS.md new file mode 100644 index 0000000..107646b --- /dev/null +++ b/protocols/HTTPS.md @@ -0,0 +1,19 @@ +# `https` + +`https` is a protocol that defines to use secure HTTP. + +Deprecated: use `/tls/http`. + +## Representation Format + +### Human-readable + +None + +### Binary + +None + +## Binary Size + +None \ No newline at end of file diff --git a/protocols/IP4.md b/protocols/IP4.md new file mode 100644 index 0000000..2781182 --- /dev/null +++ b/protocols/IP4.md @@ -0,0 +1,23 @@ +# `ip4` + +`ip4` is a protocol that defines which IPv4 address should be used. + +## Representation Format + +### Human-readable + +The human-readable format of the `ip4` protocol uses the quad-dotted format: + + 127.0.9.1 + +TODO: Consider also supporting decimal format. + +### Binary + +The binary format of the `ip4` protocol uses the well-known binary format of 32 bits: + + 0x7F 0x00 0x00 0x01 + +## Binary Size + +32 bits (Implicit) \ No newline at end of file diff --git a/protocols/IP6.md b/protocols/IP6.md new file mode 100644 index 0000000..3d66a30 --- /dev/null +++ b/protocols/IP6.md @@ -0,0 +1,23 @@ +# `ip6` + +`ip6` is a protocol that defines which IPv6 address should be used. + +## Representation Format + +### Human-readable + +The human-readable format of the `ip6` protocol uses the colon-seperated format: + + 2604:1380:4602:5c00::3 + +TODO: Consider also supporting decimal format and/or format that encloses the IP address with `[` and `]`. + +### Binary + +The binary format of the `ip6` protocol uses the well-known binary format of 128 bits: + + 0x26 0x04 0x13 0x80 0x46 0x02 0x5c 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x03 + +## Binary Size + +128 bits (Implicit) \ No newline at end of file diff --git a/protocols/IP6ZONE.md b/protocols/IP6ZONE.md new file mode 100644 index 0000000..8e3dbac --- /dev/null +++ b/protocols/IP6ZONE.md @@ -0,0 +1,17 @@ +# `ip6zone` + +`ip6zone` is a protocol that defines which IPv6 Scope Zone should be used. + +## Representation Format + +### Human-readable + +TODO + +### Binary + +TODO + +## Binary Size + +Variable (Explicit) \ No newline at end of file diff --git a/protocols/IPFS.md b/protocols/IPFS.md new file mode 100644 index 0000000..35d9738 --- /dev/null +++ b/protocols/IPFS.md @@ -0,0 +1,17 @@ +# `ipfs` + +`ipfs` is a protocol that defines which file should be queried using the CID containing its hash. + +## Representation Format + +### Human-readable + +See the CID specification. + +### Binary + +See the CID specification. + +## Binary Size + +Variable (Explicit) \ No newline at end of file diff --git a/protocols/IPNS.md b/protocols/IPNS.md new file mode 100644 index 0000000..3253cde --- /dev/null +++ b/protocols/IPNS.md @@ -0,0 +1,17 @@ +# `ipns` + +`ipns` is a protocol that defines which file should be queried using the CID containing its hashed public key. + +## Representation Format + +### Human-readable + +See the CID specification. + +### Binary + +See the CID specification. + +## Binary Size + +Variable (Explicit) \ No newline at end of file diff --git a/protocols/P2P.md b/protocols/P2P.md new file mode 100644 index 0000000..41b8964 --- /dev/null +++ b/protocols/P2P.md @@ -0,0 +1,17 @@ +# `p2p` + +`p2p` is a protocol that defines which peer should be connected to using the PeerId containing its hashed public key. + +## Representation Format + +### Human-readable + +See the [PeerId](https://docs.libp2p.io/concepts/peer-id/) specification. + +### Binary + +See the [PeerId](https://docs.libp2p.io/concepts/peer-id/) specification. + +## Binary Size + +Variable (Explicit) \ No newline at end of file diff --git a/protocols/QUIC.md b/protocols/QUIC.md new file mode 100644 index 0000000..4f98779 --- /dev/null +++ b/protocols/QUIC.md @@ -0,0 +1,17 @@ +# `quic` + +`quic` is a protocol that defines to use QUIC. + +## Representation Format + +### Human-readable + +None + +### Binary + +None + +## Binary Size + +None \ No newline at end of file diff --git a/protocols/SCTP.md b/protocols/SCTP.md new file mode 100644 index 0000000..6547ce4 --- /dev/null +++ b/protocols/SCTP.md @@ -0,0 +1,17 @@ +# `sctp` + +`sctp` is a protocol that defines which SCTP port should be used. + +## Representation Format + +### Human-readable + +TODO + +### Binary + +TODO + +## Binary Size + +16 bits (Implicit) \ No newline at end of file diff --git a/protocols/TCP.md b/protocols/TCP.md new file mode 100644 index 0000000..e0f726f --- /dev/null +++ b/protocols/TCP.md @@ -0,0 +1,17 @@ +# `tcp` + +`tcp` is a protocol that defines which TCP port should be used. + +## Representation Format + +### Human-readable + +TODO + +### Binary + +TODO + +## Binary Size + +16 bits (Implicit) \ No newline at end of file diff --git a/protocols/TLS.md b/protocols/TLS.md new file mode 100644 index 0000000..0063cef --- /dev/null +++ b/protocols/TLS.md @@ -0,0 +1,17 @@ +# `tls` + +`tls` is a protocol that defines to use TLS. + +## Representation Format + +### Human-readable + +None + +### Binary + +None + +## Binary Size + +None \ No newline at end of file diff --git a/protocols/UDP.md b/protocols/UDP.md new file mode 100644 index 0000000..8a646dc --- /dev/null +++ b/protocols/UDP.md @@ -0,0 +1,17 @@ +# `udp` + +`udp` is a protocol that defines which UDP port should be used. + +## Representation Format + +### Human-readable + +TODO + +### Binary + +TODO + +## Binary Size + +16 bits (Implicit) \ No newline at end of file diff --git a/protocols/WS.md b/protocols/WS.md new file mode 100644 index 0000000..36d5578 --- /dev/null +++ b/protocols/WS.md @@ -0,0 +1,17 @@ +# `ws` + +`ws` is a protocol that defines to use WebSocket. + +## Representation Format + +### Human-readable + +None + +### Binary + +None + +## Binary Size + +None \ No newline at end of file diff --git a/protocols/WSS.md b/protocols/WSS.md new file mode 100644 index 0000000..1bb906d --- /dev/null +++ b/protocols/WSS.md @@ -0,0 +1,19 @@ +# `wss` + +`wss` is a protocol that defines to use secure WebSocket. + +Deprecated: use `/tls/ws`. + +## Representation Format + +### Human-readable + +None + +### Binary + +None + +## Binary Size + +None \ No newline at end of file