feat: implement Tamper-Proof Merkle Hash-Chain Audit Vault

[T-kesh]

feat: Implement Tamper-Proof Merkle Hash-Chain Audit Vault

First off, apologies for the slight delay in getting this PR up! Implementing a cryptographically secure audit system required meticulous care, extensive testing, and rigorous edge-case checks (especially around database race conditions) to guarantee absolute immutability. Thank you for your patience!

Overview

This PR introduces the Tamper-Proof Merkle Hash-Chain Audit Vault to satisfy our strict financial compliance requirements. It ensures that all critical event logs are cryptographically immutable and anchors their verifiable proofs onto the Stellar network.

Key Features & Architectural Changes

1. Database-Level Tamper Resistance

• audit_hash_chain & audit_roots tables: Created robust Postgres schemas to store event hashes and batched Merkle roots.
• Sequential Hashing Engine: Built HashChainEngine which uses SELECT ... FOR UPDATE row locks to guarantee zero sequence number gaps. Each new record's hash natively commits to the previous record's hash ($curr_hash = SHA256(payload + prev_hash)$).

2. Stellar On-Chain Anchoring

• Soroban Contract Updates: Modified the zk-credential smart contract to accept and durably store 32-byte Merkle Roots against a block index using the anchor_audit_root admin function.
• Background Worker Engine: Implemented AuditAnchorWorker to run asynchronously. It processes completed batches of 1,000 logs, calculates the aggregated Merkle Root, and securely anchors it on-chain, storing the resulting transaction hash for immediate lookup.

3. Inclusion Proof Generation & Verification

• API Proof Endpoints: Added a high-performance GET /api/v1/audit/proof/:eventId endpoint utilizing a custom ProofGenerator. It mathematically reconstructs the Merkle branch and returns a full, cryptographically sound inclusion proof.
• Auditor Portal UI: Built the AuditorPortal and AuditProofViewer frontend components. Compliance officers can now input any Sequence ID and instantly view its verifiable on-chain inclusion proof.

4. Integrity Validation Tooling

• Continuous Audit CLI: Developed scripts/verify-audit-chain.ts for deep, offline validation of the entire database hash chain to instantly flag unauthorized database tampering.
• Test Coverage: Fully backed by comprehensive unit tests (hash-chain.test.ts, audit-vault.test.ts) and end-to-end integration tests (audit_tamper_detection.test.ts).

Notes for Reviewers

• The End-to-End tests require a running local Postgres instance and will skip/fail locally if the database is not provisioned. The logic itself is strictly guarded.
• All hash operations rely on native node:crypto (SHA-256) for maximum throughput.

This pr closes #405

[vercel]

@T-kesh is attempting to deploy a commit to the jotelfootball-tech's projects Team on Vercel.

A member of the Team first needs to authorize it.

[T-kesh]

I'm aware that node and contract ci are failing and I am currently working on them. I'll get it all clear before the end of today.
Thank you for your patience.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
velo	Ready	Preview	Aug 30, 2026 2:14pm
velo-frontend	Ready	Preview	Aug 30, 2026 2:14pm

[jotel-dev]

All checks pass, no conflicts. Reviewed and looks good — merging now. Thanks for the contribution!
@T-kesh

[jotel-dev]

Great work @T-kesh

[T-kesh]

Great work @T-kesh

Thank you for the swift review, I once again apologise for the late pr. Thank you for the opportunity and i look forward to work with you next wave.