append-only audit log for state-changing contracts operations

[mikewheeleer]

Summary

There is no record of who changed contracts state, when, or how — making incident review and compliance impossible. Add an append-only audit log capturing every mutation.

Why this matters

Without an audit trail, you cannot investigate incidents or prove correctness. An append-only log is the standard, queryable primitive.

Requirements

• Record an entry for every state-changing contracts operation: actor, action, target, before/after summary, timestamp.
• Entries are append-only and immutable; never updated or deleted.
• Provide a query by target id and by actor, with pagination.
• Redact secrets/PII from recorded payloads.

Technical guidance

• Write the audit entry in the same unit of work as the mutation.
• Keep the entry schema stable and versioned.

Edge cases — each must have a test

• a mutation -> exactly one audit entry with correct fields
• a read -> no audit entry
• query by target -> returns that target's history
• secrets -> never appear in entries
• entries are ordered and immutable

Acceptance criteria

• All requirements and every edge case above implemented and covered by tests
• New unit and integration tests; existing tests still pass and no regressions
• Structured, typed errors (no leaked internals; stable codes)
• npm run lint, npm test, and npm run build all pass locally
• Code follows the repo's existing conventions; no duplication or dead code
• Short docs/comments explaining the design and any non-obvious decisions
• PR description explains the approach and includes Closes #<issue>

Out of scope

• Tamper-proofing / hash chaining
• External SIEM export

Rewards

Part of the GrantFox OSS / Official Campaign (FWC26) — this task may be rewarded. PR quality is assessed by AI: depth, correctness under edge cases, meaningful tests, and clean design are what earn the reward. Shallow changes (typos, formatting, trivial docs) do not qualify.

[OmniZlatoon]

Good day sir, Ready to deliver the task A.S.A.P. Gone through the issue and to be honest, i can work the task with the right tools at hand. please assign me maintainer . My eta is 5 hours