Add JSDoc/TSDoc and a usage guide for the cached contract-read layer (lib/contracts + lib/cache/contract-cache.ts)

[Baskarayelu]

📋 Description

The frontend reads on-chain data through a cached contract layer: lib/cache/contract-cache.ts, lib/cache/registry.ts, and cached wrappers like lib/contracts/remittance-split-cached.ts and lib/contracts/insurance-cached.ts. The caching semantics (TTL, invalidation via app/api/cache/invalidate/route.ts, lru-cache usage) are non-obvious and undocumented, making it risky for contributors to add a new cached read correctly.

Why this matters: a contributor who caches a write result or sets the wrong TTL can serve stale balances. Clear docs on when and how to cache are essential before more readers are added.

🎯 Requirements & Context

Functional requirements

• Add TSDoc to the public functions in lib/cache/contract-cache.ts and lib/cache/registry.ts (params, TTL semantics, invalidation, what is safe to cache).
• Write docs/contract-cache.md explaining the read/cache/invalidate flow, the registry, and a step-by-step "add a new cached read" recipe (mirroring remittance-split-cached.ts).
• Document the invalidation endpoint at app/api/cache/invalidate/route.ts.
• Cross-link from README.md.

Context & constraints

• Docs must match the existing tests in tests/unit/contract-cache.test.ts / tests/unit/cached-wrappers.test.ts.
• Documentation-only; do not change behavior.

🛠️ Suggested Execution

git checkout -b docs/contract-cache-guide

• Add TSDoc + docs/contract-cache.md + README cross-link.

npm run lint
npm run test:unit

• Edge cases to document: cache miss, manual invalidation, TTL expiry, what must never be cached (writes, balances post-transfer).

Example commit message

docs(cache): document contract-cache layer and add-a-reader recipe

Adds TSDoc to cache/registry plus docs/contract-cache.md covering TTL,
invalidation, and a step-by-step new cached read recipe.

✅ Acceptance Criteria & Guidelines

Requirement	Target
TSDoc on cache/registry public API	Required
docs/contract-cache.md complete + accurate	Required
Invalidation endpoint documented	Required
README cross-link	Required
Lint + unit tests still pass	Required
Timeframe	96 hours from assignment

💬 Community & Support

Join the RemitWise contributor community on Discord: https://discord.gg/CtQuPZFMA

Comment to claim before starting. 🚀

[Tobi-8]

I can confidently handle this, please assign

[Menjay7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. Thank you!

[jaynomyaro]

Hi! I’m a full-stack developer with a strong blockchain background. I’d love to handle this issue and can deliver a clean, reliable solution. Kindly assign it to me.

[Senorespecial]

I would like to work on this issue please assign

[grantfox-oss]

🦊 GrantFox — @Tobi-8 has been assigned to this issue!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #477)
2. Your PR will be reviewed by the Remitwise-Org maintainers

Good luck! Track your progress on GrantFox.