How the Zanii protocol changes
The protocol is the contract between everyone who writes receipts and everyone who checks them, long after either has moved on. A change that quietly altered how an old receipt is judged would turn honest history into apparent tampering. These rules exist to make that impossible.
The promise
A receipt that verified under the version it was written for verifies forever.
No later version may change a past verdict. When the rules for new receipts change, the
old rules stay available to verifiers — for example, payload commitments written before
1.1 remain checkable with verifyPayloadLegacy / verify_payload_legacy.
Two version numbers
- The document version,
MAJOR.MINOR(currently 1.2), names this specification. - The wire version, the
"v"field inside every receipt, certificate and record. It equals the document'sMAJOR. Every 1.x document describes"v": 1objects.
What each kind of change is
| Change | Version | Example |
|---|---|---|
| A new optional field, receipt convention, or endpoint that no existing verdict depends on | MINOR | payload_encoding (1.1), risk (1.2) |
| A clarification that changes no verdict for any existing object | MINOR | specifying an encoding every implementation already agreed on |
| Anything that changes how an existing object is encoded, hashed, signed or judged | MAJOR, new "v" |
a different signature scheme for receipts |
| Retroactively changing whether a past object verifies | never |
What makes additive changes safe is one rule every verifier follows: a field the verifier does not recognise is still part of the signed bytes, and is never a reason to reject. A new optional field is therefore covered by the existing signature, and an older verifier still verifies the receipt correctly without understanding the field.
How a change lands
- A proposal states the problem, the change, and its class from the table above.
- The change ships complete, never as prose alone:
- the specification text;
- conformance vectors in the published kit, including must-reject cases;
- both reference implementations (TypeScript and Python), byte-identical on the
vectors;
- if it touches the log, receipt chains or monitoring, an updated formal model, with
every configuration in
formal/ending as expected. - The release bumps the document version, records the change in
CHANGELOG.md, and freezes the previous version verbatim inversions/. Released versions are never edited.
Who decides
The protocol is maintained by Zanii. Proposals and implementation questions go to info@zanii.agency. The process above applies to Zanii's own changes first: nothing reaches the specification without vectors, both implementations, and — where it applies — a passing model check.