feat(contracts): lazy pool state initialization with on-demand loading (#721)

[daniella-techie]

Closes #721
Closes #714
Closes #715
Closes #716

Context

Pool state initialization was eager and slow — all pool state was loaded at startup.

What changed

• stellar-lend/contracts/hello-world/src/pool_state.rs (new) — consolidated PoolStateSnapshot (interest-rate, risk, liquidity, reserve components) that is materialized lazily on first access and memoised in short-lived (temporary) storage keyed by (pool, global epoch).
• On-demand loading — sub-components are resolved only while a snapshot is being built, never at contract initialize time; missing sub-config falls back to protocol defaults instead of erroring.
• State caching with invalidation — a global monotonic epoch is bumped by every mutation that can change a snapshot (set_risk_params, update_interest_rate_config, set_reserve_factor). Because the epoch is part of the cache key, stale entries are ignored automatically; invalidate_pool_state (admin) forces a rebuild for a pool.
• State consistency guarantees — every component of a snapshot is read within a single load call against one epoch, and the epoch is embedded in the returned value so callers can detect staleness. Snapshots are never partially mutated in place.
• State loading monitoring — hit / miss / rebuild / invalidation / pools-initialized counters kept in persistent storage, exposed via get_pool_state_metrics.
• New contract entrypoints — get_pool_state, is_pool_state_initialized, get_pool_state_epoch, get_pool_state_metrics, invalidate_pool_state.
• stellar-lend/contracts/hello-world/src/storage.rs — PoolStateKey / PoolStateTempKey storage keys.
• api/src/services/stellar.service.ts — StellarService.getPoolState() lazily loads and caches snapshots keyed by the on-chain epoch, with cache-hit-rate + load-latency metrics (getPoolStateCacheMetrics) and per-pool cache invalidation (invalidatePoolStateCache). Warm reads are served from the local cache well within the <50ms target.
• stellar-lend/benchmarks/src/pool_state_benchmarks.rs (new) — cold / warm / invalidation / metrics gas benchmarks for the lazy pool-state path; registered in the benchmark runner.

Acceptance criteria

• Lazy state initialization
• On-demand state loading
• State caching with invalidation
• State loading performance <50ms (epoch-keyed cache hit path)
• State consistency guarantees (single-epoch reads, epoch embedded in snapshot)
• State loading monitoring (get_pool_state_metrics / getPoolStateCacheMetrics)
• State loading documentation (module docs + PR description)

---

Related performance work (context only — not addressed in this PR)

#714 — Optimize liquidation gas costs with early exit and batched operations

Liquidation gas costs can be reduced through optimization. Current liquidation operations are gas-inefficient. Expected: early-exit optimizations for unprofitable liquidations, batched storage operations, gas-efficient data structures, gas regression testing in CI, gas optimization documentation, and gas benchmarks/comparison for liquidations. Scope: stellar-lend/contracts/hello-world/src/liquidate.rs, stellar-lend/benchmarks/, .github/workflows/, docs/gas-optimization.md.

#715 — Implement interest calculation caching with incremental updates

Interest calculations are performed on every query and recalculated on every access. Expected: interest calculation caching, incremental updates on state changes, cache invalidation on relevant events, interest calculation <10ms, cache hit-rate monitoring, and interest calculation benchmarks/documentation. Scope: stellar-lend/contracts/hello-world/src/interest_rate.rs, stellar-lend/contracts/lending-interest/src/, api/src/services/redisCache.service.ts, stellar-lend/benchmarks/.

#716 — Add transaction simulation cache for common pool operations

Transaction simulation is slow for repeated operations and is simulated from scratch each time. Expected: transaction simulation caching, cache key generation from inputs, cache invalidation on state changes, simulation performance <500ms, cache hit-rate monitoring, simulation accuracy validation, and simulation caching documentation. Scope: api/src/services/stellar.service.ts, api/src/services/redisCache.service.ts, api/src/routes/, stellar-lend/benchmarks/.

.

[vercel]

Someone is attempting to deploy a commit to the smartdevs17's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@daniella-techie 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