Hello, I'm Maneshwar. I'm building git-lrc, a Micro AI code reviewer that runs on every commit. It is free and source-available on Github. Star git-lrc to help devs discover the project. Do give it a try and share your feedback.
Yesterday we understood XOR distance, that weird little metric that has nothing to do with geography but somehow behaves exactly like a distance is supposed to.
If you haven't read it, quick recap: XOR two IDs, read the result as a number, that's your distance, and it satisfies zero-self-distance, symmetry, and the triangle inequality.
Cool math. But math alone doesn't route packets.
So today we look at the thing that actually uses that math to build a real, working, decentralized network: Kademlia.
You've used Kademlia even if you've never heard the name.
It's the DHT (distributed hash table) algorithm quietly running under BitTorrent, IPFS, Ethereum's peer discovery, and Ethereum Swarm's storage layer.
One algorithm, four very different products.
The problem Kademlia is actually solving
Imagine you're building a network with no central server.
Thousands of peers join and leave whenever they feel like it, and you need to answer one question fast: "who has the thing I'm looking for?"
The obvious approaches all fall apart:
- Ask everyone. Congrats, you've built a broadcast storm generator, not a network.
- Keep a central index. That's just a server with extra steps, and now you have a single point of failure and the "decentralized" label is a lie.
- Every node remembers every other node. Works fine until you have a million nodes and your "lightweight P2P client" needs a gigabyte of RAM just for contacts.
Kademlia's pitch is simple to state and genuinely clever to pull off: every node only needs to remember a small, logarithmic number of peers, and it can still find anything in the network in a logarithmic number of hops.
No central authority.
No full peer list.
Nodes can vanish mid-lookup and the system barely notices.
The routing table: k-buckets
This is where yesterday's XOR distance actually gets used.
Each node keeps a routing table split into "buckets," where bucket i holds peers whose XOR distance falls in the range [2^i, 2^(i+1)).
In plain English: bucket 0 holds peers that differ from you in only the very last bit, and the highest bucket holds peers that barely share anything with your ID at all.
class KBucket:
def __init__(self, capacity=20):
self.capacity = capacity
self.peers = [] # most recently seen at the end
def add(self, peer):
if peer in self.peers:
# seen again, move to the back (most recently active)
self.peers.remove(peer)
self.peers.append(peer)
elif len(self.peers) < self.capacity:
self.peers.append(peer)
else:
# bucket full: ping the oldest peer (front of list)
# if it's alive, keep it and drop the new one
# if it's dead, evict it and add the new peer
pass # handled by a liveness check elsewhere
That eviction rule is the sneaky important bit.
Kademlia trusts old, still-responsive peers over shiny new ones, because nodes that have been around a while are statistically more likely to keep being around.
Long-lived peers get to stay.
New peers have to wait for someone old to actually die first.
graph LR
Me["My Node"]
B0["Bucket 0<br/>closest, tiny range<br/>kept extremely fresh"]
B1["Bucket 1"]
B2["..."]
Bn["Bucket 159<br/>farthest, huge range<br/>lots of possible peers"]
Me --> B0
Me --> B1
Me --> B2
Me --> Bn
style B0 fill:#2d5,stroke:#1a3
style Bn fill:#d52,stroke:#a31Notice the asymmetry: low buckets cover a tiny slice of ID space so there aren't many peers that could even qualify, and you know them intimately.
High buckets cover a massive slice of ID space, so you just keep a small sample instead of trying to know everyone out there.
Finding something: the lookup
Say you want to find whoever's closest to some target ID.
You don't ask one peer and hope.
Kademlia asks alpha peers in parallel (usually 3), and keeps looping: ask your current best guesses for who they know that's even closer, fold the new answers in, repeat, until nobody can suggest anyone closer.
def find_node(target_id, initial_peers, alpha=3):
shortlist = sorted(initial_peers, key=lambda p: xor_distance(p.id, target_id))
contacted = set()
while True:
to_query = [p for p in shortlist[:alpha] if p not in contacted]
if not to_query:
break # nobody left to ask, we've converged
for peer in to_query:
contacted.add(peer)
new_peers = peer.query_closer_nodes(target_id)
shortlist.extend(new_peers)
shortlist = sorted(set(shortlist), key=lambda p: xor_distance(p.id, target_id))[:20]
return shortlist
Because of the triangle inequality we talked about yesterday, this loop is guaranteed to make monotonic progress.
No dead ends, no going in circles.
Typically this converges in about O(log n) hops for a network of n nodes, which is the whole reason this scales to millions of peers without falling over.
sequenceDiagram
participant You
participant A as Peer A (far)
participant B as Peer B (closer)
participant C as Peer C (closest)
participant T as Target
You->>A: who's closer to target?
A-->>You: try Peer B
You->>B: who's closer to target?
B-->>You: try Peer C
You->>C: who's closer to target?
C-->>T: found it
Where this actually gets used
Here's the fun part. The same core algorithm shows up wearing very different outfits:
- BitTorrent's Mainline DHT (BEP 5) uses it so torrents can find peers without needing a central tracker.
- IPFS / libp2p (spec here) uses it to find which peers on the network are hosting a given content-addressed piece of data.
- Ethereum's discv5 (spec here) uses it purely for peer discovery, finding other Ethereum nodes to connect to.
The Ethereum Swarm twist is worth dwelling on for a second because it's genuinely different from vanilla Kademlia.
Instead of just using exact XOR distance, Swarm groups nodes into "neighborhoods" based on shared leading bit prefix (they call this Proximity Order), and an entire neighborhood becomes collectively responsible for storing the same chunks of data.
It's Kademlia's routing idea repurposed into a storage assignment system, not just a lookup system.
Swarm also runs "forwarding Kademlia" instead of the classic "iterative Kademlia".
In iterative mode, you personally ask each closer node and the answer comes straight back to you.
In forwarding mode, each node passes the query along to the next closer node, and the response gets relayed back down the same chain, which means nobody in the middle of the chain (except the very first hop) knows who actually started the request.
Free anonymity, as a side effect of how the routing already works.
So what did we actually learn
XOR distance gives you a mathematically well behaved ruler.
Kademlia is what happens when you actually build a routing table and a lookup algorithm around that ruler, and get logarithmic scaling, self-healing under churn, and (depending on the flavor) either speed or anonymity, basically for free.
Not bad for something that boils down to "XOR two numbers and see which one's smaller."
AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.
git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.
Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.
⭐ Star it on GitHub:
HexmosTech
/
git-lrc
Free, Micro AI Code Reviews That Run on Git Commit
| 🇩🇰 Dansk | 🇪🇸 Español | 🇮🇷 Farsi | 🇫🇮 Suomi | 🇯🇵 日本語 | 🇳🇴 Norsk | 🇵🇹 Português | 🇷🇺 Русский | 🇦🇱 Shqip | 🇨🇳 中文 | 🇮🇳 हिन्दी |
git-lrc
Free, Micro AI Code Reviews That Run on Commit
GenAI today is a race car without brakes. It accelerates fast -- you describe something, and large blocks of code appear instantly. But AI agents silently break things: they remove logic, relax constraints, introduce expensive cloud calls, leak credentials, and change behavior -- without telling you. You often find out in production.
git-lrc is your braking system. It hooks into git commit and runs an AI review on every diff before it lands. 60-second setup. Completely free.
In short, git-lrc helps Prevent Outages, Breaches, and Technical Debt Before They Happen
At a glance: 10 risk categories · 100+ failure patterns tracked · every commit…
