Skip to main content

Module lookup

decdn_node::dht

Module lookup 

Source
Expand description

Requester-side iterative FindValue lookup (ADR 022 §FIND_VALUE Flow + §Lookup integrity).

Wraps the per-RPC primitive super::client::find_value in a standard Kademlia iteration with α=3 parallelism, three response filters applied in order, and provider-set randomisation before return. The lookup returns the raw surviving provider set; ranking / probing belongs to the downstream caller.

§Termination

Stops as soon as either:

  • providers.len() >= k (saturation — caller has enough to probe), OR
  • a full round completes without surfacing any candidate strictly closer to target than the current best queried node (convergence — no further progress possible).

Mirrors the textbook Kademlia termination. The empty-providers convergence case lets the caller fall back to the on-chain origin-directory (super::OriginDirectory) per ADR 022 § FIND_VALUE Flow.

§Three filters (ADR 022 § Lookup integrity)

Applied in order to every FindValueResponse:

  1. XOR-distance — drop closer_nodes entries whose distance to the target is not strictly less than the responder’s own distance. Honest Kademlia responders never produce such entries.
  2. Active-staker — drop non-staked NodeIds from both closer_nodes and providers. The DHT routing pool is restricted to staked nodes by spec.
  3. Negative probe cache — drop (provider, target) pairs the requester has already observed returning has_blob: false within the cache TTL. Only applies to providers, never to closer_nodes.

After filtering, the surviving provider set is randomised before return. ADR 022 § Lookup integrity: “Randomization on the requester is the load-bearing defense against ordering manipulation.”

Structs§

LookupConfig
Lookup tuning knobs. alpha and k are NonZeroUsize so the type system rules out the silent-no-op states a zero would produce — empty batches from pick_round_batch, instant “saturation” from have_enough_providers. Caller-side clamping belongs at the config-parse boundary, not at every lookup entry.

Constants§

DEFAULT_ALPHA
Default α — parallel in-flight RPCs per round. ADR 022 § Routing Table.
DEFAULT_K
Default K — providers-accumulated saturation cap. ADR 022 § Routing Table.
DEFAULT_ROUND_TIMEOUT
Default round timeout. Belt over the per-RPC 8s timeout in super::client; bounds the wall-clock budget for a single iteration even if a few peers hang.
MAX_LOOKUP_ROUNDS
Hard ceiling on the number of rounds one lookup may run (#1145 review).

Functions§

find_providers
Run the iterative FindValue lookup for target.