From eac24e95cf437e10e97d052eb6e7572c4c88dd8e Mon Sep 17 00:00:00 2001
From: gregemax <gregemax700@gmail.com>
Date: Wed, 27 May 2026 19:08:59 +0100
Subject: [PATCH] feat(stellar): retry + exponential backoff for Soroban RPC
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add withRetry(fn, opts) helper with 4 attempts, exponential backoff
  (200/400/800/1600ms ±25% jitter), and AbortSignal support
- Retry on HTTP 408/429/502/503/504, TypeError (network), SyntaxError (JSON)
- Skip retry on other 4xx, AbortError, and StellarRetryExhaustedError
- Emit onRetry telemetry hook for future PostHog integration
- Wire withRetry into all Stellar fetches in StellarSend and StellarReceive
- Show 'Network unstable — try again.' + retry button on exhaustion
- 16 unit tests covering all retry/no-retry paths
---
 src/components/StellarReceive.tsx |  93 ++++++++++++++-------
 src/components/StellarSend.tsx    |  44 +++++++---
 src/lib/stellar/retry.test.ts     | 133 ++++++++++++++++++++++++++++++
 src/lib/stellar/retry.ts          |  85 +++++++++++++++++++
 4 files changed, 316 insertions(+), 39 deletions(-)
 create mode 100644 src/lib/stellar/retry.test.ts
 create mode 100644 src/lib/stellar/retry.ts

diff --git a/src/components/StellarReceive.tsx b/src/components/StellarReceive.tsx
index d279a52..8b873c6 100644
--- a/src/components/StellarReceive.tsx
+++ b/src/components/StellarReceive.tsx
@@ -24,6 +24,7 @@ import { useStellarWallet } from '@/context/StellarWalletContext';
 import { CopyButton } from '@/components/CopyButton';
 import { stellarTxUrl, stellarAddrUrl } from '@/lib/explorer';
 import { STELLAR_NETWORK } from '@/config';
+import { withRetry, StellarRetryExhaustedError } from '@/lib/stellar/retry';
 
 const ANNOUNCER_CONTRACT = 'CCJLJ2QRBJAAKIG6ELNQVXLLWMKKWVN5O2FKWUETHZGMPAD4MHK7WVWL';
 const REGISTRY_CONTRACT = 'CC2LAUCXYOPJ4DV4CYXNXYAXRDVOTMAWFF76W4WFD5OVQBD6TN4PYYJ5';
@@ -36,20 +37,22 @@ async function fetchAnnouncementEvents(
 
   try {
     let startLedger = 1;
-    const probeRes = await fetch(rpcUrl, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        jsonrpc: '2.0',
-        id: 0,
-        method: 'getEvents',
-        params: {
-          startLedger: 1,
-          filters: [{ type: 'contract', contractIds: [contractId] }],
-          pagination: { limit: 1 },
-        },
+    const probeRes = await withRetry(() =>
+      fetch(rpcUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          id: 0,
+          method: 'getEvents',
+          params: {
+            startLedger: 1,
+            filters: [{ type: 'contract', contractIds: [contractId] }],
+            pagination: { limit: 1 },
+          },
+        }),
       }),
-    });
+    );
     const probeData = await probeRes.json();
 
     if (probeData.error?.message) {
@@ -78,11 +81,13 @@ async function fetchAnnouncementEvents(
         params.startLedger = startLedger;
       }
 
-      const res = await fetch(rpcUrl, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'getEvents', params }),
-      });
+      const res = await withRetry(() =>
+        fetch(rpcUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'getEvents', params }),
+        }),
+      );
 
       const data = await res.json();
       const events = data.result?.events ?? [];
