[Proposal] v0 conformance vectors for open_mandate_hash derivation (cross-impl validated)

[chopmob-cloud]

Summary

Proposing a v0 conformance vector set for open_mandate_hash derivation against code/sdk/schemas/ap2/open_checkout_mandate.json. Independently cross-implementation validated, ready to land as tests/conformance/canonicalization/ (or similar) for any third implementer to derive deterministically.

Why now

In Discussion #262 (cycles-ap2-python show-and-tell), the maintainer @amavashev surfaced the gap directly:

Which raises the open question for the AP2 community: do we have, or plan to publish, conformance vectors for open_mandate_hash derivation? […] Spec-published vectors would let any third implementer derive the same hash deterministically rather than re-arrive at the assumption — the difference between "interop works because we agree" and "interop works because the spec is precise enough not to need agreement."

This issue is the artefact that answers that question, ready for spec inclusion.

Derivation rule (proposed normative text)

open_mandate_hash = SHA-256(JCS_RFC8785(unsigned open-checkout-mandate body))

Lowercase hex. Hash input is the claims object, not the JWS compact form. The latter is the load-bearing interop subtlety — JWS re-encoding by intermediaries changes the envelope even when the underlying payload is identical, which would silently break hash matching between implementations that round-trip through different JWS libraries.

v0 conformance vectors

Published at https://gist.github.com/chopmob-cloud/1dca25fd6107db4b7a30bed5dbf2ded8 — 7 vectors anchored to code/sdk/schemas/ap2/open_checkout_mandate.json at sha e3d9cafa7311d90612c7f908ae9b8821ddc8735a, structured as pairs so the canonicalisation rules are self-checking:

Vector	Pair invariant	Result
baseline-001	—	reference baseline
object-key-order-002	with 001	JCS sorts object members → byte-identical to 001
array-order-003	with 001	arrays are order-significant; do NOT sort → differs from 001
optional-fields-004	with 001	presence ≠ absence, not collapsed → differs from 001
currency-minor-unit-005	—	ISO-4217 integer minor units; no decimal/float
unicode-nfc-006a	with 006b	RFC 8785 does NO Unicode normalisation
unicode-nfd-006b	with 006a	NFC and NFD inputs hash differently

The array-order and Unicode pairs are the ones that catch divergence in practice. An implementer who sorts arrays "to canonicalise" or who NFC-normalises merchant strings before hashing matches the wrong vector immediately rather than silently producing an incompatible hash.

Cross-implementation validation

Implementation	Authors	Language	Result
rfc8785@0.1.4	William Woodruff	Python 3.14.3	7/7 JCS bytes + 7/7 hashes + 4/4 pair invariants ✓
canonicalize@3.0.0	Samuel Erdtman + Anders Rundgren (contributor — RFC 8785 author)	JavaScript	7/7 JCS bytes + 7/7 hashes + 4/4 pair invariants ✓

Different authors, different languages, entirely different codebases — identical canonical bytes and identical hashes for every vector. The Unicode NFC-vs-NFD pair (the canonicalisation edge case where RFC 8785 implementations most often diverge) agrees byte-for-byte under both, which is the direct evidence that the no-Unicode-normalisation rule is implementation-independent.

Validation history is in Discussion #262 comments (2026-05-19 → 2026-05-20).

Scope and non-scope

In scope of this issue:

• Adopting the derivation rule as normative spec text
• Adopting the 7 v0 vectors as official conformance fixtures
• Suggested repo location: code/sdk/schemas/ap2/conformance/open_mandate_hash/

Not in scope (separate work):

• The JWS signing layer above the hashed body (out of scope of canonicalisation)
• payment_mandate.json, payment_receipt.json, checkout_mandate.json, etc. — same rule should likely apply uniformly across all mandate types, but each needs its own vector set keyed to its schema. Happy to follow up with sibling sets if v0 lands well.

Happy to

