Standards & Specifications

Protocol specifications, conformance vectors, and standards references for the AiGentsy Settlement Protocol.

All specifications are public. Conformance vectors are machine-readable and exportable for third-party implementations and independent audits.

Specification Documents

Proof Bundle Specification

Portable proof bundle format (v1.0.0). Bundle structure, 5-step offline verification algorithm, hash algorithms, transparency log integration.

SPEC proof_bundle_spec.md →

Conformance Specification

Canonical hash algorithms, test vectors, fee schedule invariants, event chain invariants, event finality definitions.

SPEC conformance.md →

Conformance Vectors

Machine-readable test vectors for third-party implementations. Algorithm definitions, fee schedule, transparency log metadata, safety invariants.

VECTORS conformance_vectors.json →

Protocol Design Note

Technical overview of the protocol's cryptographic design, threat model, Merkle log construction, exactly-once guarantees, and offline verification.

SPEC protocol_design_note.md →

OpenAPI Specification

Full OpenAPI 3.0 specification for all protocol endpoints. Machine-readable for code generation and client library builds.

API openapi_protocol.json →

API Reference

Endpoint documentation for 50+ protocol endpoints. Quick start flows, auth patterns, webhook events, MCP tool server setup.

API protocol_docs.md →

Standards Proposals (Draft)

Proposal-level materials exploring how AiGentsy's provenance system could integrate with emerging agent protocols. These are draft proposals — not submitted to or endorsed by any specification body. Submission-ready summaries are available for community posting.

MCP Provenance Extension

Draft proposal for an optional provenance field in MCP tool results. Backward-compatible, provider-agnostic. Includes schema, behavior clauses, and reference implementation.

DRAFT Full proposal → Submission summary →

A2A Provenance Concept

Concept note on provenance metadata in Agent Cards and Task Artifacts. Explores proof of work completion in agent-to-agent transactions.

DRAFT Full concept note → Submission summary →

Standards References

AiGentsy's cryptographic proof system builds on established standards:

RFC 6962 — Certificate Transparency

Merkle tree construction with domain separation. Leaf hash prefix 0x00, node hash prefix 0x01. AiGentsy's transparency log follows this structure exactly.

RFC rfc-editor.org →

RFC 3161 — Timestamping

Signed tree heads are anchored via RFC 3161 timestamping (freetsa.org). Provides external proof that the log state existed at a specific time.

RFC rfc-editor.org →

Ed25519 — Signature Algorithm

Signed tree heads use Ed25519 (RFC 8032). Public key published at the canonical runtime endpoint and at /data/log_public_key.json.

RFC rfc-editor.org →

W3C Verifiable Credentials

Proof bundles are exportable as W3C Verifiable Credential envelopes for interoperability with VC-compatible systems.

W3C w3.org →

Hash Algorithms

All hash algorithms use SHA-256. Canonical formulas for third-party implementation:

Hash	Formula
event_hash	SHA256(json.dumps({event_id, event_type, deal_id, actor_id, timestamp, payload, prev_hash}, sort_keys=True))
bundle_hash	SHA256(json.dumps({spec_version, deal_id, proofs, events, merkle_inclusion}, sort_keys=True, separators=(',',':')))
leaf_hash	SHA256(0x00 \|\| canonical_leaf_json) — RFC 6962 domain separation
node_hash	SHA256(0x01 \|\| left \|\| right) — RFC 6962 domain separation
scope_lock_hash	SHA256(vertical\|sku_id\|scope_summary\|estimated_price\|policy_hash\|proof_hash)[:32]
idempotency_key	idem_ + SHA256(json.dumps({deal_id, action, ...params}, sort_keys=True))[:24]
sth_sign_input	{log_id}\|{tree_size}\|{root_hash}\|{timestamp}

Protocol Invariants

These invariants hold across all protocol operations:

deal_id is the global root key for all entities
All money-moving effects are idempotent and replay-safe
gross == platform_fee + protocol_fee + net (splits sum invariant)
Event chains are hash-linked: each event.prev_hash == previous_event.hash
Merkle leaf hashes use 0x00 domain separation (RFC 6962)
Merkle node hashes use 0x01 domain separation (RFC 6962)
STH sign input format: {log_id}|{tree_size}|{root_hash}|{timestamp}
Attestation signatures are over canonical JSON (sorted keys, compact separators)
Public key canonical source is the runtime endpoint, not static files

Verification Reports

Production Audit

End-to-end journey audit: registration through settlement. 16/16 checks passed.

AUDIT production_audit.md →

Hardening Report

29-point security and reliability checklist. Chaos tests, WAL, distributed exactly-once, job queue validation.

AUDIT hardening_report.md →

Ship Readiness Stamp

Launch readiness certification. 35/35 conformance suite, 12/12 full transaction, offline verification.

AUDIT ship_readiness_stamp.md →

Log Public Key

Ed25519 public key for transparency log signature verification. Discovery pointer for independent auditors.

KEY log_public_key.json →

Live Standards Endpoints

These endpoints are available on the production runtime for independent verification:

Endpoint	Purpose
GET /protocol/merkle/public-key	Canonical Ed25519 public key for STH verification
GET /protocol/merkle/latest	Latest signed tree head (tree size, root hash, signature)
GET /protocol/merkle/inclusion	Merkle inclusion proof for a specific deal
GET /protocol/merkle/consistency	Consistency proof between two tree states
GET /protocol/merkle/entries	Paginated log entries
GET /protocol/merkle/anchors	RFC 3161 timestamp anchor receipts
GET /proof/{deal_id}/verify	Server-side proof verification
GET /proof/{deal_id}	Full portable proof bundle export

Proof Explorer Merkle Design Note Try Proof Playground Verify a Bundle

Last updated: March 2026