DOCSEARCHbyAlgolia
Submit Docs

pkarr

repository·main·Indexed 19 days ago

https://github.com/pubky/pkarr

An I/O library for Public-Key Addressable Resource Records (Pkarr) that enables users to turn Ed25519 public keys into decentralized domain names. It allows publishing and resolving signed DNS records (A, AAAA, TXT, CNAME, NS, HTTPS, SVCB) over the BitTorrent Mainline DHT using the BEP44 protocol. Available as a Rust crate and a JavaScript/TypeScript library (@synonymdev/pkarr) via WebAssembly, with an accompanying pkarr-relay server for browser-based network interaction.

Tokens
34.7K
Snippets
107
Records
156
Agent score
64%

What's inside pkarr

  1. What is Pkarr?

    main

    Pkarr (Public-Key Addressable Resource Records) is a system that uses Ed25519 public keys as sovereign, censorship-resistant top-level domains. It enables users to own their online identity without relying on centralized registrars or platforms by publishing self-signed DNS records to the Mainline DHT (Distributed Hash Table).

    Key features include:

    • Cryptographic Identity: Your identity is your Ed25519 public key.
    • Decentralized Discovery: Uses the Mainline DHT (the same network powering BitTorrent) for record discovery.
    • Standard DNS Records: Supports A, AAAA, TXT, CNAME, and other standard DNS resource records.
    • Sovereignty: Since you hold the private key, you can update your records to point to new providers without losing your identity.

  3. Use Relays for UDP-less environments

    main
    In environments where UDP is unavailable (such as web browsers, virtual machines, containers, or firewalled networks), clients must use a remote Relay server to proxy PUT and GET messages to the DHT network. Relays act as intermediaries that perform DHT operations on behalf of the client.

  4. Understand the SignedPacket data structure

    main

    The SignedPacket is the fundamental unit of data in Pkarr. It contains the DNS records and the cryptographic proof required to verify them. Because the Mainline DHT has a 1000-byte limit, the DNS packet portion is compressed.

    ComponentSizeDescription
    Public Key32 bytesEd25519 public key identifying the owner
    Signature64 bytesEd25519 signature proving authenticity
    Timestamp8 bytesMicrosecond UNIX timestamp for versioning
    DNS PacketUp to 1000 bytesCompressed DNS resource records

    The timestamp is used for versioning (newer timestamps supersede older ones), and the signature covers both the timestamp and the DNS packet to prevent tampering.

  5. Understand how Resolvers work

    main

    Resolvers are specialized, well-known, and long-running DHT nodes that function similarly to DNS resolvers.

    Workflow for a get request for a mutable value:

    1. Cache Check: The resolver checks its cache of Signed Pkarr packets.
    2. Cache Hit: The resolver returns the packet encoded according to Bep_0044.
    3. Cache Miss: The resolver queries the DHT directly to fetch the data, then caches the result for subsequent requests to the same Pkarr key.

    Key Characteristics:

    • Latency: Offers lower latency than standard DHT traversal (especially for frequent keys) by utilizing an LRU (Least Recently Used) cache.
    • Reliability: Provides more stable storage and uptime compared to standard DHT nodes, which often suffer from high churn and limited resources.
    • Censorship Resistance: They are used in parallel with the DHT, not as a replacement, ensuring they do not negatively impact the network's censorship resistance.

  6. Manage record lifecycle: Ephemeral storage and republishing

    main

    Pkarr records are ephemeral. The Mainline DHT does not store data permanently; records are dropped after hours or days if not refreshed. This prevents the network from accumulating stale data but requires active management.

    To keep your identity discoverable, you must republish your records periodically via:

    • Automated Clients: Running a client that handles automatic republishing.
    • Associates: Having trusted peers republish your records.
    • Hosting Providers: Using providers that are incentivized to keep your records alive.

  7. How Pkarr endpoint resolution works

    main

    Pkarr uses a combination of SignedPacket lookups and DNS-style resource records (specifically HTTPS, A, and AAAA) to resolve endpoints.

    For standard web access, it is recommended to use SVCB and HTTPS (RFC 9460) records. This allows servers to be accessed via URLs like https://<pkarr key>.

    Clients resolve a <pkarr key> by:

    1. Fetching the SignedPacket for the key.
    2. Using A or AAAA records for IP addresses.
    3. Using HTTPS records to discover port numbers and protocol parameters like Encrypted Client Hello (ECH) and ALPN (for HTTP/2 and HTTP/3).

    For custom protocols (e.g., foo://<pkarr key>), the client fetches the SignedPacket for the key and searches for an HTTPS record named _foo.<pkarr_key>.

  8. How Pkarr public key encoding works

    main

    Pkarr represents Ed25519 public keys as human-typeable strings using z-base32 encoding. This produces a 52-character string consisting only of lowercase letters and digits, making them suitable for use in URIs.

    Example of a Pkarr public key: o4dksfbqk85ogzdb5osziw6befigbuxmuxkuxq8434q89uj56uyy

    Example of a Pkarr URI: https://o4dksfbqk85ogzdb5osziw6befigbuxmuxkuxq8434q89uj56uyy

    o4dksfbqk85ogzdb5osziw6befigbuxmuxkuxq8434q89uj56uyy

  9. How PKARR works: Identity, Signing, and Resolution

    main

    PKARR turns Ed25519 public keys into domain names by leveraging the BitTorrent Mainline DHT.

    The Workflow

    1. Generate a keypair: Your Ed25519 public key serves as your domain name.
    2. Sign DNS records: You create self-signed standard records (A, AAAA, TXT, CNAME).
    3. Publish to the DHT: Records are stored on the Mainline DHT using BEP44 (mutable items).
    4. Resolve: Anyone can query the DHT to verify and retrieve your signed records.

    Important Constraints

    • Ephemeral Records: The DHT drops records after a few hours; you must republish periodically.
    • Size Limit: There is a 1000-byte limit per record. PKARR is intended for discovery, not large-scale data storage.
    • Relays: Because browsers cannot open UDP sockets, web applications use HTTP relays to interact with the network.

  10. Understand Pkarr Resolve Policies

    main

    When calling client.resolve(), choose a ResolvePolicy based on your consistency requirements:

    • ResolvePolicy::CacheFirst: (Recommended for most apps) Returns fresh cached packets. It queries the network on a cache miss or if the cache entry is expired. It does not fall back to expired local cache entries.
    • ResolvePolicy::CacheOnly: Returns a locally cached or relay-cached packet even if it is expired. It may perform an HTTP relay request on a local miss, but it never queries DHT nodes.
    • ResolvePolicy::NetworkOnly: Queries the network for the most recent state. Use this before rebuilding and publishing an updated packet.

    Note on Errors: When using NetworkOnly, handle ResolveError::InvalidSignedPacket separately from ResolveError::NotFound. An InvalidSignedPacket error indicates a newer sequence exists that did not contain a valid PKARR packet, rather than the key being missing.

  12. Configure network access: DHT vs Relays

    main

    Pkarr provides two ways to access the network, and your choice depends heavily on your target platform.

    • dht: Provides direct Mainline DHT access for publishing and resolving records. Note: This is not available in WASM environments.
    • relays: Provides HTTP relay support. This is required for WASM/browser applications where direct DHT access is unavailable.
    • full-client (default): Combines both dht and relays support.
    # For direct DHT access (Native only)
pkarr = { version = "7", default-features = false, features = ["dht"] }

# For WASM/Browser (Relays only)
pkarr = { version = "7", default-features = false, features = ["relays"] }