feat: implement quote status update logic by GeorgeGkas · Pull Request #8462 · MetaMask/core

GeorgeGkas · 2026-04-15T08:51:58Z

Explanation

Context

The Bridge API requires clients to report the lifecycle of a swap quote — when a transaction is submitted and when it finalizes (success or failure). Previously, BridgeStatusController had no mechanism to send these reports, so the Bridge API had no visibility into quote outcomes.

Additionally, batch EVM transactions (Smart Transactions / 7702-delegated flows) do not have a txHash available at submitTx time, meaning status reporting for those transactions was impossible without subscribing to a later event.

Solution

This PR introduces QuoteStatusUpdateManager inside bridge-status-controller — a resilient, persisted retry queue that reports quote lifecycle events (SUBMITTED, FINALIZED_SUCCESS, FINALIZED_FAILURE) to the Bridge API.

Key behaviours:

Immediate retries on transient errors — up to 6 attempts with a short delay before giving up or deferring.
Deferred retry queue for network failures — entries are retried every 30 minutes for up to 12 hours, and the queue is persisted to deferredStatusUpdates controller state so it survives service-worker restarts.
Non-retryable errors are evicted — errors like SVM_TRADE_DESERIALIZE_FAILED are dropped immediately rather than retried endlessly.
Feature-flagged — a new isQuoteStatusUpdateEnabled constructor option (backed by the bridgeQuoteStatusUpdateEnabled remote feature flag in the extension) gates all reporting.
Error forwarding — a new onQuoteStatusUpdateError constructor option lets callers (e.g. the extension) forward eviction errors to Sentry.

To support STX / 7702-delegated batch transactions, BridgeStatusController now subscribes to TransactionController:transactionSubmitted and triggers SUBMITTED status reporting when a hash becomes available after the fact.

bridge-controller's QuoteResponseSchema is updated to treat quoteId as a required field, since it is the stable identifier used as the key for the retry queue.

Non-obvious changes

BridgeStatusControllerMessenger.AllowedEvents now requires TransactionControllerTransactionSubmittedEvent — consumers must add this event to their messenger AllowedEvents list.
A bug in submitIntent was fixed along the way: originalTransactionId is now passed at the top level to #addTxToHistory, so the history item is correctly linked to the synthetic TransactionController entry rather than the orderUid.

References

Jira: https://consensyssoftware.atlassian.net/browse/SWAPS-4399
Related: isQuoteStatusUpdateEnabled is gated by remoteFeatureFlags.bridgeQuoteStatusUpdateEnabled

Checklist

I've updated the test suite for new or updated code as appropriate
I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
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

Note

Medium Risk
Medium risk: introduces new persisted retry queue and new event subscriptions to report quote lifecycle status to the Bridge API, and makes quoteId required in multiple schemas/types, which can break consumers if any integration omits it.

Overview
Adds required quoteId plumbing across bridge quoting and history: QuoteResponseSchema now requires quoteId, test fixtures/mocks/snapshots are updated, and BridgeHistoryItem now includes a required quoteId (breaking).

Introduces resilient quote-status reporting in BridgeStatusController via a new QuoteStatusUpdateManager, persisting a deferredStatusUpdates retry queue and reporting SUBMITTED/finalized success/failure (feature-flagged + error callback). Status reporting is triggered on submission/confirmation/failure/polling-finalization, including a new subscription to TransactionController:transactionSubmitted to handle batch/STX flows where the tx hash is only available after submission.

Fixes batch EVM submission cleanup by deleting the pre-submission (actionId-keyed) history item if batch submission fails, and rekeys batch history to the final txMeta.id while capturing batchId/approvalTxId once available.

^{Reviewed by Cursor Bugbot for commit c2e1b23. Bugbot is set up for automated code reviews on this repo. Configure here.}

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2505ac0. Configure here.}

cursor · 2026-05-04T15:19:24Z

+    // Report finalized success for swap/bridge transactions
+    if (txMeta.type && isCrossChainTx(txMeta.type)) {
+      this.#quoteStatusUpdateManager.reportFinalised(txMeta.id, true);
+    }


Premature finalized-success reported for bridge transactions

High Severity

In #onTransactionConfirmed, reportFinalised(txMeta.id, true) is called for all cross-chain tx types (both swaps and bridges) when the source chain transaction confirms. For same-chain swaps this is correct — confirmation means the swap is done. For bridge transactions, however, source chain confirmation only means the first leg succeeded; the destination chain transfer is still pending. The #fetchBridgeTxStatus polling handler later calls reportFinalised again with the actual bridge outcome. This means a bridge that ultimately fails on the destination chain will first send FINALIZED_SUCCESS (premature) and then FINALIZED_FAILURE, providing contradictory lifecycle data to the Bridge API.

