Kademlia DHT P2P Network
DataMgmt Node uses Kademlia Distributed Hash Table (DHT) for efficient peer discovery and data routing across thousands of nodes with O(log n) lookup efficiency.
What is Kademlia DHT?
Kademlia is a distributed hash table (DHT) protocol designed for decentralized peer-to-peer networks. It uses XOR-based distance metrics to organize nodes and route queries efficiently across the network.
Unlike traditional client-server architectures, Kademlia enables nodes to find data and peers without central coordination. Each node maintains a routing table with contacts organized by their distance in the 160-bit address space.
DataMgmt Node implements a production-ready Kademlia DHT with extensions for:
- Health monitoring - Automatic detection and removal of offline peers
- NAT traversal - Support for nodes behind firewalls
- Bootstrap nodes - Configurable entry points for network joining
- Peer scoring - Prioritize reliable nodes in routing
How P2P Networking Works
Node Discovery
Nodes join the network by contacting bootstrap nodes and populating their routing tables
XOR Distance Routing
Queries route through progressively closer nodes using XOR distance metrics
Data Storage
Data is stored on nodes closest to the data's hash for efficient retrieval
Health Monitoring
Continuous peer health checks ensure routing tables stay current
# Network topology example
GET /network/peers
{
"node_id": "a1b2c3d4e5f6...",
"peers": [
{
"node_id": "b2c3d4e5f6a1...",
"address": "192.168.1.10:8000",
"distance": 45,
"last_seen": "2026-04-14T10:29:55Z",
"health": "healthy"
},
{
"node_id": "c3d4e5f6a1b2...",
"address": "192.168.1.11:8000",
"distance": 89,
"last_seen": "2026-04-14T10:29:50Z",
"health": "healthy"
}
],
"routing_table_size": 156,
"bucket_distribution": {
"0-20": 12,
"21-40": 28,
"41-60": 45,
"61-80": 38,
"81-100": 33
}
} Network Operations
Kademlia DHT supports four fundamental operations that enable decentralized data management.
PING Ping
Check if a node is online and responsive. Used for health monitoring and routing table maintenance.
GET /network/ping/{node_id} STORE Store
Store a key-value pair on nodes closest to the key's hash. Data is replicated across multiple nodes for redundancy.
POST /network/store
FIND_NODE Find Node
Locate nodes closest to a given ID. Returns k-closest nodes from the recipient's routing table.
GET /network/find/{node_id} FIND_VALUE Find Value
Retrieve data by key. If the receiving node has the value, it returns it; otherwise, it returns closer nodes.
GET /data/{hash} Network Configuration
Fine-tune your node's P2P behavior with these configuration options.
| Variable | Default | Description |
|---|---|---|
| P2P_PORT | 8000 | UDP port for P2P communication |
| BOOTSTRAP_NODES | [] | Comma-separated list of bootstrap node addresses |
| K_BUCKET_SIZE | 20 | Maximum nodes per k-bucket |
| ALPHA | 3 | Concurrency factor for lookups |
| HEALTH_CHECK_INTERVAL | 60 | Seconds between peer health checks |
# Example .env configuration P2P_PORT=8000 BOOTSTRAP_NODES=192.168.1.100:8000,192.168.1.101:8000 K_BUCKET_SIZE=20 ALPHA=3 HEALTH_CHECK_INTERVAL=60
Network Monitoring API
Monitor your node's P2P network health and performance in real-time.
/network/stats Get comprehensive network statistics including peer count, routing table size, and message throughput.
/network/peers List all connected peers with their health status, distance, and last seen timestamp.
/ws WebSocket endpoint for real-time network events including peer joins, leaves, and data transfers.
Join the P2P Network
Deploy your node and connect to the decentralized data network.