The ChainGraph Standard

What ChainGraph standardizes

1. An artifact envelope (§5) — the JSON shape every conformant decision tool emits.
2. A reproducible execution hash (§6) — a canonicalization + hashing procedure any party can re-run to verify an artifact, in any language.
3. A provenance model (§7) — how one artifact cites another, forming a re-verifiable directed acyclic graph.
4. Transport bindings (§8) — how a conformant tool is discovered and called by agents over MCP and A2A, and how a graph index is published for machine discovery.

Non-goals. ChainGraph does not define payment rails, mandate semantics, credential formats, or model behavior. It carries artifacts about those domains, and is deliberately compatible with AP2, ACP, x402, A2A, KYA-OS, and MCP without replacing any of them.

Design principles

• Receipt, not protocol. The unit of value is a verifiable record of a computation, portable across vendors and transports.
• Verifiable by re-execution. Trust comes from reproducibility (recompute the hash), not from a signing authority.
• Decision, not context. Conformant tools emit a determination, not a data display.
• The graph is the product. Value compounds when artifacts chain; the envelope makes chaining cryptographically checkable.
• Privacy by locality. Compatible with — and encouraging — client-side, zero-egress execution, without mandating it.

Terms

• Decision tool — software that consumes inputs and returns a decision (verdict / score / classification / verified mandate).
• Artifact — one ChainGraph envelope instance, the output of one tool run.
• Execution hash — the SHA-256 over the canonical form of an artifact's inputs + outputs (§6).
• Chain — an ordered set of artifacts where each cites its predecessors' execution hashes.
• Provenance DAG — the directed acyclic graph formed by chain.parent_hashes edges across artifacts.
• Mandate type — an extensible classification of what the artifact decides (§7.3).
• Graph index — a published, machine-readable catalog of a vendor's tools and their chain edges (§8.3).

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY are to be interpreted as in RFC 2119.

Four levels of conformance

A tool, suite, or vendor MAY conform at increasing levels. Each level includes all lower levels.

A vendor claiming "ChainGraph L4" asserts all four levels. Conformant tools SHOULD also pass the Five Tests (§4), which operationalize the levels.

Operational conformance check

A decision tool is ChainGraph-conformant if and only if it passes all five:

1. Emits a valid artifact envelope — §5 JSON with chaingraph_version, mandate_type, tool_id, execution_hash, chain block, policy_parameters, output_payload, compliance_flags, audit_signature.
2. Exposes an agent endpoint — a typed, declared input schema and deterministic output an agent can parse without vision (MCP and/or A2A; §8).
3. Exports a decision, not context — a probability, a verdict, a verified mandate; not a data display or document dump.
4. Is chainable — its output is a valid input or precondition for at least one other conformant tool.
5. Carries a verifiable anchor — the execution hash is reproducible by an independent party via the §6 procedure.

Every tool run emits exactly one envelope

{
  "chaingraph_version": "0.1.0",
  "ap2_version": "1.0.0",        // optional compat alias
  "mandate_type": "compliance_mandate",
  "tool_id": "art-01-ap2-mandate-chain-validator",
  "tool_version": "1.1.0",
  "generated_at": "2026-06-14T14:30:00Z",
  "execution_hash": "sha256:abc123…",
  "chain": {
    "parent_hashes": [],
    "parent_tool_ids": [],
    "chain_depth": 0
  },
  "policy_parameters": {              // part of the hash preimage
    "execution_backend": "webgpu | cpu-fallback | js | server",
    "input_parameters": { … }
  },
  "output_payload": { …the decision… (part of the hash preimage) },
  "compliance_flags": [],
  "audit_signature": {                // self-asserted claims, not proofs
    "client_side_executed": true,
    "zero_pii_verified": true,
    "deterministic_run": true
  },
  "session_receipt_root": null      // optional, set by an aggregator (§7.4)
}

Key rules: execution_hash, policy_parameters, and output_payload are REQUIRED; the chain block is REQUIRED at L2. New implementations SHOULD emit chaingraph_version and MAY keep ap2_version as a compatibility alias. Implementations MUST ignore unknown top-level fields (forward compatibility), and MUST NOT place values that vary between identical runs (timestamps, nonces, request IDs) inside policy_parameters or output_payload, or the hash will not reproduce. The audit_signature block holds claims — verification comes from re-execution (§6), not from this block.

The normative field-by-field rules and a JSON Schema are in the artifact schema and the repository README.

Reproducible verification, no trusted signer

