[Backend] Historical Stream Snapshot & Balance Time-Travel Reconstruction API

[blurbeast]

Overview & Background

Auditors, accounting systems, and tax tracking tools require balance verification as of specific historical timestamps (e.g. fiscal year-end, end-of-month payroll cutoff). Currently, the backend only returns the real-time instantaneous claimable balance.

---

Detailed Problem Statement

• Users cannot verify what their claimable or remaining streaming balance was at a historical date (e.g. Dec 31, 2025 at 23:59:59 UTC).
• Bookkeepers cannot reconcile historical monthly statements.

---

Technical Specification & Architecture

1. Endpoint Specification

GET /api/v1/streams/:id/snapshot?timestamp=1735689599

2. Time-Travel Reconstruction Logic

1. Fetch stream base parameters from database.
2. Fetch all StreamEvent records for streamId where timestamp <= targetTimestamp ordered by timestamp ascending.
3. Replay state changes:
   • Sum deposits and top-ups up to target timestamp.
   • Sum withdrawals executed prior to target timestamp.
   • Reconstruct active pause durations applicable at target timestamp.
   • Compute claimableAtTimestamp using historical accrual anchor.
4. Return structured balance snapshot:

   {
     "streamId": "42",
     "timestamp": 1735689599,
     "depositedAmount": "50000000000",
     "withdrawnAmount": "20000000000",
     "claimableAmount": "15000000000",
     "unvestedAmount": "15000000000",
     "statusAtTimestamp": "ACTIVE"
   }

---

Target Files

• backend/src/controllers/stream.controller.ts
• backend/src/services/claimable.service.ts
• backend/src/routes/v1/stream.routes.ts

---

Acceptance Criteria

• Accurate reconstruction of historical claimable and unvested balances at any given Unix timestamp.
• Replays top-up, withdrawal, and pause event histories correctly.
• Comprehensive unit tests verifying snapshot math against live contract simulations.

[egwujiohaifesinachiperpetual-max]

Please assign
ETA is 4 hours

[Ranjeet2063]

Hi @maintainers, I am ready to resolve this!

Execution Plan for [Backend] Historical Stream Snapshot & Balance Time-Travel Reconstruction API:

• Backend Implementation: Structure [Backend] Historical Stream Snapshot & Balance Time-Travel Reconstruction API with strict input validation, idempotent handlers, and proper error codes.
• Integration Tests: Provide automated tests covering both valid payloads and failure scenarios.

Why assign me?

• Proven Proof-of-Work: #1 contributor on Mova Store (28 merged Web3 PRs) and official ElizaOS contributor.
• Fast Turnaround: Dedicated to shipping a tested, production-grade PR within 12–24 hours.
• Zero Maintainer Burden: Self-documenting code with green CI and tests included so you don't spend time debugging.

Excited to contribute—please assign this to me and I'll push a clean PR shortly!