RAGBAZ / river / Nostoi
A digest is only useful if two implementations agree on the bytes before hashing. That agreement has to be specified, not assumed.
published · Updated 2026-10-05
01 Nostoi
The digest is the SHA-256, lowercase hex, of the record without its digest field, encoded as canonical JSON: keys in code point order, no whitespace, and strings escaped only where the specification says so. Not the file as it happens to sit on your disk. Not a pretty-printed object. Not a JSON object with the fields in the order you happened to write them.
Getting this exactly right is the entire difference between a chain two languages can share and a chain that verifies only on the machine that made it. Every divergence that looks cosmetic is a divergence that will surface as a broken chain in someone else's timezone.
02 Nostoi
A record body may not contain floats. Their textual representation differs between languages and even between versions of the same language, so two correct implementations can serialise the same value differently and produce different digests for identical content.
The rule is to write decimals as strings. This is a small inconvenience at authoring time and a permanent one avoided later, and it is the clearest example of a portability constraint that looks pedantic until the first cross-language test fails.
03 Nostoi
The test suite checks the Rust implementation against the Python reference in both directions: chains written in one verify in the other. The reference uses Python's standard library, providing an independent implementation without a native extension.
Native Python bindings, a versioned WIT component and generated JavaScript and TypeScript bindings exist in the checkout. The current binding contract supports canonical attestation bytes and checking a document against a chain, with signature state explicitly unchecked. Host-side signature verification is a separate responsibility; registry publication remains pending.
04 Nostoi
Agreement on serialisation is not agreement on meaning. Two parties can encode the same bytes while describing entirely different events, and a chain will faithfully preserve that ambiguity.
It also says nothing about who produced a record. Canonical form makes the content checkable; it does not make it authentic. Authentication is a separate question with separate machinery, and a system that answers the first and is assumed to answer the second has a gap exactly where it is least likely to be noticed.
A conversation, not a sales funnel
Ask a question, tell us what you need, offer a contribution or simply show your support. RAGBAZ is a software studio working toward kindness, mutual cooperation and the good of all beings.
Prefer email? ragbaz@proton.me