Nethermind.Libp2p.Protocols.KadDht 1.1.4

dotnet add package Nethermind.Libp2p.Protocols.KadDht --version 1.1.4
                    
NuGet\Install-Package Nethermind.Libp2p.Protocols.KadDht -Version 1.1.4
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Nethermind.Libp2p.Protocols.KadDht" Version="1.1.4" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Nethermind.Libp2p.Protocols.KadDht" Version="1.1.4" />
                    
Directory.Packages.props
<PackageReference Include="Nethermind.Libp2p.Protocols.KadDht" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Nethermind.Libp2p.Protocols.KadDht --version 1.1.4
                    
#r "nuget: Nethermind.Libp2p.Protocols.KadDht, 1.1.4"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Nethermind.Libp2p.Protocols.KadDht@1.1.4
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Nethermind.Libp2p.Protocols.KadDht&version=1.1.4
                    
Install as a Cake Addin
#tool nuget:?package=Nethermind.Libp2p.Protocols.KadDht&version=1.1.4
                    
Install as a Cake Tool

Kad-DHT

Kademlia DHT support for dotnet-libp2p. It implements the libp2p /ipfs/kad/1.0.0 protocol and integrates it into an ILibp2pPeerFactoryBuilder.

The separate Nethermind.Kademlia 2.0.0 package provides the generic routing table, peer health, and iterative lookup algorithms. This package provides the libp2p protocol, peer and key adapters, network message sender, record stores, and validation.

Install

dotnet add package Libp2p.Protocols.KadDht

Configure

Register the DHT while configuring libp2p. Server mode is the default; client mode participates in routing without serving stored records.

using Libp2p.Protocols.KadDht;
using Libp2p.Protocols.KadDht.Integration;
using Microsoft.Extensions.DependencyInjection;
using Nethermind.Libp2p;

var services = new ServiceCollection();

services.AddLibp2p(builder => builder.AddKadDht(options =>
{
    options.Mode = KadDhtMode.Server;
    options.KSize = 20;
    options.Alpha = 10;
    options.ReadTimeout = TimeSpan.FromSeconds(30);
    options.MaxInboundStreams = 512;
    options.MaxInboundStreamsPerPeer = 64;
}));

After the local peer is initialized, call RunKadDhtAsync to bootstrap the DHT and run its maintenance loop. Use GetKadDht to retrieve the configured KadDhtProtocol for DHT operations.

Configuration

KadDhtOptions controls the routing-table size and query concurrency (KSize and Alpha), operating mode, record and provider retention, storage limits, message limits, maintenance intervals, operation timeout, and disjoint lookup paths. The default mode is KadDhtMode.Server.

The default protocol ID is /ipfs/kad/1.0.0; KadDhtOptions.ProtocolId can select another network's protocol ID. A single protobuf Message envelope carries PING, FIND_NODE, GET_VALUE, PUT_VALUE, GET_PROVIDERS, and ADD_PROVIDER.

Each request or response read has a configurable ReadTimeout (default 30 seconds), covering its complete length prefix and protobuf body. It is independent of OperationTimeout, starts after request transmission for outbound exchanges, and ends after deserialization. Handler execution and writes have no new deadline; outbound ADD_PROVIDER starts no response timer. Timeouts must be positive and finite, no larger than TimeSpan.FromMilliseconds(uint.MaxValue - 1). An optional DI TimeProvider controls read deadlines.

Each Kademlia registration admits at most MaxInboundStreams (512) concurrent inbound exchanges in total and MaxInboundStreamsPerPeer (64) per authenticated remote identity. Both limits must be positive. Local peers created from the same registration share its allowance, including across sessions for the same remote identity. Refused streams are reset before handler dispatch; completed, cancelled, or failed streams release their allowance. An admitted exchange consumes its allowance through handler execution and response writing. These local policies apply through AddKadDht, services plus WithKadDht, and AddKadDhtProtocols; they do not change wire framing or client-mode admission. Custom builders must support the limit-bearing AddProtocol overload; unsupported builders throw NotSupportedException.

Read deadline failures remain at Debug and increment libp2p.request_response.read_timeouts on the dotnet-libp2p meter, tagged with the protocol ID and inbound or outbound direction. Admission refusals retain their separate libp2p.streams.inbound.refused counter.

FIND_NODE sends raw target-key bytes; the receiver hashes those bytes with SHA-256 once for distance calculations. The sender and local routing table use the same rule. Relayed multiaddresses retain the destination peer ID after /p2p-circuit rather than treating the relay as the destination.

ADD_PROVIDER is a one-way wire operation. The sender does not wait for a response, but dialing and writing failures still propagate. PUT_VALUE and GET_VALUE use request/response messages. The higher-level DhtClient replicates to and queries the nearest peers currently known to its local routing table; it does not perform an additional iterative network search.

