Skip to main content

ADR-0002 — Blake3 as the Sole Hash Function for Ledger Chain Construction

Status: ACCEPTED Date: 2026-02-28 Authors: Matthew Lynch matthew.lynch@helix-os.ai FR-Refs: FR-AUD-001, FR-AUD-002 Supersedes: None Superseded by: None

Context​

HELIX OS maintains an append-only audit ledger that records every data write, configuration change, and operator action. This ledger is the foundation of GMP compliance — it provides the tamper-evident chain that auditors verify during IQ/OQ/PQ qualification and that satisfies 21 CFR Part 11 requirements for electronic records.

The ledger uses a hash-chain construction: each entry's hash includes the hash of the previous entry, forming a Merkle Mountain Range (MMR). The choice of hash function affects:

  1. Integrity guarantees — The hash must be cryptographically secure against pre-image and collision attacks.
  2. Performance — Hashing occurs on the hot path for every data write (FR-AUD-001). The hash function must not degrade the < 2 ms P99 ingest latency.
  3. Determinism — The same input must always produce the same output, regardless of platform, for cross-system ledger verification.
  4. Regulatory longevity — The algorithm must be modern enough to remain acceptable for the expected 15+ year lifecycle of pharmaceutical equipment.

A single hash function must be chosen for the entire ledger. Mixing algorithms would complicate verification, expand the attack surface, and burden the validation suite.

Decision​

The system shall use Blake3 as the sole cryptographic hash function for all ledger chain construction, integrity verification, and content-addressable storage within HELIX OS.

Key properties enforced:

  1. Exclusive use — No other hash function (SHA-256, SHA-3, MD5, etc.) shall be used for ledger operations. Blake3 is the only sanctioned algorithm.
  2. 32-byte output — All ledger hashes use Blake3's default 256-bit (32-byte) output.
  3. Keyed mode prohibited for ledger chains — Ledger chain hashes use Blake3 in unkeyed mode to ensure verifiability by any auditor without key material.
  4. O_DIRECT writes — Ledger entries are written with O_DIRECT to bypass the page cache and ensure durability, as required by FR-AUD-001.

The implementation will use the official blake3 Rust crate maintained by the Blake3 team.

Rationale​

  • Speed: Blake3 is the fastest general-purpose cryptographic hash function available. On modern x86-64 with AVX-512, it achieves > 10 GB/s. Even on ARM (bioreactor edge controllers), SIMD-accelerated Blake3 vastly outperforms SHA-256. This ensures hashing never becomes a bottleneck on the hot path.
  • Security: Blake3 is based on the well-analyzed Bao construction and the BLAKE2 family, which survived full cryptanalysis rounds. It provides 128-bit collision resistance — sufficient for audit integrity.
  • Parallelism: Blake3 natively supports tree hashing, enabling parallel computation over large payloads. This is valuable for hashing bulk simulation datasets.
  • Determinism: Blake3 produces identical output on all platforms — no endianness ambiguity, no implementation-defined behavior.
  • Single algorithm simplicity: Using one hash function for all ledger operations eliminates algorithm-negotiation complexity and reduces the validation burden. Auditors verify one algorithm, not a matrix.
  • Modern provenance: Blake3 was published in 2020. Selecting a modern algorithm avoids the regulatory risk of deploying functions (e.g., SHA-1) that may be deprecated during the system's lifecycle.

Alternatives Considered​

AlternativeReason for Rejection
SHA-2564-6x slower than Blake3 on equivalent hardware. While widely accepted, it would impose unnecessary latency on the hot path.
SHA-3 (Keccak)Slower than SHA-256 in software implementations. Limited SIMD acceleration. No practical security advantage over Blake3 for this use case.
BLAKE2bPredecessor to Blake3. Lacks native tree hashing and is ~2x slower than Blake3 on modern hardware. No reason to use an older algorithm.
SHA-512/256Faster than SHA-256 on 64-bit platforms but still ~3x slower than Blake3. Limited ecosystem tooling.
Configurable / pluggable hashAdds complexity, multiplies validation surface, introduces algorithm-negotiation attack surface. Rejected in favor of single-algorithm simplicity.

Consequences​

Positive​

  • Maximum hash throughput on all target platforms — never a bottleneck.
  • Single hash algorithm across the entire ledger simplifies verification, auditing, and testing.
  • Deterministic cross-platform output enables ledger portability between systems.
  • Modern algorithm with strong cryptographic provenance mitigates regulatory obsolescence risk.

Negative​

  • Blake3 is not a NIST-approved algorithm (unlike SHA-256/SHA-3). Some extremely conservative regulatory interpretations may question this choice. Mitigation: Blake3's security derives from well-analyzed BLAKE2/ChaCha primitives; a compliance whitepaper will be prepared for auditors.
  • The ecosystem for Blake3 tooling is smaller than SHA-256. Mitigation: the official Rust crate is high-quality, well-maintained, and widely used.

Risks​

  • Regulatory acceptance: If a specific regulatory body mandates NIST-approved hashes only, Blake3 would not qualify. Mitigation: this has not occurred in practice for electronic records under 21 CFR Part 11 or EU GMP Annex 11, which specify "validated" algorithms without mandating specific NIST standards. A formal risk assessment will be documented.
  • Supply chain: Dependency on the blake3 crate. Mitigation: the crate is audited, has no transitive dependencies beyond platform SIMD intrinsics, and can be vendored.

Compliance Notes​

  • FR-AUD-001: Every data write appended to Blake3 ledger with O_DIRECT. This ADR selects Blake3 as the hash function that fulfills this requirement.
  • FR-AUD-002: Electronic signature capture and reason-for-change enforcement. The ledger chain constructed with Blake3 provides the tamper-evident substrate on which signatures are anchored.
  • 21 CFR Part 11 §11.10(e): Requires audit trails. The Blake3 hash chain provides cryptographic integrity for the audit trail.
  • This ADR is permanent per HELIX-VAL-STR-001. Superseding it requires a full re-validation cycle including IQ/OQ/PQ.

Revision History​

DateAuthorChange
2026-02-28Matthew LynchInitial accepted decision