The law and the conformance suite

The rules are written as two law texts, each with a frozen core. One run shows whether an implementation conforms.

Two laws

zikaron/1

The law of the ledger: the byte format of an entry, signatures, how entries link, the audit report, the two forms of anchoring. The text is base/zikaron-v1.md.

zikaron.kit/1

The law of the client’s documents: fingerprint manifests and acknowledgements, credential payloads, record kits, readings, the six checks on a grant. It builds on zikaron/1. The text is base/zikaron-kit-v1.md.

Every rule in the law is a machine decision defined over all inputs. The rules fall into three classes: those decided from one entry alone; those decided from a set of entries together with the audit inputs; and those decided against a chain. The first two are decided offline, and they are exactly what the freeze covers.

The frozen cores

Each law has a reference implementation in pure Python over the standard library: the zikaron/1 core is five files under impl-py/, and the zikaron.kit/1 core is four files under kit-py/. List the SHA-256 of each file with its name, one per line, take the SHA-256 of that listing, and you have the release digest named in the law text.

Once the digest is written into the law text, the core is the criterion and the text expounds it. Both say the same thing; where readings differ, run the core on that input and take its output.

Conditions for a freeze

Freezing a core first takes an implementation written from the law text alone that agrees with it byte for byte on a generated corpus; then at least a hundred thousand fuzz samples with zero panics, zero hangs and zero wrong accepts, the same input always getting the same answer. Under every seed, the corpus has to cover both sides of every closed boundary in the two offline classes. Once all conditions are met, the digest is written into the law text and the freeze is complete.

Testing an implementation

Your implementation must expose the agreed command-line interface: zk1 for zikaron/1 and zkk for zikaron.kit/1. Each command reads its agreed inputs (mostly one file) and writes one canonical JSON value to standard output. The full contracts are HARNESS.md and HARNESS-KIT.md.

The corpus generator rewrites files in its directory, so copy base/zikaron-conformance out of the repository first and work in the copy.

The comparer lists every divergence. Zero divergences is evidence of conformance; conformance is defined as agreement on every input, so a divergence found outside the corpus belongs in an issue, as a place where the corpus should grow.

The chain-facing reference

For the rules decided against a chain, the reference is the recordings under base/zikaron-core/fixtures/: each records a stretch of chain data with the expected scan result. A scanner replays every recording and should reproduce the expected result byte for byte. scan-py/ is an independently written Python scanner that agrees with every recording.

Changing the law

A frozen core stays as it is. Changing the rules takes zikaron/2: a new spec name, a new signing-domain literal, a new core and a new digest. Ledgers written under zikaron/1 stay valid for good.

The prose of a law text is the core’s textbook and may be revised for clarity; while the core’s digest keeps its value, the law is still zikaron/1.

Outside the law

The law expressly leaves some matters to readers, arbiters and terms: money, the meaning of a grant, the weight of evidence, whether a record has to be anchored. Code that implements such features belongs to the tooling layer; see law §11.