How to dial a PeerId using kademlia

[MatthiasvB]

According to the libp2p concept docs on Peer routing

The Kad-DHT uses a process called “peer routing” to discover nodes in the network. When looking for a peer, the local node contacts the k closest nodes to the remote peer’s ID asking them for closer nodes. The local node repeats the process until it finds the peer or determines that it is not in the network.

This doesn't explicitly state how or why kademlia may be looking for a peer, just that it may do so at times.

Directly below under Content provider routing, it states that (highlight by me)

Kad-DHT also includes a feature for content provider discovery, where nodes can look up providers for a given key. The local node again contacts the k closest nodes to the key asking them for either providers of the key and/or closer nodes to the key. The local node repeats the process until it finds providers for the key or determines that it is not in the network.

The also seems to indicate that provider discovery and peer(id) discovery are conceptionally on the same level, existing in parallel, as alternatives. So I should be able to kademlia_find_provider(provided_key) and kademlia_find_peer(peer_id).

However, in the crate docs, I only find APIs for records and providers, nothing that would allow me to directly find a specific peer. I could, of course, have that peer provide its PeerId and use the provider API, but that seems awkward.

For this reason, I have so far assumed that this would happen automagically: I dial a peer, kademlia sees that and starts looking for it. However, answers to my question here seem to suggest that this is not the case.

As I understand it right now, either the rust implementation of libp2p does not fully implement kademlia as outlined by the concept, or I'm missing something fundamental. So here's the question: Given a PeerId, how do I find the addresses of that peer?

[drHuangMHT]

For Provider and Record, see file-sharing example in the repo.

In order to obtain an address of a peer, you will need at least one connected peer to bootstrap from. Bootstrapping can be triggered manually, by periodic bootstrapping, or upon new connection. By bootstrapping, peers participating in the same DHT network will send you information about the network, for example other peers that they know, and a key-value map. Then you can listen for NewExternalAddrOfPeer to get the addresses discovered by kad, or alternatively use peer-store since it also handles NewExternalAddrOfPeer. You can also iterate over kbuckets by kad:;Behaviour::kbuckets() for peers inside the routing table, but only publicly reachable peers will be in the kbucket and it has a cap of 20 peers per bucket(256 buckets in total, ordered by XOR distance of 256-bit Peer ID).

[elenaf9]

The docs aren't very clear on this, I agree.

In Kademlia, peer IDs and record IDs are mapped to the same key space. To find a peer (and their address) "closest" (XOR metric) to a key, you can use Behavior::get_closest_peers.
In case of a queried peer ID, the resulting GetClosestPeersOk should include the peer itself and its address, and in case of a queried provider key it should be a list of peers that are close to it.

cc @guillaumemichel correct me if I am wrong.

[guillaumemichel]

That is correct!