Crate dig_dht 

dig-dht — a Kademlia DHT with provider records for the DIG Node peer network

The DHT answers exactly one question for a DIG Node: “which peers hold this content?” A node that holds a store / capsule / root / resource PUTs a provider record keyed by a ContentId; a node that wants that content runs an iterative find_providers lookup and gets back the set of holder peer_ids (with candidate addresses). It then connects to those peers over dig_nat (mTLS, peer_id = SHA-256(TLS SPKI DER)) and fetches the bytes over the L7 peer RPC (dig.getAvailability → dig.fetchRange). The DHT locates peers; dig-nat and the peer RPC move the bytes.

The Kademlia core

Nodes and content share one 256-bit XOR-metric keyspace (Key): a node’s key is its peer_id verbatim, and a content key is the SHA-256 of its ContentId. Closeness is XOR distance, and the routing table is 256 k-buckets keyed by the shared-prefix length between this node and a peer. Lookups are iterative with α-parallelism, converging on the k closest peers to a target (lookup). This is textbook Kademlia (Maymounkov & Mazières).

Provider records (the point)

announce_provider PUTs a ProviderRecord at the k nodes closest to the content key (and stores it locally); find_providers walks toward the key and collects the providers found along the way. Records are TTL’d and republished before expiry, so a provider that goes offline ages out automatically.

Transport — riding dig-nat

The four DHT RPC methods (find_node, find_providers, add_provider, ping) ride an authenticated dig-nat PeerConnection: each RPC opens a logical stream, writes a length-prefixed JSON wire request, and reads a length-prefixed JSON response. The transport is abstracted behind the DhtTransport trait so the whole lookup + provider machinery is tested over an in-memory harness (many virtual nodes in one process, no real network).

Bootstrap + maintenance

A node seeds its routing table from bootstrap peers (the dig-gossip peer pool / relay introducer, supplied as input — the crate never hard-depends on a live relay) and keeps it fresh with a periodic self-lookup and per-bucket refresh.

Re-exports

pub use config::DhtConfig;

pub use content::ContentId;

pub use error::DhtError;

pub use key::Distance;

pub use key::Key;

pub use record::AddressKind;

pub use record::CandidateAddr;

pub use record::ProviderRecord;

pub use record::MAX_ADDRESSES_PER_RECORD;

pub use routing::Contact;

pub use routing::RoutingTable;

pub use service::BootstrapPeer;

pub use service::DhtService;

pub use transport::DhtTransport;

pub use wire::DhtRequest;

pub use wire::DhtResponse;

Modules

config

DhtConfig — the Kademlia tuning parameters (replication k, lookup parallelism α, provider TTL, the maintenance intervals, and the provider-store admission-control caps).

content

ContentId — what a provider record is keyed by, at the granularities the L7 dig.getAvailability shapes use, mapped consistently into the crate::Key keyspace.

error

DhtError — the crate’s error type.

key

The 256-bit Kademlia keyspace: Key, XOR Distance, and the maps from a PeerId and a ContentId into it.

lookup

The iterative Kademlia lookup: converge on the k closest peers to a target key by repeatedly querying the α closest un-queried peers we know, folding their returned closer contacts back into the shortlist, until no closer peer can be found.

provider_store

ProviderStore — the local key→providers map a node serves on find_providers / add_provider.

record

ProviderRecord — the value the DHT stores: “peer P holds content C, reachable at these addresses, until this expiry” — plus the CandidateAddr address shape it carries.

routing

The Kademlia routing table: 256 k-buckets of Contacts, keyed by XOR-distance bucket_index from this node.

service

DhtService — the public handle that ties the routing table, provider store, transport, and iterative lookup into the four operations a DIG Node needs:

transport

DhtTransport — the one operation the DHT needs from the network: “send this DhtRequest to that peer and give me the DhtResponse.”

wire

The DHT RPC wire — the four request/response messages, type-tagged JSON, framed as a u32 big-endian length prefix + JSON body (the same uniform framing dig-nat uses for its control messages).

Structs

PeerId

A peer’s stable network identity: the 32-byte SHA-256 of its TLS SPKI DER.