feat(bridge-controller): add SwapBridge failure telemetry schema and classifiers - #9947
Open
Battambang wants to merge 5 commits into
Open
feat(bridge-controller): add SwapBridge failure telemetry schema and classifiers#9947Battambang wants to merge 5 commits into
Battambang wants to merge 5 commits into
Conversation
Battambang
force-pushed
the
feat/WPN-1877-failure-telemetry-schema
branch
from
August 24, 2026 21:38
6c94234 to
bbf9454
Compare
4 tasks
Contributor
Author
|
@metamaskbot publish-preview |
Contributor
|
Preview builds have been published. Learn how to use preview builds in other projects. Expand for full list of packages and versions. |
There was a problem hiding this comment.
Pull request overview
Adds an additive telemetry schema and pure helper functions to classify SwapBridge failures into stable phases/error codes based on code path + tx-hash presence (not error_message), preparing richer analytics for a follow-up PR that will wire these fields into emitted events.
Changes:
- Introduces
FailurePhaseandSwapBridgeErrorCodeenums and exports them from the package entrypoint. - Adds
failure-telemetryclassifier helpers (+ unit tests) for quote-fetch, submit, and status/poll failure classification. - Extends Unified SwapBridge metrics context types with optional failure-telemetry and hash-presence fields for relevant events.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| packages/bridge-controller/src/utils/metrics/types.ts | Adds HashPresenceData / FailureTelemetryData and threads them into selected Unified SwapBridge event context types. |
| packages/bridge-controller/src/utils/metrics/failure-telemetry.ts | New helper functions to derive error codes, phases, and hash-presence flags. |
| packages/bridge-controller/src/utils/metrics/failure-telemetry.test.ts | Unit tests covering the new classification helpers. |
| packages/bridge-controller/src/utils/metrics/constants.ts | Adds the new telemetry enums used by schema + helpers. |
| packages/bridge-controller/src/index.ts | Re-exports the new enums, types, and helper functions from the package entrypoint. |
| packages/bridge-controller/CHANGELOG.md | Documents the new telemetry exports/types for consumers. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Battambang
force-pushed
the
feat/WPN-1877-failure-telemetry-schema
branch
2 times, most recently
from
August 26, 2026 11:53
f8653bd to
c766626
Compare
Battambang
added a commit
that referenced
this pull request
Aug 26, 2026
…sence Wire Quotes Error, submit Failed, EVM Failed, poll Failed, Submitted, and Completed to the classifiers from #9947. Mixpanel can now split quote vs broadcast vs source vs dest vs poll without parsing error_message.
micaelae
reviewed
Aug 26, 2026
Comment on lines
+31
to
+60
| /** | ||
| * Classify a thrown value from submit (sign/broadcast) catch paths. | ||
| * | ||
| * @param error - The thrown value from submit. | ||
| * @returns The Mixpanel `error_code`. | ||
| */ | ||
| export const getSubmitErrorCode = (error: unknown): SwapBridgeErrorCode => { | ||
| if (error === undefined || error === null) { | ||
| return SwapBridgeErrorCode.MissingErrorObject; | ||
| } | ||
| if (error instanceof Error) { | ||
| return SwapBridgeErrorCode.Unknown; | ||
| } | ||
| return SwapBridgeErrorCode.NonErrorRejection; | ||
| }; | ||
|
|
||
| /** | ||
| * @param sourceHash - Source tx hash if known at emit time. | ||
| * @param destinationHash - Destination tx hash if known at emit time. | ||
| * @returns Boolean hash-presence properties. | ||
| */ | ||
| export const getHashPresenceProperties = ( | ||
| sourceHash?: string | null, | ||
| destinationHash?: string | null, | ||
| ): HashPresenceProperties => { | ||
| return { | ||
| source_hash_present: Boolean(sourceHash), | ||
| destination_hash_present: Boolean(destinationHash), | ||
| }; | ||
| }; |
Member
There was a problem hiding this comment.
Please move these and the functions below to the bridge-status-controller's metrics utils
Contributor
Author
There was a problem hiding this comment.
Quote-fetch classification has to stay in bridge-controller (getQuoteFetchErrorCode + the shared enums/types), because Quotes Error is emitted there and status-controller cannot be a dependency of bridge-controller.
I have moved getHashPresenceProperties, getStatusFailurePhase, getSubmitErrorCode / getSubmitFailureTelemetry, and getStatusFailureTelemetry into bridge-status-controller metrics utils
Battambang
force-pushed
the
feat/WPN-1877-failure-telemetry-schema
branch
from
August 26, 2026 20:55
c766626 to
fc635b0
Compare
…classifiers Add FailurePhase and SwapBridgeErrorCode plus helpers so a follow-up emit can classify failures from the code path and hash presence, without parsing error_message. No Mixpanel payloads change in this commit.
…ields Quote fetch is pre-tx, so the changelog should not list source_hash_present or destination_hash_present on Quotes Error.
Battambang
force-pushed
the
feat/WPN-1877-failure-telemetry-schema
branch
from
August 27, 2026 15:37
fc635b0 to
e9a6717
Compare
Battambang
added a commit
that referenced
this pull request
Aug 27, 2026
…sence Wire Quotes Error, submit Failed, EVM Failed, poll Failed, Submitted, and Completed to the classifiers from #9947. Mixpanel can now split quote vs broadcast vs source vs dest vs poll without parsing error_message.
…ntroller Keep quote-fetch classification in bridge-controller. Hash presence and submit/status helpers belong with the controller that will emit them.
…etrics utils Fold submit/status failure telemetry helpers into the existing metrics files instead of a new module.
Battambang
added a commit
that referenced
this pull request
Aug 27, 2026
…sence Wire Quotes Error, submit Failed, EVM Failed, poll Failed, Submitted, and Completed to the classifiers from #9947. Mixpanel can now split quote vs broadcast vs source vs dest vs poll without parsing error_message.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Explanation
Problem. SwapBridge
Failedtoday is one bucket. Mixpanel cannot tell quote-fetch vs submit vs source vs dest vs poll, or whether a source/dest hash existed. That hides Tron/non-EVM diagnosis behind a blended "on-chain" failure rate. Free-texterror_messageis not a reliable classifier.This PR adds the schema and classifiers only. It does not change Mixpanel payloads - runtime analytics behavior is unchanged until the follow-up wires these into emit paths.
Classification is always derived from the failing code path and hash presence, never from
error_messagetext.Content
Each classifier lives in the package that will call it.
bridge-controllerkeeps the shared schema plus quote-fetch (the only failure it owns); submit and status classifiers live inbridge-status-controller.@metamask/bridge-controllerFailurePhase,SwapBridgeErrorCodeenums ·HashPresenceData,FailureTelemetryDatatypes ·getQuoteFetchErrorCode@metamask/bridge-status-controllergetSubmitErrorCode·getHashPresenceProperties·getStatusFailurePhase·getSubmitFailureTelemetry·getStatusFailureTelemetry·HashPresenceProperties,FailureTelemetryPropertiestypesEvent context types (all optional, additive)
failure_phase,error_codefailure_phase,error_code,source_hash_present,destination_hash_presentsource_hash_present,destination_hash_presentsource_hash_present,destination_hash_presentProperty values
failure_phasequote·broadcast·source_execution·destination_execution·poll·unknownerror_codequote_fetch_failed·missing_error_object·non_error_rejection·status_failed_without_reason·unknownsource_hash_present/destination_hash_presentClassification rules
getQuoteFetchErrorCode—missing_error_objectwhen the thrown value is nullish,quote_fetch_failedfor anError,non_error_rejectionotherwise.getSubmitFailureTelemetryalways reportsbroadcastwith both hash flagsfalse, because Core currently emits Failed beforeexecuteSubmitStrategy.getStatusFailurePhaseprefersdestination_executionwhen a dest hash exists, thensource_executionwhen a source hash exists, and falls back topollonly when neither is present.A follow-up PR (#9949) emits these fields from Quotes Error, submit catch, EVM failed, poll, Submitted, and Completed.
References
Checklist
Note
Low Risk
Additive exports, optional type fields, and classifiers with tests; no changes to submit, polling, or Mixpanel emission yet.
Overview
Adds structured SwapBridge failure telemetry ahead of a follow-up that will populate Mixpanel payloads.
@metamask/bridge-controllerintroducesFailurePhaseandSwapBridgeErrorCode, shared types (HashPresenceData,FailureTelemetryData), optional fields on Unified SwapBridge event context types (failure_phase/error_codeon Quotes Error and Failed;source_hash_present/destination_hash_presenton Failed, Submitted, and Completed), andgetQuoteFetchErrorCodeto classify quote-fetch throws without parsingerror_message.@metamask/bridge-status-controllerexports helpers to derive the same fields for submit and status failures: hash presence from tx hashes,getStatusFailurePhase(destination → source → poll), submitbroadcasttelemetry with no hashes, and status failures withstatus_failed_without_reason. Unit tests cover both packages. Runtime analytics behavior is unchanged until callers wire these helpers into emit paths.Reviewed by Cursor Bugbot for commit 847c0f6. Bugbot is set up for automated code reviews on this repo. Configure here.