@metamask/connect-multichain 0.14.0 → 1.0.0

package/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0]
+
+### Added
+
+- Add `version` getter to `MultichainCore` and `MetaMaskConnectMultichain` that returns the runtime package version ([#253](https://github.com/MetaMask/connect-monorepo/pull/253))
+- Warn at runtime when an existing singleton has a different version than the newly requested instance, indicating duplicate `@metamask/connect-multichain` resolutions ([#253](https://github.com/MetaMask/connect-monorepo/pull/253))
+
+### Changed
+
+- This release promotes @metamask/connect-multichain to a stable 1.0. From here it follows semver strictly — 1.x minor and patch releases will be backward-compatible, and breaking changes will only land in a future major. This lets the ecosystem packages (connect-evm, connect-solana, any future ecosystem packages) depend on ^1.0.0 and pick up all future 1.x improvements without a coordinated re-release, and gives consumers a dependable compatibility contract. ([#317](https://github.com/MetaMask/connect-monorepo/pull/317))
+- Rename the storage API methods for the persisted transport type from `getTransport`, `setTransport`, and `removeTransport` to `getTransportType`, `setTransportType`, and `removeTransportType`. The existing `multichain-transport` storage key is unchanged, so no persisted data migration is required. ([#307](https://github.com/MetaMask/connect-monorepo/pull/307))
+- `getVersion()` now returns the real package version injected at build time via `__PACKAGE_VERSION__`, instead of a hardcoded `'0.0.0'` ([#253](https://github.com/MetaMask/connect-monorepo/pull/253))
+- Refactor `MWPTransport.connect()` and other internals to replace deeply nested `new Promise()` and event-callback patterns with deferred promises, reducing nesting and breaking `connect()` into smaller helpers. No behavior change. ([#305](https://github.com/MetaMask/connect-monorepo/pull/305))
+
+### Removed
+
+- **BREAKING:** Remove the `transport.onNotification` constructor option from `createMultichainClient()`. The option was a fan-out of every typed event already exposed via `client.on(...)`. Migrate to the typed event API: `client.on('stateChanged' | 'wallet_sessionChanged' | 'metamask_accountsChanged' | 'metamask_chainChanged' | 'display_uri', handler)`. ([#318](https://github.com/MetaMask/connect-monorepo/pull/318))
+- **BREAKING:** Remove the public `transport` accessor from `MultichainCore` and `MetaMaskConnectMultichain`. Consumers that previously reached the underlying transport to invoke EIP-1193 / legacy provider methods (`wallet_addEthereumChain`, `wallet_switchEthereumChain`, `eth_accounts`) should now go through `client.invokeMethod({ scope, request: { method, params } })`. `RequestRouter` recognizes those methods as EIP-1193 passthroughs and forwards the raw payload to the active transport's `sendEip1193Message`, so behavior is preserved. All other RPCs continue to flow through `invokeMethod` unchanged. ([#318](https://github.com/MetaMask/connect-monorepo/pull/318))
+
+### Fixed
+
+- Restrict EIP-6963 extension detection to native MetaMask RDNS values so MMConnect-managed provider announcements do not select the browser-extension transport. ([#304](https://github.com/MetaMask/connect-monorepo/pull/304))
+- Failed `createMultichainClient()` singleton initialization now rethrows after clearing the stored singleton promise, preventing the cleanup path from resolving to `undefined` and preserving retry behavior. ([#306](https://github.com/MetaMask/connect-monorepo/pull/306))
+- `MWPTransport.request()` and `sendEip1193Message()` now reject wallet response errors returned as `result.error`, matching `DefaultTransport` error handling and preserving wallet error codes. ([#311](https://github.com/MetaMask/connect-monorepo/pull/311))
+- `MetaMaskConnectMultichain.#headlessConnect()` now removes the `dappClient` `session_request` listener once the connection settles, preventing each headless `connect()` call from leaking a listener that would re-emit `display_uri` with stale deeplinks for every subsequent session request. ([#314](https://github.com/MetaMask/connect-monorepo/pull/314))
+
+## [0.15.0]
+
+### Added
+
+- Add an `analytics.enabled` option to `createMultichainClient()`. Set it to `false` to disable dapp-side analytics events and omit `analytics.remote_session_id` connection metadata. ([#303](https://github.com/MetaMask/connect-monorepo/pull/303))
+
 ## [0.14.0]
 
 ### Added
@@ -277,7 +309,9 @@ 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.14.0...HEAD
+[Unreleased]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@1.0.0...HEAD
+[1.0.0]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.15.0...@metamask/connect-multichain@1.0.0
+[0.15.0]: https://github.com/MetaMask/connect-monorepo/compare/@metamask/connect-multichain@0.14.0...@metamask/connect-multichain@0.15.0
 [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

package/README.md

@@ -138,25 +138,25 @@ Factory function to create a new Multichain SDK instance.
 
 #### Parameters
 
-| Option                      | Type                                          | Required | Description                                                                                                     |
-| --------------------------- | --------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
-| `dapp.name`                 | `string`                                      | Yes      | Name of your dApp                                                                                               |
-| `api.supportedNetworks`     | `RpcUrlsMap`                                  | Yes      | Map of [CAIP-2 chain IDs](https://chainagnostic.org/CAIPs/caip-2) to RPC URLs                                   |
-| `dapp.url`                  | `string`                                      | No       | URL of your dApp                                                                                                |
-| `dapp.iconUrl`              | `string`                                      | No       | Icon URL for your dApp                                                                                          |
-| `dapp.base64Icon`           | `string`                                      | No       | Base64-encoded icon (alternative to iconUrl)                                                                    |
-| `storage`                   | `StoreClient`                                 | No       | Custom storage adapter                                                                                          |
-| `ui.factory`                | `BaseModalFactory`                            | No       | Custom modal factory                                                                                            |
-| `ui.headless`               | `boolean`                                     | No       | Run without UI (for custom QR implementations)                                                                  |
-| `ui.preferExtension`        | `boolean`                                     | No       | Prefer browser extension (default: true)                                                                        |
-| `ui.showInstallModal`       | `boolean`                                     | No       | Show installation modal                                                                                         |
-| `mobile.preferredOpenLink`  | `(deeplink: string, target?: string) => void` | No       | Custom deeplink handler                                                                                         |
-| `mobile.useDeeplink`        | `boolean`                                     | No       | Use `metamask://` instead of universal links                                                                    |
-| `analytics.integrationType` | `string`                                      | No       | Integration type for analytics                                                                                  |
-| `transport.extensionId`     | `string`                                      | No       | Custom extension ID                                                                                             |
-| `transport.onNotification`  | `(notification: unknown) => void`             | No       | Notification handler                                                                                            |
-| `versions`                  | `Partial<ConnectVersions>`                    | No       | Internal: set automatically by `createEVMClient` / `createSolanaClient`. Consumers do not need to provide this. |
-| `debug`                     | `boolean`                                     | No       | Enable debug logging                                                                                            |
+| Option                      | Type                                          | Required | Description                                                                                                                  |
+| --------------------------- | --------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `dapp.name`                 | `string`                                      | Yes      | Name of your dApp                                                                                                            |
+| `api.supportedNetworks`     | `RpcUrlsMap`                                  | Yes      | Map of [CAIP-2 chain IDs](https://chainagnostic.org/CAIPs/caip-2) to RPC URLs                                                |
+| `dapp.url`                  | `string`                                      | No       | URL of your dApp                                                                                                             |
+| `dapp.iconUrl`              | `string`                                      | No       | Icon URL for your dApp                                                                                                       |
+| `dapp.base64Icon`           | `string`                                      | No       | Base64-encoded icon (alternative to iconUrl)                                                                                 |
+| `storage`                   | `StoreClient`                                 | No       | Custom storage adapter                                                                                                       |
+| `ui.factory`                | `BaseModalFactory`                            | No       | Custom modal factory                                                                                                         |
+| `ui.headless`               | `boolean`                                     | No       | Run without UI (for custom QR implementations)                                                                               |
+| `ui.preferExtension`        | `boolean`                                     | No       | Prefer browser extension (default: true)                                                                                     |
+| `ui.showInstallModal`       | `boolean`                                     | No       | Show installation modal                                                                                                      |
+| `mobile.preferredOpenLink`  | `(deeplink: string, target?: string) => void` | No       | Custom deeplink handler                                                                                                      |
+| `mobile.useDeeplink`        | `boolean`                                     | No       | Use `metamask://` instead of universal links                                                                                 |
+| `analytics.enabled`         | `boolean`                                     | No       | Enables dapp-side analytics. Defaults to `true`; set to `false` to disable analytics events and wallet correlation metadata. |
+| `analytics.integrationType` | `string`                                      | No       | Integration type for analytics                                                                                               |
+| `transport.extensionId`     | `string`                                      | No       | Custom extension ID                                                                                                          |
+| `versions`                  | `Partial<ConnectVersions>`                    | No       | Internal: set automatically by `createEVMClient` / `createSolanaClient`. Consumers do not need to provide this.              |
+| `debug`                     | `boolean`                                     | No       | Enable debug logging                                                                                                         |
 
 #### Returns
 

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

@@ -406,6 +406,19 @@ type ConnectionRequest = {
 type ConnectVersions = {
     'connect-multichain': string;
 } & Partial<Record<'connect-evm' | 'connect-solana', string>>;
+type AnalyticsOptions = {
+    /**
+     * Whether to enable analytics tracking. Defaults to `true` when omitted.
+     * Set to `false` to disable all analytics event collection.
+     */
+    enabled?: boolean;
+    /**
+     * Identifies the integration surface that instantiated the SDK (e.g. `'direct'`,
+     * `'wagmi'`). Recorded as the `integration_types` global analytics property.
+     * Defaults to `'direct'` when omitted or empty.
+     */
+    integrationType?: string;
+};
 /**
  * Constructor options for creating a Multichain SDK instance.
  *
@@ -422,9 +435,7 @@ type MultichainOptions = {
         supportedNetworks: RpcUrlsMap;
     };
     /** Analytics configuration */
-    analytics?: {
-        integrationType: string;
-    };
+    analytics?: AnalyticsOptions;
     /** Storage client for persisting SDK data */
     storage: StoreClient;
     /** UI configuration options */
@@ -447,7 +458,6 @@ type MultichainOptions = {
     transport?: {
         /** Extension ID for browser extension transport */
         extensionId?: string;
-        onNotification?: (notification: unknown) => void;
     };
     /** Enable debug logging */
     debug?: boolean;
@@ -464,6 +474,7 @@ type MultiChainFNOptions = Omit<MultichainOptions, 'storage' | 'ui'> & {
  * with an existing singleton.
  */
 type MergeableMultichainOptions = Omit<MultichainOptions, 'dapp' | 'analytics' | 'storage' | 'api' | 'ui' | 'transport' | 'versions'> & {
+    analytics?: AnalyticsOptions;
     api?: MultichainOptions['api'];
     ui?: Pick<MultichainOptions['ui'], 'headless' | 'preferExtension' | 'showInstallModal'>;
     transport?: Pick<NonNullable<MultichainOptions['transport']>, 'extensionId'>;
@@ -496,6 +507,7 @@ type ExtendedTransport = Omit<Transport, 'connect'> & {
 declare const infuraRpcUrls: RpcUrlsMap;
 declare const RPC_HANDLED_METHODS: Set<string>;
 declare const SDK_HANDLED_METHODS: Set<string>;
+declare const EIP1193_PASSTHROUGH_METHODS: Set<string>;
 
 /**
  * Generates Infura RPC URLs for common networks keyed by CAIP Chain ID.
@@ -527,8 +539,8 @@ declare abstract class MultichainCore extends EventEmitter<SDKEvents> {
     abstract storage: StoreClient;
     abstract status: ConnectionStatus;
     abstract provider: MultichainApiClient<RPCAPI>;
-    abstract transport: ExtendedTransport;
     abstract transportType: TransportType;
+    abstract version: string;
     /**
      * Establishes a connection to the multichain provider, or re-use existing session
      *
@@ -553,7 +565,7 @@ declare abstract class MultichainCore extends EventEmitter<SDKEvents> {
     constructor(options: MultichainOptions);
     /**
      * Merges the given options into the current instance options.
-     * Only the mergeable keys are updated (api.supportedNetworks, versions, ui.*, mobile.*, transport.extensionId, debug).
+     * Only the mergeable keys are updated (api.supportedNetworks, analytics, versions, ui.*, mobile.*, transport.extensionId, debug).
      * The main thing to note is that the value for `dapp` is not merged as it does not make sense for
      * subsequent calls to `createMultichainClient` to have a different `dapp` value.
      * Used when createMultichainClient is called with an existing singleton.
@@ -569,9 +581,9 @@ declare abstract class StoreClient {
     abstract getAnonId(): Promise<string>;
     abstract getExtensionId(): Promise<string | null>;
     abstract setExtensionId(extensionId: string): Promise<void>;
-    abstract getTransport(): Promise<TransportType | null>;
-    abstract setTransport(transport: TransportType): Promise<void>;
-    abstract removeTransport(): Promise<void>;
+    abstract getTransportType(): Promise<TransportType | null>;
+    abstract setTransportType(transportType: TransportType): Promise<void>;
+    abstract removeTransportType(): Promise<void>;
     abstract setAnonId(anonId: string): Promise<void>;
     abstract removeExtensionId(): Promise<void>;
     abstract removeAnonId(): Promise<void>;
@@ -748,6 +760,7 @@ declare function getWalletActionAnalyticsProperties(options: MultichainOptions,
     error_message_sample?: string;
 }>;
 
+declare const packageVersion: string;
 /**
  * Returns the version of the Multichain SDK.
  *
@@ -757,4 +770,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 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 };
+export { type AnalyticsOptions, type ConnectVersions, type ConnectionRequest, type ConnectionStatus, type CreateMultichainFN, type DappSettings, type DataType, type DomainErrorCodes, EIP1193_PASSTHROUGH_METHODS, 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, packageVersion };