Records and Envelopes
DID-bound records and signed envelopes in the Weave DHT — mutable records with cryptographic provenance.
Purpose
Peer discovery, mutable records, DID envelopes, local relay sessions, adapter registry, record stores, and handles.
This page follows the real source shape for Weave Dht and explains the workflow a developer is likely to use first.
Developer workflow
Start from the smallest constructor or builder, perform one meaningful operation, inspect the returned state, then add the relevant policy, storage, or network integration. The examples below should be expanded whenever the crate API changes.
DHT records are public by default. The signature proves authorship but does not encrypt the payload. Encrypt sensitive content before putting it in the DHT, or use content-addressed records (where the bytes themselves are the key) so that knowing the key implies knowing the content.
Primary types to know
AdapterRegistry— network/weave-dht/src/methods.rsAnnouncementState— network/weave-dht/src/weave.rsAnnounceOpts— network/weave-dht/src/weave.rsDhtClient— network/weave-dht/src/lib.rsDhtConfig— network/weave-dht/src/lib.rsDhtHandle— network/weave-dht/src/lib.rsDhtMethodAdapter— network/weave-dht/src/methods.rsDhtNode— network/weave-dht/src/lib.rsDhtNodeBuilder— network/weave-dht/src/lib.rsDidEnvelope— network/weave-dht/src/envelope.rsEnhancedDhtNode— network/weave-dht/src/enhanced.rsMarsAdapter— network/weave-dht/src/methods.rs
Example shape
use weave_dht::{DidEnvelope, Proof};
fn main() -> Result<(), Box<dyn std::error::Error>> {
// DidEnvelope wraps a DID document plus an Ed25519 JWS proof. The DHT
// validates the proof before accepting a Put.
let envelope = DidEnvelope {
version: 1,
did: "did:oas:weave:agent:alice".into(),
sequence: 3,
timestamp: "2026-02-14T12:00:00Z".into(),
previous_hash: Some("z6Mk-prev-hash-multibase".into()),
controller: vec!["did:oas:weave:agent:alice".into()],
document: serde_json::json!({
"id": "did:oas:weave:agent:alice",
"verificationMethod": [{
"id": "did:oas:weave:agent:alice#key-0",
"publicKeyMultibase": "z6MkABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890abcdef"
}]
}),
proof: Proof {
proof_type: "Ed25519Signature2020".into(),
proof_purpose: "assertionMethod".into(),
verification_method: "did:oas:weave:agent:alice#key-0".into(),
jws: "eyJhbGciOiJFZERTQSJ9..signature".into(),
},
};
// canonicalize_jcs produces the byte form the JWS signs over.
let canonical = weave_dht::envelope::canonicalize_jcs(&envelope.document)?;
println!(
"did={} seq={} controllers={} canonical_bytes={}",
envelope.did,
envelope.sequence,
envelope.controller.len(),
canonical.len(),
);
Ok(())
}