The Record: protocol specification

Status: Draft 0.1, licensed 2026-09-07. This directory is a working draft extracted from the reference implementation in this repository. Chapters 01 to 10, the licensing ruling, and the reference verifier with its twenty-two conformance vectors are all published at eformogi.com/spec, so a receiver can obtain and run the whole standard without cloning anything and without an account. The specification is licensed CC BY 4.0; everything under verifier/ is licensed Apache-2.0; the name and the marks are not licensed by either. See LICENSING.md for the split, the trademark line, and the conformance policy. SECURITY.md is not published and stays under the repository root license. This standard defines the Record, the general term for everything a family holds, and the receipts it produces, chief among them the Witness Transcript™ (ruled 2026-09-12), the receipt (tr_) a family issues to a receiver. See "The name" below.

Purpose

The Record is a learner-owned learning record: a set of entries (courses, projects, work samples, notes) held by the learner's family, witnessed by adults who put their name on specific claims, sealed into content-addressed receipts, signed, committed to a public append-only log, and verifiable by anyone with the receipt and the artifact, online or offline, without an account and without asking the operator whether the receipt is real.

This specification exists so that four readers can check the same claims from the same text:

• a registrar who wants to know what a receipt proves and what it does not,
• a standards reviewer (W3C Verifiable Credentials, Open Badges 3.0, CLR v2.0) who wants field-level mappings and the exact bytes that are hashed and signed,
• a security firm that wants the threat model, the domain-separation rules, and a verifier it can run without trusting us,
• a journalist who wants to know what the operator can and cannot do to a family's record.

Scope

In scope: the data model of a Record and its entries; the receipt grammar and canonical hashing; the witness ceremony and its tiers; family and organization keys and their custody; the transparency log and its anchoring; the verification algorithm and its error semantics; export mappings; the interface a jurisdiction plugin must satisfy; the threat model; conformance vectors and the reference verifier.

Out of scope: the operator's product surfaces (dashboards, pricing, marketing), the consent-intake product for institutions except where its ecr_ receipt touches the grammar, any claim about acceptance by any receiver, and GDPR (this draft is US-first; see chapter 09).

What the Record is not. It is not a credential issued by a school on the learner's behalf. It is not a claim that any receiver accepts it. It is not zero-knowledge storage except for the individual families that have completed the key-custody ceremony described in chapter 04, and even then only for the private vault, not for the published receipts, which are public by design.

The name

Witness Transcript is a mark of Eformogi, Inc., not a description any implementation may claim by default. An implementation whose records pass the conformance suite in chapter 10 may call the resulting artifact a Witness Transcript and use the name in its own prose; an implementation that has not passed may not. The mark may not appear in a company name or a product name. Course rows and other entries a Record contains are not themselves Witness Transcripts; they are part of one. The full trademark text is in LICENSING.md; the conformance rule is in 10-conformance.md.

Conventions

• The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.
• File paths in backticks (shared/merkleLog.js) point at the reference implementation in this repository. Where the text and the code disagree, the code is the current truth and the text is a bug to fix in this draft.
• Every hash in this specification is SHA-256 over UTF-8 bytes, rendered as 64 lowercase hex characters, unless stated otherwise.
• Every signature is Ed25519, rendered as multibase base58btc with the z prefix, over a context-prefixed message, unless stated otherwise.
• Field tables carry four columns: name, type, required, meaning. "required" refers to the artifact as produced by the reference implementation, not to a wire contract a receiver may relax.

Chapters

Running the reference verifier

The verifier is a single Node file with no dependencies and no network access. Every file it needs is published alongside these chapters at /spec/verifier; nothing here requires a clone.

# every conformance vector (exits non-zero on any mismatch)
sh spec/verifier/run-vectors.sh

# one vector, with each step printed
node spec/verifier/verify-offline.js spec/verifier/vectors/v18-proof-four-steps-valid.json

# a real proof, downloaded from a /verify page or fetched from /api/receipt-proof?id=<receipt id>
node spec/verifier/verify-offline.js proof.json [--jwk pub.jwk] [--sha256 <hash of the artifact you hold>]

Exit codes: 0 verified or verdict matched, 1 failed or verdict mismatched, 2 usage or unreadable input. Node 18 or newer.

Relationship to the reference implementation

This draft documents what the code does today, including its gaps, and marks each gap as planned with the missing piece named. It does not describe a system that does not exist yet. Where the code is flag-gated (family signing under EFG_SIGNED_RECEIPTS, key custody under VITE_ZK_CUSTODY), the text says so.