Agent Action Receipt Specification (AAR v1.0)

Status of This Document

This document defines version 1.0 of the Agent Action Receipt (AAR) format. It is written in an RFC-style profile intended for direct implementation.

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in RFC 2119.

1. Abstract

Agent Action Receipt (AAR) is a lightweight, cryptographically signed receipt format for AI agent actions. AAR enables verifiable audit trails for agent-to-agent commerce, regulatory compliance, and dispute resolution. The format is transport-agnostic, deterministic under canonical serialization, and suitable for machine verification.

2. Motivation

As AI agents perform autonomous actions (API calls, payments, content generation, trades), stakeholders require verifiable evidence of what occurred, who initiated it, when it happened, and what it cost. Existing approaches are ad hoc and platform-specific, which prevents cross-platform auditing and weakens evidentiary integrity. AAR provides a common format and verification procedure so independent parties can validate receipts without trusted intermediaries.

3. Use Cases

1. Agent commerce (x402/payment verification): bind payment evidence and action execution in one signed artifact.
2. Trading signal provenance: prove origin and timing of strategy outputs used for execution.
3. Content generation audit trails: attest model runs, prompts (by hash), and outputs (by hash).
4. Enterprise compliance exports: produce machine-verifiable records for governance and regulators.
5. Multi-agent workflow accountability: track handoffs and responsibility across agent graphs.

x402 is a complementary standard for payment flow semantics; AAR complements x402 by adding cryptographic action attestations.

4. Receipt Format

4.1 Media Type and Encoding

• A receipt is a UTF-8 JSON object.
• Canonical form for signing MUST use canonical JSON serialization (Section 5).

4.2 Top-Level Fields

An AAR receipt object MUST include the following fields:

• receiptId (string): globally unique identifier (UUID format RECOMMENDED).
• agent (object): identity of the acting agent.
• principal (object): identity of the principal on whose behalf the action was performed.
• action (object): action type, target, method, and result status.
• scope (object): authorization/payment scope and constraints.
• inputHash (object): hash of canonicalized or normalized input payload.
• outputHash (object): hash of canonicalized or normalized output payload.
• timestamp (string): action completion timestamp in RFC 3339 format.
• cost (object): execution and/or payment accounting.
• signature (object): signature metadata and detached signature bytes.
• metadata (object): extension bag for protocol-specific attributes.

4.3 Field Definitions

4.3.1 agent

• id (string, REQUIRED): stable agent identifier (DID, URI, or vendor namespace).
• name (string, OPTIONAL): human-readable name.
• version (string, OPTIONAL): agent/runtime version.
• publicKey (string, OPTIONAL): base64url Ed25519 public key if not resolved by signature.kid.

4.3.2 principal

• id (string, REQUIRED): principal identifier (user, org, service account).
• type (string, REQUIRED): e.g., user, organization, service.

4.3.3 action

• type (string, REQUIRED): semantic action label, e.g., api.call, trade.signal, content.generate.
• target (string, REQUIRED): target resource URI, route, or contract identifier.
• method (string, OPTIONAL): operation verb such as GET, POST, EXECUTE.
• status (string, REQUIRED): terminal action status (success, failure, partial).

4.3.4 scope

• permissions (array of string, REQUIRED): grants used by the action.
• constraints (object, OPTIONAL): limits such as region, budget, or model policy.
• x402 (object, OPTIONAL): payment attributes when x402 is used.

4.3.5 inputHash and outputHash

• alg (string, REQUIRED): hash algorithm (sha256 RECOMMENDED).
• digest (string, REQUIRED): base64url-encoded digest bytes.

Raw sensitive inputs/outputs SHOULD NOT be embedded in receipt content; hashes SHOULD be used for privacy and minimization.

4.3.6 cost

• amount (string, REQUIRED): decimal string to avoid floating-point ambiguity.
• currency (string, REQUIRED): ISO 4217 code or protocol-specific token symbol.
• unit (string, OPTIONAL): e.g., request, token, execution.
• payer (string, OPTIONAL): actor funding the action.

4.3.7 signature

• alg (string, REQUIRED): MUST be Ed25519 for AAR v1.0.
• kid (string, REQUIRED): key identifier resolvable to a trusted public key.
• publicKey (string, OPTIONAL): base64url Ed25519 public key; MAY be omitted when resolver is available.
• canonicalization (string, REQUIRED): MUST be JCS-SORTED-UTF8-NOWS.
• sig (string, REQUIRED): base64url detached signature over canonical bytes.

4.3.8 evidenceRef (OPTIONAL)

Array of external evidence bundle references. Each entry is a hash pointer to an independently verifiable proof artifact that provides deeper audit coverage beneath the receipt layer.

• type (string, REQUIRED): evidence bundle type identifier (e.g., aelitium/binding-bundle, ai-decision-tracer/audit-trail, insumer/attestation, scc/certificate-chain).
• hash (object, REQUIRED): content hash of the referenced artifact, using the same hashObject format as inputHash/outputHash.
• uri (string, OPTIONAL): retrieval URI for the evidence bundle (HTTPS, IPFS, Arweave, or other content-addressable store).
• issuer (string, OPTIONAL): identifier of the entity that produced the evidence.

Evidence references enable layered trust: the receipt proves what the agent did, while referenced bundles can prove what the model returned (LLM call bindings), that state transitions were valid (coordination proofs), or that the agent's identity is attested (on-chain credentials). Each layer is independently verifiable.

