Module routing 

Kademlia k-bucket routing table for cdn/dht/v1 (ADR 022 §Routing Table).

256 buckets indexed by the XOR-distance prefix length to the node’s own NodeId; each bucket holds up to K = 20 peers ordered most-recently-seen last. The table is in-memory and rebuilt from the on-chain registry + FindNode self-lookup on restart (ADR 022 §Bootstrap).

Self-NodeId handling

Inserting the node’s own NodeId is a no-op: XOR distance is zero, the bucket index would underflow, and a node listing itself as a peer would cause iterative lookup to terminate on its own routing table without ever contacting the network.

Eviction policy

On bucket overflow the least-recently-seen entry is evicted and the new NodeId appended at the tail. Standard Kademlia would ping the LRU first and evict only if it does not respond; ADR 022 §Routing Table does not mandate the ping-then-evict variant and we do not implement it. The simpler LRU here preserves the “newcomers are reachable” property — the LRU is the one least recently confirmed to be live, so evicting it is the safest bet among entries already in the bucket.

Structs

NodeId

A 32-byte node identifier (Ed25519 public key).

RoutingTable

In-memory k-bucket routing table (ADR 022 §Routing Table).

Constants

KEYSPACE_BITS

Number of bits in the keyspace — equals NODE_ID_LEN * 8. The routing table holds one bucket per possible XOR-prefix length.

K_BUCKET_SIZE

Kademlia bucket size (ADR 022 §Routing Table). Equal to MAX_CLOSER_NODES so a fully-populated bucket can be serialised straight into a closer_nodes field without re-truncation.

NODE_ID_LEN

Number of bytes in an iroh NodeId (32-byte Ed25519 public key). Matches the [u8; 32] representation used on the wire in decdn_protocol::dht.

Functions

xor_distance

Bytewise XOR distance between two NodeIds. Thin wrapper over xor_distance_bytes for the common same-domain case.

xor_distance_bytes

Bytewise XOR distance between two 32-byte keyspace points. Cheap (one AVX register on 64-bit) and the only function the bucket index depends on.