@@ -150,6 +155,7 @@ function StellarStealthRow({
   const [withdrawing, setWithdrawing] = useState(false);
   const [withdrawHash, setWithdrawHash] = useState<string | null>(null);
   const [error, setError] = useState('');
+  const [retryExhausted, setRetryExhausted] = useState(false);
   const [showKey, setShowKey] = useState(false);
 
   const scalarHex = match.stealthPrivateScalar.toString(16).padStart(64, '0');
@@ -157,7 +163,9 @@ function StellarStealthRow({
   useEffect(() => {
     (async () => {
       try {
-        const res = await fetch(`${STELLAR_NETWORK.horizonUrl}/accounts/${match.stealthAddress}`);
+        const res = await withRetry(() =>
+          fetch(`${STELLAR_NETWORK.horizonUrl}/accounts/${match.stealthAddress}`),
+        );
         if (!res.ok) {
           setBalance('0');
           return;
@@ -176,13 +184,16 @@ function StellarStealthRow({
   const handleWithdraw = async () => {
     if (!dest) return;
     setError('');
+    setRetryExhausted(false);
     setWithdrawing(true);
 
     try {
       const horizonUrl = STELLAR_NETWORK.horizonUrl;
       const networkPassphrase = STELLAR_NETWORK.networkPassphrase;
 
-      const res = await fetch(`${horizonUrl}/accounts/${match.stealthAddress}`);
+      const res = await withRetry(() =>
+        fetch(`${horizonUrl}/accounts/${match.stealthAddress}`),
+      );
       if (!res.ok) throw new Error('Account not found');
       const account = await res.json();
 
@@ -213,11 +224,13 @@ function StellarStealthRow({
       const signatureBase64 = Buffer.from(signature).toString('base64');
       tx.addSignature(match.stealthAddress, signatureBase64);
 
-      const submitRes = await fetch(`${horizonUrl}/transactions`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: `tx=${encodeURIComponent(tx.toXDR())}`,
-      });
+      const submitRes = await withRetry(() =>
+        fetch(`${horizonUrl}/transactions`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: `tx=${encodeURIComponent(tx.toXDR())}`,
+        }),
+      );
 
       const submitData = await submitRes.json();
       if (!submitRes.ok) {
@@ -229,7 +242,12 @@ function StellarStealthRow({
       setWithdrawHash(submitData.hash);
       onWithdrawn();
     } catch (err) {
-      setError(err instanceof Error ? err.message : 'Withdraw failed');
+      if (err instanceof StellarRetryExhaustedError) {
+        setRetryExhausted(true);
+        setError('Network unstable — try again.');
+      } else {
+        setError(err instanceof Error ? err.message : 'Withdraw failed');
+      }
     } finally {
       setWithdrawing(false);
     }
@@ -292,7 +310,19 @@ function StellarStealthRow({
         </div>
       )}
 
-      {error && <p className="text-xs text-error">{error}</p>}
+      {error && (
+        <div className="flex items-center gap-3">
+          <p className="text-xs text-error">{error}</p>
+          {retryExhausted && (
+            <button
+              onClick={handleWithdraw}
+              className="font-heading text-[11px] font-semibold uppercase tracking-widest text-primary underline"
+            >
+              Retry
+            </button>
+          )}
+        </div>
+      )}
 
       {withdrawHash && (
         <div className="flex items-center gap-2">
@@ -345,6 +375,7 @@ export function StellarReceive() {
   const [matched, setMatched] = useState<MatchedAnnouncement[]>([]);
   const [hasScanned, setHasScanned] = useState(false);
   const [error, setError] = useState('');
+  const [scanRetryExhausted, setScanRetryExhausted] = useState(false);
   const [isRegistering, setIsRegistering] = useState(false);
   const [isRegSuccess, setIsRegSuccess] = useState(false);
   const [regHash, setRegHash] = useState<string | null>(null);
@@ -502,7 +533,13 @@ export function StellarReceive() {
       setMatched(results);
       setHasScanned(true);
     } catch (err) {
-      setError(err instanceof Error ? err.message : 'Scan failed');
+      setError(
+        err instanceof StellarRetryExhaustedError
+          ? 'Network unstable — try again.'
+          : err instanceof Error
+            ? err.message
+            : 'Scan failed',
+      );
     } finally {
       setIsScanning(false);
     }
diff --git a/src/components/StellarSend.tsx b/src/components/StellarSend.tsx
index 6626d1f..5554a05 100644
--- a/src/components/StellarSend.tsx
+++ b/src/components/StellarSend.tsx
@@ -18,6 +18,7 @@ import { useStellarWallet } from '@/context/StellarWalletContext';
 import { stellarTxUrl, stellarAddrUrl } from '@/lib/explorer';
 import { STELLAR_NETWORK } from '@/config';
 import { CopyButton } from '@/components/CopyButton';
+import { withRetry, StellarRetryExhaustedError } from '@/lib/stellar/retry';
 
 const ANNOUNCER_CONTRACT = 'CCJLJ2QRBJAAKIG6ELNQVXLLWMKKWVN5O2FKWUETHZGMPAD4MHK7WVWL';
 
@@ -27,6 +28,7 @@ export function StellarSend() {
   const [amount, setAmount] = useState('');
   const [error, setError] = useState('');
   const [isPending, setIsPending] = useState(false);
+  const [retryExhausted, setRetryExhausted] = useState(false);
   const [stealthResult, setStealthResult] = useState<{
     stealthAddress: string;
     ephemeralPubKey: Uint8Array;
@@ -42,6 +44,7 @@ export function StellarSend() {
     }
 
     setError('');
+    setRetryExhausted(false);
     setIsPending(true);
 
     try {
@@ -59,13 +62,13 @@ export function StellarSend() {
       const horizonUrl = STELLAR_NETWORK.horizonUrl;
       const networkPassphrase = STELLAR_NETWORK.networkPassphrase;
 
-      const accountRes = await fetch(`${horizonUrl}/accounts/${address}`);
+      const accountRes = await withRetry(() => fetch(`${horizonUrl}/accounts/${address}`));
       if (!accountRes.ok) throw new Error('Failed to load sender account');
       const accountData = await accountRes.json();
       const sourceAccount = new Account(address, accountData.sequence);
 
-      const stealthExists = await fetch(`${horizonUrl}/accounts/${result.stealthAddress}`).then(
-        (r) => r.ok,
+      const stealthExists = await withRetry(() =>
+        fetch(`${horizonUrl}/accounts/${result.stealthAddress}`).then((r) => r.ok),
       );
 
       let classicTx;
@@ -94,11 +97,13 @@ export function StellarSend() {
 
       const signedXdr = await signTransaction(classicTx.toXDR());
 
-      const submitRes = await fetch(`${horizonUrl}/transactions`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: `tx=${encodeURIComponent(signedXdr)}`,
-      });
+      const submitRes = await withRetry(() =>
+        fetch(`${horizonUrl}/transactions`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: `tx=${encodeURIComponent(signedXdr)}`,
+        }),
+      );
 
       const submitData = await submitRes.json();
       if (!submitRes.ok) {
@@ -115,7 +120,7 @@ export function StellarSend() {
         const soroban = new rpcMod.Server(STELLAR_NETWORK.rpcUrl);
         const announcerContract = new Contract(ANNOUNCER_CONTRACT);
 
-        const freshRes = await fetch(`${horizonUrl}/accounts/${address}`);
+        const freshRes = await withRetry(() => fetch(`${horizonUrl}/accounts/${address}`));
         const freshData = await freshRes.json();
         const freshAccount = new Account(address, freshData.sequence);
 
@@ -152,7 +157,12 @@ export function StellarSend() {
 
       setIsSuccess(true);
     } catch (err) {
-      setError(err instanceof Error ? err.message : 'Transaction failed');
+      if (err instanceof StellarRetryExhaustedError) {
+        setRetryExhausted(true);
+        setError('Network unstable — try again.');
+      } else {
+        setError(err instanceof Error ? err.message : 'Transaction failed');
+      }
     } finally {
       setIsPending(false);
     }
@@ -263,7 +273,19 @@ export function StellarSend() {
             </div>
           </div>
 
-          {error && <p className="text-sm text-error">{error}</p>}
+          {error && (
+            <div className="flex items-center gap-3">
+              <p className="text-sm text-error">{error}</p>
+              {retryExhausted && (
+                <button
+                  onClick={handleSend}
+                  className="font-heading text-[11px] font-semibold uppercase tracking-widest text-primary underline"
+                >
+                  Retry
+                </button>
+              )}
+            </div>
+          )}
 
           <button
             onClick={handleSend}
diff --git a/src/lib/stellar/retry.test.ts b/src/lib/stellar/retry.test.ts
new file mode 100644
index 0000000..ab9df2a
--- /dev/null
+++ b/src/lib/stellar/retry.test.ts
@@ -0,0 +1,133 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { withRetry, StellarRetryExhaustedError } from './retry';
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+/** Run fn, flush all timers, then return the settled result. */
+async function run<T>(fn: () => Promise<T>): Promise<T> {
+  const p = fn();
+  await vi.runAllTimersAsync();
+  return p;
+}
+
+describe('withRetry', () => {
+  it('resolves immediately on success', async () => {
+    const fn = vi.fn().mockResolvedValue('ok');
+    expect(await run(() => withRetry(fn))).toBe('ok');
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries on TypeError (network error) and succeeds', async () => {
+    const fn = vi
+      .fn()
+      .mockRejectedValueOnce(new TypeError('Failed to fetch'))
+      .mockResolvedValue('ok');
+    expect(await run(() => withRetry(fn, { attempts: 4 }))).toBe('ok');
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('retries on SyntaxError (JSON parse) and succeeds', async () => {
+    const fn = vi
+      .fn()
+      .mockRejectedValueOnce(new SyntaxError('Unexpected token'))
+      .mockResolvedValue('data');
+    expect(await run(() => withRetry(fn, { attempts: 4 }))).toBe('data');
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('retries on 429 error and succeeds', async () => {
+    const fn = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('HTTP 429 Too Many Requests'))
+      .mockResolvedValue('ok');
+    expect(await run(() => withRetry(fn, { attempts: 4 }))).toBe('ok');
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it.each([502, 503, 504])('retries on %i and succeeds', async (status) => {
+    const fn = vi
+      .fn()
+      .mockRejectedValueOnce(new Error(`HTTP ${status}`))
+      .mockResolvedValue('ok');
+    expect(await run(() => withRetry(fn, { attempts: 4 }))).toBe('ok');
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('throws StellarRetryExhaustedError after all attempts fail', async () => {
+    const fn = vi.fn().mockRejectedValue(new TypeError('Failed to fetch'));
+    const err = await run(() => withRetry(fn, { attempts: 3 }).catch((e) => e));
+    expect(err).toBeInstanceOf(StellarRetryExhaustedError);
+    expect(fn).toHaveBeenCalledTimes(3);
+  });
+
+  it('StellarRetryExhaustedError carries the last error as cause', async () => {
+    const cause = new TypeError('Failed to fetch');
+    const fn = vi.fn().mockRejectedValue(cause);
+    const err = await run(() => withRetry(fn, { attempts: 2 }).catch((e) => e));
+    expect(err).toBeInstanceOf(StellarRetryExhaustedError);
+    expect((err as StellarRetryExhaustedError).cause).toEqual(cause);
+  });
+
+  it('does NOT retry on 400 Bad Request', async () => {
+    const fn = vi.fn().mockRejectedValue(new Error('HTTP 400 Bad Request'));
+    const err = await run(() => withRetry(fn, { attempts: 4 }).catch((e) => e));
+    expect(err).toBeInstanceOf(StellarRetryExhaustedError);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('does NOT retry on 401 Unauthorized', async () => {
+    const fn = vi.fn().mockRejectedValue(new Error('HTTP 401 Unauthorized'));
+    const err = await run(() => withRetry(fn, { attempts: 4 }).catch((e) => e));
+    expect(err).toBeInstanceOf(StellarRetryExhaustedError);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('does NOT retry on AbortError', async () => {
+    const fn = vi.fn().mockRejectedValue(new DOMException('Aborted', 'AbortError'));
+    const err = await run(() => withRetry(fn, { attempts: 4 }).catch((e) => e));
+    expect(err).toBeInstanceOf(StellarRetryExhaustedError);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('does NOT retry on StellarRetryExhaustedError itself', async () => {
+    const fn = vi.fn().mockRejectedValue(new StellarRetryExhaustedError(new Error('inner')));
+    const err = await run(() => withRetry(fn, { attempts: 4 }).catch((e) => e));
+    expect(err).toBeInstanceOf(StellarRetryExhaustedError);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('respects AbortSignal — aborts before first attempt', async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const fn = vi.fn().mockResolvedValue('ok');
+    const err = await run(() => withRetry(fn, { signal: controller.signal }).catch((e) => e));
+    expect((err as DOMException).name).toBe('AbortError');
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('calls onRetry with attempt number and delay', async () => {
+    const onRetry = vi.fn();
+    const fn = vi
+      .fn()
+      .mockRejectedValueOnce(new TypeError('Failed to fetch'))
+      .mockResolvedValue('ok');
+    await run(() => withRetry(fn, { attempts: 4, onRetry }));
+    expect(onRetry).toHaveBeenCalledTimes(1);
+    expect(onRetry).toHaveBeenCalledWith(
+      expect.objectContaining({ attempt: 1, error: expect.any(TypeError) }),
+    );
+  });
+
+  it('uses default 4 attempts', async () => {
+    const fn = vi.fn().mockRejectedValue(new TypeError('net'));
+    const err = await run(() => withRetry(fn).catch((e) => e));
+    expect(err).toBeInstanceOf(StellarRetryExhaustedError);
+    expect(fn).toHaveBeenCalledTimes(4);
+  });
+});
diff --git a/src/lib/stellar/retry.ts b/src/lib/stellar/retry.ts
new file mode 100644
index 0000000..ece794f
--- /dev/null
+++ b/src/lib/stellar/retry.ts
@@ -0,0 +1,85 @@
+export class StellarRetryExhaustedError extends Error {
+  readonly cause: unknown;
+  constructor(cause: unknown) {
+    super('Network unstable — try again.');
+    this.name = 'StellarRetryExhaustedError';
+    this.cause = cause;
+  }
+}
+
+export type RetryEvent = { attempt: number; error: unknown; delayMs: number };
+export type OnRetry = (event: RetryEvent) => void;
+
+export interface RetryOptions {
+  attempts?: number;
+  signal?: AbortSignal;
+  onRetry?: OnRetry;
+}
+
+const RETRYABLE_STATUS = new Set([408, 429, 502, 503, 504]);
+
+function isRetryable(err: unknown): boolean {
+  if (err instanceof StellarRetryExhaustedError) return false;
+
+  // Aborted — respect the signal, don't retry
+  if (err instanceof DOMException && err.name === 'AbortError') return false;
+
+  // Network / fetch errors (TypeError: Failed to fetch, etc.)
+  if (err instanceof TypeError) return true;
+
+  if (err instanceof Error) {
+    // JSON parse errors (RPC returned HTML on overload)
+    if (err instanceof SyntaxError) return true;
+
+    // HTTP status errors — only retry specific codes
+    const match = err.message.match(/\b(\d{3})\b/);
+    if (match) {
+      const status = parseInt(match[1], 10);
+      // 4xx not in allowlist → don't retry
+      if (status >= 400 && status < 500 && !RETRYABLE_STATUS.has(status)) return false;
+      return RETRYABLE_STATUS.has(status);
+    }
+  }
+
+  return true;
+}
+
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const id = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(id);
+      reject(new DOMException('Aborted', 'AbortError'));
+    });
+  });
+}
+
+export async function withRetry<T>(
+  fn: (signal?: AbortSignal) => Promise<T>,
+  { attempts = 4, signal, onRetry }: RetryOptions = {},
+): Promise<T> {
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    if (signal?.aborted) throw new DOMException('Aborted', 'AbortError');
+
+    try {
+      return await fn(signal);
+    } catch (err) {
+      lastError = err;
+
+      if (!isRetryable(err) || attempt === attempts) break;
+
+      // Exponential backoff: 200, 400, 800, 1600 ms ±25%
+      const base = 200 * Math.pow(2, attempt - 1);
+      const jitter = base * 0.25 * (Math.random() * 2 - 1);
+      const delayMs = Math.round(base + jitter);
+
+      onRetry?.({ attempt, error: err, delayMs });
+
+      await delay(delayMs, signal);
+    }
+  }
+
+  throw new StellarRetryExhaustedError(lastError);
+}