In-memory + IndexedDB cache layer for `fetchAnnouncements`

[truthixify]

Labels: Stellar Wave, stellar, perf, feature, drips, help-wanted
Tier: M (2–4 days)
Type: perf / feature

Context

Issue #11 adds cursor support so callers can fetch incrementally. But cursors don't persist across page reloads — the demo or any consumer re-fetches the whole window every time the user reopens the app. We can dramatically cut RPC traffic with a real cache layer.

This is the consumer-side companion to issue #11 and the contract-side companion to contracts/22 (event topic indexing).

Scope

Build a cache abstraction at sdk/src/chains/stellar/cache.ts:

1. Interface:

   interface AnnouncementCache {
     get(network: Network, fromLedger: number, toLedger: number): Promise<Announcement[] | null>
     put(network: Network, announcements: Announcement[]): Promise<void>
     getLastSeen(network: Network): Promise<{ ledger: number; cursor: string } | null>
     setLastSeen(network: Network, ledger: number, cursor: string): Promise<void>
     clear(network: Network): Promise<void>
   }

2. Two implementations:
   • MemoryCache — LRU in-memory (default for Node / RN / server).
   • IndexedDBCache — persistent browser cache (auto-selected in browser environment).
3. Wire into fetchAnnouncements:
   • On first call, query the cache for getLastSeen.
   • If present, set fromLedger to lastSeen + 1 and merge results with cache.
   • On success, update lastSeen and put the new announcements.
4. Support a bypassCache: true option for callers who need a fresh read (e.g., post-payment confirmation).

Constraints

• Cache must NEVER store the user's viewing key or any derived material. It's announcement data only.
• IndexedDB writes batched (don't issue 1000 individual put calls for a 1000-announcement page).
• Cache key includes network — testnet/mainnet data never collide.
• Cap the IndexedDB cache at 50 MB; LRU-evict beyond that.
• Versioning: cache schema has a version constant; on mismatch the cache is dropped and rebuilt.

Acceptance criteria

• Cache abstraction + both implementations.
• Tests under test/chains/stellar/cache.test.ts covering eviction, version migration, network isolation, and idempotency.
• Benchmarks showing the speedup for repeated scans (use #05's harness).
• Documented integration pattern in the JSDoc / docs.

Why this matters

The Spectre TEE polls every 5 minutes. The demo polls every minute when on the receive page. The console will poll for analytics. Multiply this by every user × every chain × forever — caching is the difference between Wraith being a polite RPC citizen and being a noisy neighbor.

[Kaycee276]

@Kaycee276 has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hi please id love to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Kaycee276 to this issue.

[AlonsoFi]

@AlonsoFi has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hey! I'd like to take on this issue. The RPC traffic reduction angle is clear and the constraints are well-defined. My plan:

• Build cache.ts with the AnnouncementCache interface and both implementations: MemoryCache (LRU for Node/RN/server) and IndexedDBCache (auto-selected in browser, batched writes, 50MB cap with LRU eviction)
• Wire into fetchAnnouncements: check getLastSeen on first call, set fromLedger = lastSeen + 1, merge and update on success
• Add bypassCache: true option for post-payment fresh reads
• Enforce the key constraints: no viewing key or derived material ever cached, network-isolated keys, schema versioning with auto-drop on mismatch
• Write tests covering eviction, version migration, network isolation, and idempotency
• Add benchmarks using the Stellar SDK benchmark suite + baseline report #5 harness showing speedup on repeated scans

Can I get this assigned?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @AlonsoFi to this issue.

[TheDEV111]

@TheDEV111 has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hi can I work on this issue pls

ℹ️ Repo Maintainers: To accept this application, review their application or assign @TheDEV111 to this issue.

[drips-wave]

Congratulations, @AlonsoFi! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @AlonsoFi: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