---
title: "architecture"
---

In-depth look at the architecture of [PKARR](https://pubky.org/explore/pubkycore/pkarr/introduction.md), including its components, data formats, and how they interact.

## Components

- **Client**: Applications or users that publish or query [PKARR](https://pubky.org/explore/pubkycore/pkarr/introduction.md) records. The main Rust crate provides `Keypair`/`PublicKey` types, `SignedPacket` builder, and `Client` for publishing/resolving.
- **Relay**: HTTP relay for environments without UDP access (browsers, firewalled networks). Also serves as intermediary for services on major cloud providers (AWS, GCP, Azure), whose IP ranges are often blocked by DHT nodes.
- **[Mainline DHT](https://pubky.org/explore/technologies/mainline-dht.md)**: The peer-to-peer network used to announce and resolve [PKARR](https://pubky.org/explore/pubkycore/pkarr/introduction.md) records.
- **Republisher**: Keeps [PKARR](https://pubky.org/explore/pubkycore/pkarr/introduction.md) records alive on the [Mainline DHT](https://pubky.org/explore/technologies/mainline-dht.md) by [periodically republishing](https://github.com/pubky/pkarr-churn/blob/main/results-node_decay.md) them (~hourly). The `pkarr-republisher` component handles this for Homeserver operators.

## SignedPacket Format

```
SignedPacket = public-key(32) + signature(64) + timestamp(8) + dns-packet(≤1000)
```

Maximum total size: 1104 bytes. Public keys are encoded as 52-character z-base32 strings for DNS compatibility. All packets are Ed25519-signed, ensuring authenticity and integrity. Published to the DHT using BEP44 mutable item operations. The `dns-packet` is a standard compressed DNS packet (see [Supported DNS Record Types](#supported-dns-record-types) below).

See the [PKARR repository](https://github.com/pubky/pkarr) for the full format specification and API reference.

## Interaction Flow

1. **Publishing**: Clients publish [PKARR](https://pubky.org/explore/pubkycore/pkarr/introduction.md) to the [Mainline DHT](https://pubky.org/explore/technologies/mainline-dht.md), either directly or through a relay (required for browsers since the DHT uses UDP).
2. **Republishing**: Homeservers and relays republish records for their users to [keep them available](https://github.com/pubky/pkarr-churn/blob/main/results-node_decay.md) on the [Mainline DHT](https://pubky.org/explore/technologies/mainline-dht.md). Records degrade over hours to days without republishing, so hourly republishing is recommended.
3. **Querying**: Clients query the [Mainline DHT](https://pubky.org/explore/technologies/mainline-dht.md) for [PKARR](https://pubky.org/explore/pubkycore/pkarr/introduction.md) using the SHA1 hash of the public key, either directly or through a relay.

## Supported DNS Record Types

A, AAAA, CNAME, TXT, HTTPS/SVCB (RFC 9460).

Pubky discovery usually uses two PKARR records:
- The user's record publishes `_pubky` as an HTTPS/SVCB alias to the [Homeserver](https://pubky.org/explore/pubkycore/homeserver.md) public key.
- The Homeserver's record advertises the actual endpoints, often both a direct [PubkyTLS](https://pubky.org/glossary.md#pubkytls) endpoint and an ICANN endpoint.

```
# User packet, signed by the user key and queried as _pubky.<user-public-key>
_pubky HTTPS 0 <homeserver-public-key>

# Homeserver packet, signed by the Homeserver key
. HTTPS 1 . port=6287
. A 203.0.113.10
. HTTPS 10 homeserver.example.com port=443
```

SDK clients resolve the full `_pubky.<user-public-key>` name so the alias reaches the Homeserver endpoint records. Native SDK clients prefer the direct endpoint when it is reachable and fall back to the ICANN endpoint automatically; browsers use the ICANN-compatible path. During ICANN fallback, the request is sent to the ICANN domain with the user public key preserved in the `pubky-host` header.

## Caching

- **InMemoryCache**: LRU cache for lightweight deployments
- **LmdbCache**: Persistent LMDB-backed cache for relays and servers

## Failure Modes

See [DHT outages](https://pubky.org/explore/pubkycore/security-model.md#scenario-dht-unreachable), [record expiry](https://pubky.org/explore/technologies/mainline-dht.md#data-lifecycle), and [attack resilience](https://pubky.org/explore/pubkycore/security-model.md#dht-attackers).

## Key Technologies

- **[Mainline DHT](https://pubky.org/explore/technologies/mainline-dht.md)**: A global, censorship-resistant p2p network of 10+ million peers. [PKARR](https://pubky.org/explore/pubkycore/pkarr/introduction.md) records are announced here using BEP44.

See [Security Model](https://pubky.org/explore/pubkycore/security-model.md) for the DHT threat model and the [pkarr repository](https://github.com/pubky/pkarr) for code examples and multi-platform support details.