Add spec on addressing & use of multiaddr #191
Conversation
| addresses are generally exchanged over the wire as binary-encoded multiaddrs in | ||
| libp2p's core protocols. | ||
|
|
||
| When exchanging addresses, peers send a multiaddr containing both their network |
There was a problem hiding this comment.
Nit: on the wire, we usually don't include the peer-id part (it's usually implicit). I'm not sure how to convey this.
There was a problem hiding this comment.
When sending self addresses over the wire, we omit the identity part, as it's considered superfluous because libp2p connections are authenticated by principle. If the other party needs to relay our addresses to a third party, it should add the identity part to form a fully qualified address.
There was a problem hiding this comment.
Revisiting this...
- "network" address is usually referred to as the "transport" address (not critical, but it could involve relays and multiple network addresses).
- We usually send AddrInfos (
AddrInfo{ID: <peer-id>, Addrs: <transport-addrs>}).
But this section is really fine as-is, this is just me nit picking.
|
👍 for not trying to be too generic, and instead exhaustively listing the valid multiaddresses. That's the way to go! |
There was a problem hiding this comment.
Thanks for taking this on! 🎉🎉🎉
A few comments:
- It feels like the term
multiaddris somewhat overloaded to refer to multiaddr particles and full multiaddrs, but there's no formal concept of validity/conformance/soundness. - How about we make this spec solely about defining
sound/functional multiaddrsin the context of libp2p? i.e. what combinations/compositions are valid and should be understood by all implementations. - We can move the valuable background context narrative to a non-normative doc, and refer to it from here. This doc would then stay on as a normative spec.
- If we do (2) and (3), we can remove the overloading by making "multiaddr" refer to "sound multiaddr" everywhere, and making its constituents just components.
| addresses are generally exchanged over the wire as binary-encoded multiaddrs in | ||
| libp2p's core protocols. | ||
|
|
||
| When exchanging addresses, peers send a multiaddr containing both their network |
There was a problem hiding this comment.
When sending self addresses over the wire, we omit the identity part, as it's considered superfluous because libp2p connections are authenticated by principle. If the other party needs to relay our addresses to a third party, it should add the identity part to form a fully qualified address.
Co-authored-by: raulk <raul@protocol.ai> Co-authored-by: Marcin Rataj <lidel@lidel.org>
marten-seemann
force-pushed
the
addressing-spec
branch
from
b0b722d
to
0e770a8
Compare
There was a problem hiding this comment.
Left a couple of comments. All but one contain a direct change suggestion.
Other than that, this looks good to me. Thanks @yusefnapora and @marten-seemann for the work!
Small ask: Can we wrap the lines to e.g. 80 characters before merging? I am happy to do it. Just let me know once ready.
Co-authored-by: Max Inden <mail@max-inden.de>
It's ready now. But is this something we actually care about? If so, should we check this in CI? |
Wow, that was a fast turnaround time. Thanks.
While i prefer Markdown documents to be wrapped at XXX chars, the thing I mostly care about is consistency across the repository. The majority of documents is wrapped at 80 chars, thus I would prefer new documents to comply with that convention.
I am not opposed to it, though I am not sure it is worth it, given that there are likely some cases where more than 80 chars are needed, e.g. for visualizations. |
|
@Stebalien @lidel @yusefnapora @raulk This PR has been sitting here for quite a while, and we only made a bunch of cosmetic changes to it now. In the interest of moving things forward (both this PR and Protocol Select, which will modify this document), we're going to merge this PR this week, unless we hear any blocking feedback by Friday EOD. As always, merging this PR doesn't mean that this document is final, further improvements are possible (and welcome!) via separate PRs. |
| addresses are generally exchanged over the wire as binary-encoded multiaddrs in | ||
| libp2p's core protocols. | ||
|
|
||
| When exchanging addresses, peers send a multiaddr containing both their network |
There was a problem hiding this comment.
Revisiting this...
- "network" address is usually referred to as the "transport" address (not critical, but it could involve relays and multiple network addresses).
- We usually send AddrInfos (
AddrInfo{ID: <peer-id>, Addrs: <transport-addrs>}).
But this section is really fine as-is, this is just me nit picking.
| /p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N | ||
| ``` | ||
|
|
||
| Where `QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` is the string representation |
There was a problem hiding this comment.
nit: encoded string representation
This is a spec on addressing I've been chipping away at for a while now. So far it covers how multiaddrs basically work, the rules for DNS resolution, and the address formats for (most) transports.
TODO:
Also TODO, but probably in a second pass:
@Stebalien, the DNS resolution described here aligns with where you're going with this PR, I think: multiformats/go-multiaddr-dns#17