Crate pkarr 

Pkarr

Pkarr turns Ed25519 public keys into sovereign domain names. This crate creates and verifies signed DNS packets, then publishes and resolves them through the Mainline DHT, HTTP relays, or both.

Installation

cargo add pkarr

The example below uses Tokio as its async runtime:

cargo add tokio --features macros,rt-multi-thread

Quick Start

use pkarr::{Client, Keypair, ResolvePolicy, SignedPacket};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let keypair = Keypair::random();
    println!("Public key: {}", keypair.public_key());

    let packet = SignedPacket::builder()
        .txt("_hello".try_into()?, "world".try_into()?, 300)
        .sign(&keypair)?;

    let client = Client::builder().build()?;
    let stored_on = client.publish(&packet).await?;
    println!("Stored on at least {stored_on} DHT nodes");

    let resolved = client
        .resolve(&keypair.public_key(), ResolvePolicy::CacheFirst)
        .await?;
    println!("Resolved:\n{resolved}");

    Ok(())
}

The client API is asynchronous. Tokio is used here to run the example; on native targets, Pkarr also supports other executors through async_compat.

Choosing Features

Use case	Command
Native application using DHT and relays	cargo add pkarr
DHT only	cargo add pkarr --no-default-features --features dht
Relay only or browser/WASM	cargo add pkarr --no-default-features --features relays
Sign and verify packets without networking	cargo add pkarr --no-default-features --features signed_packet
Key generation and parsing only	cargo add pkarr --no-default-features

The default full-client feature enables both DHT and relay support. Browsers cannot access the UDP DHT directly and must use relays; WASI is not supported. Optional features also provide persistent LMDB caching, endpoint discovery, and reqwest integration. See the feature reference for the complete list.

Next Steps

• Quickstart
• Integration guide
• Examples
• API documentation

Feature flags

• dht (enabled by default) — Enable the Client with mainline support.

• relays (enabled by default) — Enables Client with Relays.

• lmdb-cache — Use the LmdbCache implementation.

• endpoints — Enables endpoints spec.

  Only available if the client module is enabled.

• tls — Enables tls spec.

  Only available if the client module is enabled.

• reqwest-resolve — Use reqwest::dns::Resolve trait implementation for Client.

  Only available if the client module is enabled.

• reqwest-builder — Create a reqwest::ClientBuilder from Client.

  Only available if the client module is enabled.

• full-client (enabled by default) — Use all features

• extra — Extra features that might benefit most but not all developers building apps using Pkarr.

  Only available if the client module is enabled.

• full — Use all features including the full-client and extra features.

• __client (enabled by default) — Enable client dependencies.

  Does not enable anything on its own you need to enable either dht and/or relays to enable the Client.

  Except in WASM where you have to enable relays, while dht does not do anything.

Re-exports

pub use simple_dns as dns;

pub use types::*;

Modules

dht

Mainline DHT integration.

errors

Exported errors

extra

Extra features that might benefit most but not all developers building apps using Pkarr.

relay_client

Single-relay HTTP client.

types

Protocol data types.

Structs

Client

Pkarr client for publishing and resolving SignedPackets over the configured networks.

ClientBuilder

A builder for constructing a Client with custom configuration.

InMemoryCache

A thread-safe wrapper around lru::LruCache.

Timestamp

Strictly monotonic timestamp since SystemTime::UNIX_EPOCH in microseconds.

Constants

DEFAULT_CACHE_SIZE

Default cache size: 1000

DEFAULT_MAXIMUM_TTL

Default maximum TTL: 24 hours.

DEFAULT_MINIMUM_TTL

Default minimum TTL: 5 minutes.

DEFAULT_RELAYS

Default Relays.

DEFAULT_REQUEST_TIMEOUT

Default request timeout for DHT and relay requests.

PKARR_DHT_STORED_NODES

Relay response header carrying the number of DHT nodes that acknowledged storing a published packet.

PKARR_INVALID_SIGNED_PACKET_SEQ

Relay response header carrying the mutable item sequence number when the DHT has a newer mutable item that is not a valid signed packet for a key.

Traits

Cache

A cache for SignedPackets used by a Pkarr crate::Client.

Type Aliases

CacheKey

The SHA-1 hash of the crate::PublicKey used as the key in Cache.