Audit trail with tamper evident#99
Merged
elizabetheonoja-art merged 3 commits intoJul 18, 2026
Merged
Conversation
…rification Add tamper-evident audit trail hash chain
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
Provide a compact, on-chain tamper-evident audit trail so off-chain monitors can detect deletion, reordering, or mutation of critical lifecycle and billing events.
Cover high-value operations (meter registration, funding/top-up, and signed usage deductions) so settlement and monitoring systems can verify integrity end-to-end.
Description
Add a new AuditRecord contract type that stores sequence, previous_hash, record_hash, action, subject_id, actor, timestamp, and payload_hash for compact, privacy-preserving verification.
Add storage keys DataKey::AuditHead and DataKey::AuditRecord(u64) and implement helpers zero_hash, audit_payload_hash, calculate_audit_record_hash, and append_audit_record to maintain a chained hash head and persist per-sequence records.
Append audit records from critical paths by calling the append helper in register_meter, top_up, and deduct_units, and emit an AuditTrail event when records are appended.
Expose monitor-facing contract methods get_audit_head, get_audit_record, and verify_audit_chain to allow off-chain watchers to fetch and verify inclusive ranges of the chain, and add AUDIT_TRAIL_RUNBOOK.md with verification, alerting, and deployment guidance.
Testing
Ran cargo test --manifest-path contracts/utility_contracts/Cargo.toml audit --lib, which did not complete successfully because the workspace currently has pre-existing unrelated compile errors (e.g. duplicate MIGRATION_INSTRUCTION_BUDGET and outdated test/client signatures).
Ran cargo fmt --manifest-path contracts/utility_contracts/Cargo.toml --check, which failed because several repository files are not rustfmt-clean; no broad formatting changes were applied to avoid unrelated churn.
No new unit tests were added for the audit helpers in this change set; monitors can exercise the new public helpers via integration testing and canary deployments as described in the runbook.
Closes #92