Skip to content

feat(kad-dht): terminate query paths once the closest-K set is full#3539

Open
tabcat wants to merge 4 commits into
libp2p:mainfrom
tabcat:feat/kad-dht-converge-on-closest-k
Open

feat(kad-dht): terminate query paths once the closest-K set is full#3539
tabcat wants to merge 4 commits into
libp2p:mainfrom
tabcat:feat/kad-dht-converge-on-closest-k

Conversation

@tabcat

@tabcat tabcat commented Jun 11, 2026

Copy link
Copy Markdown
Member

Description

A query path keeps querying every peer closer than the one that returned it,
walking each disjoint path to exhaustion with no convergence check. This adds the
Kademlia/S-Kademlia termination condition: each path tracks the closest peers that
have responded, and once that set is full it stops at peers that can no longer
enter it - both when a peer comes off the queue, and before queuing a newly
discovered one (the latter also avoids the expensive dialability check for peers
it wouldn't query).

The effect is on a cold or sparse routing table, where a lookup explores widely; a
warm table converges in a step or two and the gate rarely fires. Measured against
the public Amino DHT, fresh node per lookup (table seeded only by bootstrap, ~5-7
peers):

peers contacted per lookup without with gate
mean 555 245
median 755 218
max 838 440

At kBucketSize = 20 the gate never triggers on the small topologies in the
existing tests, so they're unchanged; it only prunes over-exploration at scale.

Part of #3536.

Change checklist

  • I have performed a self-review of my own code
  • I have made corresponding changes to the documentation if necessary (this includes comments as well)
  • I have added tests that prove my fix is effective or that my feature works

tabcat added 2 commits June 11, 2026 20:43
Each disjoint path tracks the closest peers that have responded and stops querying peers that can no longer enter that set, the Kademlia/S-Kademlia termination condition. Prunes over-exploration at scale; at small topologies the gate never triggers, so existing tests are unchanged.
tabcat added 2 commits June 15, 2026 00:40
Add canAddKadId unit tests (incl. the equal-distance boundary) and a test that the enqueue-time gate skips the dialability check for pruned peers. Also reduce the gate comments and log the converged-path skip.
@tabcat tabcat marked this pull request as ready for review June 15, 2026 12:35
@tabcat tabcat requested a review from a team as a code owner June 15, 2026 12:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant