Add TTL-based caching to TrustFlowClient.getBalance to reduce redundant Horizon calls

[meshackyaro]

Description

This issue aims to address the implementation of TTL-Cached getBalance.

The core objective is to: Add opt-in TTL-based caching to TrustFlowClient.getBalance (src/client.ts), using the SDK's existing (currently unused) SimpleCache from src/utils/cache.ts, so repeated balance checks for the same address within a short window don't each trigger a fresh server.loadAccount(address) Horizon round-trip. TrustFlowClient.getBalance(address) currently calls this.server.loadAccount(address) on every single invocation with no caching layer — a UI polling balance every few seconds (exactly the pattern src/hooks/useBalance.ts sets up via its useEffect) generates a fresh Horizon request every time even if the balance hasn't changed. src/utils/cache.ts's SimpleCache<K, V> already implements exactly the TTL-expiry primitive this would need, but currently has no real call site anywhere in the codebase.

By completing this feature, we will ensure that the TrustFlow protocol maintains its high standards for security, usability, and decentralized logic. This issue requires careful attention to the SDK Wrapper architecture and adherence to the existing project conventions.

Component

SDK

Difficulty

🟡 Medium

Tasks

• Review existing Typescript classes (TrustFlowClient, SimpleCache)
• Implement SDK method for: TTL-based caching on TrustFlowClient.getBalance using SimpleCache, with a sensible default TTL and a way to force a fresh fetch (e.g. a { skipCache?: boolean } option)
• Ensure Tsup successfully exports to ESM and CJS
• Update typedoc comments for the new feature
• Write Jest tests validating cache hits, cache expiry (fake timers), and the force-refresh option
• Run npm run build to verify standard bundling

Acceptance Criteria

• Feature accurately implements the objective above
• A second getBalance call for the same address within the TTL window does not trigger a second Horizon request
• Any PR that introduces TypeScript errors is automatically blocked
• Code is properly reviewed and approved by codeowners

Estimated Time

2-3 days

[Kureszn]

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

I've reviewed the issue and believe I can contribute effectively. My experience spans software development, blockchain technologies, cybersecurity and open source collaboration. I take a structured approach to contributions carefully understanding the existing codebase, identifying the root cause and delivering a thoroughly tested implementation.

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

[Johnjnr1]

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

i’m very conversant in solving problems like this, let me work on it

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

[entitydev30]

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

Kindly assign me to this issue

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

[femiolutayo]

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

Hello maintainer, Please, assign this issue to me. I beg you, biko.

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

[Priyanshu1-62]

@Priyanshu1-62 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi maintainers,
Please assign this issue to me.

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

[somotochukwu-dev]

@somotochukwu-dev has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi
Please assign this issue to me
Thanks

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

[connelevalsam]

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

I like this project and would like to work on this.

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

[drips-wave]

Congratulations, @connelevalsam! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

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