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. Per-Patient Scoping: Rather than combining all events across all patients into a single global tree or forcing a hardware device, the system constructs independent Merkle ledgers per patient (patient_id). This provides cryptographic isolation and supports software-only EVV systems without hardware devices.

  2. Event Batching: The system gathers all new ledger events committed for a specific patient since that patient's last block was created.

  3. 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.

  4. 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.

  5. Root Chaining (Chained Blocks): The final Merkle root is stored in a merkle_blocks table linked to patients.id. Each block includes the previous_block_hash referencing the Merkle root of the previous block for that specific patient, starting with block ID 0.

  6. Stateless Verification: Cryptographic proof verification is performed statelessly in the API gateway. The gateway retrieves the event's stored inclusion proof and the block's Merkle root, then runs the verification algorithm by recomputing hashes from the leaf to the root and checking for a match.

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.