Skip to content
Documentation/Technical reference

Canonicalization & hashing

ucy-hash-v2: canonical bytes, Merkle trees, salts, and recordRoot.

On this page

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.

ucy-hash-v2
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.ts
  • packages/hashing/src/hash-v2.ts
  • docs/specs/ucy-hash-v2.md