From 5aec8c3a7778c7518091a054dbbd1dfb0b28039b Mon Sep 17 00:00:00 2001
From: pharwasz <biliaminufawas44@gmail.com>
Date: Sat, 17 Oct 2026 07:53:44 +0100
Subject: [PATCH] fix: add end-to-end submission idempotency (#213)

---
 docs/guides/offline-queue.md          |  34 ++-
 e2e/offline-queue.spec.ts             | 107 +++++++++
 src/components/OfflineQueuePanel.tsx  |  18 +-
 src/components/StellarSend.tsx        | 151 +++++++++++--
 src/lib/offlineQueue.test.ts          |  12 +
 src/lib/offlineQueue.ts               |  29 ++-
 src/lib/submissionIdempotency.test.ts | 145 ++++++++++++
 src/lib/submissionIdempotency.ts      | 307 ++++++++++++++++++++++++++
 src/stores/offlineQueueStore.ts       |  23 +-
 9 files changed, 781 insertions(+), 45 deletions(-)
 create mode 100644 src/lib/submissionIdempotency.test.ts
 create mode 100644 src/lib/submissionIdempotency.ts

diff --git a/docs/guides/offline-queue.md b/docs/guides/offline-queue.md
index ee2303a..a4f43b8 100644
--- a/docs/guides/offline-queue.md
+++ b/docs/guides/offline-queue.md
@@ -1,4 +1,4 @@
-# Offline queue and reconciliation policy (Wave 9, #184)
+# Offline queue, reconciliation, and submission idempotency (Wave 9, #184; Wave 10, #213)
 
 The PWA shell caches assets (see `src/sw/app-sw.ts`), but transaction and
 scanner work used to have no documented offline policy: a user who lost
@@ -8,6 +8,7 @@ This document is the policy. The implementation lives in:
 - `src/lib/offlineQueue.ts` — queue core: classification, validation, persistence
 - `src/lib/offlineReconcile.ts` — reconnect reconciliation engine
 - `src/stores/offlineQueueStore.ts` — persisted zustand store + explicit broadcast
+- `src/lib/submissionIdempotency.ts` — persistent operation IDs and serialized Stellar submission
 - `src/hooks/useOfflineReconcile.ts` — `online` / service-worker triggers
 - `src/components/OfflineQueuePanel.tsx` — review UI (Send page)
 - `src/components/OfflineBanner.tsx` — queue-aware connectivity banner
@@ -57,7 +58,26 @@ Captured at the source, while offline:
 The stealth-announcement scanner needs no queue: it resumes from the
 persisted `lastScannedLedger` checkpoint on every run.
 
-## 3. Reconcile on reconnect with clear conflict handling
+## 3. Reuse one operation ID for direct sends and queue retries
+
+Every Stellar payment intent receives an operation ID before it can be
+submitted. The ID travels with the queued intent and into the review URL.
+Before the first Horizon broadcast, the signed envelope and its transaction
+hash are persisted under `wraith-submission-idempotency-v1`. A retry after a
+reload or a lost response reuses that exact envelope; an operation ID cannot
+be rebound to a different transaction.
+
+Broadcasts use the browser Web Locks API and the persisted operation record
+to serialize same-operation submissions across tabs. If a response is lost,
+the explicit queue retry may submit the same envelope again, but it cannot
+create a different Stellar transaction: the signed envelope and transaction
+hash are unchanged, and the network deduplicates that transaction hash.
+Browsers without cross-tab locking support fail closed rather than claiming
+retry safety. A failed direct broadcast is saved as a signed queue entry when
+the queue has capacity, with the original operation ID, so queue replay shares
+the same idempotency record.
+
+## 4. Reconcile on reconnect with clear conflict handling
 
 Triggers (first one wins; reconciliation is a no-op while offline):
 
@@ -86,12 +106,16 @@ a resolution action (review pre-filled in Send, or discard). Terminal
 states (`done`, `conflict`, `failed`) are never re-processed; "Clear
 finished" removes them.
 
-## 4. Coverage
+## 5. Coverage
 
 - Unit: `src/lib/offlineQueue.test.ts` (classification, validation,
   persistence round-trip, dedupe, cap pruning) and
   `src/lib/offlineReconcile.test.ts` (intent/scan outcomes, stale
-  envelopes, attempt budget, offline no-op, throwing consumers).
+  envelopes, attempt budget, offline no-op, throwing consumers), plus
+  `src/lib/submissionIdempotency.test.ts` (stable operation IDs, concurrent
+  submissions, delayed retry, and transaction binding).
 - E2E: `e2e/offline-queue.spec.ts` (banner + queue count while offline,
   real offline send → queued intent, reconnect reconciliation incl.
-  expired-intent conflict, signed envelopes never auto-broadcast).
+  expired-intent conflict, signed envelopes never auto-broadcast,
+  concurrent cross-tab broadcast, and same-envelope retry after a lost
+  response).
diff --git a/e2e/offline-queue.spec.ts b/e2e/offline-queue.spec.ts
index 92719b6..68b7b81 100644
--- a/e2e/offline-queue.spec.ts
+++ b/e2e/offline-queue.spec.ts
@@ -137,6 +137,7 @@ test.describe('Offline queue and reconciliation', () => {
     // Reviewing prefills the Send form from the queued intent.
     await entry.getByRole('button', { name: 'Review in Send' }).click();
     await expect(page).toHaveURL(/to=/);
+    await expect(page).toHaveURL(/operationId=/);
   });
 
   test('expired intents conflict and signed envelopes never auto-broadcast', async ({
@@ -214,4 +215,110 @@ test.describe('Offline queue and reconciliation', () => {
     await panel.getByRole('button', { name: 'Clear finished' }).click();
     await expect(panel.getByTestId('offline-queue-entry')).toHaveCount(0);
   });
+
+  test('concurrent queue broadcasts in two tabs submit only once', async ({ page, context }) => {
+    let broadcastPosts = 0;
+    await context.route('https://horizon-testnet.stellar.org/transactions', async (route) => {
+      if (route.request().method() === 'POST') {
+        broadcastPosts += 1;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        await route.fulfill({
+          status: 200,
+          contentType: 'application/json',
+          body: JSON.stringify({ hash: 'shared_operation_hash', ledger: 101 }),
+        });
+      } else {
+        await route.continue();
+      }
+    });
+    await seedQueue(context, [
+      seedEntry({
+        id: 'shared-operation-id',
+        kind: 'signed-submit',
+        payload: {
+          chain: 'stellar',
+          operationId: 'shared-operation-id',
+          txHash: 'shared_operation_hash',
+          signedXdr: 'AAAA',
+        },
+      }),
+    ]);
+
+    const secondPage = await context.newPage();
+    await Promise.all([page.goto('/send'), secondPage.goto('/send')]);
+    const firstEntry = page.getByTestId('offline-queue-entry');
+    const secondEntry = secondPage.getByTestId('offline-queue-entry');
+    await expect(firstEntry.getByRole('button', { name: 'Broadcast now' })).toBeVisible();
+    await expect(secondEntry.getByRole('button', { name: 'Broadcast now' })).toBeVisible();
+
+    await Promise.all([
+      (async () => {
+        await firstEntry.getByRole('button', { name: 'Broadcast now' }).click();
+        await firstEntry.getByRole('button', { name: 'Confirm broadcast' }).click();
+      })(),
+      (async () => {
+        await secondEntry.getByRole('button', { name: 'Broadcast now' }).click();
+        await secondEntry.getByRole('button', { name: 'Confirm broadcast' }).click();
+      })(),
+    ]);
+
+    await expect(firstEntry).toContainText('Done');
+    await expect(secondEntry).toContainText('Done');
+    expect(broadcastPosts).toBe(1);
+    await secondPage.close();
+  });
+
+  test('delayed retry reuses the original signed envelope after a lost response', async ({
+    page,
+    context,
+  }) => {
+    const acceptedEnvelopes = new Set<string>();
+    const submittedEnvelopes: string[] = [];
+    await context.route('https://horizon-testnet.stellar.org/transactions', async (route) => {
+      if (route.request().method() !== 'POST') {
+        await route.continue();
+        return;
+      }
+      const body = route.request().postData() ?? '';
+      submittedEnvelopes.push(body);
+      const envelope = new URLSearchParams(body).get('tx') ?? '';
+      acceptedEnvelopes.add(envelope);
+      if (submittedEnvelopes.length === 1) {
+        // Simulate Horizon accepting the transaction while its response is lost.
+        await route.abort('failed');
+        return;
+      }
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ hash: 'delayed_retry_hash', ledger: 102 }),
+      });
+    });
+    await seedQueue(context, [
+      seedEntry({
+        id: 'delayed-operation-id',
+        kind: 'signed-submit',
+        payload: {
+          chain: 'stellar',
+          operationId: 'delayed-operation-id',
+          txHash: 'delayed_retry_hash',
+          signedXdr: 'AAAA',
+        },
+      }),
+    ]);
+    await page.goto('/send');
+
+    const entry = page.getByTestId('offline-queue-entry');
+    await expect(entry.getByRole('button', { name: 'Broadcast now' })).toBeVisible();
+    await entry.getByRole('button', { name: 'Broadcast now' }).click();
+    await entry.getByRole('button', { name: 'Confirm broadcast' }).click();
+    await expect(entry.getByText('Conflict')).toBeVisible();
+    await entry.getByRole('button', { name: 'Retry broadcast' }).click();
+    await entry.getByRole('button', { name: 'Confirm broadcast' }).click();
+
+    await expect(entry.getByText('Done')).toBeVisible();
+    expect(submittedEnvelopes).toHaveLength(2);
+    expect(submittedEnvelopes[0]).toBe(submittedEnvelopes[1]);
+    expect(acceptedEnvelopes.size).toBe(1);
+  });
 });
