@metamask/connect-multichain 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0]
+
+### Added
+
+- Attach a `failure_reason` tag to `mmconnect_wallet_action_failed` and `mmconnect_connection_failed` events via a new `classifyFailureReason` helper, distinguishing transport timeouts, transport disconnects, EIP-1193 wallet errors (`4100 wallet_unauthorized`, `4200 wallet_method_unsupported`, `4902 unrecognized_chain`), and JSON-RPC wallet errors (`-32601`, `-32602`, `-32603`, plus the `-32000…-32099` server-error range), with an `unknown` fallback. Schema-side: [`metamask-sdk-analytics-api#31`](https://github.com/consensys-vertical-apps/metamask-sdk-analytics-api/pull/31). ([#290](https://github.com/MetaMask/connect-monorepo/pull/290))
+- Attach `error_code` and `error_message_sample` companion properties to `mmconnect_wallet_action_failed` and `mmconnect_connection_failed`. `error_code` preserves the raw wallet-side JSON-RPC / EIP-1193 code (e.g. `4001`, `-32603`). `error_message_sample` is a sanitised, 200-char-max preview of the original error message, with wallet addresses, long hex blobs, URLs, and large decimal numbers scrubbed. Both fields are optional and only set on the two `*_failed` events. Schema-side: [`metamask-sdk-analytics-api#32`](https://github.com/consensys-vertical-apps/metamask-sdk-analytics-api/pull/32). ([#290](https://github.com/MetaMask/connect-monorepo/pull/290))
+
+### Changed
+
+- Improves QR code scanning reliability. The QR code MWP flow (desktop web and Node.js) now omits the initial `wallet_createSession` request from the deeplink URI, instead sending it as a separate request after the wallet completes the MWP handshake. This results in a shorter deeplink URI and a less dense QR code. The native deeplink (non-QR MWP) flow used on mobile web and React Native is unchanged. ([#295](https://github.com/MetaMask/connect-monorepo/pull/295))
+
+### Fixed
+
+- Tightened `isRejectionError` so `mmconnect_wallet_action_rejected` more accurately reflects user-driven cancellations: it now unwraps `RPCInvokeMethodErr` (so wallet-side codes survive the router's transport-boundary wrapping rather than being masked by the wrapper's `code: 53`), no longer classifies EIP-1193 `4100 Unauthorized` as a rejection (it's a CAIP-25 permission denial, not a user decision), and narrows the bare `"user"` substring match to four explicit phrases — `"user rejected"` / `"user denied"` / `"user cancelled"` / `"user canceled"` — so unrelated messages like Account Abstraction's `"user operation reverted"` no longer count. Net effect: `_rejected` becomes more precise; `_failed` picks up everything `4100` was previously hiding. ([#292](https://github.com/MetaMask/connect-monorepo/pull/292))
+
 ## [0.13.0]
 
 ### Uncategorized
@@ -262,7 +277,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release
 
-[Unreleased]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.13.0...HEAD
+[Unreleased]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.14.0...HEAD
+[0.14.0]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.13.0...@metamask/connect-multichain@0.14.0
 [0.13.0]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.12.1...@metamask/connect-multichain@0.13.0
 [0.12.1]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.12.0...@metamask/connect-multichain@0.12.1
 [0.12.0]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.11.1...@metamask/connect-multichain@0.12.0

package/dist/browser/es/connect-multichain.d.mts

@@ -679,13 +679,42 @@ declare abstract class Modal<Options, Data extends DataType = DataType> {
     set data(data: Data);
 }
 
+/**
+ * Tag describing the cause of a failed wallet action / connection. Surfaced
+ * as the `failure_reason` property on `mmconnect_wallet_action_failed` and
+ * `mmconnect_connection_failed` events so we can distinguish e.g. a transport
+ * timeout from a wallet-side internal error in Mixpanel.
+ *
+ * Intentionally a string union (not a const enum) so callers stay free to
+ * pass through a new bucket; the schema-side property is an open string for
+ * the same reason.
+ */
+type FailureReason = 'transport_timeout' | 'transport_disconnect' | 'wallet_method_unsupported' | 'wallet_invalid_params' | 'wallet_internal_error' | 'wallet_unauthorized' | 'unrecognized_chain' | 'unknown';
 /**
  * Checks if an error represents a user rejection.
  *
+ * Unwraps `RPCInvokeMethodErr` so the wallet's `code: 4001` survives the
+ * SDK's transport-boundary wrapping (the outer error otherwise reports
+ * `code: 53`, which would never match the heuristics here).
+ *
  * @param error - The error object to check
  * @returns True if the error indicates a user rejection, false otherwise
  */
 declare function isRejectionError(error: unknown): boolean;
+/**
+ * Classifies a failed wallet action / connection error into a short tag for
+ * the `failure_reason` analytics property. Caller is expected to have already
+ * established that the error is *not* a user rejection (use `isRejectionError`
+ * for that branching).
+ *
+ * The taxonomy is deliberately producer-side-only — the schema accepts any
+ * string — so we can add buckets here without an API migration. Once the
+ * distribution stabilises we may convert the schema field to a closed enum.
+ *
+ * @param error - The error to classify
+ * @returns A short, snake_case tag describing why the operation failed
+ */
+declare function classifyFailureReason(error: unknown): FailureReason;
 /**
  * Gets analytics properties specific to wallet action events.
  *
@@ -693,15 +722,30 @@ declare function isRejectionError(error: unknown): boolean;
  * @param storage - Storage client for getting anonymous ID
  * @param invokeOptions - The invoke method options containing method and scope
  * @param transportType - The transport type to use for the analytics event
+ * @param extra - Optional event-specific diagnostic properties. Used by
+ * `mmconnect_wallet_action_failed` to attach the {@link ErrorDiagnostics}
+ * bundle (`failure_reason`, `error_code`, `error_message_sample`).
+ * @param extra.failure_reason - A short tag describing why the operation
+ * failed; see `classifyFailureReason` and the `FailureReason` union.
+ * @param extra.error_code - The raw wallet-side error code, if present.
+ * @param extra.error_message_sample - A sanitised, truncated sample of the
+ * original error message.
  * @returns Wallet action analytics properties
  */
-declare function getWalletActionAnalyticsProperties(options: MultichainOptions, storage: StoreClient, invokeOptions: InvokeMethodOptions, transportType: TransportType): Promise<{
+declare function getWalletActionAnalyticsProperties(options: MultichainOptions, storage: StoreClient, invokeOptions: InvokeMethodOptions, transportType: TransportType, extra?: {
+    failure_reason?: FailureReason;
+    error_code?: number;
+    error_message_sample?: string;
+}): Promise<{
     mmconnect_versions: Record<string, string>;
     dapp_id: string;
     method: string;
     caip_chain_id: string;
     anon_id: string;
     transport_type: TransportType;
+    failure_reason?: FailureReason;
+    error_code?: number;
+    error_message_sample?: string;
 }>;
 
 /**
@@ -713,4 +757,4 @@ declare function getVersion(): string;
 
 declare const createMultichainClient: CreateMultichainFN;
 
-export { type ConnectVersions, type ConnectionRequest, type ConnectionStatus, type CreateMultichainFN, type DappSettings, type DataType, type DomainErrorCodes, type Enumerate, type ErrorCodeRange, type ErrorCodes, EventEmitter, type EventTypes, type ExtendedTransport, type InstallWidgetProps, type InvokeMethodOptions, type LoggerNameSpaces, type MergeableMultichainOptions, Modal, type ModalFactoryConnectOptions, type ModalFactoryOptions, MultichainCore, type MultichainOptions, type NotificationCallback, type OTPCode, type OTPCodeWidgetProps, PlatformType, type QRLink, type RPCAPI, type RPCErrorCodes, RPCHttpErr, RPCInvokeMethodErr, RPCReadonlyRequestErr, RPCReadonlyResponseErr, type RPCResponse, RPC_HANDLED_METHODS, type RpcMethod, type RpcUrlsMap, type SDKEvents, SDK_HANDLED_METHODS, type Scope, type StorageErrorCodes, StoreAdapter, StoreClient, type StoreOptions, TransportType, createLogger, createMultichainClient, enableDebug, getInfuraRpcUrls, getPlatformType, getTransportType, getVersion, getWalletActionAnalyticsProperties, hasExtension, infuraRpcUrls, isEnabled, isMetamaskExtensionInstalled, isRejectionError, isSecure };
+export { type ConnectVersions, type ConnectionRequest, type ConnectionStatus, type CreateMultichainFN, type DappSettings, type DataType, type DomainErrorCodes, type Enumerate, type ErrorCodeRange, type ErrorCodes, EventEmitter, type EventTypes, type ExtendedTransport, type FailureReason, type InstallWidgetProps, type InvokeMethodOptions, type LoggerNameSpaces, type MergeableMultichainOptions, Modal, type ModalFactoryConnectOptions, type ModalFactoryOptions, MultichainCore, type MultichainOptions, type NotificationCallback, type OTPCode, type OTPCodeWidgetProps, PlatformType, type QRLink, type RPCAPI, type RPCErrorCodes, RPCHttpErr, RPCInvokeMethodErr, RPCReadonlyRequestErr, RPCReadonlyResponseErr, type RPCResponse, RPC_HANDLED_METHODS, type RpcMethod, type RpcUrlsMap, type SDKEvents, SDK_HANDLED_METHODS, type Scope, type StorageErrorCodes, StoreAdapter, StoreClient, type StoreOptions, TransportType, classifyFailureReason, createLogger, createMultichainClient, enableDebug, getInfuraRpcUrls, getPlatformType, getTransportType, getVersion, getWalletActionAnalyticsProperties, hasExtension, infuraRpcUrls, isEnabled, isMetamaskExtensionInstalled, isRejectionError, isSecure };

package/dist/browser/es/connect-multichain.mjs

@@ -679,17 +679,94 @@ var init_ui = __esm({
 });
 
 // src/multichain/utils/analytics.ts
+function sanitiseErrorMessage(message) {
+  if (!message) {
+    return void 0;
+  }
+  let sanitised = message;
+  for (const { pattern, replacement } of SANITISE_PATTERNS) {
+    sanitised = sanitised.replace(pattern, replacement);
+  }
+  if (sanitised.length > ERROR_MESSAGE_SAMPLE_MAX_LENGTH) {
+    sanitised = `${sanitised.slice(0, ERROR_MESSAGE_SAMPLE_MAX_LENGTH - 1)}\u2026`;
+  }
+  return sanitised;
+}
+function getUnwrappedErrorDetails(error) {
+  var _a3, _b, _c, _d;
+  if (typeof error !== "object" || error === null) {
+    return { code: void 0, message: "" };
+  }
+  if (error instanceof RPCInvokeMethodErr) {
+    return {
+      code: (_a3 = error.rpcCode) != null ? _a3 : error.code,
+      message: (_c = (_b = error.rpcMessage) != null ? _b : error.message) != null ? _c : ""
+    };
+  }
+  const errorObj = error;
+  return {
+    code: errorObj.code,
+    message: (_d = errorObj.message) != null ? _d : ""
+  };
+}
 function isRejectionError(error) {
-  var _a3, _b;
   if (typeof error !== "object" || error === null) {
     return false;
   }
+  const { code, message } = getUnwrappedErrorDetails(error);
+  const errorMessage = message.toLowerCase();
+  return code === 4001 || errorMessage.includes("reject") || errorMessage.includes("denied") || errorMessage.includes("cancel") || // Narrow "user …" matches — bare "user" is too greedy (catches Account
+  // Abstraction errors like "user operation reverted").
+  errorMessage.includes("user rejected") || errorMessage.includes("user denied") || errorMessage.includes("user cancelled") || errorMessage.includes("user canceled");
+}
+function classifyFailureReason(error) {
+  var _a3, _b;
+  if (typeof error !== "object" || error === null) {
+    return "unknown";
+  }
   const errorObj = error;
-  const errorCode = errorObj.code;
-  const errorMessage = (_b = (_a3 = errorObj.message) == null ? void 0 : _a3.toLowerCase()) != null ? _b : "";
-  return errorCode === 4001 || // User rejected request (common EIP-1193 code)
-  errorCode === 4100 || // Unauthorized (common rejection code)
-  errorMessage.includes("reject") || errorMessage.includes("denied") || errorMessage.includes("cancel") || errorMessage.includes("user");
+  const errorName = (_a3 = errorObj.name) != null ? _a3 : "";
+  const errorMessageRaw = (_b = errorObj.message) != null ? _b : "";
+  const errorMessage = errorMessageRaw.toLowerCase();
+  const { code } = getUnwrappedErrorDetails(error);
+  if (typeof code === "number") {
+    if (code === -32601) {
+      return "wallet_method_unsupported";
+    }
+    if (code === -32602) {
+      return "wallet_invalid_params";
+    }
+    if (code === -32603) {
+      return "wallet_internal_error";
+    }
+    if (code <= -32e3 && code >= -32099) {
+      return "wallet_internal_error";
+    }
+    if (code === 4100) {
+      return "wallet_unauthorized";
+    }
+    if (code === 4200) {
+      return "wallet_method_unsupported";
+    }
+    if (code === 4902) {
+      return "unrecognized_chain";
+    }
+  }
+  if (errorName === "TransportTimeoutError" || errorMessageRaw === "Request timeout" || errorMessage.includes("timed out") || errorMessage.includes("timeout")) {
+    return "transport_timeout";
+  }
+  if (errorName === "TransportError" || errorMessage.includes("not connected") || errorMessage.includes("transport disconnect") || errorMessage.includes("connection lost") || errorMessage.includes("socket closed")) {
+    return "transport_disconnect";
+  }
+  return "unknown";
+}
+function extractErrorDiagnostics(error) {
+  const failureReason = classifyFailureReason(error);
+  const { code, message } = getUnwrappedErrorDetails(error);
+  const messageSample = sanitiseErrorMessage(message);
+  return __spreadValues(__spreadValues({
+    failure_reason: failureReason
+  }, typeof code === "number" ? { error_code: code } : {}), messageSample ? { error_message_sample: messageSample } : {});
 }
 function getBaseAnalyticsProperties(options, storage) {
   return __async(this, null, function* () {
@@ -705,26 +782,61 @@ function getBaseAnalyticsProperties(options, storage) {
     };
   });
 }
-function getWalletActionAnalyticsProperties(options, storage, invokeOptions, transportType) {
+function getWalletActionAnalyticsProperties(options, storage, invokeOptions, transportType, extra) {
   return __async(this, null, function* () {
     var _a3;
     const dappId = getDappId(options.dapp);
     const anonId = yield storage.getAnonId();
-    return {
+    return __spreadValues(__spreadValues(__spreadValues({
       mmconnect_versions: (_a3 = options.versions) != null ? _a3 : {},
       dapp_id: dappId,
       method: invokeOptions.request.method,
       caip_chain_id: invokeOptions.scope,
       anon_id: anonId,
       transport_type: transportType
-    };
+    }, (extra == null ? void 0 : extra.failure_reason) ? { failure_reason: extra.failure_reason } : {}), typeof (extra == null ? void 0 : extra.error_code) === "number" ? { error_code: extra.error_code } : {}), (extra == null ? void 0 : extra.error_message_sample) ? { error_message_sample: extra.error_message_sample } : {});
   });
 }
+var ERROR_MESSAGE_SAMPLE_MAX_LENGTH, SANITISE_PATTERNS;
 var init_analytics = __esm({
   "src/multichain/utils/analytics.ts"() {
     "use strict";
     init_utils2();
     init_domain();
+    ERROR_MESSAGE_SAMPLE_MAX_LENGTH = 200;
+    SANITISE_PATTERNS = [
+      // EVM-style 20-byte hex addresses (e.g. `0x` + 40 hex chars).
+      { pattern: /0x[a-fA-F0-9]{40}/gu, replacement: "<addr>" },
+      // Other long hex blobs: tx hashes, signatures, raw byte strings, large
+      // hex amounts. 16+ hex chars catches 32-byte hashes/signatures without
+      // snagging EVM method selectors (8 chars) or short hex codes.
+      { pattern: /(?:0x)?[a-fA-F0-9]{16,}/gu, replacement: "<hex>" },
+      // URLs of any scheme up to the first whitespace / quote / closing paren.
+      // Catches RPC endpoints, dapp deeplinks, query strings with secrets.
+      { pattern: /https?:\/\/[^\s"')]+/gu, replacement: "<url>" },
+      // Bech32 addresses: short HRP (1-10 lowercase chars) + `1` separator +
+      // ≥38 chars of Bech32 data alphabet `[ac-hj-np-z02-9]` (excludes the
+      // look-alike chars `b`, `i`, `o`, `1`). Covers Bitcoin SegWit
+      // (`bc1…`/`tb1…`) and Cosmos-SDK chains (`cosmos1…`, `osmo1…`,
+      // `juno1…`, `inj1…`, etc.) without enumerating every HRP. Runs before
+      // the Base58 pattern below — see header comment for why.
+      {
+        pattern: /\b[a-z]{1,10}1[ac-hj-np-z02-9]{38,}\b/gu,
+        replacement: "<addr>"
+      },
+      // Base58 tokens (32+ chars, Base58 alphabet `[1-9A-HJ-NP-Za-km-z]`).
+      // Covers Solana pubkeys (32-44 chars), Solana tx signatures (~88 chars),
+      // and Bitcoin Base58 addresses ≥32 chars. The 32-char floor and `\b`
+      // word boundary keep English words and shorter alphanumerics safe.
+      {
+        pattern: /\b[1-9A-HJ-NP-Za-km-z]{32,}\b/gu,
+        replacement: "<addr>"
+      },
+      // Long decimal numbers — token amounts, gas units, timestamps, lamports.
+      // 10+ digits catches typical chain quantities without affecting JSON-RPC
+      // codes (-32601, 4001, etc.) or short numeric IDs.
+      { pattern: /\d{10,}/gu, replacement: "<num>" }
+    ];
   }
 });
 
@@ -1386,13 +1498,24 @@ var init_mwp = __esm({
                     return resolveConnection();
                   });
                   this.dappClient.on("message", initialConnectionMessageHandler);
+                  const platformType = getPlatformType();
+                  const isQRCodeFlow = [
+                    "web-desktop" /* DesktopWeb */,
+                    "nodejs" /* NonBrowser */
+                  ].includes(platformType);
+                  const initialPayload = {
+                    name: MULTICHAIN_PROVIDER_STREAM_NAME,
+                    data: request
+                  };
                   dappClient.connect({
                     mode: "trusted",
-                    initialPayload: {
-                      name: MULTICHAIN_PROVIDER_STREAM_NAME,
-                      data: request
+                    initialPayload: isQRCodeFlow ? void 0 : initialPayload
+                  }).then(() => __async(this, null, function* () {
+                    if (isQRCodeFlow) {
+                      return dappClient.sendRequest(initialPayload);
                     }
-                  }).catch((error) => {
+                    return void 0;
+                  })).catch((error) => {
                     if (initialConnectionMessageHandler) {
                       this.dappClient.off(
                         "message",
@@ -2290,7 +2413,7 @@ withAnalyticsTracking_fn = function(options, execute) {
       if (isRejection) {
         yield __privateMethod(this, _RequestRouter_instances, trackWalletActionRejected_fn).call(this, options);
       } else {
-        yield __privateMethod(this, _RequestRouter_instances, trackWalletActionFailed_fn).call(this, options);
+        yield __privateMethod(this, _RequestRouter_instances, trackWalletActionFailed_fn).call(this, options, error);
       }
       if (error instanceof RPCInvokeMethodErr) {
         throw error;
@@ -2325,13 +2448,14 @@ trackWalletActionSucceeded_fn = function(options) {
     analytics.track("mmconnect_wallet_action_succeeded", props);
   });
 };
-trackWalletActionFailed_fn = function(options) {
+trackWalletActionFailed_fn = function(options, error) {
   return __async(this, null, function* () {
     const props = yield getWalletActionAnalyticsProperties(
       this.config,
       this.config.storage,
       options,
-      this.transportType
+      this.transportType,
+      extractErrorDiagnostics(error)
     );
     analytics.track("mmconnect_wallet_action_failed", props);
   });
@@ -2777,7 +2901,7 @@ var _MetaMaskConnectMultichain = class _MetaMaskConnectMultichain extends Multic
       versions: __spreadValues({
         // typeof guard needed: Metro (React Native) bundles TS source directly,
         // bypassing the tsup build that substitutes __PACKAGE_VERSION__.
-        "connect-multichain": false ? "unknown" : "0.13.0"
+        "connect-multichain": false ? "unknown" : "0.14.0"
       }, (_f = options.versions) != null ? _f : {})
     });
     super(allOptions);
@@ -3479,9 +3603,9 @@ handleConnection_fn = function(promise, scopes, transportType) {
             transport_type: transportType
           }));
         } else {
-          analytics2.track("mmconnect_connection_failed", __spreadProps(__spreadValues({}, baseProps), {
+          analytics2.track("mmconnect_connection_failed", __spreadValues(__spreadProps(__spreadValues({}, baseProps), {
             transport_type: transportType
-          }));
+          }), extractErrorDiagnostics(error)));
         }
       } catch (e) {
         logger2("Error tracking connection failed/rejected event", error);
@@ -3926,6 +4050,7 @@ export {
   StoreAdapter,
   StoreClient,
   TransportType,
+  classifyFailureReason,
   createLogger,
   createMultichainClient,
   enableDebug,