The execution hash lets any party confirm an artifact by recomputation, with no shared secret. The preimage is a single JSON object with exactly two keys, in order:

preimage = { "policy_parameters": <…>, "output_payload": <…> }

Canonicalization (MUST be deterministic across implementations)

1. Recursively sort all object keys lexicographically (by Unicode code point).
2. Serialize to JSON with no insignificant whitespace (no spaces after : or ,; no trailing newline).
3. Preserve array order exactly (arrays are ordered data; do not sort them).
4. Numbers: shortest round-trip form; quantize derived numeric outputs to a fixed precision before hashing (document the precision in policy_parameters) to avoid floating-point equality issues.
5. Strings: UTF-8, no escaping beyond the JSON minimum.

Then: execution_hash = "sha256:" + lowercase_hex( SHA-256( utf8( canonical_json ) ) ).

Reference implementation (browser, no library)

async function executionHash(policy_parameters, output_payload) {
  const canon = (v) => Array.isArray(v) ? v.map(canon)
    : (v && typeof v === 'object')
      ? Object.keys(v).sort().reduce((o,k)=>(o[k]=canon(v[k]),o),{})
      : v;
  const preimage = JSON.stringify(canon({ policy_parameters, output_payload }));
  const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(preimage));
  return 'sha256:' + [...new Uint8Array(buf)].map(b=>b.toString(16).padStart(2,'0')).join('');
}

The chain block

"chain": {
  "parent_hashes": ["sha256:…"],
  "parent_tool_ids": ["art-01-ap2-mandate-chain-validator"],
  "chain_depth": 1
}

A tool that consumes another artifact MUST copy each consumed artifact's execution_hash into parent_hashes and the matching tool_id into parent_tool_ids (same order). Roots use empty arrays and chain_depth: 0; otherwise chain_depth = max(parent depths) + 1. The graph MUST be acyclic — reject a chain that would cite an ancestor.

Re-verifiability. Because each parent is named by its execution hash, an auditor can re-run any parent with the recorded inputs, recompute the hash, and confirm the child's citation. The whole DAG is independently checkable without trusting the vendor — the property that distinguishes a ChainGraph chain from a documentation claim that two tools "work together."

7.3 · Mandate-type registry (extensible)

Core types (unprefixed, reserved by the Standard): prompt_template, payment_mandate, payment_policy, settlement_mandate, compliance_mandate, risk_control, liquidity_mandate, capital_assessment, credit_assessment, model_governance, attestation_mandate, cryptographic_mandate, infrastructure_mandate, treasury_mandate, account_mandate.

Namespaced extension types. A vendor MUST namespace any non-core type as <reverse-dns-or-registry-id>/<type> — e.g. co.ainumbers/payment_mandate, org.apexlogics/credential_assessment, me.omegacentauri/imbh_constraint. Unprefixed types not in the core registry are invalid; consumers MUST treat an unrecognized namespaced type as opaque (carry it, do not reject the chain).

Note on AP2. AP2 (Agent Payments Protocol, FIDO-governed) defines Intent/Cart/Payment mandates. ChainGraph mandate_type is an independent classification vocabulary, not an AP2 field. A ChainGraph tool MAY validate real AP2 structures, but emitting a ChainGraph artifact does not assert AP2 conformance — keep the two distinct in user-facing copy.

7.4 · Session receipts (aggregation)

An aggregator tool MAY consume N artifacts from a session and emit an artifact whose output_payload contains a SHA-256 Merkle root over their execution hashes, plus per-artifact inclusion proofs, setting session_receipt_root. This yields a single tamper-evident receipt for an entire agent session — the audit object suited to record-keeping regimes (e.g. EU AI Act Art. 12, DORA). The aggregator is itself a conformant tool.

Agent-callable and discoverable

8.1 · MCP binding (L3)

A conformant tool exposed over the Model Context Protocol registers a tools/call endpoint with a typed input schema, declares readOnlyHint: true when it mutates nothing, and returns the artifact envelope as structuredContent. It SHOULD additionally provide three graph-level tools:

• emit_<vendor>_artifact — given tool_id + policy_parameters, return the signed artifact.
• verify_execution_hash — given an artifact, recompute and compare (§6).
• build_chaingraph — given a chain name or goal, return the ordered node list with explicit parent_hashes wiring from the graph index.

It MAY use MCP async Tasks for long-running computations and Sampling-with-Tools to run a chain as a server-side agent loop (MCP 2025-11-25 / 2026-07-28). Compute that must remain local MUST NOT be moved server-side merely to satisfy a binding — return a Task handle or deep-link instead.