diff --git a/src/components/OfflineQueuePanel.tsx b/src/components/OfflineQueuePanel.tsx
index 1b3132f..eabb5d6 100644
--- a/src/components/OfflineQueuePanel.tsx
+++ b/src/components/OfflineQueuePanel.tsx
@@ -43,7 +43,10 @@ function intentLink(payload: PaymentIntentPayload): string | null {
   if (payload.chain !== 'stellar') return null;
   const params = new URLSearchParams({ to: payload.recipient });
   if (payload.amount) params.set('amount', payload.amount);
+  if (payload.asset) params.set('asset', payload.asset);
   if (payload.memo) params.set('memo', payload.memo);
+  if (payload.expiresAt != null) params.set('exp', String(Math.floor(payload.expiresAt / 1000)));
+  if (payload.operationId) params.set('operationId', payload.operationId);
   return `/send?${params.toString()}`;
 }
 
@@ -81,7 +84,10 @@ function EntryActions({ entry }: { entry: OfflineQueueEntry }) {
   }
 
   if (entry.kind === 'signed-submit') {
-    if (entry.status !== 'needs-review') {
+    const canBroadcast =
+      entry.status === 'needs-review' ||
+      (entry.status === 'conflict' && entry.conflictReason === 'broadcast-rejected');
+    if (!canBroadcast) {
       return (
         <button
           type="button"
@@ -111,7 +117,13 @@ function EntryActions({ entry }: { entry: OfflineQueueEntry }) {
           }}
           className="h-9 bg-primary px-3 font-heading text-[11px] font-semibold uppercase tracking-widest text-surface disabled:opacity-50"
         >
-          {busy ? 'Broadcasting…' : confirming ? 'Confirm broadcast' : 'Broadcast now'}
+          {busy
+            ? 'Broadcasting…'
+            : confirming
+              ? 'Confirm broadcast'
+              : entry.status === 'conflict'
+                ? 'Retry broadcast'
+                : 'Broadcast now'}
         </button>
         {!confirming && (
           <button
@@ -222,7 +234,7 @@ export function OfflineQueuePanel() {
               </div>
               <p className="mt-1 font-body text-xs text-on-surface-variant">
                 {entry.kind === 'signed-submit'
-                  ? 'Signed while offline — broadcast only happens here, with your confirmation.'
+                  ? 'Signed envelope — broadcast only happens after confirmation; retries reuse its operation ID.'
                   : entry.kind === 'payment-intent'
                     ? 'Unsigned intent — review and sign in Send after reconnect.'
                     : 'Scan captured offline.'}
diff --git a/src/components/StellarSend.tsx b/src/components/StellarSend.tsx
index dcda7d9..c34fb2f 100644
--- a/src/components/StellarSend.tsx
+++ b/src/components/StellarSend.tsx
@@ -39,6 +39,14 @@ import {
 } from '@/lib/stellarSimulation';
 import { useActivityStore } from '@/stores/activityStore';
 import { useOfflineQueueStore } from '@/stores/offlineQueueStore';
+import {
+  broadcastStellarTransaction,
+  getSubmissionRecord,
+  releaseSubmissionDraft,
+  reserveSubmissionOperationId,
+  submitStellarTransactionOnce,
+  TransactionSubmissionUnknownError,
+} from '@/lib/submissionIdempotency';
 import { ExpiringNamesBanner } from '@/components/ExpiringNamesBanner';
 import { decodeQrImage, isCameraUnavailableError, parseStellarQrPayload } from '@/utils/qr';
 
@@ -105,13 +113,16 @@ export function StellarSend() {
   const paramAmount = searchParams.get('amount');
   const paramMemo = searchParams.get('memo');
   const paramExp = searchParams.get('exp');
+  const paramAsset = searchParams.get('asset');
+  const paramOperationId = searchParams.get('operationId');
+  const initialAssetKey = STELLAR_ASSETS.find((asset) => asset.key === paramAsset)?.key ?? 'XLM';
 
   const { address, isConnected, signTransaction, isNetworkMismatch } = useStellarWallet();
   const addActivity = useActivityStore((state) => state.addEntry);
   const updateActivity = useActivityStore((state) => state.updateStatus);
   const [recipient, setRecipient] = useState(paramTo || '');
   const [amount, setAmount] = useState(paramAmount || '');
-  const [assetKey, setAssetKey] = useState<StellarAssetKey>('XLM');
+  const [assetKey, setAssetKey] = useState<StellarAssetKey>(initialAssetKey);
   const [allBalances, setAllBalances] = useState<Record<string, string>>({});
   const [memo, setMemo] = useState(paramMemo || '');
   const { isKnownAddress, addContact } = useContacts();
@@ -295,6 +306,8 @@ export function StellarSend() {
   } | null>(null);
   const [txHash, setTxHash] = useState<string | null>(null);
   const [isSuccess, setIsSuccess] = useState(false);
+  const operationIdOverrideRef = useRef<string | null>(paramOperationId);
+  const submissionDraftRef = useRef<{ draft: string; operationId: string } | null>(null);
   const simulationTimeoutRef = useRef<ReturnType<typeof globalThis.setTimeout> | null>(null);
 
   const [trustlineMissing, setTrustlineMissing] = useState(false);
@@ -575,7 +588,26 @@ export function StellarSend() {
         return;
       }
       const expSecs = paramExp ? parseInt(paramExp, 10) : NaN;
+      const draft = JSON.stringify({
+        chain: 'stellar',
+        wallet: address,
+        recipient: recipient.trim(),
+        amount: amount.trim(),
+        asset: assetKey,
+        memo: memo.trim(),
+      });
+      let operationId: string;
+      try {
+        operationId = await reserveSubmissionOperationId(draft, operationIdOverrideRef.current);
+        submissionDraftRef.current = { draft, operationId };
+      } catch (storageError) {
+        setError(
+          storageError instanceof Error ? storageError.message : 'Could not save operation ID.',
+        );
+        return;
+      }
       const queued = useOfflineQueueStore.getState().enqueuePaymentIntent({
+        operationId,
         chain: 'stellar',
         recipient: recipient.trim(),
         amount: amount.trim(),
@@ -604,10 +636,22 @@ export function StellarSend() {
     setIsPending(true);
     setRetryStatus('');
     let txHashHex = '';
+    let signedXdr = '';
+    let operationId = '';
+    const draft = JSON.stringify({
+      chain: 'stellar',
+      wallet: address,
+      recipient: recipient.trim(),
+      amount: amount.trim(),
+      asset: assetKey,
+      memo: memo.trim(),
+    });
 
     const onRetry = (attempt: number) => setRetryStatus(`Retrying (${attempt}/3)…`);
 
     try {
+      operationId = await reserveSubmissionOperationId(draft, operationIdOverrideRef.current);
+      submissionDraftRef.current = { draft, operationId };
       const metaAddress = recipient;
       if (!metaAddress.startsWith('st:xlm:')) {
         setError(t('stellar.validMetaAddressError'));
@@ -615,6 +659,44 @@ export function StellarSend() {
         return;
       }
 
+      const previousSubmission = getSubmissionRecord(operationId);
+      if (previousSubmission?.txHash && previousSubmission.signedEnvelope) {
+        txHashHex = previousSubmission.txHash;
+        signedXdr = previousSubmission.signedEnvelope;
+        const stealthAddress = previousSubmission.metadata?.stealthAddress;
+        if (typeof stealthAddress === 'string') {
+          setStealthResult({ stealthAddress, ephemeralPubKey: new Uint8Array(), viewTag: 0 });
+        }
+        setTxHash(txHashHex);
+        addActivity({
+          id: txHashHex,
+          chain: 'stellar',
+          wallet: address,
+          kind: 'stealth-send',
+          direction: 'out',
+          status: 'pending',
+          amount: amountValue,
+          recipient: metaAddress,
+          timestamp: Date.now(),
+        });
+        const submittedHash = await submitStellarTransactionOnce(
+          operationId,
+          txHashHex,
+          signedXdr,
+          () => broadcastStellarTransaction(signedXdr, txHashHex, STELLAR_NETWORK.horizonUrl),
+          previousSubmission.metadata,
+        );
+        setTxHash(submittedHash);
+        setIsSuccess(true);
+        updateActivity(txHashHex, 'confirmed');
+        try {
+          await releaseSubmissionDraft(draft, operationId);
+        } catch {
+          setError('Transaction submitted, but its retry state could not be cleared.');
+        }
+        return;
+      }
+
       const decoded = decodeStealthMetaAddress(metaAddress);
       const result = generateStealthAddress(decoded.spendingPubKey, decoded.viewingPubKey);
       setStealthResult(result);
@@ -680,7 +762,7 @@ export function StellarSend() {
 
       const classicTx = builder.build();
 
-      const signedXdr = await signTransaction(classicTx.toXDR());
+      signedXdr = await signTransaction(classicTx.toXDR());
       txHashHex = classicTx.hash().toString('hex');
       setTxHash(txHashHex);
 
@@ -696,22 +778,21 @@ export function StellarSend() {
         timestamp: Date.now(),
       });
 
-      const submitRes = await 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) {
-        throw new Error(
-          submitData.extras?.result_codes?.transaction ||
-            submitData.title ||
-            t('common.transactionFailed'),
-        );
-      }
+      const submittedHash = await submitStellarTransactionOnce(
+        operationId,
+        txHashHex,
+        signedXdr,
+        () => broadcastStellarTransaction(signedXdr, txHashHex, horizonUrl),
+        {
+          stealthAddress: result.stealthAddress,
+          ephemeralPubKey: Array.from(result.ephemeralPubKey, (byte) =>
+            byte.toString(16).padStart(2, '0'),
+          ).join(''),
+          viewTag: result.viewTag,
+        },
+      );
 
-      setTxHash(submitData.hash);
+      setTxHash(submittedHash);
 
       // Add recipient to history after successful send
       addToHistory(recipient);
@@ -770,16 +851,46 @@ export function StellarSend() {
 
       setIsSuccess(true);
       updateActivity(txHashHex, 'confirmed');
+      try {
+        await releaseSubmissionDraft(draft, operationId);
+      } catch {
+        setError('Transaction submitted, but its retry state could not be cleared.');
+      }
     } catch (err) {
       setRetryStatus('');
-      if (txHashHex) updateActivity(txHashHex, 'failed');
-      setError(err instanceof Error ? err.message : t('common.transactionFailed'));
+      if (txHashHex && !(err instanceof TransactionSubmissionUnknownError)) {
+        updateActivity(txHashHex, 'failed');
+      }
+      const message = err instanceof Error ? err.message : t('common.transactionFailed');
+      if (operationId && txHashHex && signedXdr) {
+        const queued = useOfflineQueueStore.getState().enqueueSignedSubmit({
+          operationId,
+          chain: 'stellar',
+          txHash: txHashHex,
+          signedXdr,
+        });
+        if (queued) {
+          void useOfflineQueueStore.getState().reconcile();
+        } else {
+          setError(
+            `${message} The retry envelope could not be added because the offline queue is full.`,
+          );
+          return;
+        }
+      }
+      setError(message);
     } finally {
       setIsPending(false);
     }
-  }, [address, recipient, amount, assetKey, signTransaction, t]);
+  }, [address, recipient, amount, assetKey, memo, signTransaction, t, paramExp]);
 
   const reset = () => {
+    const currentSubmission = submissionDraftRef.current;
+    if (currentSubmission) {
+      void releaseSubmissionDraft(currentSubmission.draft, currentSubmission.operationId);
+      submissionDraftRef.current = null;
+    }
+    operationIdOverrideRef.current = null;
     setRecipient(paramTo || '');
     setAmount(paramAmount || '');
     setMemo(paramMemo || '');
diff --git a/src/lib/offlineQueue.test.ts b/src/lib/offlineQueue.test.ts
index e7efb0f..f7bf80e 100644
--- a/src/lib/offlineQueue.test.ts
+++ b/src/lib/offlineQueue.test.ts
@@ -71,6 +71,18 @@ describe('createOfflineEntry', () => {
     expect(entry.attempts).toBe(0);
     expect(entry.id.length).toBeGreaterThan(0);
   });
+
+  it('keeps one operation ID on both payment intents and signed submissions', () => {
+    const intentEntry = createOfflineEntry('payment-intent', intent());
+    const signedEntry = createOfflineEntry('signed-submit', {
+      chain: 'stellar',
+      txHash: 'abc',
+      signedXdr: 'AAAA',
+    });
+
+    expect(intentEntry.payload).toMatchObject({ operationId: intentEntry.id });
+    expect(signedEntry.payload).toMatchObject({ operationId: signedEntry.id });
+  });
 });
 
 describe('isOfflineEntry', () => {
diff --git a/src/lib/offlineQueue.ts b/src/lib/offlineQueue.ts
index 0f6a1d7..e2ee022 100644
--- a/src/lib/offlineQueue.ts
+++ b/src/lib/offlineQueue.ts
@@ -83,6 +83,8 @@ const TERMINAL_STATUSES: OfflineEntryStatus[] = ['done', 'conflict', 'failed'];
 
 /** Unsigned intent to send; signing happens explicitly after reconnect. */
 export interface PaymentIntentPayload {
+  /** Stable operation ID carried from offline capture through submission. */
+  operationId?: string;
   chain: string;
   recipient: string;
   amount: string;
@@ -112,6 +114,8 @@ export interface ScanSessionPayload {
  * never broadcasts or re-signs on its own.
  */
 export interface SignedSubmitPayload {
+  /** Same operation ID used by the original direct submission, when present. */
+  operationId?: string;
   chain: string;
   /** Hex transaction hash (also used for dedupe). */
   txHash: string;
@@ -183,8 +187,13 @@ export function createOfflineEntry(
   payload: OfflineEntryPayload,
   now: number = Date.now(),
 ): OfflineQueueEntry {
+  const id = createId();
+  const operationId =
+    kind === 'payment-intent' || kind === 'signed-submit'
+      ? (payload as PaymentIntentPayload | SignedSubmitPayload).operationId || id
+      : undefined;
   return {
-    id: createId(),
+    id,
     kind,
     policy: classifyOfflineWork(kind),
     status: 'queued',
@@ -192,7 +201,10 @@ export function createOfflineEntry(
     updatedAt: now,
     attempts: 0,
     maxAttempts: MAX_RECONCILE_ATTEMPTS,
-    payload,
+    payload:
+      operationId && (kind === 'payment-intent' || kind === 'signed-submit')
+        ? { ...payload, operationId }
+        : payload,
   };
 }
 
@@ -206,6 +218,7 @@ function isValidPayload(kind: OfflineWorkKind, payload: unknown): boolean {
     const p = payload as Record<string, unknown>;
     return (
       isBoundedString(p['chain'], 32) &&
+      (p['operationId'] === undefined || isBoundedString(p['operationId'], 128)) &&
       isBoundedString(p['recipient'], 512) &&
       isBoundedString(p['amount'], 64) &&
       (p['asset'] === undefined || isBoundedString(p['asset'], 32)) &&
@@ -241,6 +254,7 @@ function isValidPayload(kind: OfflineWorkKind, payload: unknown): boolean {
   const p = payload as Record<string, unknown>;
   return (
     isBoundedString(p['chain'], 32) &&
+    (p['operationId'] === undefined || isBoundedString(p['operationId'], 128)) &&
     isBoundedString(p['txHash'], 128) &&
     isBoundedString(p['signedXdr'], 20000)
   );
@@ -335,6 +349,17 @@ function oldestTerminalIds(entries: OfflineQueueEntry[], count: number): Set<str
  */
 export function addEntry(entries: OfflineQueueEntry[], entry: OfflineQueueEntry): AddEntryResult {
   if (entries.some((e) => e.id === entry.id)) return { entries, accepted: true, evicted: 0 };
+  if (
+    (entry.kind === 'payment-intent' || entry.kind === 'signed-submit') &&
+    entries.some(
+      (e) =>
+        e.kind === entry.kind &&
+        (e.payload as PaymentIntentPayload | SignedSubmitPayload).operationId ===
+          (entry.payload as PaymentIntentPayload | SignedSubmitPayload).operationId,
+    )
+  ) {
+    return { entries, accepted: true, evicted: 0 };
+  }
   if (
     entry.kind === 'signed-submit' &&
     entries.some(
diff --git a/src/lib/submissionIdempotency.test.ts b/src/lib/submissionIdempotency.test.ts
new file mode 100644
index 0000000..3fec3dd
--- /dev/null
+++ b/src/lib/submissionIdempotency.test.ts
@@ -0,0 +1,145 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  getSubmissionRecord,
+  reserveSubmissionOperationId,
+  submitStellarTransactionOnce,
+} from './submissionIdempotency';
+
+class MemoryStorage implements Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> {
+  private values = new Map<string, string>();
+
+  getItem(key: string) {
+    return this.values.get(key) ?? null;
+  }
+
+  setItem(key: string, value: string) {
+    this.values.set(key, value);
+  }
+
+  removeItem(key: string) {
+    this.values.delete(key);
+  }
+}
+
+const previousStorage = globalThis.localStorage;
+
+afterEach(() => {
+  if (previousStorage === undefined) {
+    Reflect.deleteProperty(globalThis, 'localStorage');
+  } else {
+    Object.defineProperty(globalThis, 'localStorage', {
+      configurable: true,
+      value: previousStorage,
+    });
+  }
+});
+
+function useMemoryStorage() {
+  Object.defineProperty(globalThis, 'localStorage', {
+    configurable: true,
+    value: new MemoryStorage(),
+  });
+}
+
+describe('Stellar submission idempotency', () => {
+  it('reuses a reserved operation ID after state is reloaded', async () => {
+    useMemoryStorage();
+    const draft = JSON.stringify({ wallet: 'GABC', recipient: 'st:xlm:meta', amount: '2' });
+    const first = await reserveSubmissionOperationId(draft);
+    const afterReload = await reserveSubmissionOperationId(draft);
+
+    expect(afterReload).toBe(first);
+    expect(getSubmissionRecord(first)).toMatchObject({
+      operationId: first,
+      status: 'prepared',
+    });
+  });
+
+  it('assigns a new operation ID when a queued intent is deliberately edited', async () => {
+    useMemoryStorage();
+    const originalOperationId = await reserveSubmissionOperationId('original send', 'queued-id');
+    const editedOperationId = await reserveSubmissionOperationId(
+      'edited send',
+      originalOperationId,
+    );
+
+    expect(editedOperationId).not.toBe(originalOperationId);
+    await expect(reserveSubmissionOperationId('edited send', originalOperationId)).resolves.toBe(
+      editedOperationId,
+    );
+  });
+
+  it('preserves records for independent drafts in the shared persistent store', async () => {
+    useMemoryStorage();
+    const [first, second] = await Promise.all([
+      reserveSubmissionOperationId('first draft'),
+      reserveSubmissionOperationId('second draft'),
+    ]);
+
+    expect(getSubmissionRecord(first)).toMatchObject({ operationId: first });
+    expect(getSubmissionRecord(second)).toMatchObject({ operationId: second });
+  });
+
+  it('serializes concurrent sends and returns the original result to delayed retries', async () => {
+    useMemoryStorage();
+    const operationId = await reserveSubmissionOperationId('same send');
+    let resolveSubmit!: (hash: string) => void;
+    const submit = vi.fn(
+      () =>
+        new Promise<string>((resolve) => {
+          resolveSubmit = resolve;
+        }),
+    );
+    const firstAttempt = submitStellarTransactionOnce(
+      operationId,
+      'tx-1',
+      'signed-envelope-1',
+      submit,
+    );
+    const delayedRetry = submitStellarTransactionOnce(
+      operationId,
+      'tx-1',
+      'signed-envelope-1',
+      submit,
+    );
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(submit).toHaveBeenCalledTimes(1);
+    resolveSubmit('tx-1');
+    await expect(Promise.all([firstAttempt, delayedRetry])).resolves.toEqual(['tx-1', 'tx-1']);
+
+    await expect(
+      submitStellarTransactionOnce(operationId, 'tx-1', 'signed-envelope-1', submit),
+    ).resolves.toBe('tx-1');
+    expect(submit).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries an uncertain request only with the same envelope and blocks changed transactions', async () => {
+    useMemoryStorage();
+    const operationId = await reserveSubmissionOperationId('retry after timeout');
+    const firstSubmission = vi.fn(async () => {
+      throw new TypeError('response timed out');
+    });
+
+    await expect(
+      submitStellarTransactionOnce(operationId, 'tx-2', 'signed-envelope-2', firstSubmission),
+    ).rejects.toThrow('response timed out');
+    expect(getSubmissionRecord(operationId)).toMatchObject({
+      status: 'submitting',
+      txHash: 'tx-2',
+      signedEnvelope: 'signed-envelope-2',
+    });
+
+    const retry = vi.fn(async () => 'tx-2');
+    await expect(
+      submitStellarTransactionOnce(operationId, 'tx-2', 'signed-envelope-2', retry),
+    ).resolves.toBe('tx-2');
+    expect(retry).toHaveBeenCalledOnce();
+
+    const changedTransaction = vi.fn(async () => 'tx-3');
+    await expect(
+      submitStellarTransactionOnce(operationId, 'tx-3', 'signed-envelope-3', changedTransaction),
+    ).rejects.toThrow('already bound to a different signed transaction');
+    expect(changedTransaction).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/lib/submissionIdempotency.ts b/src/lib/submissionIdempotency.ts
new file mode 100644
index 0000000..2426701
--- /dev/null
+++ b/src/lib/submissionIdempotency.ts
@@ -0,0 +1,307 @@
+const STORAGE_KEY = 'wraith-submission-idempotency-v1';
+
+export interface SubmissionRecord {
+  operationId: string;
+  draftKey: string;
+  status: 'prepared' | 'submitting' | 'submitted';
+  txHash?: string;
+  signedEnvelope?: string;
+  metadata?: Record<string, string | number>;
+}
+
+export class TransactionSubmissionUnknownError extends Error {
+  constructor() {
+    super('The transaction response was lost; retrying will reuse the same signed transaction.');
+    this.name = 'TransactionSubmissionUnknownError';
+  }
+}
+
+interface SubmissionState {
+  version: 1;
+  operations: Record<string, SubmissionRecord>;
+  drafts: Record<string, string>;
+}
+
+const localLocks = new Map<string, Promise<void>>();
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function ownValue<T>(record: Record<string, T>, key: string): T | undefined {
+  return Object.prototype.hasOwnProperty.call(record, key) ? record[key] : undefined;
+}
+
+function isValidOperationId(value: string): boolean {
+  return (
+    /^[A-Za-z0-9_-]{1,128}$/.test(value) &&
+    value !== '__proto__' &&
+    value !== 'constructor' &&
+    value !== 'prototype'
+  );
+}
+
+function storage(): Storage {
+  if (typeof localStorage === 'undefined') {
+    throw new Error('Persistent storage is required for safe transaction submission.');
+  }
+  return localStorage;
+}
+
+function readState(): SubmissionState {
+  const value = storage().getItem(STORAGE_KEY);
+  if (value === null) return { version: 1, operations: {}, drafts: {} };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error('Saved transaction submission state is invalid; clear it before retrying.');
+  }
+  if (
+    !isRecord(parsed) ||
+    !('version' in parsed) ||
+    parsed.version !== 1 ||
+    !('operations' in parsed) ||
+    !isRecord(parsed.operations) ||
+    !('drafts' in parsed) ||
+    !isRecord(parsed.drafts)
+  ) {
+    throw new Error('Saved transaction submission state is invalid; clear it before retrying.');
+  }
+  const operations: Record<string, SubmissionRecord> = {};
+  for (const [operationId, record] of Object.entries(parsed.operations)) {
+    if (
+      !isValidOperationId(operationId) ||
+      !isSubmissionRecord(record) ||
+      record.operationId !== operationId
+    ) {
+      throw new Error('Saved transaction submission state is invalid; clear it before retrying.');
+    }
+    operations[operationId] = record;
+  }
+  const drafts: Record<string, string> = {};
+  for (const [draftKey, operationId] of Object.entries(parsed.drafts)) {
+    if (
+      !/^[a-f0-9]{64}$/.test(draftKey) ||
+      typeof operationId !== 'string' ||
+      !isValidOperationId(operationId)
+    ) {
+      throw new Error('Saved transaction submission state is invalid; clear it before retrying.');
+    }
+    drafts[draftKey] = operationId;
+  }
+  return { version: 1, operations, drafts };
+}
+
+function writeState(state: SubmissionState): void {
+  storage().setItem(STORAGE_KEY, JSON.stringify(state));
+}
+
+async function withLock<T>(name: string, action: () => Promise<T> | T): Promise<T> {
+  if (typeof navigator !== 'undefined' && navigator.locks) {
+    return navigator.locks.request(`wraith-submission:${name}`, { mode: 'exclusive' }, action);
+  }
+  if (typeof window !== 'undefined') {
+    throw new Error('This browser cannot safely coordinate transaction retries across tabs.');
+  }
+
+  const previous = localLocks.get(name) ?? Promise.resolve();
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const tail = previous.then(() => gate);
+  localLocks.set(name, tail);
+  await previous;
+  try {
+    return await action();
+  } finally {
+    release();
+    if (localLocks.get(name) === tail) localLocks.delete(name);
+  }
+}
+
+function makeOperationId(): string {
+  if (globalThis.crypto?.randomUUID) return globalThis.crypto.randomUUID();
+  return `submission-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+async function hashDraft(draft: string): Promise<string> {
+  if (!globalThis.crypto?.subtle) {
+    throw new Error('This browser cannot safely persist a transaction operation ID.');
+  }
+  const bytes = new TextEncoder().encode(draft);
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+function isSubmissionRecord(value: unknown): value is SubmissionRecord {
+  if (!isRecord(value)) return false;
+  const record = value as Partial<SubmissionRecord>;
+  return (
+    typeof record.operationId === 'string' &&
+    typeof record.draftKey === 'string' &&
+    (record.status === 'prepared' ||
+      record.status === 'submitting' ||
+      record.status === 'submitted') &&
+    (record.txHash === undefined || typeof record.txHash === 'string') &&
+    (record.signedEnvelope === undefined || typeof record.signedEnvelope === 'string')
+  );
+}
+
+export async function reserveSubmissionOperationId(
+  draft: string,
+  preferredOperationId?: string | null,
+): Promise<string> {
+  const draftKey = await hashDraft(draft);
+  return withLock(`draft:${draftKey}`, () =>
+    withLock('state', () => {
+      const state = readState();
+      const mappedOperationId = ownValue(state.drafts, draftKey);
+      const mappedRecord = mappedOperationId
+        ? ownValue(state.operations, mappedOperationId)
+        : undefined;
+      const preferredRecord = preferredOperationId
+        ? ownValue(state.operations, preferredOperationId)
+        : undefined;
+      if (
+        (mappedRecord !== undefined && !isSubmissionRecord(mappedRecord)) ||
+        (preferredRecord !== undefined && !isSubmissionRecord(preferredRecord))
+      ) {
+        throw new Error('Saved transaction submission state is invalid; clear it before retrying.');
+      }
+      let operationId = makeOperationId();
+      if (mappedOperationId && mappedRecord && mappedRecord.draftKey === draftKey) {
+        operationId = mappedOperationId;
+      } else if (
+        preferredOperationId &&
+        (!preferredRecord || preferredRecord.draftKey === draftKey)
+      ) {
+        operationId = preferredOperationId;
+      }
+      if (!isValidOperationId(operationId)) {
+        throw new Error('The transaction operation ID is invalid.');
+      }
+      state.drafts[draftKey] = operationId;
+      const existing = ownValue(state.operations, operationId);
+      if (existing && !isSubmissionRecord(existing)) {
+        throw new Error('Saved transaction submission state is invalid; clear it before retrying.');
+      }
+      state.operations[operationId] ??= {
+        operationId,
+        draftKey,
+        status: 'prepared',
+      };
+      writeState(state);
+      return operationId;
+    }),
+  );
+}
+
+export function getSubmissionRecord(operationId: string): SubmissionRecord | null {
+  const value = ownValue(readState().operations, operationId);
+  if (value === undefined) return null;
+  if (!isSubmissionRecord(value)) {
+    throw new Error('Saved transaction submission state is invalid; clear it before retrying.');
+  }
+  return value;
+}
+
+export async function releaseSubmissionDraft(draft: string, operationId: string): Promise<void> {
+  const draftKey = await hashDraft(draft);
+  await withLock(`draft:${draftKey}`, () =>
+    withLock('state', () => {
+      const state = readState();
+      if (ownValue(state.drafts, draftKey) === operationId) {
+        delete state.drafts[draftKey];
+        writeState(state);
+      }
+    }),
+  );
+}
+
+export async function submitStellarTransactionOnce(
+  operationId: string,
+  txHash: string,
+  signedEnvelope: string,
+  submit: () => Promise<string>,
+  metadata?: Record<string, string | number>,
+): Promise<string> {
+  return withLock(`operation:${operationId}`, async () => {
+    const start = await withLock('state', () => {
+      const state = readState();
+      if (!isValidOperationId(operationId)) {
+        throw new Error('The transaction operation ID is invalid.');
+      }
+      const existing = ownValue(state.operations, operationId);
+      if (existing !== undefined && !isSubmissionRecord(existing)) {
+        throw new Error('Saved transaction submission state is invalid; clear it before retrying.');
+      }
+      if (
+        existing?.txHash &&
+        (existing.txHash !== txHash || existing.signedEnvelope !== signedEnvelope)
+      ) {
+        throw new Error('This operation ID is already bound to a different signed transaction.');
+      }
+      if (existing?.status === 'submitted' && existing.txHash) {
+        return { alreadySubmitted: true as const, hash: existing.txHash };
+      }
+
+      const record: SubmissionRecord = {
+        operationId,
+        draftKey: existing?.draftKey ?? '',
+        status: 'submitting',
+        txHash,
+        signedEnvelope,
+        ...((metadata ?? existing?.metadata) ? { metadata: metadata ?? existing?.metadata } : {}),
+      };
+      state.operations[operationId] = record;
+      writeState(state);
+      return { alreadySubmitted: false as const, record };
+    });
+    if (start.alreadySubmitted) return start.hash;
+
+    const submittedHash = await submit();
+    await withLock('state', () => {
+      const state = readState();
+      state.operations[operationId] = {
+        ...start.record,
+        status: 'submitted',
+        txHash: submittedHash || txHash,
+      };
+      writeState(state);
+    });
+    return submittedHash || txHash;
+  });
+}
+
+export async function broadcastStellarTransaction(
+  signedEnvelope: string,
+  fallbackHash: string,
+  horizonUrl: string,
+): Promise<string> {
+  let response: Response;
+  let data: {
+    hash?: string;
+    title?: string;
+    extras?: { result_codes?: { transaction?: string } };
+  };
+  try {
+    response = await fetch(`${horizonUrl}/transactions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: `tx=${encodeURIComponent(signedEnvelope)}`,
+    });
+    data = (await response.json()) as typeof data;
+  } catch {
+    throw new TransactionSubmissionUnknownError();
+  }
+  if (response.status >= 500 || response.status === 429) {
+    throw new TransactionSubmissionUnknownError();
+  }
+  if (!response.ok) {
+    throw new Error(data.extras?.result_codes?.transaction || data.title || 'Broadcast failed.');
+  }
+  return data.hash ?? fallbackHash;
+}
diff --git a/src/stores/offlineQueueStore.ts b/src/stores/offlineQueueStore.ts
index 31c7500..5b79e16 100644
--- a/src/stores/offlineQueueStore.ts
+++ b/src/stores/offlineQueueStore.ts
@@ -16,6 +16,10 @@ import {
 import { defaultReconcileHandlers, reconcileOfflineQueue } from '@/lib/offlineReconcile';
 import { STELLAR_NETWORK } from '@/config';
 import { useActivityStore } from './activityStore';
+import {
+  broadcastStellarTransaction,
+  submitStellarTransactionOnce,
+} from '@/lib/submissionIdempotency';
 
 export type ReconcilePhase = 'idle' | 'reconciling';
 
@@ -177,21 +181,10 @@ export const useOfflineQueueStore = create<OfflineQueueState>()((set, get) => ({
       return { ok: false, error: `Chain ${payload.chain} is not supported yet.` };
     }
     try {
-      const res = await fetch(`${STELLAR_NETWORK.horizonUrl}/transactions`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: `tx=${encodeURIComponent(payload.signedXdr)}`,
-      });
-      const data = (await res.json()) as {
-        hash?: string;
-        title?: string;
-        extras?: { result_codes?: { transaction?: string } };
-      };
-      if (!res.ok) {
-        throw new Error(
-          data.extras?.result_codes?.transaction || data.title || 'Broadcast failed.',
-        );
-      }
+      const operationId = payload.operationId ?? entry.id;
+      await submitStellarTransactionOnce(operationId, payload.txHash, payload.signedXdr, () =>
+        broadcastStellarTransaction(payload.signedXdr, payload.txHash, STELLAR_NETWORK.horizonUrl),
+      );
       const done = get().entries.map((e) =>
         e.id === id ? { ...e, status: 'done' as const, updatedAt: Date.now() } : e,
       );