Skip to content

feat(sdk-react): add IndexedDB cache for scanned announcements (#127)#146

Open
Hollujay wants to merge 4 commits into
wraith-protocol:developfrom
Hollujay:feat/127-indexeddb-cache-scanned-announcements
Open

feat(sdk-react): add IndexedDB cache for scanned announcements (#127)#146
Hollujay wants to merge 4 commits into
wraith-protocol:developfrom
Hollujay:feat/127-indexeddb-cache-scanned-announcements

Conversation

@Hollujay

Copy link
Copy Markdown
Contributor

Summary

Adds an IndexedDB-backed cache for scanned stealth announcements in @wraith-protocol/sdk-react, keyed by (chain, wallet). Returning users resume from their last scanned ledger instead of re-scanning from genesis.

Changes

New file: packages/sdk-react/src/cache/idb.ts

  • IDBCache class wrapping IndexedDB with get/set/delete/commit/clearChain/keys
  • MemoryCache fallback when IndexedDB is unavailable (SSR/Node.js)
  • LRU eviction (200 IDB / 100 memory entries) via enforceCap()
  • Database: wraith-sdk-cache-v1, store: caches, key: ${chain}:${wallet}
  • Indexes on lastAccess, chain, wallet for efficient cursor-based chain clearing
  • commit() atomically persists announcements + advances lastScannedLedger watermark

New file: packages/sdk-react/src/hooks/useScanner.ts

  • useScanner() hook with scan, commitScan, and clearCache methods
  • Watermark resume: scan() reads cached lastScannedLedger, passes fromLedger to fetchAnnouncementsStream, merges cached + fresh announcements
  • commitScan() persists announcements and advances watermark — consumer calls this only after all events in the batch are decrypted
  • clearCache() blows the entire chain's cache (e.g. on futurenet reset)
  • Singleton cache instance via globalThis.__wraith_idb_cache
  • Wallet change invalidates the old cache entry; chain reset requires explicit clearCache()

Modified file: packages/sdk-react/src/hooks.ts

  • Exports useScanner from the new dedicated module
  • Removed inline useStellarAnnouncementScan (replaced by useScanner)
  • Cleaned up unused imports

Modified file: packages/sdk-react/src/env.d.ts

  • Added fetchAnnouncementsStream to the type stub for @wraith-protocol/sdk/chains/stellar

Existing (unchanged): `packages/sdk-react/bench/bench.mjs'

  • Bench comparing cold stream fetch vs cached read performance

Acceptance Criteria

  • Returning user's cold scan resumes from watermark (measurably faster — see bench)
  • Chain reset (futurenet) blows cache cleanly via clearCache()
  • Storage cap enforced with LRU eviction
  • Graceful fallback to memory when IndexedDB unavailable
  • Build passes (CJS + ESM + DTS)
  • Existing tests pass

Closes #127

@drips-wave

drips-wave Bot commented Jul 24, 2026

Copy link
Copy Markdown

@Hollujay Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

@truthixify

Copy link
Copy Markdown
Contributor

Two things to fix before this can go in. The PR targets main but wave PRs go into develop, so retarget the base branch. Second, the bun step in CI is failing. Push the bun fix once you've retargeted and I'll take another look.

@Hollujay
Hollujay changed the base branch from main to develop July 24, 2026 10:41
@Hollujay Hollujay changed the title feat(sdk-react): IndexedDB cache for scanned announcements (#127) feat(sdk-react): add IndexedDB cache for scanned announcements (#127) Jul 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

IndexedDB cache for scanned announcements

2 participants