feat: backfill quote status manager entries after app close (#9405)

GeorgeGkas · web-flow · commit 75ac83b4b6fb · 2026-07-07T19:32:22.000Z
## Explanation The `QuoteStatusManager` keeps the bridge-api backend in sync with the outcome of every submitted quote by reporting `SUBMITTED` and later `FINALISED`. It does this through a persisted store of deferred "quote-status entries" keyed by the composite `${quoteId}:${srcTxHash}`. On startup, `QuoteStatusManager.init()` walks **only the entries that already exist in that store** and reconciles each one against the current transaction status. The problem is that a deferred entry is only ever created when `reportSubmitted` runs. If the client closes *after* a swap/bridge source transaction has been broadcast but *before* `reportSubmitted` executes (or before its entry was persisted), no entry is written. On the next launch `init()` has nothing to reconcile for that quote, so its terminal status is **never reported to the backend**, a permanently lost update. Smart-transaction (STX) swaps that confirm while the client is closed are a notable trigger, because the history item's status hash was never written. The key realization is that the persisted transaction history already carries everything needed to rebuild a lost entry. On each `BridgeHistoryItem` we persist the `quoteId`, the source tx hash (`status.srcChain.txHash`, with the underlying transaction's `hash` as a fallback), and the `txMetaId`. Those are exactly the identity fields of a quote-status entry (`quoteId:srcTxHash` + `txMetaId`). **`quoteId` + source-tx-hash therefore behave like a foreign key from a history row into the quote-status store**, which lets us treat history as the source of truth and losslessly reconstruct any missing entry: ```mermaid erDiagram TX_HISTORY_ITEM ||--o| QUOTE_STATUS_ENTRY : "quoteId + srcTxHash (composite FK)" TX_HISTORY_ITEM { string txMetaId PK "key in state.txHistory; also correlates finalisation" string quoteId FK "part of composite FK" string status_srcChain_txHash FK "srcTxHash; part of composite FK (falls back to txMeta.hash)" string reportedSubmittedTxHash "guard: prevents duplicate reportSubmitted" number startTime "compared against entry TTL" } QUOTE_STATUS_ENTRY { string entryKey PK "hash() => `quoteId:srcTxHash` virtual column, does not exist" string quoteId string srcTxHash string txMetaId "used by reportFinalised()" QuoteStatusState status number createdAt number lastAttemptAt } ``` The solution adds `#seedQuoteStatusEntriesFromHistory()`, invoked once immediately **before** `this.#quoteStatusManager.init()` in the constructor. It iterates persisted `txHistory` and, for each item that has both a `quoteId` and a `txMetaId` and is within the entry TTL, derives the `srcTxHash` and replays submission through the existing idempotent `#reportSubmittedOnce` helper. That rebuilds the missing deferred entry, and the subsequent `init()` reconciliation loop finalizes it exactly as it would in the normal (client-stayed-open) flow. Why this is robust: - **Idempotent by construction.** `#reportSubmittedOnce` short-circuits when `historyItem.reportedSubmittedTxHash === srcTxHash`, and `QuoteStatusManager.reportSubmitted` additionally ignores quotes it is already tracking. Re-seeding on every startup can never double-report or resurrect a completed quote. - **TTL-bounded.** Items older than `QUOTE_STATUS_UPDATE_ENTRY_TTL` are skipped, because the backend would reject them anyway. This bounds the amount of work at startup and avoids pointless network requests. - **No new source of truth.** Entries are derived from data we already persist on the history item, so the backfill introduces no new state to keep consistent, history remains authoritative and the store is a rebuildable projection of it. - **STX-safe fallback.** When the history status hash was never written (STX swaps confirmed while closed), it falls back to the transaction meta's `hash` via `getTransactionMetaById`, so those cases are covered too. - **Disabled-safe & correctly ordered.** The whole path is gated behind the manager's `isEnabled` check, and seeding runs before `init()` so the reconciliation loop always sees the freshly seeded entries. Changes whose purpose may not be obvious to those unfamiliar with the domain: the `startTime` TTL comparison and the `status.srcChain.txHash ?? txMeta.hash` fallback both exist purely to mirror backend acceptance rules and the STX edge case, not to change the reporting semantics. ## References https://consensyssoftware.atlassian.net/browse/SWAPS-4704 ## Checklist - [x] I've updated the test suite for new or updated code as appropriate (272 lines of new coverage in `bridge-status-controller.test.ts`). - [x] I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate (JSDoc on `#seedQuoteStatusEntriesFromHistory`, plus a `CHANGELOG.md` entry). - [x] I've communicated my changes to consumers by updating changelogs for packages I've changed. - [ ] I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them. _(N/A — additive, non-breaking startup behavior.)_  --- > [!NOTE] > **Medium Risk** > Changes startup reconciliation and backend quote-status reporting, plus shortens how long failed updates are retried; behavior is idempotent and feature-gated but affects swap/bridge observability. > > **Overview** > **On startup, missing quote-status store entries are rebuilt from persisted bridge transaction history** so quotes submitted before the client closed still get `SUBMITTED` / final status reported to the backend. > > Before `QuoteStatusManager.init()`, `#seedQuoteStatusEntriesFromHistory()` walks recent `txHistory` items and replays the existing idempotent `#reportSubmittedOnce` path using `quoteId`, `txMetaId`, and source hash (`status.srcChain.txHash` or transaction meta `hash`). Items outside a new **12h** `QUOTE_STATUS_BACKFILL_WINDOW_MS`, or without required fields, are skipped; seeding is a no-op when the quote-status manager is disabled (so `reportedSubmittedTxHash` is not set incorrectly). > > **TTL tuning:** per-entry local retry lifetime `QUOTE_STATUS_UPDATE_ENTRY_TTL` is shortened from **12h to 3h**, while the separate backfill window stays at 12h so multi-session in-flight bridges can still be resumed. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit def1682. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>
diff --git a/packages/bridge-status-controller/CHANGELOG.md b/packages/bridge-status-controller/CHANGELOG.md
@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Source transaction status from the `/getQuoteStatus` backend during polling for history items with an associated `quoteId`, falling back to the `/getTxStatus` bridge-api endpoint when no quote-status backend status is available yet or the QuoteStatusManager is disabled. ([#9389](https://github.com/MetaMask/core/pull/9389))
+- Seed missing quote-status entries from persisted transaction history on startup, so quotes submitted before the client closed still get their status reported to the backend. Entries are rebuilt from the history item's `quoteId`, source transaction hash (falling back to the transaction's hash), and `txMetaId`; history items older than the quote-status entry TTL are skipped. ([#9405](https://github.com/MetaMask/core/pull/9405))
 
 ### Changed
 
diff --git a/packages/bridge-status-controller/src/bridge-status-controller.test.ts b/packages/bridge-status-controller/src/bridge-status-controller.test.ts
@@ -50,6 +50,7 @@ import {
   DEFAULT_MAX_PENDING_HISTORY_ITEM_AGE_MS,
   MAX_ATTEMPTS,
 } from './constants';
+import { QUOTE_STATUS_BACKFILL_WINDOW_MS } from './quote-status-manager/constants';
 import { BridgeClientId } from './types';
 import type {
   BridgeId,
@@ -6806,6 +6807,285 @@ describe('BridgeStatusController', () => {
     });
   });
 
+  describe('seeding quote status entries from history on startup', () => {
+    let fetchSpy: jest.SpyInstance;
+
+    beforeEach(() => {
+      jest.useFakeTimers();
+      // Keep the quote-status update request in-flight so the manager never
+      // resolves and mutates state after the assertions/teardown.
+      fetchSpy = jest
+        .spyOn(globalThis, 'fetch')
+        .mockReturnValue(new Promise(() => undefined));
+    });
+
+    afterEach(() => {
+      fetchSpy.mockRestore();
+      jest.clearAllTimers();
+      jest.useRealTimers();
+    });
+
+    const getSeedMessengerCall = (transactions: TransactionMeta[] = []) =>
+      jest.fn((...args: unknown[]) => {
+        const actionType = args[0] as string;
+        if (actionType === 'TransactionController:getState') {
+          return { transactions };
+        }
+        if (actionType === 'AuthenticationController:getBearerToken') {
+          return Promise.resolve('auth-token');
+        }
+        return undefined;
+      });
+
+    const getSeedHistoryItem = ({
+      txMetaId,
+      quoteId,
+      srcTxHash,
+      startTime,
+      reportedSubmittedTxHash,
+    }: {
+      txMetaId: string;
+      quoteId?: string;
+      srcTxHash?: string;
+      startTime: number;
+      reportedSubmittedTxHash?: string;
+    }): BridgeHistoryItem => ({
+      ...MockTxHistory.getPending({
+        txMetaId,
+        srcTxHash: srcTxHash ?? 'undefined',
+        startTime,
+      })[txMetaId],
+      quoteId,
+      ...(reportedSubmittedTxHash ? { reportedSubmittedTxHash } : {}),
+    });
+
+    it('seeds a missing quote status entry from a recent history item', async () => {
+      await withController(
+        {
+          options: {
+            isQuoteStatusManagerEnabled: () => true,
+            state: {
+              txHistory: {
+                seedTx1: getSeedHistoryItem({
+                  txMetaId: 'seedTx1',
+                  quoteId: 'seed-quote-1',
+                  srcTxHash: '0xseedHash1',
+                  startTime: Date.now(),
+                }),
+              },
+            },
+          },
+          mockMessengerCall: getSeedMessengerCall(),
+        },
+        async ({ controller }) => {
+          expect(
+            controller.state.txHistory.seedTx1.reportedSubmittedTxHash,
+          ).toBe('0xseedHash1');
+          expect(
+            Object.keys(controller.state.quoteUpdateStatusStore),
+          ).toStrictEqual(['seed-quote-1:0xseedHash1']);
+
+          controller.resetState();
+        },
+      );
+    });
+
+    it('falls back to the transaction hash when the history item has no source hash', async () => {
+      const txMeta = {
+        id: 'seedTx2',
+        hash: '0xfallbackHash2',
+        status: TransactionStatus.submitted,
+        type: TransactionType.bridge,
+        chainId: numberToHex(42161),
+        txParams: {} as unknown as TransactionParams,
+      } as unknown as TransactionMeta;
+
+      await withController(
+        {
+          options: {
+            isQuoteStatusManagerEnabled: () => true,
+            state: {
+              txHistory: {
+                seedTx2: getSeedHistoryItem({
+                  txMetaId: 'seedTx2',
+                  quoteId: 'seed-quote-2',
+                  srcTxHash: 'undefined',
+                  startTime: Date.now(),
+                }),
+              },
+            },
+          },
+          mockMessengerCall: getSeedMessengerCall([txMeta]),
+        },
+        async ({ controller }) => {
+          expect(
+            Object.keys(controller.state.quoteUpdateStatusStore),
+          ).toStrictEqual(['seed-quote-2:0xfallbackHash2']);
+
+          controller.resetState();
+        },
+      );
+    });
+
+    it('skips history items older than the backfill window', async () => {
+      await withController(
+        {
+          options: {
+            isQuoteStatusManagerEnabled: () => true,
+            state: {
+              txHistory: {
+                seedTx3: getSeedHistoryItem({
+                  txMetaId: 'seedTx3',
+                  quoteId: 'seed-quote-3',
+                  srcTxHash: '0xseedHash3',
+                  startTime:
+                    Date.now() - QUOTE_STATUS_BACKFILL_WINDOW_MS - 1000,
+                }),
+              },
+            },
+          },
+          mockMessengerCall: getSeedMessengerCall(),
+        },
+        async ({ controller }) => {
+          expect(controller.state.quoteUpdateStatusStore).toStrictEqual({});
+          expect(
+            controller.state.txHistory.seedTx3.reportedSubmittedTxHash,
+          ).toBeUndefined();
+        },
+      );
+    });
+
+    it('skips history items without a quoteId', async () => {
+      await withController(
+        {
+          options: {
+            isQuoteStatusManagerEnabled: () => true,
+            state: {
+              txHistory: {
+                seedTx4: getSeedHistoryItem({
+                  txMetaId: 'seedTx4',
+                  srcTxHash: '0xseedHash4',
+                  startTime: Date.now(),
+                }),
+              },
+            },
+          },
+          mockMessengerCall: getSeedMessengerCall(),
+        },
+        async ({ controller }) => {
+          expect(controller.state.quoteUpdateStatusStore).toStrictEqual({});
+        },
+      );
+    });
+
+    it('skips history items without a txMetaId', async () => {
+      await withController(
+        {
+          options: {
+            isQuoteStatusManagerEnabled: () => true,
+            state: {
+              txHistory: {
+                seedTx5: {
+                  ...getSeedHistoryItem({
+                    txMetaId: 'seedTx5',
+                    quoteId: 'seed-quote-5',
+                    srcTxHash: '0xseedHash5',
+                    startTime: Date.now(),
+                  }),
+                  txMetaId: undefined,
+                },
+              },
+            },
+          },
+          mockMessengerCall: getSeedMessengerCall(),
+        },
+        async ({ controller }) => {
+          expect(controller.state.quoteUpdateStatusStore).toStrictEqual({});
+        },
+      );
+    });
+
+    it('skips when neither the history item nor the transaction has a source hash', async () => {
+      await withController(
+        {
+          options: {
+            isQuoteStatusManagerEnabled: () => true,
+            state: {
+              txHistory: {
+                seedTx6: getSeedHistoryItem({
+                  txMetaId: 'seedTx6',
+                  quoteId: 'seed-quote-6',
+                  srcTxHash: 'undefined',
+                  startTime: Date.now(),
+                }),
+              },
+            },
+          },
+          mockMessengerCall: getSeedMessengerCall([]),
+        },
+        async ({ controller }) => {
+          expect(controller.state.quoteUpdateStatusStore).toStrictEqual({});
+        },
+      );
+    });
+
+    it('does not re-seed an entry that was already reported', async () => {
+      await withController(
+        {
+          options: {
+            isQuoteStatusManagerEnabled: () => true,
+            state: {
+              txHistory: {
+                seedTx7: getSeedHistoryItem({
+                  txMetaId: 'seedTx7',
+                  quoteId: 'seed-quote-7',
+                  srcTxHash: '0xseedHash7',
+                  startTime: Date.now(),
+                  reportedSubmittedTxHash: '0xseedHash7',
+                }),
+              },
+            },
+          },
+          mockMessengerCall: getSeedMessengerCall(),
+        },
+        async ({ controller }) => {
+          expect(controller.state.quoteUpdateStatusStore).toStrictEqual({});
+        },
+      );
+    });
+
+    it('does not seed when the quote status manager is disabled', async () => {
+      await withController(
+        {
+          options: {
+            isQuoteStatusManagerEnabled: () => false,
+            state: {
+              txHistory: {
+                seedTx8: getSeedHistoryItem({
+                  txMetaId: 'seedTx8',
+                  quoteId: 'seed-quote-8',
+                  srcTxHash: '0xseedHash8',
+                  startTime: Date.now(),
+                }),
+              },
+            },
+          },
+          mockMessengerCall: getSeedMessengerCall(),
+        },
+        async ({ controller }) => {
+          expect(controller.state.quoteUpdateStatusStore).toStrictEqual({});
+          // The guard must not persist `reportedSubmittedTxHash`: doing so
+          // would mark the history item as already reported even though no
+          // store entry or backend update was ever created, so it could never
+          // be seeded once the manager is re-enabled.
+          expect(
+            controller.state.txHistory.seedTx8.reportedSubmittedTxHash,
+          ).toBeUndefined();
+        },
+      );
+    });
+  });
+
   describe('metadata', () => {
     it('includes expected state in debug snapshots', async () => {
       await withController(async ({ controller }) => {
diff --git a/packages/bridge-status-controller/src/bridge-status-controller.ts b/packages/bridge-status-controller/src/bridge-status-controller.ts
@@ -41,6 +41,7 @@ import {
   REFRESH_INTERVAL_MS,
 } from './constants';
 import {
+  QUOTE_STATUS_BACKFILL_WINDOW_MS,
   QUOTE_STATUS_UPDATE_ENTRY_TTL,
   QUOTE_STATUS_UPDATE_RETRY_INTERVAL_MS,
 } from './quote-status-manager/constants';
@@ -316,6 +317,12 @@ export class BridgeStatusController extends StaticIntervalPollingController<Brid
       },
     );
 
+    // Seed any missing quote-status entries from persisted history before
+    // init(), so init()'s reconciliation loop can finalize quotes whose
+    // deferred entry was never created (e.g. the client closed before
+    // reportSubmitted ran).
+    this.#seedQuoteStatusEntriesFromHistory();
+
     // Replay swap/bridge finalizations that resolved while the client was
     // closed, before resuming polling (which recovers in-flight bridges).
     this.#quoteStatusManager.init();
@@ -482,6 +489,9 @@ export class BridgeStatusController extends StaticIntervalPollingController<Brid
     if (!historyItem?.quoteId) {
       return;
     }
+    // `reportedSubmittedTxHash` is set once `reportSubmitted` is called.
+    // This avoids processing multiple `eportSubmitted` for the
+    // same swap/bridge.
     if (historyItem.reportedSubmittedTxHash === srcTxHash) {
       return;
     }
@@ -614,6 +624,59 @@ export class BridgeStatusController extends StaticIntervalPollingController<Brid
     return this.state.txHistory[txMetaId];
   };
 
+  /**
+   * Seeds missing quote-status entries from persisted history on startup.
+   *
+   * The deferred quote-status entry (keyed by `${quoteId}:${srcTxHash}`) is only
+   * created when `reportSubmitted` runs. If the client closes after a swap/bridge
+   * is submitted but before that happens, the entry is never created and
+   * `QuoteStatusManager.init()` has nothing to reconcile. The persisted history
+   * item carries the `quoteId`, source tx hash, and `txMetaId` needed to rebuild
+   * the entry, so we replay `reportSubmitted` here (idempotent via
+   * `#reportSubmittedOnce`) before `init()` runs.
+   */
+  readonly #seedQuoteStatusEntriesFromHistory = (): void => {
+    if (!this.#quoteStatusManager.enabled) {
+      // Skip seeding to prevent `#reportSubmittedOnce` from persisting
+      // `reportedSubmittedTxHash` so recent bridge history cannot be marked as
+      //  already reported with no store entry or backend update.
+      return;
+    }
+
+    for (const [historyKey, historyItem] of Object.entries(
+      this.state.txHistory,
+    )) {
+      const { quoteId, txMetaId } = historyItem;
+      if (!quoteId || !txMetaId) {
+        continue;
+      }
+
+      // Skip items older than the backfill window: the backend would reject
+      // a status report for a quote that old, so there is no point creating
+      // an entry or making a request.
+      if (
+        Date.now() - historyItem.startTime >
+        QUOTE_STATUS_BACKFILL_WINDOW_MS
+      ) {
+        continue;
+      }
+
+      // Prefer the history hash; fall back to the tx hash (covers STX swaps
+      // confirmed while closed, where the history hash was never written).
+      const srcTxHash =
+        historyItem.status.srcChain.txHash ??
+        getTransactionMetaById(this.messenger, txMetaId)?.hash;
+      if (!srcTxHash) {
+        continue;
+      }
+
+      // Call `reportSubmittedOnce` for each history item that satisfies
+      // the above criteria. The method will then take care the rest
+      // (ie. if it actually needs to be reported or not because it already has been).
+      this.#reportSubmittedOnce(historyKey, srcTxHash, txMetaId);
+    }
+  };
+
   /**
    * Restart polling for txs that are not in a final state
    * This is called during initialization
diff --git a/packages/bridge-status-controller/src/quote-status-manager/constants.ts b/packages/bridge-status-controller/src/quote-status-manager/constants.ts
