Overview & actors

Who participates in Yakr, what they trust, and how the reference implementation is organised across nine phases.

Protocol actors

👤

Client

Alice, Bob — holds keys, encrypts messages, derives mailbox tags

📮

Mailbox relay

Stores opaque blobs indexed by 32-byte mailbox tags

🔀

Entry relay

Forwards onion packets without storing mailbox tags (Phase 2+)

🤝

Rendezvous

Hint-only service for invite pairing (optional HTTP endpoint)

flowchart TB
  subgraph clients ["Clients - trusted with plaintext"]
    Alice[Alice]
    Bob[Bob]
  end
  subgraph relays ["Relays - untrusted for confidentiality"]
    Entry["Entry Relay<br/>Carol node"]
    Mailbox["Mailbox Relay<br/>Dave node"]
  end
  Alice -->|onion packet| Entry
  Entry -->|forward inner layer| Mailbox
  Bob -->|GET blobs by tag| Mailbox
  Alice -.->|signed invite URL| Bob

Trust boundaries

Clients are trusted with plaintext. Relays are untrusted for confidentiality — they see ciphertext, tags, timing, and sizes. Rendezvous is hint-only; pairing secrets never pass through it in the clear.

Reference implementation phases

The Python and Rust stacks implement phased features: single-hop delivery, two-hop onion, path rotation, invites, direct P2P, hybrid PQ pairing, relay groups, and cross-language interop. SeeREFERENCE_DESIGN.md on GitHub.