Canonicalization & hashing
ucy-hash-v2: canonical bytes, Merkle trees, salts, and recordRoot.
From values to deterministic bytes
Canonical JSON uses compact UTF-8, code-point key sorting, and Unicode NFC normalization. Keys that collide after normalization are rejected. Optional fields are omitted rather than set to null.
Metrics are canonical decimal strings, without floating-point arithmetic. 370.10 normalizes to 370.1; exponent notation and unknown schema fields are rejected.
Build the record identity
The D_* constants separate hash domains; each period salt is 32 random bytes. The formulas below are a schematic, not a substitute implementation.
periodCount is ABI-encoded as uint256. The Merkle tree uses OpenZeppelin StandardMerkleTree with bytes32 values and its double-hashing convention, including for a single period.
headerHash = keccak256(utf8(canonical(header)))
dataHash_i = keccak256(utf8(canonical({metrics, period})))
leaf_i = keccak256(abi.encode(D_period, headerHash, dataHash_i, salt_i))
periodsRoot = StandardMerkleTree.of([[leaf_i]], ["bytes32"]).root
recordRoot = keccak256(abi.encode(D_record, headerHash, periodsRoot, periodCount))What must be retained
Retain exact document bytes, source, salts, registry snapshot, and algorithm version. The uploaded metric file alone cannot reconstruct recordRoot because ingestion creates the header and salts.
A registry snapshot captured at ingestion lets historical records remain verifiable when the dictionary expands. Use repository golden vectors and the verifier engine to check compatibility.
Sources reviewed in the monorepo
Based on source code; live availability is stated separately.
packages/hashing/src/canonicalize.tspackages/hashing/src/hash-v2.tsdocs/specs/ucy-hash-v2.md
