Đến nội dung
Tài liệu/Tham chiếu kỹ thuật

Canonicalization & hashing

ucy-hash-v2: bytes chuẩn hóa, Merkle tree, salts và recordRoot.

Trong trang này

Từ giá trị đến bytes xác định

Canonical JSON dùng UTF-8 compact, sắp key theo code point và chuẩn hóa Unicode NFC. Key trùng sau chuẩn hóa bị từ chối. Trường tùy chọn được bỏ key; không dùng null.

Metric là decimal string chuẩn, không qua phép toán float. Giá trị 370.10 được chuẩn hóa thành 370.1; số mũ và các trường ngoài schema bị từ chối.

Dựng định danh bản ghi

Các hằng D_* tách miền hash; mỗi salt kỳ là 32 byte ngẫu nhiên. Công thức dưới là sơ đồ, không phải một hàm thay thế implementation.

periodCount được ABI encode là uint256. Merkle tree dùng OpenZeppelin StandardMerkleTree với kiểu bytes32 và quy tắc double-hash của thư viện, kể cả khi chỉ có một kỳ.

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))

Những thứ phải giữ để tái tạo

Giữ đúng bytes document, nguồn, salts, registry snapshot và phiên bản thuật toán. File metric upload một mình không đủ tái tạo recordRoot vì header và salts được tạo trong ingest.

Snapshot registry tại thời điểm ingest cho phép kiểm chứng bản ghi cũ khi dictionary được mở rộng. Dùng golden vectors và engine của repo để kiểm tương thích.

Nguồn đối chiếu trong monorepo

Nội dung dựa trên mã nguồn; trạng thái live được ghi riêng.

  • packages/hashing/src/canonicalize.ts
  • packages/hashing/src/hash-v2.ts
  • docs/specs/ucy-hash-v2.md