[Ranjeet2063]

Summary of Changes

Replaced the stub reconciliation implementation with a production-ready Claims and Payout Reconciliation engine that compares on-chain Soroban contract claim events against database payout and prediction records.

Key Capabilities

1. 6 Discrepancy Rules:

   • claimed_on_chain_missing_in_db: Event recorded on-chain but payout record missing from DB.
   • db_paid_missing_on_chain: DB records payout as settled but no corresponding on-chain claim exists.
   • amount_mismatch: Exact Stroop-level difference between on-chain claim amount and DB recorded payout amount.
   • claim_for_losing_prediction: Claim event references a prediction row whose resolved outcome is 'lost'.
   • duplicate_on_chain_claim: Multiple on-chain claim events emitted for the same prediction ID.
   • stale_unclaimed: Winning prediction unclaimed past configured grace period.

2. Exact Stroop Arithmetic:

   • Implemented parseExactStroops and formatExactStroops using 7-decimal BigInt scaling to prevent floating-point inaccuracies.

3. Database Persistence & Migrations:

   • Added tables reconciliation_reports and reconciliation_discrepancies with migration drizzle/0027_add_reconciliation_reports.sql.
   • Fingerprint deduplication (SHA-256) prevents redundant duplicate discrepancy records.
   • Keyset-paginated retrieval support for high throughput queries.

4. Admin Endpoints & OpenAPI Contract:

   • GET /api/admin/reports (keyset pagination cursor, status filter, limit).
   • GET /api/admin/reports/:id (report metadata with joined discrepancies array).
   • Guarded by requireScopedAdmin(ADMIN_SCOPES.REPORT_READ).
   • OpenAPI schemas and contract invariants validated via npm run openapi:check.

5. Worker & Observability Integration:

   • BullMQ reconciliationWorker updates Prometheus metrics: reconciliation_discrepancies_total{kind}.
   • Audit log emitted on discrepancy detection with context headers (x-request-id, x-correlation-id).

6. Documentation:

   • Comprehensive operator runbook added to docs/runbook-reconciliation.md detailing severity classifications and step-by-step triage actions.

Verification & Test Evidence

• Unit & Integration Tests: 49/49 tests passing across 4 suites:
  • tests/reconciliationPayouts.test.ts (26 tests covering all 11 issue scenarios + DB mock tests)
  • tests/reconciliationWorker.test.ts (6 tests)
  • tests/reconciliationService.test.ts
  • tests/adminReconciliation.test.ts (17 tests)
• Memory Benchmark: Scenario 10 benchmark verified memory growth < 100 MB for 50,000 keys.
• OpenAPI Validation: npm run openapi:check -> PASS.
• DB Drift Validation: npm run db:check-drift -> PASS (0 schema drift).
• TypeScript: Clean compilation with 0 errors.

Closes #980

[drips-wave]

@Ranjeet2063 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

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.