Retry + exponential backoff for Soroban RPC

[truthixify]

Labels: Stellar Wave, stellar, resilience, drips, help-wanted
Tier: M (2–4 days)
Type: resilience

Context

The Stellar Receive page calls Soroban RPC for getEvents, Horizon for balance lookups, and the announcer contract for occasional reads. Today every call is single-attempt — a single 429 or transient 502 surfaces directly to the user as "scan failed". This is unacceptably brittle.

We need a small retry primitive shared across all Stellar HTTP calls.

Scope

Add src/lib/stellar/retry.ts with a withRetry(fn, opts) helper that:

1. Attempts up to N times (default 4).
2. Backs off exponentially with jitter: 200ms, 400ms, 800ms, 1600ms, each ±25%.
3. Retries only on specific failure classes:
   • HTTP 408, 429, 502, 503, 504
   • Network errors / aborted fetches
   • JSON parse errors (sometimes RPC returns HTML on overload)
4. Does NOT retry on:
   • HTTP 4xx other than 408/429
   • Bad request / invalid input
   • Auth failures
5. Throws a typed StellarRetryExhaustedError after final attempt, carrying the last error.
6. Respects an AbortSignal from the caller (e.g., user navigated away).

Wire it into:

• src/components/StellarSend.tsx Soroban announcer write
• src/components/StellarReceive.tsx scan loop and balance fetch
• Any other Stellar fetch helpers

Acceptance criteria

• retry.ts implementation with unit tests using mocked fetch.
• All Stellar fetches wrapped.
• User-facing error UI on StellarRetryExhaustedError shows: "Network unstable — try again." with a retry button (not a generic stack trace).
• Telemetry hook: emit an event when a retry happens (we can wire this to PostHog later).

Why this matters

Soroban RPC rate limits on public endpoints are tight. Spectre's polling already pressures the same endpoints. Any user-perceived demo flakiness undercuts our entire credibility on Stellar.

[gregemax]

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

I’d like to handle this issue to make Stellar RPC calls more reliable and prevent random scan failures from affecting users.

Plan
Create withRetry() in src/lib/stellar/retry.ts
Retry up to 4 times with exponential backoff + jitter
Retry only on transient errors (429, 502–504, network, bad JSON)
Add StellarRetryExhaustedError and support AbortSignal
Wrap RPC calls in Send/Receive components and shared fetch utils
Add unit tests for retry behavior and edge cases
UX
Show: “Network unstable — try again.” with retry button on failure
ETA: 24 hours

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

[drips-wave]

Congratulations, @gregemax! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

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