go-libp2p-kad-dht

To maintain predictable message sizes on the wire and in the peerstore, this implementation bounds single peer records (a Peer ID plus its multiaddresses) to a maximum of 8 KiB during serialization.

When a record exceeds this limit, the implementation keeps the Peer ID and as many addresses as fit, dropping any remaining addresses. This 8 KiB ceiling is designed to be larger than any well-formed peer's signed self-description provided via the libp2p identify protocol.

This bounding applies to both:

1. Records this node emits.
2. Records this node ingests from other peers.

Because a trimmed record is simply a standard, smaller peer record, this optimization is compatible with all other Kademlia implementations without requiring coordination.

To add the Kademlia DHT implementation to your Go project, use the go get command to fetch the module from GitHub.

go get github.com/libp2p/go-libp2p-kad-dht

Detailed API documentation, including function signatures, types, and package structures, is available via GoDoc.

https://godoc.org/github.com/libp2p/go-libp2p-kad-dht

A LookupEvent is emitted for every notable occurrence during a DHT lookup. It is fully JSON-serializable. A single lookup instance is identified by a uuid.UUID.

An event can contain one of the following:

• Request: A *LookupUpdateEvent describing an outgoing query request.
• Response: A *LookupUpdateEvent describing an incoming query response.
• Terminate: A *LookupTerminateEvent describing why the lookup ended.

Use NewLookupEvent(...) to construct these events manually if needed, though they are typically published internally by the DHT.

The DHT can operate in several modes to control its behavior as a client or server:

• ModeAuto: Dynamically switches between Client and Server modes based on network reachability events.
• ModeClient: Operates as a client only; it cannot respond to incoming queries.
• ModeServer: Operates as a server; it can both send and respond to queries.
• ModeAutoServer: Similar to ModeAuto, but defaults to acting as a server when reachability is unknown.

The LookupUpdateEvent describes how the set of peers involved in a lookup changes. It tracks peers moving between different states in the lookup's peerset.

Fields:

• Cause: The *PeerKadID whose response (or lack thereof) triggered this update. If nil, it is the initial seeding event.
• Source: The *PeerKadID that provided the information about the peers listed below.
• Heard: Peers being set to the "heard" state.
• Waiting: Peers being set to the "waiting" state.
• Queried: Peers being set to the "queried" state.
• Unreachable: Peers being set to the "unreachable" state.

Manage how long records are stored and how they are cleaned up:

• MaxRecordAge(maxAge time.Duration): Specifies the maximum time a node holds a record. A non-positive value disables age-based expiry.
• ValueGCInterval(interval time.Duration): Sets how often the DHT sweeps the datastore to delete expired value records. A non-positive value disables the background sweep.

You can inspect the health and distribution of your routing table using GetRoutingTableDiversityStats(), which returns []peerdiversity.CplDiversityStats. This is useful for monitoring how well-distributed your peers are across the Kademlia buckets.

stats := dht.GetRoutingTableDiversityStats()
// inspect stats

The following options are experimental and may be removed:

• EnableOptimisticProvide(): Skips the last hops of the provide process using a network size estimator to return earlier.
• OptimisticProvideJobsPoolSize(size int): Configures the limit for in-flight ADD_PROVIDER RPCs when using optimistic providing.

The Ping(ctx, p) method sends a ping message to the specified peer p using the DHT's internal protocol messenger and waits for a response. This can be used to verify if a peer is reachable via the DHT protocols.

err := dht.Ping(ctx, targetPeerID)
if err != nil {
	// peer is unreachable or not responding to DHT pings
}

Use PeerID() to get the local node's peer.ID and PeerKey() to get the DHT key (the byte representation of the Peer ID used in Kademlia operations).

myID := dht.PeerID()
myKey := dht.PeerKey()