Verifiers MAY fetch and validate evidence bundles; verification of the receipt itself MUST NOT depend on evidence bundle availability.

4.3.9 metadata

Opaque extension object. Producers MAY include protocol-specific fields (e.g., x402 payment reference, model/provider tags, trace IDs). Unknown fields MUST be ignored by verifiers unless local policy requires them.

4.4 JSON Schema

The authoritative JSON Schema for AAR v1.0 is provided at:

• schema/receipt.json

Implementations SHOULD validate against that schema before signature verification.

5. Signing

AAR v1.0 uses Ed25519 with canonical JSON serialization.

5.1 Canonical Serialization

Canonicalization algorithm identifier: JCS-SORTED-UTF8-NOWS.

The signing payload MUST be created as follows:

1. Start from the full receipt object.
2. Replace signature.sig with an empty string ("") or remove it from the canonicalized payload; this specification uses removal.
3. Recursively sort all object keys lexicographically (Unicode code point order).
4. Emit JSON with no insignificant whitespace.
5. Encode as UTF-8 bytes.

5.2 Signature Generation

1. Compute canonical payload bytes (Section 5.1).
2. Sign bytes with Ed25519 private key selected by signature.kid.
3. Base64url-encode signature bytes without padding.
4. Place result into signature.sig.

6. Verification

Verifier procedure:

1. Parse JSON and validate required fields.
2. Ensure signature.alg == "Ed25519" and signature.canonicalization == "JCS-SORTED-UTF8-NOWS".
3. Resolve public key in this order:
   1. signature.publicKey if present.
   2. agent.publicKey if present.
   3. Resolver lookup by signature.kid (implementation-specific trust store).
4. Rebuild canonical payload from receipt with signature.sig removed.
5. Base64url-decode signature.sig and public key.
6. Verify Ed25519 signature over canonical payload bytes.
7. Evaluate policy checks:
   • receipt freshness and expiration,
   • replay detection (receiptId uniqueness),
   • scope/permission conformance,
   • optional input/output hash recomputation when raw artifacts are available.

Verification result SHOULD include boolean validity plus explicit failure reason.

7. Transport

A receipt MAY be transported in either of the following ways:

1. HTTP header

   • Header name: X-Agent-Receipt
   • Value: base64url-encoded UTF-8 JSON receipt.

2. HTTP response body

   • Field name: receipt
   • Value: raw JSON object receipt.

If both are present, they MUST be byte-equivalent after decoding/parsing; mismatch MUST be treated as an error.

8. Discovery

Services advertising AAR support SHOULD expose:

• /.well-known/trust-layer

Example capability document:

{
  "agentActionReceipt": {
    "version": "1.0",
    "algorithms": ["Ed25519"],
    "canonicalization": "JCS-SORTED-UTF8-NOWS",
    "transport": ["X-Agent-Receipt", "body.receipt"],
    "schema": "https://example.com/schemas/aar/v1/receipt.json",
    "jwks": "https://example.com/.well-known/jwks.json"
  }
}

9. Security Considerations

1. Key rotation: kid MUST support rotation; verifiers SHOULD retain historical keys for signature validity windows.
2. Replay protection: consumers SHOULD enforce uniqueness of receiptId and bounded timestamp skew.
3. Privacy: include hashes of sensitive inputs/outputs, not raw payloads, unless policy explicitly requires retention.
4. Receipt expiration: implementations SHOULD define TTL policy and reject stale receipts outside allowed windows.
5. Trust anchors: verification is only as strong as key distribution; use authenticated key discovery (e.g., pinned JWKS, DID method policies).
6. Canonicalization safety: signing and verifying code MUST use identical canonicalization behavior; divergence invalidates signatures.

10. Reference Implementation

Reference implementation target: BotIndex (king-backend).

Repository/path integration is implementation-specific; this specification defines interoperability requirements independent of runtime framework.

11. Authors

• Andrew Glaz (@cyber_weasel)

12. License

MIT License. See LICENSE.

13. SDKs

TypeScript

npm install botindex-aar

• npm: https://www.npmjs.com/package/botindex-aar
• Source: https://github.com/Cyberweasel777/King-Backend

Python

pip install botindex-aar

• PyPI: https://pypi.org/project/botindex-aar/
• Source: https://github.com/Cyberweasel777/botindex-aar-python

Aztec (Noir)

Zero-knowledge proof circuit for on-chain receipt verification.

• Source: https://github.com/Cyberweasel777/aar-noir-verifier

14. Extensions

Session Continuity Certificates (SCC)

SCC extends AAR to cover identity continuity across sessions. While AAR proves what an agent did, SCC proves the agent acting today is the same continuous agent that was granted authority previously.

Key features:

• Merkle tree over memory and capabilities — enables selective disclosure
• Chain validation — cryptographic linkage between sessions with gap detection
• Drift detection — signals when capabilities or memory mutate between sessions
• SR 11-7 compliant — capability lineage DAG for regulatory audit

Full spec: SCC.md

npm install botindex-aar@1.1.0  # TypeScript SCC support included

Co-developed with @botbotfromuk from FINOS ai-governance-framework.

15. Links

• Landing: https://aar.botindex.dev
• Live API (reference implementation): https://api.botindex.dev
• MCP Server: https://www.npmjs.com/package/botindex-mcp-server