Practical Example Section #474
Conversation
There was a problem hiding this comment.
Sorry for the late response here.
In my eyes this is very much needed documentation. That said, I don't think libp2p/specs is the right place for the /pk example (see below). This is my bad. I should have communicated better out of band.
I think the peer ID related example should live in https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#decoding.
@lidel do you think this is helpful for ipfs/specs#345?
| @@ -455,6 +455,53 @@ multiaddrs are stored in the node's peerbook. | |||
|
|
|||
| --- | |||
|
|
|||
| ## Practical Examples | |||
| <details> | |||
| <summary>Searching the <b>IPFS</b> Kad DHT for a Peer's Public Key</summary><blockquote> | |||
There was a problem hiding this comment.
I think my message on https://discuss.libp2p.io/ was misleading. Sorry for that. /pk is an IPFS concept and not a llibp2p concept. Thus I don't think it should belong in libp2p/specs but instead in ipfs/specs.
Now unfortunately IPFS does not (yet) have a Kademlia specification, i.e. a document that describes how IPFS uses the libp2p Kademlia protocol. This is tracked in ipfs/specs#345. //CC @lidel
I suggest moving the /pk related example to ipfs/specs.
There was a problem hiding this comment.
👍 to moving IPFS-specific things to ipfs/specs (fine to open a PR draft with copy&paste and then mention in ipfs/specs#345 so we can take it from there).
| 3. Putting these together we get `/pk/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ` | ||
| 4. But we need to turn this into it's raw byte representation | ||
| 5. For the namespace and forward slashes we just convert the utf8 string into bytes | ||
| 6. For the PeerID we need to remember that this is a [base58btc encoding](peer-ids.md#decoding) |
There was a problem hiding this comment.
I think the example of en-/ and decoding of a peer ID would be better placed in https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#decoding. We have some examples there, but none of them go all the way from private and public key to peer ID back to public key (in the case of ed25519). Would you be interested in extending the documentation there?
|
The part I wanted to focus on the most was actually key formation. When I first began interacting with the dht I naively converted the entire string '/pk/Qm...' directly into bytes. It took me a few hours to figure out you convert the namespace into bytes and append the original PeerID bytes to it. Pretty silly mistake but thought it might be helpful to jot down for others. I agree that this probably belongs somewhere in the ipfs docs. |
This PR adds a Practical Example section to the Spec in an attempt to help developers (and end users) understand how the default IPFS Kad DHT works and how Keys on the DHT are derived for various namespaces.
What?
A brief example of how to format an RPCMessage in order to query the default IPFS Kad DHT for the PublicKey Record of the Bootstrap node with PeerID
QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ.Why?
No matter how well a Spec is written I often find myself searching for an example with real data. Real data, in this case, is hard due to the ephemeral nature of the DHT, but assuming the Bootstrap node used in this example persists, the querying of it for its PublicKey Record should continue to work.
More?
Hopefully we can add more examples to this section going forward. Maybe a similar example searching the
ipnsnamespace and/or searching the KadDHT for Content Providers.Future
If the community thinks these Practical Example sections are worthwhile / helpful, we could add relevant examples to the rest of the Specs.
Notes
detailstag that defaults to closed as to not clutter the page. At the end of the day this is a Specs documentation and it should remain clear and concise, but if an implementer gets stuck, they could always dig deeper into the examples. Hopefully this doesn't break any formatting rules.Thanks