8.2 · A2A binding (L3/L4)

A conformant vendor MAY publish an A2A agent card (/.well-known/agent-card.json, Agent2Agent v1.0) listing its decision-tool families as skills, pointing to its MCP endpoint and graph index, and declaring the ChainGraph capability extension x-chaingraph:

"capabilities": {
  "extensions": [{
    "uri": "https://postoaklabs.github.io/chaingraph/ext/x-chaingraph/v0.1",
    "description": "Emits ChainGraph verifiable decision artifacts (hash-anchored, chainable).",
    "params": {
      "conformance_level": "L4",
      "graph_index": "https://ainumbers.co/chaingraph/chaingraph.json",
      "verify_endpoint": "verify_execution_hash",
      "hash_alg": "sha256",
      "mandate_namespace": "co.ainumbers"
    }
  }]
}

The x-chaingraph extension lets one agent discover, over A2A, that another agent's outputs are verifiable ChainGraph artifacts — and lets artifacts chain across vendors, each link verified through the producing vendor's verify_execution_hash.

8.3 · Graph index (L4)

A published JSON document enumerating the vendor's tools and chain edges. Minimum per-node fields: tool_id, display_name, mcp_name, mandate_type, input_schema_ref, consumes, feeds, status. Document-level: chaingraph_version, mandate_namespace, verify_endpoint, five_tests, chain_block_spec. It MUST be linked from at least one discovery surface. The AINumbers chaingraph.json is the reference shape.

Considerations

• Locality. Compatible with fully client-side, zero-egress execution and RECOMMENDS it for sensitive inputs. audit_signature flags are self-asserted; consumers needing assurance SHOULD re-execute (§6) in a trusted environment.
• No PII in the preimage. Because policy_parameters and output_payload are hashed and may be shared as a receipt, implementers MUST keep real personal data out of them.
• The hash is integrity, not authenticity. A match proves inputs→outputs reproduce; it does NOT prove who ran the tool. Add a real signature (e.g. JWS over the envelope) as a separate layer if authenticity is required.
• Determinism is a security property. Non-deterministic tools cannot be verified.
• Chain integrity. Verify parent hashes before trusting a chain's claims; a cited parent that does not reproduce invalidates the chain from that node down.

How the Standard evolves

• Semver. 0.x is draft; field renames may occur before 1.0 (notably ap2_version → chaingraph_version consolidation).
• The core mandate-type registry is additive after 1.0: new core types may be added; existing ones are never removed or repurposed. Vendor namespaces evolve independently.
• Reference implementation: the AINumbers ChainGraph suite tracks the latest draft; divergences are documented in its graph index chaingraph_version.
• Published under CC BY 4.0 so other projects — including Post Oak Labs' ApexLogics and OCS suites and third parties — can adopt and extend it. Register your mandate_namespace with the editor (open an issue) to avoid collisions.

Make an existing decision-tool suite conformant

1. L1 — wrap your outputs in the envelope (§5) and compute the execution hash (§6). For most tools this is a serialization change, not a logic change. Pick your mandate_namespace (e.g. org.apexlogics, me.omegacentauri).
2. L2 — add the chain block. Wherever a tool already consumes another tool's output, copy the parent's execution hash into parent_hashes. You now have a verifiable DAG.
3. L3 — expose tools/call + verify_execution_hash. If you already run an MCP server (ApexLogics and OCS both expose build_workflow_links-style tools), add emit_<vendor>_artifact, verify_execution_hash, and build_chaingraph. Return the envelope as structuredContent.
4. L4 — publish a graph index (§8.3) and an A2A agent card declaring x-chaingraph. Link both from your llms.txt.

A complement, not a competitor

• AP2 / ACP / x402 / Visa TAP (agent payments) — ChainGraph artifacts carry the verdict of validating these; payment_mandate/settlement_mandate tools wrap them.
• A2A (agent-to-agent) — ChainGraph rides A2A for discovery and cross-agent hand-off via x-chaingraph.
• MCP (agent-to-tool) — ChainGraph's primary call/verify transport.
• KYA-OS / eIDAS 2.0 / EUDI — subjects a ChainGraph compliance tool may decide over.
• W3C Verifiable Credentials — adjacent: VCs assert attributes with issuer signatures; ChainGraph asserts reproducible computations verified by re-execution. As of v0.4.1, ChainGraph can render any verified artifact as a W3C VC 2.0 credential via the chaingraph_export:vc profile (§13.11) — a view that re-states the canonical execution_hash and mints no new hash or proof.