Aroha Protocol
Reference
A complete reference for every primitive in the Aroha Protocol.
Identity
did:aroha:
Simple DID method. Format: did:aroha:{base58-public-key}. Resolved locally from the key bytes — no network call required.
did:aroha-web:
Two-factor DNS + HTTPS identity. Format: did:aroha-web:{domain}:{path}. Verification requires both HTTPS DID document AND DNS TXT key commitment hash. Key rotation has a 24-hour cool-down with predecessor signature chain.
Ed25519 Signatures
Every envelope is signed by the sender's Ed25519 private key. Recipients verify against the resolved public key. Nonces prevent replay (5-minute rolling window). Expiry fields prevent delayed delivery.
Messages
Envelope structure
Every message: from, to, type, correlationId, nonce, expires, proof (Ed25519 sig), body. Optional: traceparent (W3C Trace Context), routingHint (model complexity hint).
16 message types
ArohaRequest/Response/Stream for capability invocation. ArohaReserve/ReserveAck/Commit/CommitAck/Cancel/CancelAck for saga. ArohaNegotiate/CounterOffer/Accept for CSN. ArohaDelegate, ArohaError, ArohaSatisfaction, ArohaSpendingMandate.
Error codes
Structured ArohaError body: { code, message, retryable, details }. 16 canonical error codes across auth (Aroha_UNAUTHORIZED, Aroha_FORBIDDEN), validation (Aroha_EXPIRED_MESSAGE, Aroha_REPLAY_DETECTED), saga (Aroha_RESERVATION_FAILED, Aroha_COMMIT_FAILED), and availability (Aroha_NO_INVENTORY, Aroha_CAPACITY_EXCEEDED).
Saga Pattern
Reserve phase
All participants receive ArohaReserve in parallel. Each returns ArohaReserveAck with a reservationToken and expiresAt. Default timeout: 10 seconds per step (configurable). A single failure aborts all.
Commit phase
Only starts if every reserve succeeded. Commits are sent sequentially. ArohaCommit is idempotent — safe to retry. If a commit fails, compensation begins immediately.
LIFO compensation
On any failure, ArohaCancel is sent to all RESERVED and COMMITTED steps in reverse order. Cancel handlers must never return ArohaError — they always succeed. The saga log is persisted at every state transition for crash recovery.
Human approval gate
Optional. Any step can be marked requiresApproval=true. After all reserves succeed, the saga pauses at AWAITING_APPROVAL until a human (or policy) approves. Rejection triggers full LIFO compensation.
Spending Mandates
Delegation chain
User → Intent Mandate → Personal Agent → Cart Mandate → Provider Agent → Payment Mandate. Each hop narrows scope. No hop can widen it.
Narrowing constraints
spendLimitUsd, sessionLimitUsd, requireHumanApprovalAboveUsd, allowedMerchants — all four are enforced at each attenuation. A child mandate that raises the approval threshold or adds unlisted merchants is rejected.
Ed25519 signed tokens
Mandates are base64url-encoded JSON + Ed25519 signature. Verifiable offline. TTL enforced client-side and re-checked server-side. Canonical JSON (sorted keys) ensures deterministic signing.
Reputation
Bayesian Beta distribution
Each agent tracked as Beta(α,β). α increments on success, β on failure. Prior: α=2, β=2 (gives new agents a fair chance). 11 weighted signals including response time, cancellation rate, dispute rate.
Thompson Sampling
On each selection, sample θ ~ Beta(α,β) per candidate. Pick argmax θ. Optimal exploration/exploitation — agents with uncertain history get fair exploration. Regret: O(√KT·ln T).
Wilson lower-bound risk gate
Before any saga step, the Wilson lower bound is computed. Agents below the threshold are blocked regardless of their sample. Prevents exploiting sparse data on new agents for high-stakes operations.
Capability Schema Negotiation
Structural matching first
JSON Schema properties are scored structurally. Required fields: weight 1.0. Optional: weight 0.4. number ↔ integer: compatible at 0.7. Score ≥ 0.85 = confident match (no LLM). Score 0.5–0.85 = ambiguous. Score < 0.5 = incompatible.
LLM fallback (optional)
Only triggered for scores 0.5–0.85. The ICapabilityMatcher interface accepts any LLM adapter. Returns the name of the best existing Aroha capability — not a new protocol. Saga semantics are always preserved.
Discovery cache
Agreed schemas are cached by SHA-256(agentDID + schemaHash). Cache miss → full negotiation round. Cache hit → zero-latency lookup. Cache keys are cross-SDK compatible (sorted JSON keys).