Document and TSDoc the cached contract-read wrappers (insurance-cached, remittance-split-cached) and their validation contract

[Baskarayelu]

📋 Description

The cached read wrappers lib/contracts/insurance-cached.ts and lib/contracts/remittance-split-cached.ts sit between API routes and the raw contract reads, adding LRU caching (via lib/cache/contract-cache.ts), per-method TTLs (e.g. getActivePolicies 45s, getSplit 60s), input validation (Stellar address regex, policy-id format, integer amounts), and error-code preservation (INVALID_ADDRESS, NOT_FOUND). This validation/caching contract is non-obvious and undocumented.

Why this matters: a contributor calling the raw vs cached function has no guidance on which to use, what TTL applies, what inputs are rejected, or which error codes propagate. The cascading cache (calculateSplit reuses getSplit's cache) is especially easy to misuse. A focused doc + TSDoc makes the layer safe to consume.

🎯 Requirements & Context

Functional requirements

• Add docs/cached-contract-reads.md explaining: when to use cached vs raw reads, the per-method TTLs (cross-reference the CACHE_TTL table in lib/cache/contract-cache.ts), and the cascading cache behavior.
• Document the validation rules each wrapper enforces and the error codes it preserves vs wraps.
• Add/improve TSDoc on every exported function in the two cached modules (params, throws, cache behavior).
• Include a "gotchas" section (e.g. invalidation, integer-only amounts, address format).
• Cross-link from lib/README.md.

Context & constraints

• Verify TTLs and validation against the source before documenting.
• Docs + TSDoc only; no behavior change.

🛠️ Suggested Execution

1. Branch

git checkout -b docs/cached-contract-reads

2. Write & verify

npx tsc --noEmit
npm run lint

• Confirm each documented TTL/validation matches code.

Example commit message

docs(contracts): document cached read wrappers + validation/TTL contract

Adds docs/cached-contract-reads.md and TSDoc for insurance-cached and
remittance-split-cached, including cascading-cache gotchas.

✅ Acceptance Criteria & Guidelines

Requirement	Target
Cached-vs-raw guidance + TTLs documented	Required
Validation rules + error-code behavior documented	Required
TSDoc on all exported functions	Required
References match source	Required
npx tsc --noEmit + npm run lint clean	Required
Timeframe	96 hours from assignment

💬 Community & Support

Questions — join the RemitWise contributor community on Discord: https://discord.gg/CtQuPZFMA

Comment when you pick this up. 🚀

[ekwe7]

I would love to work on this issue. I have experience building production ready applications and collaborating through GitHub workflows. I'll carefully analyze the current implementation, propose a reliable solution, and submit a well-tested PR. My focus is on clean code, maintainability, and timely delivery

[ekwe7]

I would love to work on this issue. I have experience building production ready applications and collaborating through GitHub workflows. I'll carefully analyze the current implementation, propose a reliable solution, and submit a well-tested PR. My focus is on clean code, maintainability, and timely delivery

[444notdotun]

Hi,

With 4 years of hands-on experience across backend, frontend, and smart contract development, I'm confident I can complete this task quickly and to a high standard. I've reviewed the requirements in detail and fully understand what's needed.

My focus is on writing clean, efficient, and maintainable code backed by thorough testing and industry best practices. I'll ensure the solution is production-ready and delivered on time.

I expect to have my PR ready in less than 10 hours.

[leocagli]

I've gone through the details and I'm ready. Please assign me.

[drips-wave]

Congratulations, @prettylady-sys! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @prettylady-sys: 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 🌊