|
1 | | -# js-libp2p-kad-dht |
| 1 | +# js-libp2p-kad-dht <!-- omit in toc --> |
2 | 2 |
|
3 | | -js-libp2p-kad-dht is a JavaScript implementation of the [Kademlia DHT](http://www.scs.stanford.edu/%7Edm/home/papers/kpos.pdf) with some features of S/Kademlia. A "provider" node uses the DHT to advertise that it has a particular piece of content, and "querying" nodes will search the DHT for peers that have a particular piece of content. Content is modeled as a value that is identified by a key, where the key and value are Buffers. |
| 3 | +js-libp2p-kad-dht is a JavaScript implementation of the [Kademlia DHT][] with some features of [S/Kademlia][]. A "provider" node uses the DHT to advertise that it has a particular piece of content, and "querying" nodes will search the DHT for peers that have a particular piece of content. Content is modelled as a value that is identified by a key, where the key and value are Uint8Arrays. |
4 | 4 |
|
5 | | -#### DHT Identifiers |
| 5 | +## Table of contents <!-- omit in toc --> |
6 | 6 |
|
7 | | -The DHT uses a sha2-256 hash for identifiers: |
8 | | -- For peers the DHT identifier is the hash of the [PeerId][PeerId] |
9 | | -- For content the DHT identifier is the hash of the key (eg a Block CID) |
| 7 | +- [Spec](#spec) |
| 8 | +- [Extensions](#extensions) |
| 9 | + - [Disjoint paths](#disjoint-paths) |
10 | 10 |
|
11 | | -#### FIND_NODE |
| 11 | +## Spec |
12 | 12 |
|
13 | | -`findPeer (PeerId):` [PeerInfo][PeerInfo] |
| 13 | +js-libp2p-kad-dht follows the [libp2p/kad-dht spec](https://github.com/libp2p/specs/tree/master/kad-dht) and implements the algorithms described in the [IPFS DHT documentation](https://docs.ipfs.io/concepts/dht/). |
14 | 14 |
|
15 | | -The address space is so large (256 bits) that there are big gaps between DHT ids, and nodes frequently join and leave the DHT. |
| 15 | +## Extensions |
16 | 16 |
|
17 | | -To find a particular node |
18 | | -- the `querying node` converts the [PeerId][PeerId] to a DHT id |
19 | | -- the `querying node` sends a request to the nearest peers to that DHT id that it knows about |
20 | | -- those peers respond with the nearest peers to the DHT id that they know about |
21 | | -- the `querying node` sorts the responses and recursively queries the closest peers to the DHT id, continuing until it finds the node or it has queried all the closest peers. |
| 17 | +js-libp2p-kad-dht implements some additional functionality not described in the libp2p KAD-DHT spec. |
22 | 18 |
|
23 | | -#### PUT |
| 19 | +### Disjoint paths |
24 | 20 |
|
25 | | -`put (Key, Value)` |
26 | | - |
27 | | -To store a value in the DHT, the `provider node` |
28 | | -- converts the key to a DHT id |
29 | | -- follows the "closest peers" algorithm as above to find the nearest peers to the DHT id |
30 | | -- sends the value to those nearest peers |
31 | | - |
32 | | -Note that DHT nodes will only store values that are accepted by its "validators", configurable functions that validate the key/value to ensure the node can control what kind of content it stores (eg IPNS records). |
33 | | - |
34 | | -#### GET |
35 | | - |
36 | | -`get (Key): [Value]` |
37 | | - |
38 | | -To retrieve a value from the DHT |
39 | | -- the `querying node` converts the key to a DHT id |
40 | | -- the `querying node` follows the "closest peers" algorithm to find the nearest peers to the DHT id |
41 | | -- at each iteration of the algorithm, if the peer has the value it responds with the value itself in addition to closer peers. |
42 | | - |
43 | | -Note that the value for a particular key is stored by many nodes, and these nodes receive `PUT` requests asynchronously, so it's possible that nodes may have distinct values for the same key. For example if node A `PUT`s the value `hello` to key `greeting` and node B concurrently `PUT`s the value `bonjour` to key `greeting`, some nodes close to the key `greeting` may receive `hello` first and others may receive `bonjour` first. |
44 | | - |
45 | | -Therefore a `GET` request to the DHT may collect distinct values (eg `hello` and `bonjour`) for a particular key from the nodes close to the key. The DHT has "selectors", configurable functions that choose the "best" value (for example IPNS records include a sequence number, and the "best" value is the record with the highest sequence number). |
46 | | - |
47 | | -#### PROVIDE |
48 | | - |
49 | | -`provide (Key)` |
50 | | - |
51 | | -To advertise that it has the content for a particular key |
52 | | -- the `provider node` converts the key to a DHT id |
53 | | -- the `provider node` follows the "closest peers" algorithm to find the nearest peers to the DHT id |
54 | | -- the `provider node` sends a "provide" message to each of the nearest peers |
55 | | -- each of the nearest peers saves the association between the "provider" peer and the key |
56 | | - |
57 | | -#### FIND_PROVIDERS |
58 | | - |
59 | | -`findProviders (Key):` [[PeerInfo][PeerInfo]] |
60 | | - |
61 | | -To find providers for a particular key |
62 | | -- the `querying node` converts the key to a DHT id |
63 | | -- the `querying node` follows the "closest peers" algorithm to find the nearest peers to the DHT id |
64 | | -- at each iteration of the algorithm, if the peer knows which nodes are providing the value it responds with the provider nodes in addition to closer peers. |
| 21 | +js-libp2p-kad-dht uses disjoint paths when performing DHT queries. These are described in the [S/Kademlia][] paper. |
65 | 22 |
|
| 23 | +[Kademlia DHT]: (http://www.scs.stanford.edu/%7Edm/home/papers/kpos.pdf) |
| 24 | +[S/Kademlia]: (https://git.gnunet.org/bibliography.git/plain/docs/SKademlia2007.pdf) |
66 | 25 | [PeerId]: https://github.com/libp2p/js-peer-id |
67 | 26 | [PeerInfo]: https://github.com/libp2p/js-peer-info |
0 commit comments