Skip to content

feat(backend): add on-chain portfolio reconciliation and indexer repair jobs - #567

Merged
PeterOche merged 1 commit into
degenspot:mainfrom
Ibinola:feature/portfolio-reconciliation-562
Aug 19, 2026
Merged

feat(backend): add on-chain portfolio reconciliation and indexer repair jobs#567
PeterOche merged 1 commit into
degenspot:mainfrom
Ibinola:feature/portfolio-reconciliation-562

Conversation

@Ibinola

@Ibinola Ibinola commented Aug 19, 2026

Copy link
Copy Markdown
Contributor

Summary

Implements an idempotent on-chain portfolio reconciliation process and BullMQ indexer repair jobs for BACKit on Stellar.

Closes #562

Key Implementation Details

  1. Reconciliation Service & BullMQ Job: Built ReconciliationService and ReconciliationProcessor (QUEUE_RECONCILIATION) scanning configurable ledger ranges (fromLedger to toLedger) and contract IDs.
  2. 4 Record Types: Compares call creation, stake, resolution, and payout claim events against PostgreSQL using stable event identities (contractId:ledger:txHash:eventIndex).
  3. Discrepancy Classification: Classifies detected discrepancies into 5 categories: MISSING_OFFCHAIN, DUPLICATE_OFFCHAIN, VALUE_MISMATCH, UNKNOWN_CONTRACT, and UNRECOVERABLE.
  4. Dry-Run & Repair Modes:
    • Dry-run mode: Produces structured report without modifying database records.
    • Repair mode: Transactionally upserts missing records and updates statuses without ever submitting Soroban transactions. Quarantines unsafe mismatches into ReconciliationDiscrepancy.
  5. Idempotency & Distributed Locking: Enforces distributed lock (reconciliation_lock:<network>) to prevent overlapping runs and guarantees idempotent re-runs over identical ranges.
  6. Protected Admin Endpoints: Added POST /admin/reconciliation/run, GET /admin/reconciliation/runs, GET /admin/reconciliation/runs/:id, and GET /admin/reconciliation/discrepancies.
  7. Operator Runbook & Test Suite: Added docs/RECONCILIATION_RUNBOOK.md and comprehensive unit test suite in reconciliation.service.spec.ts.

@PeterOche PeterOche left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@PeterOche
PeterOche merged commit 5feb371 into degenspot:main Aug 19, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add On-Chain Portfolio Reconciliation and Indexer Repair Jobs

2 participants