Open specification / v1

Spec

The Matrix Scroll protocol is a small JSON signature envelope for AI-assisted code provenance. It is designed to be implemented by any SDK, verifier, CI gate, or hardware vendor.

Identity schemamatrixscroll.identity.v1
Signature schemamatrixscroll.signature.v1
AlgorithmEd25519 signatures as defined by RFC 8032.
Canonical inputJSON object with the top-level signature property excluded before signing.
EncodingSorted object keys, compact separators, ASCII escaping, UTF-8 bytes, and no NaN or Infinity values.
Device IDMS-XXXX-XXXX derived from SHA-256(public_key), first eight uppercase hex characters split 4-4.
Wire formatEmbeddable JSON signature block carried inside any release, commit, evidence, or vendor manifest.
Verifier ruleVerify the canonical manifest bytes with the embedded public key and signature value. Key access is never required.

Canonical encoding

The byte contract.

The top-level signature block is excluded; keys are sorted recursively; whitespace is stripped; non-ASCII is escaped with ensure_ascii; NaN and Infinity are rejected with allow_nan=False; compact separators are (",", ":"); the resulting UTF-8 bytes are signed.

body = {k: v for k, v in payload.items() if k != "signature"}
json.dumps(
    body,
    sort_keys=True,
    ensure_ascii=True,
    allow_nan=False,
    separators=(",", ":"),
).encode("utf-8")
"signature": {
  "schema": "matrixscroll.signature.v1",
  "algorithm": "ed25519",
  "device_id": "MS-EAB9-1217",
  "public_key": "Vxee+i1db9b...",
  "mode": "emulated",
  "signed_at": "2026-06-19T09:43:35Z",
  "value": "SQPMBxv3Mvjl..."
}

Signature block

Minimum public envelope.

Every verifier should require the signature schema, Ed25519 algorithm, public key, device ID, mode, timestamp, and signature value. Unknown fields may be displayed, but should not be needed for verification.

Compliance levels

One format, multiple roots of trust.

L1 Emulated

Software key

File-backed key for local development, demos, tests, and CI. Shipping today as the reference path.

L2 Hardware

Secure element

Hardware profile: signing key is generated and used inside NXP SE050 or equivalent hardware. In v0.1.x this is a roadmap profile; the shipping SDK uses emulated software keys.

L3 Attested

Remote attestation

Hardware signing plus device attestation for fleet policy, enrollment, and enterprise trust registries. Roadmap.