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.

​
Status

This page specifies version jcs-rfc8785-v2 of the canonicalisation discipline first published as urn:x402:canonicalisation:jcs-rfc8785-v1. v2 is strictly additive over v1: the canonicalisation core (RFC 8785 plus the schema-normalisation rules) is unchanged. v2 adds the signature-algorithm discipline that PQC-aware adopters need; classical adopters can continue to pin canon_version: jcs-rfc8785-v1 indefinitely without migration. Authorship: sole AlgoVoi authorship under the same lineage discipline as v1. URN: urn:x402:canonicalisation:jcs-rfc8785-v2.
IETF Internet-Draft status. An IETF Internet-Draft formalising urn:x402:canonicalisation:jcs-rfc8785-v2 under the Independent Submissions stream is pending an active IETF list thread (May 2026) on the appropriate scope and use of the Independent Submissions stream for x402-related substrate documentation. The v2 discipline is published here, in the algovoi-substrate-pqc reference implementations, and in the Substrate Adopters Registry independently of that process.

​
What v2 adds over v1

Four additions, all additive; none change any v1 normative requirement:
  1. signature_algorithm open-enum registry. A 12-row registry of named signature algorithms covering classical, post-quantum, and hybrid schemes. The enum is open: future algorithms land via revision of this discipline without invalidating existing pinned values.
  2. Fail-closed verifier discipline for unknown algorithms. A verifier encountering an unrecognised signature_algorithm value MUST raise an UnknownSignatureAlgorithm error rather than silently reject or coerce. The discipline is “reject because I do not know,” not “reject because I am sure it is invalid.”
  3. PQC algorithm normative references. Pointers to FIPS 204 (ML-DSA) and FIPS 206 (Falcon, when ratified) with the cross-implementor evidence base AlgoVoi has published.
  4. Cross-implementor convergence proof methodology. A non-normative annex documenting the producer × verifier matrix as a substrate-evidence pattern for any future PQC algorithm a downstream implementor wants to add.

​
The signature_algorithm open-enum registry

A receipt envelope under canon_version: jcs-rfc8785-v2 MAY carry a signature_algorithm field naming the algorithm used to sign the canonical bytes. The registry below names twelve algorithms with their references; the enum is open and new entries land via revision of this discipline.
ValueFamilyReferenceNotes
ES256Classical (ECDSA P-256)RFC 7518 §3.4Recommended baseline for new deployments emitting under v2
ES256KClassical (ECDSA secp256k1)RFC 8812 §3.2Common in EVM-adjacent receipt formats
Ed25519Classical (EdDSA Curve25519)RFC 8032, RFC 8037 §3.1Recommended for non-EVM deployments
ML-DSA-44Post-quantum latticeFIPS 204NIST Level 2; smallest PQC public key + signature
ML-DSA-65Post-quantum latticeFIPS 204NIST Level 3; recommended PQC default
ML-DSA-87Post-quantum latticeFIPS 204NIST Level 5; largest PQC key + signature
Falcon-512Post-quantum lattice (NTRU)FIPS 206 (pending)NIST Level 1 lattice; compact signatures
Falcon-1024Post-quantum lattice (NTRU)FIPS 206 (pending)NIST Level 5 lattice; compact signatures
SLH-DSA-SHA2-128sPost-quantum hash-based (stateless)FIPS 205Conservative PQC fallback; no lattice assumption
HMAC-SHA-256Symmetric MACRFC 2104, FIPS 180-4Internal audit-chain signing only; not for public receipts
HMAC-SHA-384Symmetric MACRFC 2104, FIPS 180-4Same scope as HMAC-SHA-256, longer truncation horizon
Hybrid-ES256K-ML-DSA-65Hybrid (classical + PQC)This document, §Hybrid scheme guidanceSame canonical bytes signed under both algorithms; downstream verifier checks both signatures
The values are case-sensitive opaque strings. A verifier under canon_version: jcs-rfc8785-v2 MUST compare signature_algorithm values as exact-byte string equality. A receipt format consuming the registry pins the algorithm value in-band on every emitted object.

​
Fail-closed verifier discipline

A v2 verifier encountering a signature_algorithm value it does not recognise MUST:
  1. Refuse to verify the receipt.
  2. Raise a programmatically-distinguishable error (recommended name: UnknownSignatureAlgorithm / UnknownSignatureAlgorithmError).
  3. NOT silently accept the receipt because the canonical bytes parse cleanly under JCS.
  4. NOT silently coerce the value to a recognised algorithm.
  5. NOT downgrade to a different algorithm value present elsewhere in the envelope.
