[Backend] Escrow Consistency Checker: Automated On-Chain vs Off-Chain Validation

[KuchiMercy]

Problem

There is currently no automated mechanism to verify that the database state matches the on-chain state. If a Stellar transaction fails silently, a webhook is missed, or a manual database edit occurs, the escrow record could become inconsistent with the blockchain. The ConsistencyCheckerService exists but only does basic checks.

Current State

• modules/admin/services/consistency-checker.service.ts — Basic checks
• modules/admin/controllers/admin-escrow-consistency.controller.ts — Manual trigger endpoint
• StellarEvents entity — Stores on-chain events but not cross-referenced
• No automated scheduled consistency checks

Acceptance Criteria

• Enhance ConsistencyCheckerService with on-chain verification:
  • For each ACTIVE escrow, query the Stellar network for the escrow account state
  • Compare: amount, asset, parties, status
  • Flag discrepancies (amount mismatch, unexpected status, missing parties)
• Add scheduled consistency checks:
  • Run a daily cron job checking all ACTIVE escrows
  • Run an immediate check for any escrow that hasn't had a status update in 24h
  • Store results in a new ConsistencyReport entity or JSON log
• Add GET /admin/consistency/reports endpoint:
  • List recent consistency check results
  • Show which escrows have discrepancies
  • Allow filtering by severity (critical, warning, info)
• Add POST /admin/consistency/resolve endpoint:
  • Allow admin to force-sync database state with on-chain state
  • Log the resolution in AdminAuditLog
• Add GET /admin/consistency/:escrowId endpoint:
  • Detailed comparison for a specific escrow
  • Show step-by-step: database values vs on-chain values
• Send admin notifications for critical discrepancies
• Add E2E test that creates a discrepancy and verifies detection

Technical Notes

• Use StellarService.getAccountInfo() and Soroban contract reads for verification
• Consistency checks should be non-blocking and not affect escrow operations
• Critical discrepancies: status mismatch, amount mismatch
• Warning discrepancies: missing events, stale timestamps

Points: 150 (Medium)

[Isihaq123]

@Isihaq123 has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

I will like to work on this project because it gives the reall energy of my environment skills

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Isihaq123 to this issue.

[SYLVIANNORUKA]

@SYLVIANNORUKA has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Can I work on this pls? I will build an Automated On-Chain vs Off-Chain Validation

ℹ️ Repo Maintainers: To accept this application, review their application or assign @SYLVIANNORUKA to this issue.

[drips-wave]

Congratulations, @SYLVIANNORUKA! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @SYLVIANNORUKA: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