Identity & key families

Two key families, never mixed:

Records

The unit of all Agora content is the signed record:

{
  "id": "<sha256 hex>",
  "pubkey": "<64-hex BIP-340>",
  "created_at": 1757900000,
  "kind": 40001,
  "tags": [["d", "my-album"]],
  "content": "…",
  "sig": "<128-hex schnorr>"
}

• id = sha256 over the canonical JSON array [0,pubkey,created_at,kind,tags,content] — key order never relied on.
• Signature: BIP-340 schnorr over the id by pubkey.
• Caps: DHT record value ≤ 32 KiB · record content ≤ 64 KiB · HTTP body ≤ 256 KiB · query limit default 500, max 5000.
• Classes: replaceable (0, 3, 10000–19999 — newer wins) · ephemeral (20000–29999 — never stored) · addressable (30000–39999 — one per d tag) · regular (dedup by id).

The record format is deliberately wire-compatible with Nostr's — a documented property that lets old-internet content enter through the node's marked door. The runtime itself imports zero relay-stack code; any change adding such types is rejected by definition.

Kind policy — the only extension surface

App ideas never add node endpoints — ever. Apps sign records with their own keys and compose the four verbs. The registry is the extension surface.

The mailbox — four verbs

Errors — match on the code, never the message

X-Agora-Api: 0
{"error":{"code":"<machine>","message":"<human>"}}
X-Agora-Error: <code>

Guard: loopback-only by default (exact-address check); --public-agora lifts it for mailbox faces only. CORS rides every /agora/* response.

Three transports, one contract

The anonymous drop-off submit face is POST /agora/put?via=onion (kind-1059 wrappers only): 202 acked, 502 dropoff_failed otherwise. The storing node sees only the onion entry hop — never the sender.

Sealing — before it touches a node

put is a dumb pipe: it verifies signature + kind policy and never inspects content. Apps seal private content themselves:

• seal → kind-13 record under the sender→recipient conversation key, signed by the sender's real key.
• gift_wrap → kind-1059 wrapper under a fresh one-time ephemeral key, with 0–2 days of timing jitter.
• The wrapper's p tag is its own ephemeral key — never the recipient. A recipient tag would leak WHO receives every private message to every node storing it.
• Delivery is pull-based via stealth tags (per-message, unlinkable) and inbox pointers signed by the wrapper's one-time key — no long-term key ever touches a stored pointer. Forgery-filtered on fetch.
• Honest residual: the first-contact tag is derivable from the public key alone — the npub leak. Pool tags are the recipient-published mitigation tier.

Every failure has a stable machine code (mac_fail, bad_seal, invalid_rumor, expired, …). The payload format runs against the official vector suite, vendored and executed in full.

Blobs

Replication rides DHT adverts + onion fetch. Serving leaves are opt-in (serve_blobs + blob_dir), content-addressed only from their own dir — they never forward and never charge fees. 32 MiB per-blob serve cap, ≤ 512 sorted adverts per sweep. v0 honesty: adverts carry the local bind address (loopback default) — cross-host serving needs an explicitly routable bind; NAT traversal is deferred.

Money — nano, bilateral, honest

• Unit: one nano = 10⁻⁹ XMR = 1000 piconero. All ledger math is integer nanos — never floats. One conversion site in the codebase, period.
• Ledger: one ledger per PAIR of nodes; every entry is 69 canonical bytes, signed by the authoring peer's swarm key, on a strict per-pair sequence chain. Balance = sum of deltas — order-free.
• Sync: attested balances + bilateral entry transport over onion-direct — a rejected batch never leaks reads; balances converge even when entries raced.
• Credit line: default ±1,000,000 nanos per pair — beyond it, metering degrades gracefully (skipped and counted).
• Fees (node-side metering): relay 1000 nanos/MiB (accrued at WS close) · blob-serve 2000 nanos/MiB. Netting settles pairs across the credit line from a spend-capable wallet, daily, above threshold.
• Mock-proven only: the wallet-rpc paths (tips watcher, netting) have never touched stagenet. The runbook exists; the claim doesn't pretend further.

Money is deliberately excluded from the Leaf profile — apps never carry operator money faces.

Swarm transport

• AGSW framing: one UDP datagram = one message — 4-byte magic, version, message type, payload. Big-endian; requests carry a 32-bit id echoed by the response (concurrent queries on one socket).
• DHT: minimal iterative Kademlia over UDP, 160-bit XOR keyspace, k = 8, α = 3, 2 s request timeout. Records are signed by the storing node; sequence is strictly monotonic; 65,536-record cap with republish-due-first eviction; 15-minute republish.
• Outbox indexing: DHT key blake3-20("outbox:" ‖ pubkey); a pointer record maps NodeId → app key (key families differ). A listed record not authored by the outbox owner is dropped before the store.
• Onion packets: 0x01 ‖ dest_token ‖ eph_pub ‖ AEAD-ct per layer; one ephemeral x25519 keypair per request; entry sees the mid, mid sees the exit, only the exit sees the object key. Answers return to the entry source — never an attacker-steerable target — under per-source rate limits.

The dial — Full / Borrow / Leaf

Versioning

Every /agora/* response carries X-Agora-Api: 0. Apps match on that header and the machine error codes; nothing else is a contract.

Sources & governance

The work lives in sibling repositories: agora-runtime (the protocol, pure — zero relay-stack code, CI-greppable), agora-node (the daemon + the compatibility door), agora-cockpit (node-owner dashboard), agora-feed, agora-photos (apps).

Governance is transparency-log-first: specs are written before the code, decisions live in each repo's plan.md, failures in MISTAKES.md. Where this page and the log disagree, the log wins — and this page is stale.