Rationale: a verifier that accepts an unknown algorithm is implicitly extending the registry on the consumer side. The registry is the discipline’s normative surface; extension happens via revision of this discipline (or downstream URN extension), not via consumer-side leniency. The fail-closed discipline applies symmetrically to producers: a producer MUST NOT emit a signature_algorithm value not in the registry (or in a downstream-extended registry the consumer has agreed to). The point is to keep registry semantics under explicit author control on both sides of the wire.

​
PQC algorithm normative references

Algorithm familyStandardStatusReference implementations cross-validated by AlgoVoi
ML-DSA-FIPS 204FinalPQClean (via pqcrypto Python), @noble/post-quantum (Paul Miller, pure JS), Bouncy Castle 1.84 MLDSASigner
Falcon- / FN-DSAFIPS 206Pending NIST publication; Falcon-1024 patent US7308097B2 has a FRAND pledge tied to FIPS 206 standardisationPQClean (via pqcrypto), @noble/post-quantum, Bouncy Castle 1.84 FalconSigner (experimental)
SLH-DSA-SHA2-128sFIPS 205FinalPQClean (via pqcrypto)
Cross-validation discipline: every PQC algorithm referenced in the registry has at least one cross-implementor byte-anchor convergence proof attested at the algovoi-substrate-pqc attestations directory. A future PQC algorithm enters the registry only when a comparable cross-implementor convergence proof is recorded.

​
Cross-implementor convergence (non-normative annex)

The substrate-evidence pattern for v2 algorithm entries is the producer × verifier matrix: every producer in the matrix signs identical canonical bytes; every verifier in the matrix verifies every producer’s output. The acceptance criterion is that the same canonical SHA-256 anchor appears in every cell of the matrix, and every verifier produces the same accept/reject outcome on every producer’s signature. The current v2 matrix as of 2026-05-26:
  • 4 producers: Python (algovoi-substrate-pqc), TypeScript (@algovoi/substrate-pqc), Ruby (verifiers/ruby/produce.rb), PHP (verifiers/php/produce.php)
  • 6 verifiers: Python, TypeScript, Ruby, PHP, Java (Bouncy Castle), Perl
  • 24 cells, all PASS — same canonical SHA-256 sha256:cc8315f7…e0 across the matrix
  • Three audit-grade PQC implementations agree byte-for-byte: PQClean (via pqcrypto), @noble/post-quantum (Paul Miller), Bouncy Castle 1.84 (MLDSASigner + experimental FalconSigner)
Full attestation: _attestations/2026-05-26-cross-product-matrix.md. Machine-readable matrix: _attestations/2026-05-26-cross-product/matrix.json. The producer × verifier matrix is the methodology a downstream implementor SHOULD reproduce when proposing a new entry to the signature_algorithm registry. Cross-implementor convergence is the substrate-evidence shape; vendor-claim is not.

​
Hybrid scheme guidance (non-normative)

A receipt emitted under signature_algorithm: Hybrid-ES256K-ML-DSA-65 carries two signatures over the identical canonical bytes under JCS RFC 8785, one signed under each algorithm. A verifier checks both signatures; verification succeeds only if both signatures verify. An attacker forging the receipt must break both the classical and post-quantum algorithms simultaneously, which provides defence-in-depth across the migration window. Field shape (informative, not normative): 
{
  "signature_algorithm": "Hybrid-ES256K-ML-DSA-65",
  "signatures": {
    "ES256K": "<base64-encoded classical signature>",
    "ML-DSA-65": "<base64-encoded PQC signature>"
  }
}
Receipt formats wishing to adopt hybrid schemes SHOULD pin the precise field shape in the receipt format’s own normative spec; this discipline only names the algorithm and the dual-signing-over-identical-canonical-bytes property.

​
Migration from v1

There is no required migration. Adopters currently pinning canon_version: jcs-rfc8785-v1 continue to operate under v1 indefinitely. v2 is opt-in:
  • An adopter MAY continue emitting under v1 forever (classical-only deployment, no PQC migration required).
  • An adopter MAY emit some objects under v1 and others under v2 (gradual migration); each emitted object carries exactly one canon_version value identifying which version was applied at emission.
  • An adopter MAY migrate entirely to v2 (classical-plus-PQC deployment).
Verifier-side: a verifier MAY accept both v1 and v2 on input. The canon_version field in each received object names which version the verifier should apply. The canonicalisation core is unchanged between v1 and v2. A receipt emitted under v1 and a structurally-identical receipt emitted under v2 produce the same canonical bytes (and thus the same SHA-256 digest) for the shared fields; v2’s signature_algorithm is an additional field, not a re-canonicalisation.

​
Reference implementations

