Transaction Fee History Trend Analyzer

[Kingsman-99]

Description

The SDK cannot currently advise callers on appropriate base fees because it has no visibility into recent ledger fee trends. Fee spikes during network congestion cause submitted transactions to be rejected without useful guidance, and manual fee tuning is tedious. A fee trend analyzer would query Horizon's /fee_stats endpoint on a rolling basis, compute percentile estimates over a sliding window, and expose a recommended fee for a caller-specified acceptance-percentile target.

Technical Context

New module src/fees/trend.ts exposing a FeeTrendAnalyzer class. Calls Horizon.Server.feeStats() from @stellar/stellar-sdk. Stores a configurable rolling window of samples using a fixed-capacity circular buffer in src/utils/circularBuffer.ts. Percentile computation extracted to src/utils/stats.ts. Configuration via FeeTrendOptions interface in src/types.ts.

Acceptance Criteria

• FeeTrendAnalyzer.sample() fetches the current fee stats snapshot and appends it to the rolling window, evicting the oldest entry when capacity is reached
• FeeTrendAnalyzer.recommendedFee(percentile: 50 | 75 | 95 | 99): number returns the fee (in stroops) at the requested percentile across all stored samples
• Window capacity is configurable (default 20, min 5, max 100) and enforced with a compile-time branded-number type
• Samples older than a configurable TTL (default 5 minutes) are automatically evicted before any percentile computation
• Unit tests verify percentile accuracy against a known 20-sample dataset, correct eviction by both capacity and TTL, and partial-window behavior
• All CI checks (npm test, npm run build, ESLint/TypeScript) pass and the branch has no merge conflicts

---

[David-Savio]

@David-Savio has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi maintainer. I will resolve this issue quickly, If it's assigned to me. Thank you.

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

[echoripplestudio]

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

I would like to work on this issue

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

[drips-wave]

Congratulations, @echoripplestudio! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

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

[drips-wave]

This issue has been completed by @echoripplestudio as part of the Stellar Wave Program's 7th Wave 🥳

😎 @echoripplestudio: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.