• Reshape vector JSON into whatever the maintainers prefer (current shape is {mandate_body, expected_jcs_bytes_b64, expected_open_mandate_hash} per vector, plus pair-invariant declarations)
• Submit a PR adding the fixtures as files rather than gist-linked
• Add a build script that regenerates the vectors from the schema so the artefact is reproducible-by-construction, not trust-the-static-file
• Extend the set if maintainers want additional rules covered (numeric precision edge cases, deeply nested arrays, large-Unicode handling)

Filing this as [Proposal] per the prior-art naming on #250 / #224 / #255.

[amavashev]

Closing the cross-impl loop for the record: the third reference implementation (gowebpki/jcs v1.0.1, Go) also reproduces all 7 v0 vectors byte-for-byte, with all four pair invariants holding.

Implementation	Author(s)	Language	Result
rfc8785@0.1.4	William Woodruff	Python	7/7 JCS + 7/7 hash + 4/4 pair invariants ✓
canonicalize@3.0.0	Erdtman + Rundgren (RFC 8785 author, contributor)	JavaScript	7/7 JCS + 7/7 hash + 4/4 pair invariants ✓
gowebpki/jcs v1.0.1	GoWebPKI org	Go	7/7 JCS + 7/7 hash + 4/4 pair invariants ✓

Three non-overlapping author sets, three languages, three codebases — same canonical bytes and hashes for every vector. That covers the three languages an AP2 conformance CI matrix would plausibly span; a maintainer picking the proposal up has a directly usable matrix shape already validated.

Strong support for adoption from the cycles-ap2-python side. The proposal scope (derivation rule + v0 fixtures at code/sdk/schemas/ap2/conformance/open_mandate_hash/ + leaving sibling mandate types for follow-up) matches what a downstream library consumer needs to cite as upstream-authoritative rather than community-seeded. Happy to validate sibling vector sets the same way if/when they land.

[chopmob-cloud]

@amavashev — the Go run is exactly what the proposal needed to lift from "two implementers agree" to "three independent canonicalisers across the three languages an AP2 conformance CI would span." Appreciated the unsolicited third validation.

The matrix shape you've drawn is the one I'd hope maintainers consider as the conformance fixture's CI form — three rows by 11 columns (7 vector JCS-byte matches + 7 hash matches + 4 pair-invariant assertions condensed), keyed on the published mandate_body inputs. Trivial to wire into a workflow if the proposal lands.

Two confirmations on the open scope, in case a maintainer drops by and wants the picture:

1. Sibling mandate types are ready to follow. The same JCS-RFC 8785 + SHA-256 derivation rule should apply uniformly across open_payment_mandate, payment_mandate, checkout_mandate, and the receipt variants. I'd commit to publishing v0 vector sets for each, mirroring the seven-vector pair structure, on the same timeline as adoption of this one — pair invariants stay constant, the schema anchor and mandate_body shape change per type. Happy to take that on as the same author-side commitment that produced this set.

2. CI-fixture migration is non-disruptive. The current gist artefact is canonical-bytes + hash pairs per vector. Reshaping into per-mandate-type files under code/sdk/schemas/ap2/conformance/open_mandate_hash/ (and siblings) is mechanical — happy to PR fixture files once a maintainer signals the preferred layout. Reproducible build script (regenerates vectors from the schema) can ship alongside if that helps the maintenance story.

Will hold for maintainer triage on the proposal itself. Independent runs against the v0 set are welcome from any other implementer reading this — the gist contains everything needed to reproduce.

[Ectsang]

Independent third-party attestations of the two runners the README flagged as welcomed (Node + Java).

Runner	Author of impl	Language	Re-run result
canonicalize@3.0.0	Erdtman + Rundgren	JavaScript	7/7 hash + 4/4 pair invariants ✓
cyberphone/json-canonicalization	Rundgren (RFC 8785 author, reference)	Java	7/7 hash + 4/4 pair invariants ✓

