feat(frontend): build real-time network fee estimator widget — Horizon fee percentile tiers, XLM/USD breakdown, Soroban resource fee add-on, congestion warning, and auto-refresh countdown

[Chibey-max]

Overview

Before funding an escrow, users want to know how much the Stellar network fee will be, in both XLM and their local currency. A fee estimator widget fetches real-time fee percentile data from Horizon, shows a cost breakdown, and recommends whether a fee-bump might be needed.

What to build

• FeeEstimatorWidget component, embedded in the escrow creation wizard and on the escrow detail page before any transaction action
• Data: call GET /api/v1/fees/estimate (backend endpoint) which aggregates:
  • Horizon fee_stats endpoint (/fee_stats): p10, p50, p95, p99 fee percentiles in stroops
  • XLM/USD live rate (from the full-stack oracle, or fallback to Coingecko)
  • Soroban resource fee for the specific operation type (from simulation result if available)
• Display:
  • Three tiers: "Slow (p10)", "Standard (p50)", "Fast (p95)" — each showing XLM cost and USD equivalent
  • Currently selected fee is highlighted; user can click to select a different tier
  • "Soroban resource fee" shown separately as a non-negotiable add-on
  • Warning badge if p99 > 3× p50 (network congestion indicator)
  • Fee-bump recommendation: if current p50 < previous_p50 * 0.5 (fee dropped significantly), suggest the user is likely fine without a bump; if p50 > previous_p50 * 2, suggest including a fee-bump budget
  • Auto-refresh every 30s; countdown timer showing next refresh
• Backend GET /api/v1/fees/estimate?operation_type=fund_escrow — returns the combined fee data; caches Horizon fee_stats for 15s in Redis

Acceptance Criteria

• Fee data fetched at most once per 15s (backend cache); widget shows cached data with "as of X seconds ago" label
• XLM amounts displayed with 7 decimal places; USD with 2 decimal places
• Selected fee tier propagates to the parent form via a callback onFeeSelected(fee_stroops: bigint)
• Congestion warning appears when p99 > 3 * p50; threshold is configurable via env var
• Auto-refresh resets the countdown on each successful fetch; does not refresh when tab is hidden (Page Visibility API)
• No XLM/USD rate available: USD column shows "—" and a tooltip "Exchange rate unavailable"
• Accessibility: fee tiers are radio buttons with role="radio"; congestion warning has role="alert"
• Unit tests: fee parsing, congestion detection, USD conversion, countdown timer behaviour

Technical notes

• Backend caches GET /fee_stats response for 15s; key: stellar:fee_stats:{network}
• Soroban resource fee is operation-specific; for the fund_escrow type, use the 90th-percentile simulation result from the last 100 simulations stored in the DB

[chidii]

Hi Maintainer, reviewed the issue in detail. Full stack background with solid experience relevant to this task. No blockers on my end — I'm ready to submit a PR shortly. Please assign.

[grantfox-oss]

🦊 GrantFox — @chidii has been assigned to this issue!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #1543)
2. Your PR will be reviewed by the Stellar-Trust-Escrow maintainers

Good luck! Track your progress on GrantFox.