Transaction History Stability & Performance Hardening (Virtualization, Caching Integrity, Error Resilience)

[jamespepper81]

Summary

Although major reliability improvements have already been implemented (sequential fetching, rate limiting, caching, stale‑while‑revalidate pattern, race condition fixes), the Transaction History feature can be further hardened for:

• Consistent UX under extreme wallet sizes (thousands of transactions)
• Memory/render performance on low-end devices
• Uniform error and empty states
• Integrity checks (no duplicates, ordering guarantees, cache TTL coherence)
• Observability (metrics & logging to confirm >99.5% crash-free goal and latency SLAs)
• Resilience in edge cases (network flapping, partial API responses, missing tx details, orphan unconfirmed txs)

Current Implementation (Key References)

• UI rendering & states: app/transaction-history.tsx (loading, error, empty, list sections)
• Data fetching & SWR logic: hooks/wallet-store.ts (queryKey ['transactions-improved', ...])
• Transaction caching & TTL management: services/transaction-cache-service.ts
• Detail retrieval & fallback behavior: app/transaction-details.tsx + transaction-explorer.tsx
• Balance reconstruction logic: components/PriceChart.tsx
• Docs: docs/PRODUCTION_READY_SUMMARY.md, docs/TESTING_GUIDE2.md, CHANGELOG.md

Observed / Potential Gaps

1. ScrollView list rendering (no virtualization) may lead to performance degradation with large datasets.
2. Multiple components (PriceChart, TransactionDetails, Explorer) independently sort/filter transactions—risk of inconsistent logic.
3. Error states duplicated (History vs Details vs Explorer) with slightly different wording & styling.
4. No explicit guard against extremely large unconfirmed pools prolonging cache churn.
5. Cache service lacks exposed metrics in UI/dev console (hit rate, TTL expirations, stale merges).
6. Missing progressive pagination (everything loaded vs chunked fetch + background expansion).
7. Balance history recalculation walks all transactions per interval (potential O(N^2) pattern for large N).
8. Transaction detail fallback logic relies on last known tx; could benefit from optimistic placeholder and eventual reconcile.
9. Rate limiting strategy is static—could adapt dynamically to 429 patterns.
10. Absence of automated integrity audit (e.g., periodic duplicate/out-of-order scan with alert flag).
11. No skeleton shimmer or virtualization placeholder—only spinner when empty.
12. Query key structure could include version token—future schema changes may invalidate old persisted data safely.

Proposed Enhancements

1. List Virtualization & Pagination: Use FlashList or SectionList, incremental hydration, batch loading.
2. Unified State Components: Abstract Loading / Empty / Error into shared component; consistent design tokens.
3. Caching Integrity & Metrics: Add getCacheStats() to a debug panel; log duplicates and auto-purge events.
4. Adaptive Rate Limiting: Implement dynamic backoff on 429; log rate-limiter events.
5. Incremental Transaction Fetching: API-based paging with sync progress indicator.
6. Balance History Optimization: Precompute running balance once, O(N) target.
7. Consistent Detail Fallback Logic: Placeholder with “Verifying…” status, reconciled when details fetched.
8. Orphan & Expired Unconfirmed Handling: Sweep expired; retry or alert for stuck txs.
9. Query Versioning: Add version to queryKey, invalidate on schema migration.
10. Instrumentation & Reporting: Emit timing/caching/duplication metrics; periodic summary logs.
11. Enhanced Testing Scripts: Simulated large wallets, network flaps, duplicates, cache expiry.

Acceptance Criteria

• Initial render: <2s with 5k transactions from cache.
• UI smoothness: No frame drops with ≥5k txs.
• Fresh sync: <8s full wallet; memory stable.
• No duplicate or out-of-order txs after audit.
• Uniform error/loading/empty states.
• Adaptive rate limiting reduces 429s by ≥80%.
• Balance chart recompute: <150ms.
• Crash-free rate: ≥99.5% in 7-day observation.
• Debug panel exposes cache stats.
• Expanded test suite covering edge cases and performance.

References

• app/transaction-history.tsx, hooks/wallet-store.ts, services/transaction-cache-service.ts, app/transaction-details.tsx, transaction-explorer.tsx, components/PriceChart.tsx, docs/TESTING_GUIDE2.md, docs/PRODUCTION_READY_SUMMARY.md, CHANGELOG.md

Optional Future Work

• Local SQLite / IndexedDB for scalability
• Streaming/partial sync for transaction lists
• Background idle sync for cache prewarm

---

Let me know if prioritization or splitting into sub-issues is desired.