Skip to content

Conversation

@noamsp-starkware
Copy link

@noamsp-starkware noamsp-starkware commented Jan 25, 2026

Description

Make the number of closest peers returned in response to FIND_NODE requests configurable.

Previously, the Kademlia implementation always returned K_VALUE (20) closest peers when responding to FIND_NODE requests. This change introduces a new configuration option set_num_closest_peers() that allows users to customize this value while maintaining backward compatibility (defaults to K_VALUE).

This is useful for use cases where:

  • More peers are needed for redundancy or faster discovery
  • Fewer peers are desired to reduce response size and network overhead
  • Custom DHT configurations require different peer list sizes

The change affects:

  • Behaviour::get_closest_peers() - now uses the configurable value
  • Behaviour::get_closest_peers_with_results() - caps results to the configurable value
  • Behaviour::closest_peers() iterator - returns up to the configurable number of peers

Related Issues:
#5501
#5875
#6247

Notes & open questions

  • The default value remains K_VALUE (20) for backward compatibility
  • This only affects the number of peers returned in responses, not the bucket size or other Kademlia parameters

Change checklist

  • I have performed a self-review of my own code
  • I have made corresponding changes to the documentation
  • I have added tests that prove my fix is effective or that my feature works
  • A changelog entry has been made in the appropriate crates

@drHuangMHT
Copy link
Contributor

I don't see why such change can reduce network overhead, because no matter how many closest peers to list, the query path to the closest peer is the same, just the number of peers to record on the path gets changed. In other words, the depth of the query remain unchanged(until the last closest reachable branch of the BTree), but the depth of recording changes(higher number of peers to return means more branches are recorded). And I don't see benefit of returning more peers than K_VALUE because the increased redundancy/resilience from listing more peers means contacting more peers after the query, which means higher network overhead whose benefit is diminishing rapidly. K_VALUE is a battle-tested value that balances all aspects, it should be respected. Correct me if I'm wrong @guillaumemichel .

Copy link
Contributor

@guillaumemichel guillaumemichel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes this is correct @drHuangMHT

We cannot change how many peers are returned in a FIND_NODE request without modifying the spec, currently the number of returned peers is K, which is a system parameter.

More peers are needed for redundancy or faster discovery

Since the number of nodes returned by FIND_NODE RPC is fixed (K), the request will converge on the K closest peers to the target key. The other peers in the list aren't guaranteed to be the next closest (e.g K+1 closest) to the target key. Hence you could get more peers, but they won't be the closest.

Fewer peers are desired to reduce response size and network overhead

Since the number of peers returned by FIND_NODE RPC is fixed, this has no impact on response size. IIRC network overhead could be reduced by calling get_n_closest_peers() with a n smaller than the bucket size.

Custom DHT configurations require different peer list sizes

Nodes that don't share basic DHT configuration such as K, bucket size, number of peers in response shouldn't participate in the same DHT swarm. Each DHT swarm should have its own spec defining these important parameters.


@noamsp-starkware you may be interested in tuning the bucket size instead. Note that if you modify the bucket size, you should form a DHT swarm containing only peers with the same bucket size, and not try to join an existing DHT swarm with a different bucket size (e.g Amino DHT).

Comment on lines 744 to -748
{
// The inner code never expect higher than K_VALUE results to be returned.
// And removing such cap will be tricky,
// The inner code never expect higher than the configured num_closest_peers results to be
// returned. And removing such cap will be tricky,
// since it would involve forging a new key and additional requests.
// Hence bound to K_VALUE here to set clear expectation and prevent unexpected behaviour.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As stated in this comment, having a cap higher than K_VALUE isn't trivial. It requires to send extra requests for forged keys.

The number of peers returned is a protocol limitation (it should be K_VALUE as per spec).

The max cap shouldn't be increased without either:

  1. A protocol change
  2. Implementing mechanism for exploring a keyspace area, which includes additional requests for forged keys.

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.

3 participants