Skip to content

Proof-of-Care Ledger Specification

Goal: An immutable, append-only log providing cryptographic proof that care was delivered, without storing PHI in Git. The system provides verifiable integrity for all care events.

Specification

Merkle Root Computation Process

The Merkle root is a single cryptographic hash ("digital fingerprint") that represents an entire block of events. It is computed periodically (e.g., hourly) by a dedicated backend worker.

  1. Event Batching: The system gathers all new ledger events committed since the last block was created into a time-based batch.

  2. Leaf Hashing: For each event in the batch: a. The event's JSON data is converted into a standard, byte-for-byte identical format using JSON Canonicalization Scheme (JCS - RFC 8785). b. A 0x00 byte is prepended to the canonical data (leaf prefix). c. The result is hashed using SHA-256 to create a unique "leaf" hash for the event.

  3. Tree Construction: The tree is built by recursively pairing and hashing nodes: a. Leaf hashes are paired (e.g., H1 with H2, H3 with H4). b. The concatenated pair has a 0x01 byte prepended (internal node prefix) and is then hashed with SHA-256 to create a parent node. c. This process is repeated up the levels of the tree until a single hash remains: the Merkle Root.

  4. Root Chaining: The final Merkle root is stored in a root_hashes table, which includes a hash of the previous block's root, creating a blockchain-like chain that makes historical tampering computationally infeasible.

Records

  • event_id, timestamp, subject_code
  • event_type, confidence, route
  • signer (device or caregiver app), signature

Export Bundle for Third-Party Auditing

To allow an external party (e.g., an auditor) to verify event integrity without direct database access, the system generates a self-contained Export Bundle (ZIP file).

The bundle contains:

  1. events.csv / events.json: A human-readable report of all events in the export scope.
  2. manifest.json: Contains metadata, including the final Merkle Root hash that corresponds to the events in the report.
  3. proofs.json: A file containing a Merkle Inclusion Proof for every single event listed in the report. This proof is the minimal set of sibling hashes required to recalculate the root hash from a specific event's leaf hash.
  4. verify.py: A simple, open-source verification script that an auditor can run locally. The script will: a. Select an event from events.csv. b. Hash the event using the same canonicalization rules. c. Use the corresponding proof from proofs.json to recalculate the Merkle root. d. Compare the calculated root to the official root in manifest.json. A match provides mathematical proof of the event's authenticity and integrity.