Additional Locations (1)

packages/bridge-status-controller/src/bridge-status-controller.ts#L906-L910

^{Reviewed by Cursor Bugbot for commit 2505ac0. Configure here.}

This is expected, we care only about reporting the success/failure of the the source tx.

infiniteflower · 2026-05-04T18:19:45Z

+            this.state.txHistory[txMetaId] ??
+            (actionId ? this.state.txHistory[actionId] : undefined);
+          if (historyItem?.quoteId) {
+            this.#quoteStatusUpdateManager.reportSubmitted(


Just wondering why this is called twice, once here at transactionSubmitted and once at transactionStatusUpdated (submitted status) above? Aren't those 2 the same and would there be duplicated reports?

@infiniteflower they are indeed similar. There was a change recently introduced on the transaction controller where they added a universal event TransactionController:transactionStatusUpdated. I originally made the implementation using the separate submitted event listener and later they introduced the updated event. I kept both for completeness, note there are not issues with duplicate calls, I already tested that.

@infiniteflower I gave it another look and we indeed require both. TransactionController:transactionStatusSubmitted is called immediately once we broadcast the tx while the update event is triggered on later time. If we omit the submitted event listener, there is an edge case where the quote status manager won't be able to create a record if user closes the app immediately after submitting a swap (or loose internet connection). We'll never get back the tx status in that case.

the #onTransactionStatusChange handler in TransactionController (line 3337) publishes transactionStatusUpdated right after submitted, so I think this does duplicate the event handling

We use the generic transaction statusUpdated event instead of specific ones like transactionSubmitted because the initial hash generated during submission can be replaced before it's confirmed on chain

micaelae · 2026-05-04T19:36:30Z

+- Add required `quoteId: string` to `QuoteResponseSchema`; quote responses without a `quoteId` will now fail validation ([#8462](https://github.com/MetaMask/core/pull/8462))
+


Please mark this as a breaking change. Client e2e tests will need to be updated

micaelae · 2026-05-04T20:04:00Z


+      // Finalize the quote status update as a failure since we can no longer
+      // determine the outcome via polling.
+      this.#quoteStatusUpdateManager.reportFinalised(bridgeTxMetaId, false);


The controller restarts polling for these transactions next time the wallet restarts so it's too soon to report finalization here. This will also result in duplicate finalization status updates

The #handleOldHistoryItem handler deletes the history item to permanently stop polling so the report should happen there

micaelae · 2026-05-04T20:09:32Z

+              isCrossChainTx(txMeta.type) &&
+              !isApprovalTxMeta
+            ) {
+              if (historyItem?.quoteId && txMeta.hash) {


There are multiple places in the code where we assume quoteId is defined, but it won't be for older txHistory items. Can you make it optional in the BridgeHistoryItem type to ensure this undefined check is always done?

micaelae · 2026-05-04T20:13:19Z


+    // Report finalized success for swap/bridge transactions
+    if (txMeta.type && isCrossChainTx(txMeta.type)) {
+      this.#quoteStatusUpdateManager.reportFinalised(txMeta.id, true);


for bridge transactions, do we only care about the src transaction? or should finalized only be reported when both src and dest are confirmed?

micaelae · 2026-05-04T20:32:18Z

+    return (await res.json()) as QuoteStatusUpdateResponse;
+  };


Please add a validator and infer the type for QuoteStatusUpdateResponse rather than casting the response. Validating ensures that the data matches the shape we expect. In the worst case the app or background worker may crash when we attempt to use unvalidated objects

micaelae · 2026-05-04T20:35:12Z

    addTransactionBatchFn,
    config,
    traceFn,
+    onQuoteStatusUpdateError,


Is this logic going to be different across clients?

micaelae · 2026-05-04T20:36:55Z

    config,
    traceFn,
+    onQuoteStatusUpdateError,
+    isQuoteStatusUpdateEnabled,


If this is only based on a client feature flag, I'd read the flag directly in the controller/update manager

That was my initial thought as well, but I wanted to keep the controller as stateless as possible, which is why I prefer to pass callbacks and let clients handle initialization. While directly reading the flag might seem appropriate for now, it introduces tight coupling between our service and an external dependency (the LD flags), which complicates testing.

My main concern, however, is that this won’t be the final requirement for the update manager. Since Ethan is planning to add more logic after v1, and we don’t know the exact changes yet, I wanted to keep the interface generic. That way, when we eventually update the implementation logic, the public API can remain stable, making future documentation simpler and more consistent.

micaelae · 2026-05-04T20:53:05Z


+    // Report finalized failure for swap/bridge transactions
+    if (txMeta.type && isCrossChainTx(txMeta.type)) {
+      this.#quoteStatusUpdateManager.reportFinalised(txMeta.id, false);


Have you tested this with a HW wallet rejection? If you submit the trade, but reject the tx on a HW wallet, does the submitted event fire? If it doesn't then this should happen after the rejected check below

Good catch, will have to do it.

micaelae · 2026-05-04T21:34:51Z

+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...getClientHeaders({


Pass the clientVersion too

micaelae · 2026-05-04T22:02:00Z

+    if (
+      type === QuoteStatusUpdateErrorType.InvalidStatusTransaction ||
+      type === QuoteStatusUpdateErrorType.QuoteStatusOnChainMismatch
+    ) {
+      const finalizationStatus = response.currentStatus;
+      entry.pendingStatuses = [finalizationStatus];
+      this.#persistToState();
+      this.#inFlight.delete(key);
+      await this.#attemptFinalizationWithRetries(key, entry);
+      return;
+    }


Why post the status update again? If this happens, doesn't it mean the backend already has the fimnalizationStatus. So all we need to do is remove this from the deferred statuses

micaelae · 2026-05-04T22:12:39Z

+      for (const key of this.#deferredRetryQueue.keys()) {
+        setTimeout(() => this.#processSingleEntry(key), delay);
+        delay += 125;


ensureRetryTimerRunning also causes these entries to be processed. Why do both need to be started around the same time?

GeorgeGkas · 2026-05-05T06:45:44Z

From @micaelae :

I think this means the controller will need to publish the “submitted” event for intents after the submitOrder call as well

GeorgeGkas added 30 commits April 14, 2026 21:46

feat: new

1fe19d3

fix: use correct request field

2efe9f3

style: fix lint

e5e0779

style: formatting

3afb9f7

fix: package

2489b21

feat: extract logic to service

27e2ff3

style: fix

17f4900

style: fix

bdcb4f8

feat: add persist mechanism and state management

66c1e98

Merge branch 'main' into swaps-quotes

9768267

style: fix

f26d2bc

style: fix

0d03c32

fix: edge case

3ae606e

Merge branch 'main' into swaps-quotes

8e03e75

style: lint

3481a8e

feat: improve

277d97a

refactor: naming

2e0b70f

feat: use quoteId rather than requestId

c9fd515

style: lint

4921fd5

fix: startup retry logic

0d8c536

feat: add error handling

b51b91e

feat: add enable flag

0fb17cb

style: fix

a328d15

test: update

64acb94

style: format

64ec113

test: fix

de7f861

test: add tests

91bab64

style: fix

e5a633a

chore: add changelog

4cdbf1d

Merge branch 'main' into swaps-quotes

7732c30

GeorgeGkas added 2 commits May 4, 2026 16:38

chore: update changelog

7c742a5

chore: changelog

c04f7ef

GeorgeGkas marked this pull request as ready for review May 4, 2026 14:33

GeorgeGkas requested review from a team as code owners May 4, 2026 14:33

GeorgeGkas changed the title ~~Swaps quotes~~ feat: implement quote status update logic May 4, 2026

cursor Bot reviewed May 4, 2026

View reviewed changes

Comment thread packages/bridge-status-controller/src/bridge-status-controller.ts

Comment thread packages/bridge-status-controller/src/bridge-status-controller.ts

fix: cursor bugbot review

2505ac0

cursor Bot reviewed May 4, 2026

View reviewed changes

GeorgeGkas mentioned this pull request May 4, 2026

feat: wire up quote status update MetaMask/metamask-extension#42385

Draft

7 tasks

infiniteflower reviewed May 4, 2026

View reviewed changes

Comment thread packages/bridge-controller/CHANGELOG.md

GeorgeGkas requested a review from infiniteflower May 4, 2026 18:10

infiniteflower reviewed May 4, 2026

View reviewed changes

Comment thread packages/bridge-status-controller/src/types.ts Outdated

refactor: type

c2e1b23

micaelae reviewed May 4, 2026

View reviewed changes

GeorgeGkas requested a review from infiniteflower May 4, 2026 19:51

micaelae reviewed May 4, 2026

View reviewed changes

		- Add required `quoteId: string` to `QuoteResponseSchema`; quote responses without a `quoteId` will now fail validation ([#8462](https://github.com/MetaMask/core/pull/8462))

Uh oh!

Conversation

GeorgeGkas commented Apr 15, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation

Context

Solution

Non-obvious changes

References

Checklist

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot May 4, 2026

Choose a reason for hiding this comment

Premature finalized-success reported for bridge transactions

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GeorgeGkas commented May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

GeorgeGkas commented Apr 15, 2026 •

edited by cursor Bot

Loading