Architecture

Five layers.
Clean separation.

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 ↓

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 Reserve, waits, commits, or compensates LIFO. AgentSelector uses Thompson Sampling.

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
CSN3 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