[thatElisha]

Closes #844
Closes #849
Closes #852
Closes #853

Summary of Changes

This pull request resolves issues #844, #849, #852, and #853 across integration, error handling, Soroban caching, and account reserve alerting.

---

1. #844 PriceOracle integration: Stale Price Feed Detection

• Problem: When integrating with price oracles for fee estimations or exchange rates, feed update timestamps were not verified. Stale prices (e.g. from hours or days prior) were accepted as current, resulting in off-market rates and miscalculated fees.
• Solution:
  • Implemented PriceOracle, checkPriceFeedStaleness, and validatePriceFeedQuote.
  • Added timestamp normalization supporting epoch milliseconds, epoch seconds, Date objects, and ISO date strings.
  • Implemented configurable staleness threshold via stalenessThresholdMs (defaults to 5 minutes / 300,000 ms).
  • Configurable staleness behavior: reject (returns a structured SERVICE_UNAVAILABLE error result) or warn (triggers warning callback / logs while allowing degraded execution).
  • Integrated timestamp staleness verification into atomicSwap.ts.
  • Added unit test suite in priceOracle.test.ts.

2. #849 SourceAccountNotFound: Actionable Recovery Guidance

• Problem: When loading source accounts failed with 404 (account does not exist on-ledger), errors lacked actionable recovery guidance, leaving callers unaware of whether to retry, wait, fund the account, or use a fallback.
• Solution:
  • Added SOURCE_ACCOUNT_NOT_FOUND to SorokitErrorCode.
  • Added suggestions?: string[] to both RecoveryGuidance and SorokitError in response.ts.
  • Documented and structured recovery suggestions for all 4 key scenarios:
    1. Retry: Check network connectivity and Horizon endpoint status, then retry if the account fetch was transiently unavailable.
    2. Wait: Wait for a pending account creation or funding transaction to confirm on-chain before retrying.
    3. Create Account: Create and fund the account with minimum reserve (at least 1 XLM) on the Stellar network before submitting transactions.
    4. Use Fallback: Use a fallback account or different active keypair with sufficient balance as the source account.
  • Added sourceAccountNotFoundError helper and integrated with buildHelpers.ts, buildTransaction.ts, and getAccount.ts.
  • Added unit test suite in sourceAccountNotFound.test.ts.

3. #852 LedgerEntryCache: Hit, Miss, Eviction, and Memory Statistics

• Problem: LedgerEntryCache stored frequently queried entries without recording cache hit rates, eviction events, or memory usage, making cache tuning and monitoring impossible.
• Solution:
  • Implemented LedgerEntryCache with getStats() exporting:
    • hits: Successful cache hits
    • misses: Cache misses (missing or expired entries)
    • evictions: Entries evicted due to LRU capacity limits or TTL expiration
    • memoryUsed: Approximate memory used in bytes (keys + values)
    • hitRate: Ratio hits / (hits + misses)
    • size: Active entry count
    • capacity: Maximum entries capacity
  • Implemented resetStats() to allow resetting counters for benchmarking without purging active cache entries.
  • Added unit test suite in ledgerEntryCache.test.ts.

4. #853 BalanceAlertRule: Minimum Balance Reserve Tracking

• Problem: Alert rules supported percentage changes and threshold alerts but could not track minimum balance reserves (stroops required to maintain an account). Accounts risked sub-reserve destruction or transaction failure without warning.
• Solution:
  • Implemented calculateMinimumReserve and calculateMinimumReserveStroops:
    $$\text{Minimum Reserve (XLM)} = (2 + \text{subentryCount}) \times 0.5\text{ XLM}$$
    where subentries include trustlines, offers, additional signers, and data entries.
  • Added "min_reserve" condition to BalanceAlertCondition and BalanceAlertRule.
  • Added minReserveAlert rule generator with optional early warning buffer (bufferXlm / threshold).
  • Enhanced evaluateBalanceAlerts to evaluate sub-reserve conditions and attach minimumReserve, minimumReserveStroops, and isSubReserve: boolean to emitted alerts.
  • Added unit test suite in balanceAlertsMinReserve.test.ts.

---

Linked Issues

Closes #844
Closes #849
Closes #852
Closes #853

[drips-wave]

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