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.

I knew XOR.

Truth tables, bit flips, the whole deal, nothing new there.

Then I was reading some article about P2P networking and ran into the phrase "XOR distance" and just kind of stopped.

XOR I know. Distance I know. XOR distance? That's not a thing, that's two things wearing a trenchcoat.

So I went and actually learned how it works, and it turns out it's one of those ideas that's simple once it clicks and mildly infuriating right up until it does.

So let's do this properly.

We're going to talk about bits, buckets, and why your node's "neighbors" have nothing to do with where they physically live.

The one-line version

XOR distance between two IDs is just: XOR their bits together, read the result as a number.

That number is your "distance."

Bigger number, farther apart.

Smaller number, closer.

That's it. That's the tweet.

Obviously that's not satisfying, so let's actually build it up.

Step 1: what XOR even does

XOR (exclusive or) looks at two bits and asks one question: "do you two agree?"

Same bits, you get 0.

Different bits, you get 1.

XOR is basically the "spot the difference" operator of computer science.

Now take two IDs (in real systems these are 160-bit or 256-bit hashes, but let's use 4 bits so nobody has to squint):

A = 1100
B = 1010
    ----
    0110   (this is the XOR)

Read 0110 as a plain binary number and you get 6.

So distance(A, B) = 6.

Congrats, you just computed an XOR distance by hand, you can put that on your resume now.

Step 2: why we're even allowed to call this a "distance"

Math is picky about the word "distance."

For something to count as a proper metric, it needs three properties, and XOR happens to nail all three, which honestly feels like a happy accident but isn't.

1. distance(A, A) = 0. Anything XOR'd with itself is all zeros. You are exactly zero distance from yourself, which, philosophically, checks out.
2. Symmetric. A XOR B always equals B XOR A. XOR doesn't play favorites with argument order.
3. Triangle inequality. distance(A, C) ≤ distance(A, B) + distance(B, C). This is the one that actually matters for engineering, because it guarantees that if you keep hopping toward nodes with smaller XOR distance to your target, you are provably making progress. No wandering, no local minima, no getting stuck in a cul-de-sac of the network.

That third property is the whole reason this isn't just a cute math trick, it's what makes routing converge.

Step 3: not all bit flips are created equal

Here's the part that trips people up.

XOR distance isn't "count how many bits differ" (that's Hamming distance, a different and much less useful cousin).

XOR distance cares about where the differing bits are, because it's read as a number, and in numbers, the leftmost digit matters way more than the rightmost one.

1000 XOR 0000 = 1000 = 8   <- disagree on the leftmost (high) bit
0000 XOR 0001 = 0001 = 1   <- disagree on the rightmost (low) bit

Both pairs differ in exactly one bit.

One of them is 8x "farther" than the other.

Same amount of disagreement, wildly different distance, all because of where the disagreement lives.

Here's roughly how that feels, emotionally:

Step 4: let's write actual code

Enough theory, let's compute this for real:

def xor_distance(a: int, b: int) -> int:
    return a ^ b

def bucket_index(distance: int) -> int:
    """Which 'bucket' this distance falls into, i.e. index of the
    highest set bit. This is the thing Kademlia uses to organize
    its routing table."""
    return distance.bit_length() - 1 if distance else -1

A = 0b1100
B = 0b1010
C = 0b1101

print(xor_distance(A, B))        # 6  -> pretty far
print(xor_distance(A, C))        # 1  -> very close
print(bucket_index(xor_distance(A, B)))  # 2
print(bucket_index(xor_distance(A, C)))  # 0

The bucket_index function is the sneaky important part.

It tells you how far in terms of "shared prefix length."

A distance that falls in a high bucket means the IDs barely agree on anything at the front.

A distance in bucket 0 means they agree on almost everything except the last bit.

This bucketing is literally how Kademlia (the algorithm behind BitTorrent's DHT, IPFS, and Ethereum's node discovery) organizes who a node bothers to remember.

Step 5: the routing table, visually

Every node keeps a set of buckets, one per "distance range," and each bucket holds a few peers at that rough distance. Think of it like this:

You keep detailed, well-maintained knowledge of nodes close to you, and increasingly fuzzy, "eh, good enough" knowledge of nodes far away.

It's basically how your own brain works with acquaintances: you remember your best friend's birthday, you remember that one guy from a conference exists.

Step 6: how a lookup actually converges

Say you want to find the node closest to some target ID T, and you're not there yet.

You ask whoever you currently know that's closest to T.

They, in turn, know someone closer to T than you do (because of how the buckets are structured), and they hand you that contact. Repeat.

Because of the triangle inequality, each hop is guaranteed to strictly shrink your distance to T.

In practice this converges in roughly O(log n) hops for a network of n nodes, because each hop tends to fix another bit of agreement with the target.

No coordinates, no GPS, no "which continent is this peer even on," just pure bit math.

Step 7: the "wait, so it's not about geography" moment

This is the bit that messes with people's intuition the most, because we're all trained to think "distance" means physical distance.

A node in Bengaluru and a node in Reykjavik can have a tiny XOR distance if their hashed IDs happen to share a long bit prefix, purely by coincidence of hashing.

Meanwhile two servers sitting in the same rack can be maximally far apart in XOR space if their IDs hash unluckily.

And honestly, that's kind of the whole point. XOR distance throws away geography entirely and replaces it with something that's provably well behaved for routing, at the cost of being completely unintuitive to a human looking at a map. Worth it.

Where you'll actually run into this

If you want to go further down the hole:

• The original Kademlia paper by Maymounkov and Mazières, this is the source of pretty much everything above.
• libp2p's Kad-DHT spec, a modern, readable implementation used by IPFS.
• BitTorrent's Mainline DHT spec (BEP 5), one of the oldest and most battle tested real world uses of this exact idea.
• Ethereum's discv5 spec, same core idea, adapted for node discovery on Ethereum's network.

Wrapping up

XOR distance isn't really "distance" in any sense your GPS would recognize, it's a purpose-built mathematical ruler that happens to satisfy exactly the properties routing needs: zero self-distance, symmetry, and a triangle inequality that guarantees convergence.

Once that clicks, a huge chunk of how DHTs work stops feeling like magic and starts feeling like, well, bit flips with really good manners.

Anyway, that's XOR distance. Go forth and route responsibly.

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…

View on GitHub