The signature-algorithm discipline and the fail-closed verifier are implemented in the AlgoVoi-authored PQC integration packages:

Python: algovoi-substrate-pqc

pip install algovoi-substrate-pqc. Implements the v2 signature_algorithm registry, fail-closed verifier discipline, and ES256 / Ed25519 / Falcon-1024 / ML-DSA-65 producers and verifiers. Wraps pqcrypto (PQClean) plus rfc8785. Apache 2.0.

TypeScript: @algovoi/substrate-pqc

npm install @algovoi/substrate-pqc. Pure-JS, browser + Node + Bun + Deno compatible. Wraps @noble/post-quantum (Paul Miller) for PQC, @noble/curves + @noble/hashes for classical, and canonicalize for JCS. Apache 2.0.
Both packages declare canon_version: jcs-rfc8785-v2 on every signed envelope they emit. Source code: chopmob-cloud/algovoi-substrate-pqc.

​
Substrate adopters

Parties anchoring their own services or specifications to v2 (pinning canon_version: jcs-rfc8785-v2 in publicly-citable artefacts) are recorded in the Substrate Adopters Registry alongside v1 adopters. The registry distinguishes v1 and v2 adoption via the Anchor column on each row. An adopter MAY appear in both v1 and v2 rows simultaneously if they emit under both discipline versions. Current v2 adopters:
  • AlgoVoi — reference implementation via algovoi-substrate-pqc (Python) and @algovoi/substrate-pqc (npm), published 2026-05-26. Cross-validated byte-for-byte across three audit-grade PQC implementations (PQClean via pqcrypto, @noble/post-quantum, Bouncy Castle 1.84 with MLDSASigner).
To request listing as a v2 adopter, follow the submission process in the registry. AlgoVoi validates submissions against the artefact’s canonical bytes and adds qualifying entries. The Citation discipline section of the Adopters Registry describes the patterns adopters typically surface when citing the discipline they anchor to. Those patterns apply equally to v1 and v2. v1 adopters retain their registry position. Adopting v2 adds a separate row pinned to jcs-rfc8785-v2 rather than replacing the v1 row. v1 adopters who do not migrate to v2 retain their Adopters Registry row indefinitely under the unchanged v1 Citation Discipline.

​
Acknowledgements (scoped credit)

The v2 discipline is solely AlgoVoi-authored. AlgoVoi acknowledges with thanks the post-quantum contribution recorded below. The cross-implementor convergence proof methodology rests on independent libraries from independent authors (see Reference implementations section above and PQC algorithm normative references); the substrate-author position is empirically validated by these libraries, not by AlgoVoi self-claim. The following contribution is acknowledged with credit scoped strictly to the work noted:
  • PQSafe — ML-DSA-65 (FIPS 204) signature contribution over the AP2 PaymentMandate canonical bytes, landed via chopmob-cloud/ap2-pq-conformance#1 (merged 2026-05-26). Credit is scoped to that ML-DSA-65 contribution only. PQSafe is not a co-author of the v2 discipline, the signature_algorithm registry, the fail-closed verifier rule, the cross-implementor convergence methodology, or any other normative or non-normative section of this document.
Reference-implementation libraries used in the cross-implementor matrix (PQClean via pqcrypto; @noble/post-quantum by Paul Miller; Bouncy Castle 1.84 with MLDSASigner and experimental FalconSigner) are cited in the PQC algorithm references section above; citation of a library is acknowledgment of the library’s role in cross-validation, not co-authorship of the discipline. Beyond the PQSafe scoped credit above (ML-DSA-65 contribution only), no other party is credited as co-author, contributor, reviewer, or endorser of the v2 discipline. Independent forks under the urn:x402:canonicalisation:jcs-rfc8785-v<n> URN namespace not authored by AlgoVoi are not part of the authoritative discipline lineage (see Version governance).

​
Version governance

Successor versions to v2 (jcs-rfc8785-v3, jcs-rfc8785-v4, …) within the urn:x402:canonicalisation:jcs-rfc8785-v<n> URN namespace are authored under the same authorship discipline established in v1: sole authorship by AlgoVoi, with downstream-adopter acknowledgments recorded in the Substrate Adopters Registry and (when the IETF I-D track resolves) in Appendix C of the corresponding Internet-Draft. Independent forks of the discipline under that URN namespace that are not authored by AlgoVoi or its named successors are not part of the authoritative discipline lineage; such forks SHOULD be published under their own URN namespace. Substantive proposals for inclusion in successor versions are welcome via pull requests against the canonical Mintlify source or off-list to the AlgoVoi authorship contact. Inclusion is at the editorial discretion of the discipline author.

​
See also