Both runs against ap2-omh-v0.json from the gist, on a clean machine, no shared state with @chopmob-cloud's or @amavashev's runs. SHA-256 output byte-identical to the published expected_open_mandate_hash for all seven vectors, including the Unicode NFC-vs-NFD pair (006a/006b).

That brings the cross-impl status to five validators across the three Python + JS + Java + Go languages, with all four library codebases (rfc8785, canonicalize, cyberphone/json-canonicalization, gowebpki/jcs) now attested by at least one author other than the runner's author. Strong support for adoption from this side.

The pair-invariant construction in the artefact is doing useful work: each divergence case (array sort, Unicode normalisation, optional-field collapse) is caught at the rule level rather than at the per-vector level, which is the property a v0 fixture needs to make the spec self-checking for future implementers.

[chopmob-cloud]

@Ectsang — thank you. The two independent re-runs of canonicalize and cyberphone/json-canonicalization close exactly the seam the v0 publication had left honest about: the JS and Java runs were originally self-run alongside the Python reference, with @amavashev's prior runs covering the Python and Go sides. Your clean-machine attestations land the JS and Java independence directly.

Combined with @amavashev's prior Python re-run and Go run, plus @seritalien's Rust 5th-impl from vauban-zkpay-x402 (gist seritalien/b0b86baabae33e289fdb6d2f3fb30130) yesterday, the cross-impl provenance is now:

Library	Language	Author of impl	Runs by	Third-party-attested
rfc8785@0.1.4	Python	Trail of Bits	chopmob-cloud, @amavashev	✓
canonicalize@3.0.0	JS	Erdtman + Rundgren (contrib.)	chopmob-cloud, @Ectsang	✓
gowebpki/jcs v1.0.1	Go	GoWebPKI	@amavashev	✓ (originator)
cyberphone/json-canonicalization	Java	Rundgren (RFC 8785 reference)	chopmob-cloud, @Ectsang	✓
serde_jcs 0.2.0	Rust	l1h3r	@seritalien	✓ (originator)

Five libraries / five languages / four non-overlapping author sets / every codebase third-party-attested. That matches the matrix shape we hoped maintainers would see going into the conformance decision.

Concur on the structural read of the pair-invariant construction. Each invariant is asserted at the rule level — same_hash_as:<vector> and different_hash_from:<vector> — rather than as per-vector golden values alone, which keeps the v0 fixture self-checking against schema drift across future implementers and protects against the AP2 schema evolving in ways that would silently invalidate vector hashes without breaking the relations.

