Dynamic Fee Surge Detector

[Kingsman-99]

Description

Stellar's base fee rises during network congestion, making hard-coded fee values cause transaction failures during surges. The SDK currently uses a fixed fee from StellarSplitConfig and does not react to real-time ledger fee data. A surge detector should monitor recent ledger fee statistics via Horizon and automatically recommend or apply an adjusted fee multiplier when the network is congested.

Technical Context

Extend src/feeEstimator.ts and src/fee.ts. Uses @stellar/stellar-sdk Server.feeStats() which returns FeeStatsRecord with p10, p50, p95 fee percentiles. Add FeeSurgeConfig and FeeRecommendation to src/types.ts. Integrate with src/txBuilder.ts so the surge-adjusted fee is applied before transaction signing. Optionally emits a feeSurgeDetected event via src/events.ts.

Acceptance Criteria

• detectFeeSurge(): Promise<FeeRecommendation> fetches current fee stats and computes a recommended base fee at a configurable percentile (default p75)
• A surge threshold (e.g. 2× the 30-ledger average) triggers a feeSurgeDetected event with the recommended fee
• src/txBuilder.ts calls detectFeeSurge() before building each transaction and applies the recommendation when autoFeeAdjust: true is set in config
• Fee history is sampled over a configurable rolling window (default: last 10 ledgers) fetched from feeStats()
• Unit tests mock feeStats() responses and assert correct surge detection at various percentile thresholds
• All CI checks (npm test, npm run build, ESLint/TypeScript) pass and the branch has no merge conflicts

---

[MorsH14]

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

id love to work on this issue

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

[Prasiejames]

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

id love to work on this issue

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

[drips-wave]

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

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