fix(receipts): verify locally stored payment receipts against Horizon…

[Anadudev]

Closes #136

Overview

Previously, payment receipts stored in browser localStorage were trusted implicitly and displayed as confirmed in the Dashboard without verifying transaction existence, ledger confirmation, or on-chain settlement parameters against Stellar Horizon.

This PR introduces an on-chain Horizon verification engine that checks the network, transaction hash, asset, amount, and destination receiving address for each receipt. Receipts in the Dashboard are now displayed with distinct visual statuses (unverified, pending, confirmed, and mismatched), with granular discrepancy diagnostic banners and manual re-verification capabilities.

---

Key Changes

1. Horizon Receipt Verification Engine (src/lib/receiptVerification.ts):

   • verifyReceiptAgainstHorizon(receipt, options): Queries the Stellar Horizon ledger endpoint for the given transaction hash and operations.
   • Validates that:
     • The transaction exists and has successful: true on the ledger.
     • Payment operations match the expected asset (USDC or XLM), amount (normalized float comparison), and destination receiving address.
     • Soroban contract invocations (invoke_host_function) for x402 payments are verified.
     • Network identifiers (stellar:mainnet vs stellar:testnet) match.
   • verifyReceiptsAgainstHorizon(receipts, options): Batch verification utility.
   • getHorizonUrlForNetwork(network): Network URL resolution.

2. Distinct Verification States & Dashboard UI (src/pages/DashboardPage.tsx):

   • Added verification state tracking (verificationMap) and status badges for each receipt:
     • Confirmed: Neon-green glowing dot, green CONFIRMED #<ledger> badge with check icon.
     • Pending: Pulsing cyan dot, VERIFYING... badge with animated loader.
     • Mismatched: Red glowing dot, red MISMATCHED badge with alert icon, diagnostic banner displaying specific discrepancy details (e.g., amount, asset, or destination mismatch), and a Re-verify button.
     • Unverified: Subtle gray dot, UNVERIFIED badge with help icon, and a Re-verify button.
   • Added header summary counters showing confirmed, mismatched, and unverified receipt counts.
   • Added VERIFY ALL action button to trigger parallel on-chain re-verification.
   • Added DOWNLOAD BUNDLE action button to export cryptographic receipt bundles.

3. Receipt Storage & Integrity Enrichment (src/hooks/useSearch.ts):

   • Enriched receipt persistence in stellarsearch_receipts localStorage to store asset, destination, amount, network, and status: 'unverified'.

4. Online Bundle Verification (src/lib/receiptBundle.ts):

   • Added verifyBundleOnline(bundle, options) to perform both offline cryptographic SHA-256 proof checks and on-chain Horizon ledger verification for all included receipts.

5. Type System Updates (src/types/index.ts):

   • Added ReceiptVerificationStatus ('unverified' | 'pending' | 'confirmed' | 'mismatched').
   • Added ReceiptVerificationDetail with ledger sequence, timestamp, and mismatch details.
   • Extended SearchReceipt and SearchResponse with asset, destination, and verification status.

---

Verification & Testing

• Receipt Verification Unit Tests (src/lib/receiptVerification.test.ts):
  • 16 tests covering confirmed payments, Soroban contract invocations, 404 not found, failed transactions, amount mismatches, asset mismatches, destination mismatches, network mismatches, Horizon 500 errors, and batch lookups.
• Dashboard UI Tests (src/pages/DashboardPage.test.tsx):
  • 4 tests covering empty audit log state, automatic verification on mount, distinct visual badges, manual re-verification, and bundle download.
• Hook Tests (src/hooks/useSearch.test.ts):
  • Verified receipt persistence with complete metadata.
• Receipt Bundle Tests (src/lib/receiptBundle.test.ts):
  • 24 tests covering offline proof validation and online Horizon verification.
• Full Test Suite:
  • Ran npm test: all 37 test suites and 376 tests passed.
• Typecheck & Build:
  • npx tsc --noEmit and npm run build passed with zero errors.

[drips-wave]

@Anadudev Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[vercel]

@Anadudev is attempting to deploy a commit to the Emmanuel's projects Team on Vercel.

A member of the Team first needs to authorize it.