> ## Documentation Index > Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt > Use this file to discover all available pages before exploring further. # The Keystone > The AlgoVoi Keystone is the agentic payment trust chain, byte verifiable end to end: identity, authority, policy, decision, execution and verdict. The Keystone is the complete agentic-payment trust chain, expressed as one recomputable sequence of content-addressed references. It answers, in order, the five questions a payment agent's actions raise, and binds each answer to the next so the whole chain is verifiable end to end with no issuer contact. ``` passport_ref -> mandate_ref -> policy_bound_ref -> decision_ref -> execution_ref -> trust_query_ref who is it? what may it under which was it what did it one verdict spend? policy? authorized? actually do? over the chain ``` Each reference is `"sha256:" + SHA-256(JCS(...))` over the reference before it, so recompute any input field and that reference and everything downstream of it diverges. A decision made for one agent, authority, or policy cannot be silently re-attributed; an execution recorded under one decision cannot be claimed by another. ## What 1.0.0 closes `algovoi-substrate` 1.0.0 closes the Keystone with [`execution_ref`](/execution-ref), decision-bound execution evidence. Identity proves *who* an agent is and a decision proves an action was *authorized*; `execution_ref` proves *what the agent did* and binds that execution to the exact decision that authorized it. This is the consistency property: the evidence is bound to the decision, not merely correlated with an identity. It is the gap the field has been naming as "post-identity trust," now shipped, byte-verifiable, and optionally post-quantum signed. ## The whole chain, in one call ```python theme={null} from algovoi_substrate import build_keystone k = build_keystone( passport_ref="sha256:b3594e33...", # identity (Agent Passport) mandate_ref="sha256:a4f8cb5e...", # authority (Payment Mandate) policy_bound_ref="sha256:aaee2091...", # policy in force (Policy Binding) verdict="ALLOW", # the pre-payment decision action_type="payment", scope="bilateral", outcome="COMMITTED", executed_at_ms=1716460800000, trust_outcome="TRUSTED", ) k["decision_ref"] # the pre-payment decision k["execution_ref"] # decision-bound execution evidence k["trust_query_ref"] # one verdict over the whole ordered chain k["chain"] # [passport_ref, mandate_ref, policy_bound_ref, decision_ref, execution_ref] ``` Python and TypeScript (`buildKeystone`) produce byte-identical output. The three upstream references are issued by their own tiers (Agent Passport, Payment Mandate, Policy Binding) and supplied by value; the substrate composes the rest. ## Verify the whole Keystone yourself The end-to-end composition is proven byte-for-byte in the conformance corpus, offline, with no package import (an RFC 8785 JCS library and SHA-256 are the whole dependency): ``` git clone https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors cd algovoi-jcs-conformance-vectors python composition/keystone_v1/verify_keystone.py # 6/6 links byte-for-byte node composition/keystone_v1/verify_keystone.mjs # Node == Python ``` `keystone_v1` recomputes every reference from raw fields, shows each equals the published output of its own conformance set, and shows the execution tier binds the exact decision the chain produced. It is the flagship "verify it yourself" proof for the whole chain. ## The agentic lifecycle composes onto the Keystone The agentic lifecycle extends through the whole post-decision sequence, composing directly onto the Keystone chain. Each step is an additive composition in the conformance corpus (0.24.0), built on the same JCS + SHA-256 discipline with no new hashing primitive: * **Settlement binds to execution.** A settlement attestation whose `settled_payment_ref` is the exact `execution_ref` the Keystone produced, capped by one `execution_binding` over `{execution_ref, settlement_ref, retention_chain_ref}`. What settled binds to what executed, not to an identity. (`composition/settlement_binding_v1`) * **Refund binds to execution.** A refund receipt anchored to the `execution_ref` of the payment that committed, not merely to the decision that authorized it. (`composition/refund_execution_v1`) * **PEF carries the Keystone.** A Payment Evidence Frame is the signed transport envelope: it wraps a Keystone reference and pins it, so its `frame_id` commits to the exact Keystone position it carries. PEF is the delivery and attribution layer, not a new link in the chain. (`composition/pef_keystone_v1`) * **Audit chain of frames (the capstone).** The whole lifecycle, execution then settlement then refund, expressed as a chain of PEF frames whose `receipt_hash` equals the Keystone reference each one transports, linked by `prev_hash` and capped by one `trust_query_ref`. Tamper any frame and its `frame_id`, the downstream rows, and the cap all diverge. (`composition/audit_chain_of_frames_v1`) * **Compliance gate binds the decision.** The compliance verdict (`gate_ref`) assessed the exact `policy_bound_ref` the decision used, so the decision was admitted under the compliance verdict in force; a compliance-spanning `trust_query_ref` caps it. (`composition/compliance_gate_keystone_v1`) * **Cancellation closes the authority.** The authority-side mirror of refund: a cancellation receipt whose `mandate_ref` is the exact Keystone mandate, closing the authority before execution. (`composition/cancellation_keystone_v1`) * **Admitted under the input-bounds profile.** The Keystone record is within every bound of the substrate-guard `profile_ref`, so the input gate that runs before canonicalisation admits it (a precondition, not a chain link). (`composition/guard_keystone_v1`) **Produce frames with the package.** `algovoi-pef-keystone` (PyPI) and `@algovoi/pef-keystone` (npm) build and chain these evidence frames over any substrate version. Open and content addressed; the cryptographic signature (hybrid Falcon-1024 and ML-DSA-65) is the commercial tier. ``` pip install algovoi-pef-keystone ``` Verify them the same way, offline from raw fields: ``` python composition/settlement_binding_v1/verify_settlement_binding.py python composition/refund_execution_v1/verify_refund_execution.py python composition/pef_keystone_v1/verify_pef_keystone.py python composition/audit_chain_of_frames_v1/verify_audit_chain_of_frames.py python composition/compliance_gate_keystone_v1/verify_compliance_gate_keystone.py python composition/cancellation_keystone_v1/verify_cancellation_keystone.py python composition/guard_keystone_v1/verify_guard_keystone.py ``` Each has a Node twin (`.mjs`) that produces identical references, or run the whole corpus at once with `python composition/verify_corpus.py`. ## Flow-point hardening (open) Three open securing refs deepen the lifecycle at the points where a bare ref proves a fact was recorded but not that it was recorded *correctly* or *freshly*. Each is the same `"sha256:" + SHA-256(JCS(...))` construction, byte-identical to every other Keystone ref, so any verifier recomputes it offline. * **Decision audit binding.** `decision_audit_ref` binds a decision to the exact passport, mandate, policy-binding and compliance screen it consumed, so the authorization is auditable instead of a black box. A rotated policy, a swapped passport or a silently dropped screen each diverge the ref. * **Guard context.** `guard_context_ref` pins the exact policy, mandate and passport the admission gate saw at an integer-millisecond moment, so the guard decision is reproducible. * **Freshness.** `with_validity` and `check_freshness` attach and enforce an integer-millisecond validity window on any ref preimage, closing replay and staleness. They register in their Keystone slots through the `algovoi.keystone.steps` entry point (guard context before passport, decision audit at the decision stage, freshness as a cross-cutting source), so the settings panel discovers them automatically. ``` pip install --extra-index-url https://pip.algovoi.co.uk/simple/ algovoi-keystone-secure-lite ``` Conformance vectors are public (`keystone_decision_audit_v1`, `keystone_guard_context_v1`); each recomputes with SHA-256 and RFC 8785 only. Open and content addressed; signing these refs into a Falcon-1024 evidence chain and ingesting them into the Compliance Command Center is the commercial tier. ## Carry the Keystone into other standards A Keystone decision's `execution_ref` travels into the common agent and observability formats, so the decision stays verifiable wherever it goes. Each adapter maps a Keystone decision into one format; a consumer recomputes `execution_ref` from the carried fields with only JCS (RFC 8785) and SHA-256, and the references live under AlgoVoi-owned identifiers, never inside a namespace governed by another body. * **CloudEvents 1.0.** The `execution_ref` is the event `id`; the Keystone references live in the event `data`, with no invented extension attributes. `pip install algovoi-cloudevents` or `npm i @algovoi/cloudevents`. * **W3C Verifiable Credential (Data Model 2.0).** A `KeystoneExecutionCredential` whose `credentialSubject` id is the `execution_ref`, recomputable from the subject before any signature suite is applied. `pip install algovoi-keystone-vc` or `npm i @algovoi/keystone-vc`. * **Model Context Protocol.** Tools that recompute and check a Keystone `execution_ref` from any MCP client, offline. `pip install algovoi-keystone-mcp` or `npm i @algovoi/keystone-mcp`. * **LangChain run traces.** A Keystone decision attached to a LangChain run as metadata and a tag under `algovoi.keystone.*`, so LangSmith and any tracer show a reference a reviewer recomputes from the run alone. `pip install algovoi-keystone-langchain` or `npm i @algovoi/keystone-langchain`. * **Webhook events.** An AlgoVoi webhook verifier that checks the HMAC signature and recomputes the keystone `execution_ref` carried in the event, so a consumer proves both the signature and that the keystone reference is authentic. `pip install algovoi-webhook-verifier` or `npm i @algovoi/webhook-verifier`. Python and TypeScript produce the same `execution_ref` byte for byte. Apache-2.0. Each adapter is validated against the standard it targets, not just against itself: the CloudEvents event is accepted by the CloudEvents SDK as a valid 1.0 event, the credential conforms to the Verifiable Credentials Data Model 2.0, and the MCP tools complete a real server to client protocol round-trip. In every case the consumer recomputes the same `execution_ref` from the carried record alone, with no AlgoVoi software. ## Authorization composes across parties A receipt proves an action happened. It does not prove the agent was allowed to take it, and that gap widens the moment authority is delegated from one party to another. The Keystone Orchestrator produces verifiable, end-to-end evidence that authority flowed correctly across organizational boundaries and was not exceeded, recomputable offline. Composition proofs available on request. The same cross-party proof binds straight into your multi-agent framework. The CrewAI, LangGraph, AutoGen, and A2A journey adapters each record a run's hops and the delegations between them and emit one `journey_ref` over the whole task, so a crew, a graph, a group chat, or an agent to agent task verifies as a single proof. Commercial; ships in the Payment Rails bundle. ## Verified performance The full Keystone, including the signed transport frames and the capped audit chain, recomputes in well under a millisecond. A sustained single core soak (Docker `--cpus=1`, 120 seconds, driven through the published `algovoi-substrate` canonicalizer) recorded: | Runtime | Sustained throughput | Latency p50 / p99 | Memory | | --------------------- | ---------------------- | ----------------- | ------------------------- | | Python (`rfc8785`) | \~3,850 keystones/sec | 0.20 / 0.60 ms | plateaus \~25 MB, no leak | | Node (`canonicalize`) | \~14,200 keystones/sec | 0.05 / 0.29 ms | plateaus \~68 MB, no leak | Across 2.17 million recomputations over both runtimes the references never drifted: every reference still matched its published value at the end of the soak. Throughput held steady with no degradation and memory plateaued with no leak. One Keystone is about a dozen JCS + SHA-256 references, and throughput scales with cores. ## Composition proofs on request You do not need the engine to hold the proof. Submit your agentic-action evidence and receive a portable attestation, signed by AlgoVoi, that a counterparty, auditor, or regulator verifies offline against the published key, with no access to the engine and nothing to re-run. Composition proofs, and conformance suites for your own governance or payment contract, are available under license. Contact `chopmob@gmail.com`. ## Commercial: signed, CCC-ingestable execution evidence The open tier binds and proves. The commercial tier signs and renders: the execution tier is co-signed with Falcon-1024 and ML-DSA-65 and emitted as a hash-linked `execution_evidence` chain that the Compliance Command Center ingests and re-verifies offline, surfacing a "Keystone, execution evidence" posture tier. The compliance step deepens the same way. The open Compliance Gate emits the verdict; the commercial tier binds that receipt into the keystone as a screen stage, so the screening provably informed this exact decision, and adds a signed decision basis: which compliance standards drove the verdict, the jurisdiction check bound to its geo determination, no PII and recomputable offline, co-signed with Falcon-1024 and ML-DSA-65 and ingested by the Command Center. Commercial only. ## Keystone settings panel `algovoi-keystone-control` is an open (Apache-2.0) browser panel for installed AlgoVoi keystone packages. It auto-detects which keystone steps are present in the environment, shows their current settings, and lets operators edit them via a pin-gated HTTPS panel. ```bash theme={null} pip install algovoi-keystone-control ALGV_ADMIN_TOKEN= algv-keystone ``` The panel opens at `https://0.0.0.0:8077`. It recognises all 10 keystone steps (guard, passport, mandate, policy\_bound, screen, decision, execution, trust\_query, revocation, journey), shows which are installed and at what version, and presents their settings in two tabs: application settings (thresholds, limits, flags) and the keystone substrate variables (canon version, hash algorithm, required fields, chain constraints). Both are editable; changes are persisted to a local JSON store. The panel installs keystone packages from the **AlgoVoi index**, which is the integrity path: the index is baked into the installer, so you run the validated build rather than a mutable public artifact. The same packages are **also published to PyPI** for those who prefer plain `pip`, and new releases land on the AlgoVoi index first. Getting the panel itself is the normal install shown above. Third-party bolt-ons register under the `algovoi.keystone.steps` entry-point group and appear in the panel automatically with no code change. The entry point points at a callable that returns a dict with at least `step` (the panel row name) and `ref` (the ref it emits); optional `package`, `order`, `posture`, and `default` settings round out the row. A bolt-on that fails to load is skipped rather than breaking the panel. For example, [`algovoi-kyc-passport`](/passport-bolt-ons) registers a `passport_kyc` entry that maps a Jumio or Sumsub verification into a `passport_ref`. | Endpoint | Description | | ---------------------------------- | ----------------------------------------------------- | | `GET /v1/steps` | Installed steps with current settings | | `GET /v1/catalogue` | Every known step, installed or not, with its provider | | `GET /v1/steps/{step}/settings` | Current + default settings for a step | | `PUT /v1/steps/{step}/settings` | Update settings for a step (pin-gated) | | `DELETE /v1/steps/{step}/settings` | Reset a step to defaults (pin-gated) | All endpoints require `Authorization: Bearer `. Apache-2.0. ## Keystone badges Keystone compatibility has **two tiers**, each with its own badge — and both are **self-verifiable**, not just labels: [![Keystone Enabled](https://img.shields.io/badge/Keystone-enabled-5cb9f8)](https://docs.algovoi.co.uk/keystone)   [![Keystone Integration](https://img.shields.io/badge/Keystone-integration-7c8aa0)](https://docs.algovoi.co.uk/keystone) * **Keystone Enabled** — the package **produces** a keystone ref at a decision-flow stage (a *step*). The panel's catalogue recognises it (a built-in step or its open/lite variant) or it registers an `algovoi.keystone.steps` entry point. * **Keystone Integration** — the package **consumes, exports, or verifies** keystone evidence (a *tool*): trace adapters, exporters, and verifiers. Keystone-compatible by design, but not a step. Verify either tier with one command — it exits `0` on PASS, `1` otherwise, so it drops straight into CI: ```bash theme={null} pip install algovoi-keystone-control keystone-verify # PASS is Keystone Enabled -> step '...' (emits ..._ref, via catalogue|entry-point) # PASS is a Keystone Integration -> exporter|verifier|tracer (...) ``` Display the matching badge in your README: ```markdown theme={null} [![Keystone Enabled](https://img.shields.io/badge/Keystone-enabled-5cb9f8)](https://docs.algovoi.co.uk/keystone) [![Keystone Integration](https://img.shields.io/badge/Keystone-integration-7c8aa0)](https://docs.algovoi.co.uk/keystone) ``` | Tier | Badge | Packages | | ----------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Enabled** (steps) | `Keystone-enabled` | substrate-guard, agent-passport-lite, payment-mandate-lite, policy-binding, compliance-gate-lite, spend-guardrail-lite, execution-ref, composite-trust-query-lite, delegation-ref, cancellation-receipt-lite, refund-receipt-lite, retention-chain, [kyc-passport](/passport-bolt-ons), a2a-journey | | **Integration** (tools) | `Keystone-integration` | keystone-vc, keystone-mcp, keystone-langchain, keystone-crewai, keystone-autogen, keystone-adk, cloudevents, tap-verifier, webhook-verifier | ## Build your own bolt-on The panel auto-detects bolt-ons through one small contract, so you can add your own and have it recognised without us changing anything. There is **no catalogue to get added to and no limit** — every package that declares the relevant entry point is discovered on install. A bolt-on is either a **step** (it produces a keystone ref at a decision-flow stage) or an **integration** (it consumes, exports, or verifies keystone evidence). Each has its own entry-point group. ### A step bolt-on In your `pyproject.toml`: ```toml theme={null} [project.entry-points."algovoi.keystone.steps"] my_step = "my_package.keystone:keystone_step" ``` It returns a dict; `step` and `ref` are the only required keys. ```python theme={null} def keystone_step(): return { "package": "my-package", # your distribution name "step": "my_step", # the decision-flow stage you cover "ref": "my_ref", # the *_ref your package emits "order": 50, # optional: where it sits in the flow "posture": "what it does", # optional: one line } ``` Install it alongside `algovoi-keystone-control`, then verify: ```bash theme={null} keystone-verify my-package # PASS my-package is Keystone Enabled -> step 'my_step' (emits my_ref, via entry-point) ``` ### An integration bolt-on (connector / exporter / verifier) If your package binds a data plane, exports keystone evidence to another format, or verifies it, register it under the `algovoi.keystone.integrations` group instead. Same idea, a different descriptor — and the same self-discovery on install. ```toml theme={null} [project.entry-points."algovoi.keystone.integrations"] my_connector = "my_package:descriptor" ``` It returns a dict; `name` and `role` are the only required keys. `role` is one of `connector`, `exporter`, `verifier`, `tracer`, or `interface`. ```python theme={null} def descriptor(): return { "name": "acme-neo4j", # the panel row name "role": "connector", # connector | exporter | verifier | tracer | interface "posture": "Bind Neo4j writes to keystone execution_ref", # optional: one line # "package": "acme-keystone-neo4j", # optional: defaults to the providing distribution } ``` ```bash theme={null} keystone-verify acme-keystone-neo4j # PASS acme-keystone-neo4j is a Keystone Integration -> connector (...) ``` That is the whole contract. Publish your package and anyone with the panel installed sees your bolt-on — step or integration — with its [Keystone badge](#keystone-badges) self-verifiable in their own CI. A bolt-on that fails to load is skipped rather than breaking the panel, and the built-in catalogue is unaffected, so your additions only ever stack on top. ## See also * [Agent Mesh](/agent-mesh): the paid Keystone component for agent-to-agent settlement across any chain, binding two post-quantum agent identities into one execution reference * [`execution_ref`](/execution-ref): the link that closes the Keystone * [Keystone connectors](/keystone-connectors): bind real data-layer operations (databases, Kafka, HTTP, gRPC, object storage) to the decision that authorised them -- `pip install algovoi-keystone-` from [PyPI](https://pypi.org/search/?q=algovoi-keystone) * [Spend decision chain](/spend-decision-chain): the decision tier * [Conformance vectors](/conformance-vectors): 11 composition proofs incl. `keystone_v1`, `settlement_binding_v1`, `pef_keystone_v1`, `refund_execution_v1`, `audit_chain_of_frames_v1`, `compliance_gate_keystone_v1`, `cancellation_keystone_v1`, `guard_keystone_v1` * [Canonicalisation substrate](/canonicalisation-substrate): the JCS discipline underneath * [Substrate comparison, Layer 2](/substrate-comparison#layer-2-the-trust-chain): how the trust chain compares by capability, and why every network-dependent revocation technique fails open offline while a content-addressed one stays closed