feat(sdk): add in-memory caching layer with LRU eviction and TTL for …

[jerrymusaga]

Closes #175

Summary

• CacheManager (sdk/src/cache.ts) — opt-in in-memory cache with:

  • LRU eviction via Map insertion-order (O(1) get/set/evict)
  • Configurable TTL per-entry and globally (defaultTtlMs, default 30 s)
  • Hit/miss/eviction metrics (getMetrics() / resetMetrics())
  • Cache warming via warmUp(entries[]) to pre-seed from trusted data
  • Optional localStorage persistence with BigInt serialization (browser only, graceful no-op in Node/SSR)

• bcForgeClient — wired via opt-in cacheConfig in the constructor config:

  • All read methods (getBalance, getTotalSupply, getName, getSymbol, getDecimals, getAllowance, getVersion) go through the cache
  • Write methods invalidate precisely the keys they affect (e.g. mint → balance:{to} + supply; transfer → balance:{from} + balance:{to})
  • No invalidation on failed transactions
  • upgrade / initialize → full cache clear
  • New public API: getCacheMetrics(), clearCache(), warmUpCache(), prefetchBalances()

• index.ts — exports CacheManager, DEFAULT_CACHE_CONFIG, and all cache types

Test plan

• LRU eviction at capacity
• TTL expiry (per-entry and global), no-expiry with ttlMs: 0
• Hit/miss metrics and hitRate
• invalidate, invalidateByPrefix, invalidateAll
• Cache warming, metrics reset
• localStorage round-trips including BigInt serialization
• Expired entries not restored from storage
• Client integration: cache hit bypasses RPC, invalidation on successful writes, no invalidation on failure
• All 59 tests pass (npm test)
• tsc --noEmit — no errors

[drips-wave]

@jerrymusaga 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