This page is a reading guide. The documents on the main branch of arsialabs/arsia-protocol (opens in a new tab) are the source of truth for Draft-01.1.
One foundation. Five primitives.
Core defines the envelope and the trust model. The five primitives, whose initials spell ARSIA, build on it.
ARSIA-Core(opens in a new tab)Envelope structure, EdDSA signing, discovery, authorization, the compliance field and transport bindings. The foundation for everything else.
ARSIA-Actions(opens in a new tab)Capabilities, human oversight (
pending_approval,approval_decision), explainability, the action registry and rollback.ARSIA-Routing(opens in a new tab)Message routing, compliance broker topology, data residency, delivery guarantees and idempotency.
ARSIA-State(opens in a new tab)State operations (GET, SET, DELETE, QUERY, PURGE), GDPR erasure and portability, and audit trail generation.
ARSIA-Identity(opens in a new tab)Agent identity, certificates and trust levels, onboarding, JWKS discovery and key rotation.
ARSIA-Assets(opens in a new tab)Transaction validation, escrow conditions, asset transfers and MiFID II, DORA and PSD2 controls. Financial intent, not execution.
How to read it
Begin with Core for the envelope, signing and the trust model. Then read the primitives your application needs: Actions for oversight, State for audit and erasure, Identity for onboarding and keys.
Requirements use RFC 2119 keywords. MUST and MUST NOT are absolute; SHOULD allows exceptions you can justify; MAY is optional.
Three version identifiers mean different things: the specification draft (Draft-01.1), the wire version carried in v (1.0), and the SDK release (1.0.1). See versions.
Message intents
| Intent | Purpose |
|---|---|
request | Ask another agent to perform an action, with capabilities, payload and compliance requirements. |
response | Return the result, correlated to the request. |
event | A one-way notification. No response expected. |
error | A structured error with a standard code and description. |
pending_approval | Pause and ask a human reviewer before executing. |
approval_decision | The reviewer’s decision, approved or denied, with a justification. |
Rollback is not a separate intent: it is a request whose payload type is the original action followed by /rollback.
Error codes
Fourteen standard codes, each with an HTTP status and a retry policy, so a failure means the same thing to every implementation.
- invalid_request
- unauthorized
- forbidden
- not_found
- conflict
- payload_too_large
- rate_limited
- internal_error
- not_implemented
- service_unavailable
- certificate_invalid
- certificate_expired
- key_mismatch
- certificate_revoked
Machine-readable artifacts
Every structure has a JSON Schema (Draft 2020-12), and the test vectors exercise valid and invalid messages with real cryptography.
| Artifact | Draft-01.1 |
|---|---|
| JSON Schemas | 31 schemas, JSON Schema 2020-12 |
| Test vectors | 611 vectors: 413 valid, 123 invalid, 75 runtime-only |
| Test keypairs | 57 published: 53 Ed25519, 2 ES256, 2 RS256 |
| Compliance profiles | 7 profiles in one JSON file |
| License | Apache 2.0 for schemas, profiles and test vectors |
Follow changes
Pin your implementation to a reviewed revision, and check the changelog before updating.