algovoi-substrate (Python)

AlgoVoi agentic-payments substrate reference implementation.

JCS RFC 8785 canonicalisation, action_ref atomic primitive, composite trust-query algorithm, compliance receipt shape, and audit chain primitives that compose the substrate underneath x402, AP2, A2A, and MPP receipts.

The substrate runs in production at https://api.algovoi.co.uk/compliance. This package is the AlgoVoi-authored reference implementation; cross-validated byte-for-byte against four other JCS implementations (JavaScript canonicalize, Go gowebpki/jcs, Java cyberphone, Rust serde_jcs) on 53 conformance vectors and 3 composite-trust-query vectors.

Install

pip install algovoi-substrate

Quickstart

from algovoi_substrate import (
    canonicalize,
    sha256_jcs,
    action_ref,
    composite_trust_query_hash,
    build_compliance_receipt,
    append_to_chain,
    verify_audit_chain,
)

# Canonicalise an object to RFC 8785 JCS bytes.
canonicalize({"b": 1, "a": 2})  # -> '{"a":2,"b":1}'

# The action_ref atomic primitive:
# SHA-256(JCS({agent_id, action_type, scope, timestamp_ms}))
ref = action_ref(
    agent_id="agent-x",
    action_type="payment",
    scope="bilateral",
    timestamp_ms=1716460800000,
)

# Composite trust-query (PR #2440 in x402-foundation/x402).
# Aggregates multi-source attestations into a single canonical hash.
rows = [
    {"source_id": "trust-a", "score": 80, "sig": "sig-bytes"},
    {"source_id": "trust-b", "score": 75, "sig": "sig-bytes"},
]
composite_hash = composite_trust_query_hash(rows)

# Compliance receipt (AlgoVoi production schema).
receipt = build_compliance_receipt(
    payer_ref="sha256:abc123",
    screen_result="ALLOW",
    screen_timestamp_ms=1716460800000,
    screen_provider_did="did:web:api.algovoi.co.uk",
    jurisdiction_flags=["UK", "EU"],
)

# Audit chain: monotonic per-row hash chain with content_hash + prev_hash.
row0 = append_to_chain(payload=dict(receipt), prev_row=None)
row1 = append_to_chain(payload={"event": "next"}, prev_row=row0)
verify_audit_chain([row0, row1])

Substrate discipline

This package enforces the AlgoVoi canonicalisation discipline, specified in draft-hopley-x402-canonicalisation-jcs-v1 (IETF I-D, sole AlgoVoi authorship):

• Rule 1. timestamp_ms is an epoch-millisecond integer. Floats, ISO 8601 strings, and negative values are rejected at the source-side.
• Rule 4. Type validation happens before canonicalisation. A field declared integer that receives a float is a hard validation failure, not a silent type-cast.
• canon_version pin. Receipts carry canon_version: "jcs-rfc8785-v1" as an in-band format-version pin, so a year-five re-canonicalisation knows which rule was active at emission without depending on an out-of-band rule registry.
• Array element order preserved. ["UK","EU"] and ["EU","UK"] are distinct canonical preimages per RFC 8785 §3.2.3 -- producer-side ordering is load-bearing.

The categorical screen result (ALLOW / REFER / DENY) is enforced as a closed set. Under UK POCA 2002 s.330 a REFER carries a mandatory SAR obligation that DENY does not; collapsing this to a score / tier projection would lose the property and break year-five auditability.

Cross-impl validation

The substrate has been byte-for-byte cross-validated across five implementations on the AlgoVoi-authored vector sets:

• Python rfc8785@0.1.4 (this package wraps it)
• JavaScript canonicalize@3.0.0
• Go gowebpki/jcs v1.0.1
• Java cyberphone/json-canonicalization
• Rust serde_jcs@0.2.0

Vector sets (Apache 2.0, AlgoVoi-authored):

• AP2 OMH v0 -- 10 vectors
• CTEF + APS v1 -- 14 vectors
• privacy_class v0.1 -- 10 vectors
• per-chain envelope v0 -- 19 vectors

Substrate matrix: https://gist.github.com/chopmob-cloud/b327814c4e17ed9fc7b4f29c8bda523c

Composite trust-query matrix: https://gist.github.com/chopmob-cloud/f2e9f0877b7d9fff70c8eca46e4ce636

Tests

pip install -e ".[test]"
pytest

Production reference

The reference exhibit for this substrate is AlgoVoi's /compliance/attestation audit chain, live at https://api.algovoi.co.uk/compliance/attestation. Receipts retained under seven-year Object Lock COMPLIANCE retention (current horizon 2033-05-04). The migration boundary (receipts before / after 2026-05-21) is observable directly from the chain.

Spec references

• draft-hopley-x402-canonicalisation-jcs-v1 -- IETF I-D (Independent Submission, Informational, sole AlgoVoi authorship). Specifies the JCS RFC 8785 receipt-body canonicalisation discipline this HTTP-signature verifier composes against.
• PR #2453 -- live upstream spec PR for the canonicalisation discipline (replaces closed #2436).
• draft-vauban-x402-stark-receipts -- third-party adopter-authored receipt format that anchors to the AlgoVoi canonicalisation discipline.

Relationship to the canonicalisation discipline

This package verifies HTTP message signatures per RFC 9421 + RFC 9530 -- a different canonicalisation surface from the AlgoVoi JCS RFC 8785 receipt-body discipline at docs.algovoi.co.uk/canonicalisation-substrate. HTTP signature verification (this package) and receipt-content verification (algovoi-audit-verifier + the receipt-format packages) are complementary surfaces: this verifier confirms wire-level message integrity; the AlgoVoi JCS substrate confirms receipt-body canonical integrity. Both are AlgoVoi-authored under sole authorship.

Parties anchoring to the AlgoVoi canonicalisation discipline are recorded in the Substrate Adopters Registry; the registry's canon_version pin criterion applies to receipt-body artefacts, not to HTTP signatures as such.

Licence

Apache 2.0. See LICENSE.

Author

AlgoVoi (Christopher Hopley, GitHub chopmob-cloud).