Open specification / v1 (frozen)

Spec

The Matrix Scroll protocol uses a compact JSON signature envelope for agent-assisted Git commit provenance. Frozen v1 under Apache-2.0: SPEC.md ยท commit-envelope.v1.json.

Read SPEC.md Open schema Test the verifier
Canonical bytes

Sorted keys, ASCII escaping, compact separators, and the top-level signature removed before signing.

Embedded proof

Public key, device ID, mode, timestamp, and signature value travel with the document.

One wire format

The same public contract spans release manifests, commit envelopes, and evidence packs.

Identity schemamatrixscroll.identity.v1
Signature schemamatrixscroll.signature.v1
Commit envelope schemamatrixscroll.commit_envelope.v1 - JSON schema - GitHub
Release manifest schemarelease-manifest.v1.json
Evidence pack schemaevidence-pack.v1.json
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 release, commit, evidence, or vendor manifests.
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 (",", ":"), and 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 shown, but they should not be required 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 Enclave

Secure enclave

Enclave profile: signing key is generated and managed inside secure enclaves, TPMs, or local keychains. Roadmap, not the default shipping SDK path today.

L3 Attested

Durable attestation

Enclave signing combined with transparency logs and remote identity verification registries. Roadmap.