[Frontend] Optimistic UI State Engine & IndexedDB Offline Stream Cache #1473

Overview & Background

In Web3 applications, blockchain transactions and indexer synchronization introduce latency (typically 3 to 10 seconds on Stellar/Soroban). Users who submit transactions (create stream, withdraw, top-up, pause) experience an awkward delay where the UI remains stale or shows blocking loading spinners until the transaction confirms and the backend indexer processes the event. Implementing an Optimistic UI state engine paired with client-side IndexedDB caching delivers instantaneous feedback and fluid user experience.

Detailed Problem Statement

1. Perceived Latency & UI Freezes:
   • Submitting a withdrawal currently forces the user to wait for ledger inclusion and API polling before the balance updates on screen.
2. Cold-Start Latency:
   • Every page refresh queries the backend REST endpoints from scratch, causing empty skeletons or layout shifts while data is fetched.
3. Flaky Network Disconnects:
   • Users on intermittent mobile connections or high-latency networks cannot view their existing streams or draft transactions if offline.

Technical Specification & Architecture

1. IndexedDB Persistence Layer (Dexie.js or idb-keyval)

Implement frontend/src/lib/storage/stream-cache.ts:

• Schema:
  • cached_streams: Primary store keyed by streamId, indexed by sender, recipient, tokenAddress, updatedAt.
  • optimistic_mutations: Store of pending user actions (CREATE, WITHDRAW, TOP_UP, CANCEL, PAUSE).
• Cache lifecycle:
  • On app load: Read instantly from IndexedDB to hydrate React Query / Zustand stores in < 15ms.
  • Background sync: Query backend API / SSE / WebSocket in the background and reconcile stale entries.

2. Optimistic Mutation Engine

• When a user submits an action (e.g. withdraw(streamId, amount)):
  • Generate an ephemeral optimistic patch updating stream.withdrawnAmount += amount and stream.claimableAmount -= amount.
  • Instantly re-render the UI with optimistic state and attach a subtle "Pending Ledger Confirmation" pulse badge.
  • Store the optimistic patch in optimistic_mutations.
• Reconciliation:
  • When the indexer event arrives via SSE or transaction hash is confirmed by RPC, replace the optimistic state with the canonical on-chain record.
  • If the transaction reverts or fails on-chain, automatically roll back the optimistic patch and display an actionable toast error.

3. Continuous Ticker Synchronization

• Ensure the real-time claimable balance ticker integrates seamlessly with optimistic mutations without jumping backward or jittering.

Target Files

• frontend/src/lib/storage/stream-cache.ts
• frontend/src/context/StreamContext.tsx
• frontend/src/hooks/useOptimisticStream.ts
• frontend/src/components/dashboard/StreamCard.tsx
• frontend/src/__tests__/optimistic-ui.test.tsx

Acceptance Criteria

• Application loads and renders cached streams from IndexedDB immediately on launch without waiting for network responses.
• Submitting stream mutations (withdraw, top-up, cancel) immediately updates the UI without blocking spinners.
• Pending optimistic state displays a non-intrusive status indicator.
• Canonical indexer updates silently reconcile optimistic values without UI flicker.
• Simulated transaction failures trigger a clean rollback to prior state and show explanatory error toast.