Skip to main content

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 composite trust query (CTQ) response is the top-of-stack format above the four AlgoVoi receipt formats. A verifier walks an audit chain composed of compliance, settlement, cancellation, and refund receipts, applies a structured query, and emits a single composite-trust-claim response anchoring the chain by its content-addressed root. It is AlgoVoi-authored, specified in IETF Internet-Draft draft-hopley-x402-composite-trust-query (POSTED on IETF datatracker 2026-05-25, Independent Submission, Informational), and published as a standalone reference implementation:
  • TypeScript: @algovoi/composite-trust-query (live, v0.1.0)
  • Python: algovoi-composite-trust-query (PyPI publish pending rate-limit clearance; npm package live)
Both packages depend on algovoi-substrate / @algovoi/substrate for the JCS canonicalisation primitive. Apache 2.0.

​
Lifecycle position

admission     settlement     cancellation    refund (if owed)
compliance -> settlement  -> cancellation -> refund
receipt       attestation    receipt         receipt
                                  |
                                  v   (chain_ref)
                              CTQ response (TRUSTED | PROVISIONAL | INSUFFICIENT_EVIDENCE | UNTRUSTED)
Regulators, dashboards, and downstream agents consuming the CTQ response get a single byte-deterministic statement of the trust posture without re-walking the underlying chain. The chain remains independently verifiable at the response’s chain_ref content-address.

​
Why a four-state enumeration

Operationally distinct trust outcomes drive distinct operator actions. The format pins:
  • TRUSTED — proceed under the asserted trust posture.
  • PROVISIONAL — proceed cautiously; re-query after pending events finalise.
  • INSUFFICIENT_EVIDENCE — gather more evidence; do not proceed under TRUSTED.
  • UNTRUSTED — halt the action the query was framed to authorise.
A collapse to three values (e.g. TRUSTED / NOT_TRUSTED / PENDING) loses the operationally-distinct INSUFFICIENT_EVIDENCE state (“we could not verify either way”) from UNTRUSTED (“we verified and the answer is no”). The two trigger different operator actions: gather more evidence vs halt.

​
Response shape

A CTQ response is a seven-field JSON object canonicalised under RFC 8785 (JCS). Field names are sorted lexicographically by JCS during canonicalisation. 
{
  "canon_version": "jcs-rfc8785-v1",
  "chain_ref": "sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f",
  "ctq_timestamp_ms": 1716494400000,
  "jurisdiction_flags": ["UK", "EU"],
  "query_ref": "sha256:8b7df143d91c716ecfa5fc1730022f6b421b05cedee8fd52b1fc65a96030ad52",
  "trust_outcome": "TRUSTED",
  "verifier_did": "did:web:api.algovoi.co.uk"
}
FieldTypeDescription
canon_versionstringIn-band canonicalisation pin. Fixed jcs-rfc8785-v1.
chain_refstringsha256:{hex} reference to the audit chain root.
ctq_timestamp_msintegerEpoch ms when verifier emitted the response. Substrate Rule 2.
jurisdiction_flagsordered arrayISO-3166-1 codes. Order significant under RFC 8785.
query_refstringsha256:{hex} reference to the canonical bytes of the query that was answered.
trust_outcomestring (closed enum)TRUSTED / PROVISIONAL / INSUFFICIENT_EVIDENCE / UNTRUSTED.
verifier_didstringDID URI of the verifier.

​
The closed enumeration: trust_outcome

ValueSemanticOperator action
TRUSTEDVerified chain answers the query affirmatively. All anchored receipts valid, present, and consistent.Proceed under asserted trust posture.
PROVISIONALChain partially complete; some receipts in PENDING_FINALITY or analogous non-terminal state.Proceed cautiously; re-query after pending events finalise.
INSUFFICIENT_EVIDENCEChain does not contain enough evidence to answer the query.Gather more evidence; do not proceed under TRUSTED.
UNTRUSTEDChain contains evidence that negates the query.Halt the action the query was framed to authorise.
Each value produces a byte-distinct content_hash.

​
Two content-addressed references

The response carries two sha256:{hex} references:
  • chain_ref points to the audit chain root. Resolving the chain itself is out-of-band (chain-by-content-address dereference, operator-side audit-log fetch, etc.). Consumers can independently walk the chain at chain_ref to verify the verifier’s conclusion.
  • query_ref points to the canonical bytes of the query that was answered. The query format is opaque to the response shape; callers may use JSON-LD, JSON Schema, SQL-like predicates, or any structured-question encoding. The reference is what binds the response to the specific question.
Both prefixes (sha256:) are part of the canonical bytes and MUST NOT be stripped.

​
Verifier-of-verifier composition

A CTQ response MAY itself be embedded as a row in a higher-level audit chain. A verifier-of-verifier reading the higher chain walks sequences of CTQ responses (a chain of verifier conclusions over chains of receipts) and emits a meta-CTQ response over the composite. This enables multi-party audit-chain composition: a regulator verifying an operator’s audit chain emits a CTQ response. A higher-level supervisor verifying multiple regulators’ CTQ responses emits a meta-CTQ response over those. Each level retains independent byte-deterministic verifiability.

​
Conformance vectors

8 byte-level reference vectors + 7 pair invariants + 3 chain invariants at vectors/composite_trust_query_v1/.

​
Quick start

​
TypeScript

import { buildCtqResponse } from "@algovoi/composite-trust-query";
import { sha256Jcs } from "@algovoi/substrate";

const r = buildCtqResponse({
  trust_outcome: "TRUSTED",
  chain_ref:
    "sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f",
  query_ref:
    "sha256:8b7df143d91c716ecfa5fc1730022f6b421b05cedee8fd52b1fc65a96030ad52",
  ctq_timestamp_ms: 1716494400000,
  verifier_did: "did:web:api.algovoi.co.uk",
  jurisdiction_flags: ["UK", "EU"],
});
console.log(sha256Jcs(r));
// fd461c6c63330e0b15ed57b40d687ccadbd1ca2359cb5cf0f53e23c5d4f5c555

​
What this is NOT

  • Not a receipt. Receipts record events that happened; a CTQ response records a verifier’s categorical conclusion over an event chain.
  • Not the query itself. The query is identified by query_ref (content-addressed); the query format is opaque to this response shape.
  • Not a chain-finality model. The verifier applies whatever finality semantics its risk model requires; the response records the categorical conclusion, not the evaluation discipline.

​
Companion IETF Internet-Draft

draft-hopley-x402-composite-trust-query (Independent Submission, Informational). AlgoVoi-authored. Normatively references draft-hopley-x402-canonicalisation-jcs-v1. Welcomes downstream-adopter contributions per the Appendix C “Known Adopters” pattern.

​
See also