[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