Thinking in LLM + harness terms — brain, tools, skills, RAG? There's a mapping for that.

Where Aroha fits in your agent's anatomy →
Architecture

Five layers.
Clean separation.

Aroha is the trust layer between your AI agents — it makes sure every request is signed, every spending limit is enforced, and every action can be traced back to the human who approved it.

If you are building your first agent, start with the Quickstart — the SDK handles every layer automatically. Come back here when you need to understand what is happening beneath the surface.

The kernel never imports the extensions. Extensions never import the application. Every layer is independently testable and replaceable.

  • →Dependencies flow downward only
  • ⊥No circular imports across layers
  • ✓Each layer has its own test suite
  • ∅Zero upward extension dependencies

protocol layer stack · dependencies ↓

L04Application LayerConsumer-facing agentsPersonal AgentsProvider AgentsOrchestratorsData AgentCalendar Agentdepends onL03Orchestration LayerMulti-agent coordinationSagaEngineAgentSelectorCSN NegotiatorApprovalGateHumanApprovalGatedepends onL02Extension LayerPluggable, zero upward dependenciescredentialssettlementreputationregistrycachepolicydepends onL01Transport LayerHTTP + WebSocket transportArohaServerArohaClientWebSocketMiddlewareArohaMicrodepends onL00Identity & CryptoFoundation — never imports above itdid:aroha:Ed25519AES-256-GCMSpendingMandateNonceRegistryStrict one-way dependency — no layer imports from a layer above it
Layer Details

What lives in each layer

Layer 04

Application Layer

Your agents live here. They use the layers below without caring about crypto, transport, or saga mechanics.

Personal AgentsProvider AgentsOrchestratorsData AgentCalendar Agent
Layer 03

Orchestration Layer

Multi-agent coordination. SagaEngine fans out sub-tasks, waits for agents to confirm they can handle them, then commits — or rolls everything back if one fails. AgentSelector picks the best agent automatically. Capability Negotiation (CSN) lets two agents agree on what they can do before work starts.

SagaEngineAgentSelectorCSN NegotiatorApprovalGateHumanApprovalGate
Layer 02

Extension Layer

Pluggable packages. Mount only what you need. No extension has an upward dependency on another.

@aroha-sdk/credentials@aroha-sdk/settlement@aroha-sdk/reputation@aroha-sdk/registry@aroha-sdk/cache@aroha-sdk/policy
Layer 01

Transport Layer

HTTP + WebSocket transport. ArohaServer serves /.well-known and /aroha/v1. Middleware runs after signature verification.

ArohaServerArohaClientWebSocket streamsMiddleware chainArohaMicro
Layer 00

Identity & Crypto

Foundation that never imports anything above it. Every envelope is signed; every nonce is tracked.

did:aroha:did:aroha-web:Ed25519 signingAES-256-GCMSpendingMandateNonceRegistry
dependencies flow downward only · no circular imports
Transaction Model

Saga State Machine

Atomic multi-agent transactions with automatic LIFO compensation. Either all agents commit, or all roll back — no partial state.

Wire Protocol

16 Message Types

All wire-compatible across every SDK. Same JSON structure, same Ed25519 signatures, same correlation IDs.

Core4 types
→
ArohaRequest
Capability invocation
←
ArohaResponse
Synchronous result
←
ArohaStream
Streaming event
←
ArohaError
Structured error
Saga6 types
→
ArohaReserve
Saga: reserve hold
←
ArohaReserveAck
Saga: hold confirmed
→
ArohaCommit
Saga: commit
←
ArohaCommitAck
Saga: committed
→
ArohaCancel
Saga: compensate
←
ArohaCancelAck
Saga: cancelled
Capability Negotiation (CSN)3 types
→
ArohaNegotiate
CSN: schema offer
←
ArohaCounterOffer
CSN: counter
←
ArohaAccept
CSN: agreed
Trust / Auth3 types
→
ArohaDelegate
Sub-task delegation
→
ArohaSatisfaction
Reputation signal
→
ArohaSpendingMandate
Payment credential
Security Model

Envelope Anatomy

Every Aroha message is a signed envelope. No bare HTTP payloads. The signature covers the full body — routing headers, nonce, expiry, and payload together.

Ed25519 signatures
Compact, fast, and resistant to side-channel attacks. Keys anchored to DID document.
5-minute nonce window
Replay protection built in. Server maintains a NonceRegistry for the window.
Correlation IDs
UUID v4 ties request → response → stream events across the full saga.
ArohaEnvelope — every message
interface ArohaEnvelope {
  // Routing
  from:          string;  // sender DID
  to:            string;  // recipient DID
  type:          ArohaMessageType;
  correlationId: string;  // UUID v4

  // Security
  nonce:   string;        // replay guard (5 min)
  expires: string;        // ISO 8601
  proof:   string;        // Ed25519 sig (base64url)

  // Payload
  body: ArohaBodyByType[ArohaMessageType];

  // Optional
  traceparent?:  string;  // W3C Trace Context
  routingHint?:  { complexity?: number };
}

Ready to build?

Read the full protocol specExplore the SDKs