The default in-memory provider store retains at most MaxProviderKeys (10,000) keys, MaxProvidersPerKey (20) providers per key, and inspects the first MaxAddressesPerProvider (16) addresses per record. MaxProviderRecordBytes (1,024) bounds each record's variable-length payload: twice the Base64 key length, plus the peer ID byte length, twice its Base58 dictionary-key length, and twice the sum of retained address-string lengths. The shared key is conservatively charged to every record. Object and collection overhead and transient message parsing are additional.

Records whose key and identity alone exceed that budget are rejected. Whole addresses that do not fit are omitted, preserving the order of those retained; malformed or skipped wire entries still consume an address slot. Zero retained addresses is allowed. The store owns a read-only address-list snapshot. Incoming announcements apply the same payload policy before calling a custom store; custom stores own their aggregate limits. Operators may raise these positive limits explicitly.

Wire peer responses have separate positive limits: MaxPeerIdBytes (128 bytes), MaxAddressesPerPeer (16 closer-peer address slots), MaxPeerRecordBytes (8 KiB per peer), and MaxPeerResponseBytes (64 KiB across both peer lists). The first KSize closer entries and MaxProvidersPerKey provider entries are inspected; provider addresses use MaxAddressesPerProvider. Invalid, duplicate, and skipped entries consume slots. GET_PROVIDERS gives provider records priority when building and reading a response; closer peers use the remaining combined budget. Provider records can still be truncated when they exhaust that budget themselves. Encoded bytes (including protobuf peer-field framing) and retained payload are bounded independently. Retained payload charges both identity copies and UTF-16 address strings, including destination IDs appended during normalization. Admitted address parsing consumes budget even on failure; oversized whole addresses are skipped. These response limits also apply to custom stores and nearest-peer callbacks and do not replace the provider store's retention limits above.

When serving FIND_NODE, the requester is excluded before the wire policy applies the KSize output limit. A separate inspection budget bounds the callback iterator to at most KSize + 1 candidates. The registered routing callbacks exclude the requester during the table lookup, before its own K limit, so a requester among the nearest peers does not leave the response short. Custom callbacks should supply up to KSize + 1 candidates when available. Repeated requester, invalid, or duplicate entries never extend the bounded prefix, so a response can still be shorter than KSize.

Wire identities must be complete multihashes with minimal unsigned varint headers of at most nine bytes and an exact digest length; unknown hash codes remain structurally acceptable. Response addresses bound to another destination are omitted. Received closer peers without usable addresses are excluded from lookup and discovery; provider records may still have no addresses. Protobuf parsing is separately bounded by MaxMessageSize; response budgets bound subsequent conversion and retention. These limits bound one response, rather than cumulative discovery over many requests.

The public MessageHelper.ToWirePeer and CreateAddProviderRequest helpers throw ArgumentException for malformed peer IDs or IDs exceeding the default 128-byte limit. Response builders omit invalid entries instead. Callers using the public helpers should validate their inputs or handle that exception.

PUT_VALUE echoes a record only when the store reports that its bytes were stored. The envelope and record keys must match. Channel closure cancels cancellation-aware storage operations, and cancelled operations produce no acknowledgement. Connection flags default to NOT_CONNECTED; registered response handlers report CONNECTED only for a matching successfully established session whose closure token is live. This is evidence at serialization time, rather than a guarantee of future reachability.

Wire semantics follow the Kad-DHT specification and multiformats unsigned varint encoding. The conservative connection mapping also matches go-libp2p.

At key capacity, new keys are rejected while all buckets contain live records. Existing providers can still refresh, and expired providers on the requested key are pruned before admission. A fully expired unrelated bucket is reclaimed when needed, even without RunAsync or intervening reads. Maintenance and lookups also remove expired records; expiration occurs strictly after StoredAt + Ttl. Live records are never evicted to admit a new key. These are local resource limits and do not change the wire protocol.

Bucket refresh uses approximate random raw-key sampling. A FIND_NODE receiver hashes the raw key, so selecting raw bytes that hash into a particular bucket prefix would require finding bytes with a chosen SHA-256 prefix. This limitation replaces the former non-wire-compatible PublicKey.FromHash shortcut.

Migrating from the in-tree Kademlia implementation

This migration intentionally changes the public API. Generic routing and lookup types now come from Nethermind.Kademlia. ValueHash256.Bytes is a ReadOnlySpan<byte>; use ValueHash256.FromBytes(...) to construct a hash and hash.Bytes.ToArray() when an owned array is needed. The mutable Bytes setter and BytesAsSpan accessor are no longer available. Consumers must rebuild against the new package API.

License

This project is MIT-licensed. The separate Nethermind.Kademlia package has its own license metadata.

Builder and compatibility migration

Automatic protocol activation now happens at Build(), after builder Services registrations are complete. Supplied services remain available during configuration; new builder registrations resolve at build time, including nested constructor and factory dependencies. Builder registrations take precedence over the supplied provider. The first successful build freezes registrations and subsequent builds return the same factory. Late service or protocol changes throw InvalidOperationException. Dispose the builder (or the containing DI provider) after its peers; it disposes its own services and implicitly created protocols while leaving explicit instances and supplied services owned by their original registration. A failed build can be corrected and retried. Factories for different registrations may run concurrently. Factory calls and supplied provider resolution run outside the container cache lock. Disposal rejects new resolutions and waits for active resolutions before disposing owned services; concurrent disposal calls await the same cleanup.

