DHT message format

Relay DHT protocol · DHT operations

Connections and message framing

DHT operations run between eligible public relays already verified under relay connections and identity authentication. Each stream uses libp2p protocol /meshline/kad/1.0.0; messages are encoded as an unsigned-varint length prefix followed by protobuf bytes, with a maximum message size of 1 MiB. The outer prefix follows the common message length-prefix encoding rules.

Protocol 1.0 does not transmit resources that cannot fit in one message. Oversized content MUST NOT be written to a single Record. Peer eligibility, connection identity, and routing-table maintenance are defined in overlay and node maintenance.

Protobuf messages

DHT streams use the following subset of the libp2p Kademlia protobuf schema. Message is the outer frame for a DHT query or write and its reply; Record carries the resource value for a DHT key; the nested Peer represents a candidate relay peer, closer to the target key, supplied in the reply direction.

message Record {
  optional bytes key = 1;
  optional bytes value = 2;
}

message Message {
  enum MessageType {
    PUT_VALUE = 0;
    GET_VALUE = 1;
    ADD_PROVIDER = 2;
    GET_PROVIDERS = 3;
    FIND_NODE = 4;
    PING = 5;
  }
  enum ConnectionType {
    NOT_CONNECTED = 0;
    CONNECTED = 1;
    CAN_CONNECT = 2;
    CANNOT_CONNECT = 3;
  }
  message Peer {
    optional bytes id = 1;
    repeated bytes addrs = 2;
    optional ConnectionType connection = 3;
  }
  optional MessageType type = 1;
  optional bytes key = 2;
  optional Record record = 3;
  repeated Peer closerPeers = 8;
}

Field semantics

• Message.key carries the operation's raw target input; Message.record.key is the raw 32-byte resource key obtained from the resource-key derivation rules;
• Message.record.value carries the resource content; its encoding and size are specified by the account route resource rules;
• Peer.id is the raw multihash bytes of the candidate Peer ID; each Peer.addrs entry is the binary encoding of a multiaddr. Candidate processing follows connections and identity authentication.

Presence requirements for type, key, record, and closerPeers in each operation are defined in DHT operations.

Extensions and compatibility

• providerPeers, clusterLevelRaw, and unused message types MUST NOT affect resource-query results;
• Unknown protobuf fields are ignored under protobuf compatibility rules.

Message rejection and failure handling

Receivers MUST reject messages whose key length violates the relevant operation's requirements. If a message carries record, it MUST also be rejected when Message.record.key differs from Message.key, or Message.record.value violates the rules for its resource type.

Kademlia messages have no protocol-error response field. Invalid length prefixes terminate the stream under connections and message framing. When rejecting a message because of other framing errors, an oversized message, rate limiting, an invalid key, an invalid record, or an unsupported resource type, the receiver MUST close or reset the corresponding stream.

If the stream terminates before a valid reply is received, the initiator MUST treat the operation as a temporary failure and apply its local backoff policy. It MUST NOT retry immediately in a loop.