For context across adjacent threads: the same pair-invariant discipline is now applied at the attestation layer (privacy_class_v0/v0.1 on x402 #2326) with a seventh invariant for field-name canonicalisation, and a coalition is forming on x402 #2326 around a shared canonicalisation section that would reference these vector sets normatively. Independent attestations of the AP2 set bolster that work by construction.

— AlgoVoi (chopmob-cloud)

[seritalien]

@chopmob-cloud thank you for the cross-impl matrix update and the runner provenance breakdown ; five libraries / five languages / four non-overlapping author sets, with every codebase third-party attested, is the matrix shape an AP2 maintainer can adopt as upstream-authoritative.

Following up here for the AP2 thread record : Vauban has extended the serde_jcs 0.2.0 Rust runner to two adjacent AlgoVoi conformance vector sets since the AP2 OMH v0 publication :

Vector set	Vauban Rust runner result
AP2 OMH v0 (this issue)	7/7 vectors + 4/4 pair invariants ✓
CTEF + APS v1	14/14 vectors + 12/12 pair invariants ✓
privacy_class v0.1 (x402 #2326)	13/13 vectors + 12/12 pair invariants ✓

Cumulative : 34/34 vectors + 28/28 pair invariants under serde_jcs 0.2.0. The same Rust impl reproduces every vector across the three published artefacts byte-for-byte, including all Unicode NFC vs NFD pairs and the field-name canonicalisation invariant from privacy_class v0.1. The pair-invariant construction discipline @chopmob-cloud and @Ectsang highlighted in this thread holds uniformly across the three sets.

Vauban runner gist updated : https://gist.github.com/seritalien/b0b86baabae33e289fdb6d2f3fb30130 ; three runners + Cargo.toml + extended README documenting the cross-set status. The pattern transfers cleanly to any sibling mandate type the AP2 maintainers want to anchor next.

For the AP2 v0 fixture decision specifically, the cross-spec status now suggests the proposal landing is on solid ground regardless of the language a downstream library picks. The cycles-ap2-python side (@amavashev), the Java side (@Ectsang attesting Rundgren's reference implementation), and the Rust side (this runner) all reproduce the same canonical bytes for the same inputs.

When sibling mandate type vector sets (open_payment_mandate, payment_mandate, checkout_mandate, receipts) follow @chopmob-cloud's committed timeline, the same Rust runner shape will validate those by changing only the schema anchor and mandate_body shape. The 4/4 pair-invariant assertions (object_key_order, array_order, optional_fields, unicode_normalisation) carry across by construction.

Cross-protocol context for AP2 readers : the same JCS substrate vector sets and the same pair-invariant discipline are also anchoring a coalition canonicalisation discipline section in progress on x402-foundation/x402#2326, which both privacy_class (here as v0.1) and the x402 receipt_format extension will reference normatively. The cross-protocol normalisation matters because downstream consumers of either AP2 or x402 should not have to learn two different canonicalisation rules to handle agentic-commerce receipts.

Strong support for adoption of the v0 fixtures into code/sdk/schemas/ap2/conformance/open_mandate_hash/ from the cryptographic-axis side of this coalition.

— Vauban Pay (seritalien)

[chopmob-cloud]

@seritalien -- 34/34 vectors + 28/28 pair invariants under serde_jcs 0.2.0 across the three published sets is the cross-set result that closes the adoption-confidence question. The critical check is the pair-invariant construction: array_order, object_key_order, optional_fields, and unicode_normalisation all holding uniformly across AP2 OMH v0, CTEF+APS v1, and privacy_class v0.1 means the fixture discipline transfers between mandate types by construction, not just by coincidence on the first set.

For AP2 maintainers reading this thread:

The cross-set Rust result is additive to the prior three-impl coverage (Python rfc8785 / JS canonicalize / Java cyberphone/json-canonicalization) plus @Ectsang's independent Java re-run. The full matrix for AP2 OMH v0 specifically is now: Python / JS / Go / Java (two independent runs) / Rust -- 5 language runtimes, 4 non-overlapping library authors, 0 divergences on any vector including Unicode NFC/NFD pairs.

On sibling mandate types:

The committed timeline for open_payment_mandate, payment_mandate, checkout_mandate, and receipt vector sets follows. The pair-invariant assertions carry across by construction as seritalien notes -- the same 4-assertion test harness validates any mandate shape by swapping the mandate_body anchor. The Rust runner gist update confirms that shape transfers without runner modifications.

Cross-protocol context for this thread:

The same JCS substrate and pair-invariant discipline is also anchoring the shared canonicalisation section (x402-foundation/x402#2326, v3 just locked with three-voice sign-off). The cross-protocol normalisation is intentional: a downstream library consuming both AP2 mandate receipts and x402 payment receipts should derive identical canonical bytes under the same rule. Single JCS substrate, two protocol surfaces. The per-chain envelope v0 set (the fourth AlgoVoi anchor) specifically addresses the chain-level encoding variation both protocols encounter.

-- AlgoVoi (chopmob-cloud)

[seritalien]

The pair-invariant structure (006a/006b especially) is the right approach ; purely positive vectors don't catch the silent divergence cases, and Unicode NFC/NFD is exactly where implementations disagree in practice without realising it.

Adjacent context from the x402 Linux Foundation working group: we've converged on the same JCS RFC 8785 composition for canonical byte construction in the STARK receipts extension (draft-vauban-x402-stark-receipts-00, live). The load-bearing subtlety you identified ; hash the claims object, not the JWS compact form ; is the same one we documented in x402#2326 canonicalisation v3: intermediaries that round-trip the JWS envelope can silently break hash matching between implementations that otherwise agree on the underlying payload.

Two things worth normalising across AP2 and x402:

1. Shared JCS reference: open_mandate_hash = SHA-256(JCS_RFC8785(unsigned body)) maps directly onto how we construct SettlementReceipt proof inputs in x402 STARK receipts ; same composition, same exclusion of the JWS envelope layer. If AP2 checkout mandates and x402 payment receipts reference the same normative JCS discipline (RFC 8785 + the explicit no-JWS-envelope rule), interop between the two protocols becomes deterministic by construction rather than by convention.

2. Third implementation (Rust): we can run your 7 vectors against our Rust JCS implementation (zkpay-types) as a third cross-impl validation. Happy to publish results here before the spec lands if it helps the maintainers gain confidence ahead of merging.

The 7-vector set is solid. A PR landing these in code/sdk/schemas/ap2/conformance/open_mandate_hash/ with a reproducible build script would be the right artefact ; static fixtures plus a derive-from-schema generator so the set isn't trusted-static.

Vauban Pay (pay.vauban.tech) / x402 Linux Foundation contributor

[seritalien]

Rust third-implementation run ; ap2-omh-v0 (serde_jcs 0.2.0, RFC 8785)

vector_id                                          jcs      hash
--------------------------------------------------------------------
ap2-omh-v0-baseline-001                             OK       OK
ap2-omh-v0-object-key-order-002                     OK       OK
ap2-omh-v0-array-order-003                          OK       OK
ap2-omh-v0-optional-fields-004                      OK       OK
ap2-omh-v0-currency-minor-unit-005                  OK       OK
ap2-omh-v0-unicode-nfc-006a                         OK       OK
ap2-omh-v0-unicode-nfd-006b                         OK       OK

Pair invariants:
  PASS  001 == 002 (object key order ; JCS sorts, hash must match)
  PASS  001 != 003 (array order significant ; JCS preserves, hash must differ)
  PASS  001 != 004 (optional fields not collapsed ; hash must differ)
  PASS  006a != 006b (no Unicode normalisation ; NFC != NFD, hash must differ)

==> 7/7 vectors pass (jcs bytes + hash), 4/4 pair invariants pass
    Implementation : serde_jcs 0.2.0 (Rust, l1h3r) ; RFC 8785 JSON Canonicalization Scheme + SHA-256

Three independent implementations now agree byte-for-byte across all 7 vectors:

Implementation	Authors	Language	JCS bytes	Hash	Pair invariants
rfc8785@0.1.4	William Woodruff	Python	7/7	7/7	4/4
canonicalize@3.0.0	Samuel Erdtman + Anders Rundgren	JavaScript	7/7	7/7	4/4
serde_jcs 0.2.0	l1h3r	Rust	7/7	7/7	4/4

The Unicode pair (006a/006b) is the one that catches divergent implementations ; byte-identical output from three codebases in three languages confirms the no-normalisation rule is implementation-independent.

Runner source : crates/zkpay-x402/examples/runner-ap2-omh.rs in the Vauban Pay workspace (Apache-2.0, available if the maintainers want to reference it alongside the existing runners).

Vauban Pay (pay.vauban.tech) / x402 Linux Foundation contributor

[chopmob-cloud]

@seritalien -- Rust 7/7 + 4/4 pair invariants is the right addition. Combined with AlgoVoi's earlier 4-impl run on this set, the AP2 OMH v0 vectors are now 5-implementation multi-party attested across all 7 vectors and all 4 pair invariants -- including the 006a/006b Unicode NFC/NFD divergence pair that catches normalisation drift.

The five runs together:

Implementation	Language	Library author	Run / attestation
rfc8785@0.1.4	Python	Trail of Bits	AlgoVoi (+ independent @amavashev attestation)
canonicalize@3.0.0	JavaScript	Erdtman / Rundgren	AlgoVoi (+ independent @Ectsang attestation)
gowebpki/jcs v1.0.1	Go	Web PKI WG	AlgoVoi
cyberphone/json-canonicalization	Java	Anders Rundgren	AlgoVoi
serde_jcs 0.2.0	Rust	l1h3r	Vauban Pay (@seritalien)

7 vectors × 5 implementations × 3 organisations involved (AlgoVoi, Vauban Pay, two independent third-party attestations). No remaining cross-impl ambiguity on the AP2 OMH v0 set.

For AP2 maintainers reading this thread. The v0 set is AlgoVoi-authored, Apache 2.0, published at gist chopmob-cloud/1dca25fd6107db4b7a30bed5dbf2ded8, with single-file runner sources for all five reference implementations alongside the vectors. The broader substrate the x402 / A2A / AP2 coalition is converging on (specs/canonicalisation.md, PR #2436 in x402-foundation/x402, three-voice co-signed, also 5-impl attested) anchors on the same JCS RFC 8785 + SHA-256 composition.

A first-pass AP2 normative reference to the open_mandate_hash derivation -- citing this v0 set as the conformance vectors -- would freeze the cross-protocol interop surface that AP2 mandates, x402 payment receipts, and A2A trust evidence all need to share. The full matrix is now in place to support that.

-- AlgoVoi (chopmob-cloud)

[jithinraj]

Adding one downstream implementation data point.

PEAC added a small fixture set that uses the open_mandate_hash derivation discussed here when recording AP2 mandate references in signed interaction records:

https://github.com/peacprotocol/peac/tree/main/specs/conformance/interop/ap2-open-mandate-hash

The fixtures are complementary to the v0 conformance vectors in this issue, not a replacement for them. They cover three scenario-shaped positive cases: baseline, budget-bound, and expiry-bound, plus two composition-failure cases: non-SHA-256 digest and non-JCS canonicalization.

The boundary is simple: AP2 defines the mandate and open_mandate_hash derivation; PEAC records a reference to the AP2 mandate artifact. No AP2 semantics change, no alternate derivation rule, and no PEAC-specific behavior requested.

If these vectors land in the AP2 repo, the PEAC-side fixtures can track them as the upstream reference point.

[chopmob-cloud]

@jithinraj -- thanks. The boundary you drew (AP2 defines the mandate shape and open_mandate_hash derivation; PEAC records a reference to the AP2 mandate artifact, no semantic change) is the right one and the kind of downstream composition the v0 set was designed to receive.

Two observations on the PEAC fixture set worth noting for AP2 maintainers reading this thread:

Positive coverage (baseline / budget-bound / expiry-bound). Three scenario-shaped variations on a real mandate, each consuming the v0 derivation rule unchanged. Confirms the derivation transfers to the next layer (signed interaction records) by content-addressed reference rather than by re-derivation, which is the property open_mandate_hash was specified to provide.

Negative coverage (non-SHA-256 digest / non-JCS canonicalisation). These two failure cases are the precise discipline-anchor failure modes the v0 set was built to prevent. A fixture set that includes them as explicit failures is more rigorous than one that only ships positive vectors. The composition is verifiable from PEAC's side: a PEAC interaction record that references a mandate computed under SHA-512, or under any non-JCS canonicalisation, fails to match the AP2-side open_mandate_hash and the boundary holds.

PEAC has been added to the Substrate Adopters Registry at docs.algovoi.co.uk/adopters as a downstream-adopter, with the PEAC fixture path as the evidence link. The registry is the public web-accessible parallel to the Appendix C "Known Adopters" section maintained in the underlying canonicalisation Internet-Draft.

For AP2 maintainers: this thread now has direct evidence of organic downstream consumption (PEAC), independent cross-impl validation across five language runtimes by three organisations, and two independent third-party attestation runs. Landing the v0 set normatively, citing the gist as the conformance vector reference, gives PEAC and other downstream consumers an upstream anchor to track rather than a forked-fixture-set drift risk.

-- AlgoVoi