Schedule periodic RevenueReconciliationService runs with dead-letter alarms

[thlpkee20-wq]

Summary

Schedule periodic RevenueReconciliationService runs with dead-letter alarms

Why this matters

RevenueReconciliationService.reconcile is invoked only on demand from src/routes/reconciliationRoutes.ts, so drift between on-chain receipts and recorded reports is detected only when an operator triggers it. Add a scheduled job that runs reconciliation per active offering on a cadence, persists each run summary, and raises a dead-letter alarm when discrepancies exceed a configured tolerance.

Scope

Implement the requested behavior across src/routes/reconciliationRoutes.ts, src/services/revenueReconciliationService.ts, src/services/distributionScheduler.ts, src/lib/metrics.ts. The solution must preserve existing compatibility, authorization, and production safeguards.

Priority

High

Acceptance criteria

• The requested behavior is implemented across src/routes/reconciliationRoutes.ts, src/services/revenueReconciliationService.ts, src/services/distributionScheduler.ts, src/lib/metrics.ts with a clear, reviewable contract.
• Security, authorization, validation, and data-integrity requirements in the repository context are enforced and covered by tests.
• Failure, retry, timeout, concurrency, and boundary behavior is explicit and produces safe, diagnosable outcomes where applicable.
• Regression coverage includes empty, invalid, duplicate, and boundary inputs relevant to this flow.
• Existing API, storage, and deployment compatibility is preserved unless a migration is explicitly documented.

Validation

Include focused tests for:

• happy paths;
• invalid input and authorization boundaries;
• concurrency, retries, or failure recovery;
• backward compatibility;
• relevant integration or contract behavior.

The implementation must pass the repository’s existing build, lint, test, and formatting checks (use npm test where applicable).

Non-goals

• Typo-only, formatting-only, or documentation-only changes.
• Unrelated refactors or dependency upgrades.
• Weakening security, authorization, CI, or production safeguards.
• Changing public behavior outside this issue’s scope.

Contributor application

Before implementation, comment with:

1. relevant experience;
2. a concise implementation approach;
3. expected files or modules affected;
4. an estimate for opening the first PR.

Wait for maintainer assignment before coding.

PR requirements

Use a feature branch and include Closes #.

The PR must:

• address every acceptance criterion;
• link each criterion to code and tests;
• explain security and failure-mode handling;
• include meaningful regression coverage;
• document compatibility or migration considerations;
• pass the repository checks.

Reward-readiness

This is a substantive quality issue. Merge status does not guarantee reward eligibility; final evaluation is determined separately.

Implementation context

Description

RevenueReconciliationService.reconcile is invoked only on demand from src/routes/reconciliationRoutes.ts, so drift between on-chain receipts and recorded reports is detected only when an operator triggers it. Add a scheduled job that runs reconciliation per active offering on a cadence, persists each run summary, and raises a dead-letter alarm when discrepancies exceed a configured tolerance.

Requirements and context

• Must be secure, tested, and documented
• Should be efficient and easy to review
• Relevant code: src/services/revenueReconciliationService.ts, src/services/distributionScheduler.ts, src/lib/metrics.ts
• Alarms must be exposed through the metrics endpoint with an offering_id label respecting cardinality caps

Suggested execution

• Fork the repo and create a branch
• git checkout -b feat/scheduled-reconciliation-alarms
• Implement changes
  • Add a ReconciliationScheduler modeled on DistributionScheduler
  • Persist run summaries keyed by (offering_id, period_id, started_at)
  • Emit reconciliation_discrepancy_total and reconciliation_alarm_open metrics
• Validate security and correctness assumptions

Test and commit

• Run tests
  • npm test
• Cover edge cases
  • Per-offering cadence respected, missed run resumes, alarm clears on subsequent balanced run, label cardinality cap enforced
• Include test output and notes

Example commit message

feat: schedule periodic reconciliation with discrepancy alarms

Guidelines

• Minimum 95 percent test coverage
• Clear documentation
• Timeframe: 96 hours

[aliyuHabibu]

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

Hi maintainer please assign this issue to me.

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

[drips-wave]

Congratulations, @aliyuHabibu! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @aliyuHabibu: 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 🌊

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@aliyuHabibu's PR #900 was approved and merged by @thlpkee20-wq.

🏆 @aliyuHabibu: You earned 35 FoxPoints for this contribution! Your current tier: Builder (1,022 total points). Track your full progress on GrantFox.

👏 Great work, @aliyuHabibu! Keep contributing to RevoraOrg.