Skip to content

Commit d4ed859

Browse files
Winter-SorenWinter-Soren
authored
Merge branch 'main' into feat/619-store-pubkey-peerid-peerstore
2 parents a3492cf + 79094d7 commit d4ed859

31 files changed

+5818
-24
lines changed

‎Makefile

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,9 @@ PB = libp2p/crypto/pb/crypto.proto \
5858
libp2p/security/secio/pb/spipe.proto \
5959
libp2p/security/noise/pb/noise.proto \
6060
libp2p/identity/identify/pb/identify.proto \
61-
libp2p/host/autonat/pb/autonat.proto
61+
libp2p/host/autonat/pb/autonat.proto \
62+
libp2p/kad_dht/pb/kademlia.proto
63+
6264
PY = $(PB:.proto=_pb2.py)
6365
PYI = $(PB:.proto=_pb2.pyi)
6466

‎docs/examples.kademlia.rst

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
Kademlia DHT Demo
2+
=================
3+
4+
This example demonstrates a Kademlia Distributed Hash Table (DHT) implementation with both value storage/retrieval and content provider advertisement/discovery functionality.
5+
6+
.. code-block:: console
7+
8+
$ python -m pip install libp2p
9+
Collecting libp2p
10+
...
11+
Successfully installed libp2p-x.x.x
12+
$ cd examples/kademlia
13+
$ python kademlia.py --mode server
14+
2025-06-13 19:51:25,424 - kademlia-example - INFO - Running in server mode on port 0
15+
2025-06-13 19:51:25,426 - kademlia-example - INFO - Connected to bootstrap nodes: []
16+
2025-06-13 19:51:25,426 - kademlia-example - INFO - To connect to this node, use: --bootstrap /ip4/127.0.0.1/tcp/28910/p2p/16Uiu2HAm7EsNv5vvjPAehGAVfChjYjD63ZHyWogQRdzntSbAg9ef
17+
2025-06-13 19:51:25,426 - kademlia-example - INFO - Saved server address to log: /ip4/127.0.0.1/tcp/28910/p2p/16Uiu2HAm7EsNv5vvjPAehGAVfChjYjD63ZHyWogQRdzntSbAg9ef
18+
2025-06-13 19:51:25,427 - kademlia-example - INFO - DHT service started in SERVER mode
19+
2025-06-13 19:51:25,427 - kademlia-example - INFO - Stored value 'Hello message from Sumanjeet' with key: FVDjasarSFDoLPMdgnp1dHSbW2ZAfN8NU2zNbCQeczgP
20+
2025-06-13 19:51:25,427 - kademlia-example - INFO - Successfully advertised as server for content: 361f2ed1183bca491b8aec11f0b9e5c06724759b0f7480ae7fb4894901993bc8
21+
22+
23+
Copy the line that starts with ``--bootstrap``, open a new terminal in the same folder and run the client:
24+
25+
.. code-block:: console
26+
27+
$ python kademlia.py --mode client --bootstrap /ip4/127.0.0.1/tcp/28910/p2p/16Uiu2HAm7EsNv5vvjPAehGAVfChjYjD63ZHyWogQRdzntSbAg9ef
28+
2025-06-13 19:51:37,022 - kademlia-example - INFO - Running in client mode on port 0
29+
2025-06-13 19:51:37,026 - kademlia-example - INFO - Connected to bootstrap nodes: [<libp2p.peer.id.ID (16Uiu2HAm7EsNv5vvjPAehGAVfChjYjD63ZHyWogQRdzntSbAg9ef)>]
30+
2025-06-13 19:51:37,027 - kademlia-example - INFO - DHT service started in CLIENT mode
31+
2025-06-13 19:51:37,027 - kademlia-example - INFO - Looking up key: FVDjasarSFDoLPMdgnp1dHSbW2ZAfN8NU2zNbCQeczgP
32+
2025-06-13 19:51:37,031 - kademlia-example - INFO - Retrieved value: Hello message from Sumanjeet
33+
2025-06-13 19:51:37,031 - kademlia-example - INFO - Looking for servers of content: 361f2ed1183bca491b8aec11f0b9e5c06724759b0f7480ae7fb4894901993bc8
34+
2025-06-13 19:51:37,035 - kademlia-example - INFO - Found 1 servers for content: ['16Uiu2HAm7EsNv5vvjPAehGAVfChjYjD63ZHyWogQRdzntSbAg9ef']
35+
36+
Alternatively, if you run the server first, the client can automatically extract the bootstrap address from the server log file:
37+
38+
.. code-block:: console
39+
40+
$ python kademlia.py --mode client
41+
2025-06-13 19:51:37,022 - kademlia-example - INFO - Running in client mode on port 0
42+
2025-06-13 19:51:37,026 - kademlia-example - INFO - Connected to bootstrap nodes: [<libp2p.peer.id.ID (16Uiu2HAm7EsNv5vvjPAehGAVfChjYjD63ZHyWogQRdzntSbAg9ef)>]
43+
2025-06-13 19:51:37,027 - kademlia-example - INFO - DHT service started in CLIENT mode
44+
2025-06-13 19:51:37,027 - kademlia-example - INFO - Looking up key: FVDjasarSFDoLPMdgnp1dHSbW2ZAfN8NU2zNbCQeczgP
45+
2025-06-13 19:51:37,031 - kademlia-example - INFO - Retrieved value: Hello message from Sumanjeet
46+
2025-06-13 19:51:37,031 - kademlia-example - INFO - Looking for servers of content: 361f2ed1183bca491b8aec11f0b9e5c06724759b0f7480ae7fb4894901993bc8
47+
2025-06-13 19:51:37,035 - kademlia-example - INFO - Found 1 servers for content: ['16Uiu2HAm7EsNv5vvjPAehGAVfChjYjD63ZHyWogQRdzntSbAg9ef']
48+
49+
The demo showcases key DHT operations:
50+
51+
- **Value Storage & Retrieval**: The server stores a value, and the client retrieves it
52+
- **Content Provider Discovery**: The server advertises content, and the client finds providers
53+
- **Peer Discovery**: Automatic bootstrap and peer routing using the Kademlia algorithm
54+
- **Network Resilience**: Distributed storage across multiple nodes (when available)
55+
56+
Command Line Options
57+
--------------------
58+
59+
The Kademlia demo supports several command line options for customization:
60+
61+
.. code-block:: console
62+
63+
$ python kademlia.py --help
64+
usage: kademlia.py [-h] [--mode MODE] [--port PORT] [--bootstrap [BOOTSTRAP ...]] [--verbose]
65+
66+
Kademlia DHT example with content server functionality
67+
68+
options:
69+
-h, --help show this help message and exit
70+
--mode MODE Run as a server or client node (default: server)
71+
--port PORT Port to listen on (0 for random) (default: 0)
72+
--bootstrap [BOOTSTRAP ...]
73+
Multiaddrs of bootstrap nodes. Provide a space-separated list of addresses.
74+
This is required for client mode.
75+
--verbose Enable verbose logging
76+
77+
**Examples:**
78+
79+
Start server on a specific port:
80+
81+
.. code-block:: console
82+
83+
$ python kademlia.py --mode server --port 8000
84+
85+
Start client with verbose logging:
86+
87+
.. code-block:: console
88+
89+
$ python kademlia.py --mode client --verbose
90+
91+
Connect to multiple bootstrap nodes:
92+
93+
.. code-block:: console
94+
95+
$ python kademlia.py --mode client --bootstrap /ip4/127.0.0.1/tcp/8000/p2p/... /ip4/127.0.0.1/tcp/8001/p2p/...
96+
97+
How It Works
98+
------------
99+
100+
The Kademlia DHT implementation demonstrates several key concepts:
101+
102+
**Server Mode:**
103+
- Stores key-value pairs in the distributed hash table
104+
- Advertises itself as a content provider for specific content
105+
- Handles incoming DHT requests from other nodes
106+
- Maintains routing table with known peers
107+
108+
**Client Mode:**
109+
- Connects to bootstrap nodes to join the network
110+
- Retrieves values by their keys from the DHT
111+
- Discovers content providers for specific content
112+
- Performs network lookups using the Kademlia algorithm
113+
114+
**Key Components:**
115+
- **Routing Table**: Organizes peers in k-buckets based on XOR distance
116+
- **Value Store**: Manages key-value storage with TTL (time-to-live)
117+
- **Provider Store**: Tracks which peers provide specific content
118+
- **Peer Routing**: Implements iterative lookups to find closest peers
119+
120+
The full source code for this example is below:
121+
122+
.. literalinclude:: ../examples/kademlia/kademlia.py
123+
:language: python
124+
:linenos:

