Audit Trail & Chain of Custody
How VetRx Ledger's hash-chained, append-only ledger works — and how to export, verify, and present chain-of-custody reports.
Why an append-only ledger?
Paper logs and conventional database tables can be silently modified — a row can be updated or deleted without leaving a trace. An append-only, hash-chained ledger makes tampering mathematically detectable: each event records a cryptographic hash of the previous event, forming an unbroken chain. Any modification to a past event invalidates every subsequent hash, and the integrity check fails immediately.
This design is directly analogous to blockchain structures but is optimised for the audit and compliance use case: fast writes, instant local verification, and exportable evidence packages that stand up in regulatory hearings.
How the chain works
Each ledger event contains the following hash-relevant fields:
id— UUID for the eventvial_id,type,qty— the core transaction datadevice_ts— ISO-8601 timestamp from the recording devicedvm_id,tech_id— identity of recorder and administering DVMprev_hash— SHA-256 hash of the previous event in the chainhash— SHA-256 hash of this event's canonical JSON string (includingprev_hash)
The genesis event has prev_hash: "0". Every subsequent event hashes the previous event's hash field into itself. The verification function recomputes every hash in sequence and reports the first failure (if any).
Hardware-backed e-signatures
For WASTE events and reconciliation sign-offs, VetRx Ledger optionally requires a WebAuthn / FIDO2 hardware signature. This binds the action to a physical device (YubiKey, Face ID, Windows Hello) that cannot be cloned or shared. The public key credential is stored per-user and referenced in the event record.
Verifying chain integrity
- Navigate to Ledger → Verify.
- Click Run Verification. VetRx Ledger re-derives every hash in your ledger and confirms the chain is unbroken.
- The result shows: Valid — N events verified or FAILED at event <id>.
- Click Show Event Table to see per-event hash, timestamp, and type in an expandable grid.
- Download a Verification Report (JSON) — a signed timestamp of the verification result suitable for filing with a regulator or insurer.
Exporting chain-of-custody packages
VetRx Ledger supports two export formats from Ledger → Verify → Export:
| Format | Use case |
|---|---|
| JSON (chain-of-custody) | Full machine-readable export with every event, hash, drug name, lot, and audit metadata. Submit to DEA investigators or insurers for independent verification. |
| CSV | Human-readable tabular export for spreadsheet review or import into other systems. Does not include hash fields — use JSON for integrity verification. |
Every export is automatically logged in the Audit Log (audit_log/exportcategory) with the actor's IP address and user agent. You can view who downloaded what and when from Settings → Audit Log.
Audit log
Separate from the ledger, VetRx Ledger maintains an append-only audit logthat records system-level actions:
- Every ledger export (actor, timestamp, filter parameters)
- Settings changes (privacy toggles, org name, team invites)
- Failed authentication attempts
- Witness session creation and consumption
View the audit log at Settings → Audit Log or via the direct navigation link. Filter by category, date range, or actor. Export as CSV or JSON for external SIEM or compliance reporting.
Presenting evidence in an inspection
- Navigate to Ledger → Verify and run a verification with the inspector present or watching.
- Export the JSON chain-of-custody package for the period in question.
- Show the inspector the Valid chain integrity badge and the event count.
- If requested, export the audit log CSV to demonstrate who accessed records and when.
- Present signed reconciliation PDFs from the binder for each month in scope.