AddKadDht, AddKadDht on IServiceCollection, and WithKadDht share the same request handler. The standard builder creates routing state and runtime identity lazily once per peer; it does not require an ILocalPeer singleton. GetKadDht(), GetProtocol<KadDhtProtocol>(), and RunKadDhtAsync() still work. The runtime is not a second negotiated listener. Client mode keeps outbound dialing available while refusing inbound DHT negotiation and omitting DHT from Identify. The additive ProtocolRef.AcceptInbound flag controls listener negotiation separately from IsExposed; other protocol registrations keep their previous defaults. Custom builders can implement the additive IPeerServiceBuilder and IProtocolFactoryBuilder capabilities. Existing builder interfaces have no new mandatory members. Handler-only custom builders remain supported when they enforce the inbound stream allowance.

Kademlia registrations now always attach an InboundStreamLimit, including with default options. A custom builder implementing only the two-argument AddProtocol(instance, isExposed) now throws NotSupportedException when registering Kademlia. Implement the three-argument overload and enforce its allowance, or provide IProtocolFactoryBuilder support that honors ProtocolRef.InboundLimit. Zero limits are invalid; there is no configuration switch to silently restore unlimited inbound streams.

Retrieve a client's peer-bound service with ((IPeerServices)peer).GetPeerService<DhtClient>(). The existing singleton-peer DI pattern also retains GetRequiredService<KadDhtProtocol>() and now registers DhtClient. Explicit store arguments override registered stores; registered stores override defaults. Store instances retain their configured capacities and existing DI sharing semantics, while each peer has its own routing state. Use a separate provider per peer when stores must also be isolated.

DhtClient retains its original constructor and string methods and adds a constructor accepting IDhtMessageSender, IValueStore, IRecordValidator, and KadDhtOptions. The old constructor is obsolete. DhtClient now implements IDisposable and IAsyncDisposable; peer disposal cancels and drains its active operations. Dispose manually constructed clients after use; prefer asynchronous disposal when operations are active. Both paths validate PUTs and cached/remote GET results, select valid remote candidates through the validator, and propagate caller cancellation. Rejected local writes do not count as storage successes. A valid lookup can return a value even when cache capacity prevents storing it. Default production validation uses CompositeRecordValidator, including signed IPNS validation. GET responses must carry the requested record key. Local and wire reads revalidate custom or legacy store content. These intentional behavior changes reject records previously accepted without validation. For binary keys and values (including IPNS), use the byte-oriented KadDhtProtocol API; the legacy string client continues to encode and decode UTF-8.

Public API inspection found exported signatures for both TestNode types, TestNodeAddressBook, PublicKeyKeyOperator, KademliaSessionManager, ISessionManager, SessionOptions, the generic network sender, and the legacy value store. Absence of in-tree consumers does not establish external usage. No public type, constructor, or method was removed or internalized. Both TestNode types, the address book, key operator, session manager, generic sender, old client constructor, and SharedDhtState.ValueStore are deprecated with Obsolete warnings. Existing consumers using warnings-as-errors must migrate or acknowledge those warnings specifically at their legacy call sites. Use DhtNode, KadDhtProtocol, IDhtMessageSender, and IValueStore for new code. The compatibility session manager adapts legacy nodes at its boundary and runs the routing algorithm on DhtNode; production DI does not register TestNode-based services. The internal test transport helper lives in the test assembly.

SharedDhtState.ValueStore is a synchronous compatibility facade over the authoritative IValueStore, with no second dictionary or cleanup timer. Standalone DhtValueStore construction remains supported; reads filter expiration, and explicit store cleanup reclaims expired entries. The facade does not own or dispose its backing store. Production operations use the asynchronous store directly. There is no wire ID or protobuf change. The DhtClient constructor accepting an IValueStore binds the supplied state's compatibility facade to that store and the configured record TTL once, atomically. Subsequent clients must supply the same store instance and TTL or construction throws InvalidOperationException; concurrent clients cannot replace each other's facade. Reading ValueStore or constructing a legacy client also fixes the existing binding, so a facade already handed to a caller cannot become detached. Legacy clients inherit that binding's record TTL. Same-store clients retain the same facade instance. Use separate state objects for different stores or TTLs. Production registration binds the store when creating each peer-bound state.

If protocol activation fails, builder rollback attempts both directly activated and container-owned cleanup and restores the configuration for retry. Cleanup exceptions do not replace the original build exception; they are retained as an AggregateException in its Data["RollbackFailures"] entry.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Nethermind.Libp2p.Protocols.KadDht:

Package Downloads
Nethermind.Libp2p

A libp2p implementation for .NET

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.1.4 0 11/15/2026