‎docs/examples.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ Examples
1111
examples.echo
1212
examples.ping
1313
examples.pubsub
14+
examples.kademlia

‎docs/libp2p.kad_dht.pb.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
libp2p.kad\_dht.pb package
2+
==========================
3+
4+
Submodules
5+
----------
6+
7+
libp2p.kad_dht.pb.kademlia_pb2 module
8+
-------------------------------------
9+
10+
.. automodule:: libp2p.kad_dht.pb.kademlia_pb2
11+
:members:
12+
:undoc-members:
13+
:show-inheritance:
14+
15+
Module contents
16+
---------------
17+
18+
.. automodule:: libp2p.kad_dht.pb
19+
:no-index:
20+
:members:
21+
:undoc-members:
22+
:show-inheritance:

‎docs/libp2p.kad_dht.rst

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
libp2p.kad\_dht package
2+
=======================
3+
4+
Subpackages
5+
-----------
6+
7+
.. toctree::
8+
:maxdepth: 4
9+
10+
libp2p.kad_dht.pb
11+
12+
Submodules
13+
----------
14+
15+
libp2p.kad\_dht.kad\_dht module
16+
-------------------------------
17+
18+
.. automodule:: libp2p.kad_dht.kad_dht
19+
:members:
20+
:undoc-members:
21+
:show-inheritance:
22+
23+
libp2p.kad\_dht.peer\_routing module
24+
------------------------------------
25+
26+
.. automodule:: libp2p.kad_dht.peer_routing
27+
:members:
28+
:undoc-members:
29+
:show-inheritance:
30+
31+
libp2p.kad\_dht.provider\_store module
32+
--------------------------------------
33+
34+
.. automodule:: libp2p.kad_dht.provider_store
35+
:members:
36+
:undoc-members:
37+
:show-inheritance:
38+
39+
libp2p.kad\_dht.routing\_table module
40+
-------------------------------------
41+
42+
.. automodule:: libp2p.kad_dht.routing_table
43+
:members:
44+
:undoc-members:
45+
:show-inheritance:
46+
47+
libp2p.kad\_dht.utils module
48+
----------------------------
49+
50+
.. automodule:: libp2p.kad_dht.utils
51+
:members:
52+
:undoc-members:
53+
:show-inheritance:
54+
55+
libp2p.kad\_dht.value\_store module
56+
-----------------------------------
57+
58+
.. automodule:: libp2p.kad_dht.value_store
59+
:members:
60+
:undoc-members:
61+
:show-inheritance:
62+
63+
libp2p.kad\_dht.pb
64+
------------------
65+
66+
.. automodule:: libp2p.kad_dht.pb
67+
:members:
68+
:undoc-members:
69+
:show-inheritance:
70+
71+
Module contents
72+
---------------
73+
74+
.. automodule:: libp2p.kad_dht
75+
:members:
76+
:undoc-members:
77+
:show-inheritance:

‎docs/libp2p.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Subpackages
1111
libp2p.host
1212
libp2p.identity
1313
libp2p.io
14+
libp2p.kad_dht
1415
libp2p.network
1516
libp2p.peer
1617
libp2p.protocol_muxer

0 commit comments

Comments
 (0)