refactor: Lazy-load MWP packages + eciesjs/KeyManager behind dynamic import() (#244)

ffmcgee725 · adonesky1 · jiexi · web-flow · commit 34b87687af9c · 2026-05-04T13:27:18.000-07:00
* refactor: lazy load MWP packages + eciesjs/KeyManager behind dynamic import()

* address code review feedback

* minor adjustment

* Update packages/connect-multichain/CHANGELOG.md

Co-authored-by: Alex Donesky &lt;adonesky@gmail.com&gt;

* address code review

* fix changelog

* cleanup transportType getter

* lint

---------

Co-authored-by: Alex Donesky &lt;adonesky@gmail.com&gt;
Co-authored-by: Jiexi Luan &lt;jiexiluan@gmail.com&gt;
diff --git a/packages/connect-multichain/CHANGELOG.md b/packages/connect-multichain/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Lazy-load MWP transport dependencies: `@metamask/mobile-wallet-protocol-core`, `@metamask/mobile-wallet-protocol-dapp-client`, and `eciesjs` are now dynamically imported only when MWP transport is actually used, allowing bundlers to code-split the entire MWP + crypto dependency tree for consumers who only use the browser extension flow ([#244](https://github.com/MetaMask/connect-monorepo/pull/244))
 - Tighten `MultichainApiClientWrapperTransport` connected transport check on `wallet_getSession` and `wallet_invokeMethod`. Remove defined transport check on `wallet_revokeSession`. ([#280](https://github.com/MetaMask/connect-monorepo/pull/280))
 
 ## [0.12.1]
diff --git a/packages/connect-multichain/src/domain/multichain/index.ts b/packages/connect-multichain/src/domain/multichain/index.ts
@@ -7,13 +7,13 @@ import type {
 import type { CaipAccountId, Json } from '@metamask/utils';
 
 import { EventEmitter, type SDKEvents } from '../events';
-import type { StoreClient } from '../store/client';
 import type { InvokeMethodOptions, RPCAPI, Scope } from './api/types';
 import type {
   ExtendedTransport,
   MergeableMultichainOptions,
   MultichainOptions,
 } from './types';
+import type { StoreClient } from '../store/client';
 
 export type ConnectionStatus =
   | 'pending'
diff --git a/packages/connect-multichain/src/multichain/index.ts b/packages/connect-multichain/src/multichain/index.ts
@@ -4,14 +4,8 @@
 /* eslint-disable promise/always-return -- Event handlers */
 /* eslint-disable no-async-promise-executor -- Async promise executor needed for complex flow */
 import { analytics } from '@metamask/analytics';
-import {
-  ErrorCode,
-  ProtocolError,
-  type SessionRequest,
-  SessionStore,
-  WebSocketTransport,
-} from '@metamask/mobile-wallet-protocol-core';
-import { DappClient } from '@metamask/mobile-wallet-protocol-dapp-client';
+import type { SessionRequest } from '@metamask/mobile-wallet-protocol-core';
+import type { DappClient } from '@metamask/mobile-wallet-protocol-dapp-client';
 import {
   type SessionProperties,
   getMultichainClient,
@@ -59,8 +53,6 @@ import { RpcClient } from './rpc/handlers/rpcClient';
 import { RequestRouter } from './rpc/requestRouter';
 import { DefaultTransport } from './transports/default';
 import { MultichainApiClientWrapperTransport } from './transports/multichainApiClientWrapper';
-import { MWPTransport } from './transports/mwp';
-import { keymanager } from './transports/mwp/KeyManager';
 import {
   getDappId,
   getGlobalObject,
@@ -90,6 +82,8 @@ export class MetaMaskConnectMultichain extends MultichainCore {
 
   #beforeUnloadListener: (() => void) | undefined;
 
+  #transportType?: TransportType;
+
   public _status: ConnectionStatus = 'pending';
 
   #listener: (() => void | Promise<void>) | undefined;
@@ -126,14 +120,12 @@ export class MetaMaskConnectMultichain extends MultichainCore {
     return this.#dappClient;
   }
 
-  get storage(): StoreClient {
-    return this.options.storage;
+  get transportType(): TransportType {
+    return this.#transportType ?? TransportType.UNKNOWN;
   }
 
-  get transportType(): TransportType {
-    return this.#transport instanceof MWPTransport
-      ? TransportType.MWP
-      : TransportType.Browser;
+  get storage(): StoreClient {
+    return this.options.storage;
   }
 
   readonly #sdkInfo = `Sdk/Javascript SdkVersion/${getVersion()} Platform/${getPlatformType()} dApp/${this.options.dapp.url ?? this.options.dapp.name} dAppTitle/${this.options.dapp.name}`;
@@ -284,16 +276,15 @@ export class MetaMaskConnectMultichain extends MultichainCore {
     }
   }
 
-  async #getStoredTransport(): Promise<
-    DefaultTransport | MWPTransport | undefined
-  > {
+  async #getStoredTransport(): Promise<ExtendedTransport | undefined> {
     const transportType = await this.storage.getTransport();
     const hasExtensionInstalled = await hasExtension();
     if (transportType) {
       if (transportType === TransportType.Browser) {
         if (hasExtensionInstalled) {
           const apiTransport = new DefaultTransport();
           this.#transport = apiTransport;
+          this.#transportType = TransportType.Browser;
           this.#providerTransportWrapper.setupTransportNotificationListener();
           this.#listener = apiTransport.onNotification(
             this.#onTransportNotification.bind(this),
@@ -303,9 +294,11 @@ export class MetaMaskConnectMultichain extends MultichainCore {
       } else if (transportType === TransportType.MWP) {
         const { adapter: kvstore } = this.options.storage;
         const dappClient = await this.#createDappClient();
+        const { MWPTransport } = await import('./transports/mwp');
         const apiTransport = new MWPTransport(dappClient, kvstore);
         this.#dappClient = dappClient;
         this.#transport = apiTransport;
+        this.#transportType = TransportType.MWP;
         this.#providerTransportWrapper.setupTransportNotificationListener();
         this.#listener = apiTransport.onNotification(
           this.#onTransportNotification.bind(this),
@@ -327,7 +320,7 @@ export class MetaMaskConnectMultichain extends MultichainCore {
         await this.transport.connect();
       }
       this.status = 'connected';
-      if (this.transport instanceof MWPTransport) {
+      if (this.#transportType === TransportType.MWP) {
         await this.storage.setTransport(TransportType.MWP);
       } else {
         await this.storage.setTransport(TransportType.Browser);
@@ -374,32 +367,45 @@ export class MetaMaskConnectMultichain extends MultichainCore {
   }
 
   async #createDappClient(): Promise<DappClient> {
+    const [mwpCore, { DappClient: DappClientClass }, { createKeyManager }] =
+      await Promise.all([
+        import('@metamask/mobile-wallet-protocol-core'),
+        import('@metamask/mobile-wallet-protocol-dapp-client'),
+        import('./transports/mwp/KeyManager'),
+      ]);
+    const keymanager = await createKeyManager();
+
     const { adapter: kvstore } = this.options.storage;
-    const sessionstore = await SessionStore.create(kvstore);
+    const sessionstore = await mwpCore.SessionStore.create(kvstore);
     const websocket =
       // eslint-disable-next-line no-negated-condition
       typeof window !== 'undefined'
         ? WebSocket
         : (await import('ws')).WebSocket;
-    const transport = await WebSocketTransport.create({
+    const transport = await mwpCore.WebSocketTransport.create({
       url: MWP_RELAY_URL,
       kvstore,
       websocket,
     });
-    const dappClient = new DappClient({ transport, sessionstore, keymanager });
+    const dappClient = new DappClientClass({
+      transport,
+      sessionstore,
+      keymanager,
+    });
     return dappClient;
   }
 
   async #setupMWP(): Promise<void> {
-    if (this.#transport instanceof MWPTransport) {
+    if (this.#transportType === TransportType.MWP) {
       return;
     }
-    // Only setup MWP if it is not already mwp
     const { adapter: kvstore } = this.options.storage;
     const dappClient = await this.#createDappClient();
     this.#dappClient = dappClient;
+    const { MWPTransport } = await import('./transports/mwp');
     const apiTransport = new MWPTransport(dappClient, kvstore);
     this.#transport = apiTransport;
+    this.#transportType = TransportType.MWP;
     this.#providerTransportWrapper.setupTransportNotificationListener();
     this.#listener = this.transport.onNotification(
       this.#onTransportNotification.bind(this),
@@ -474,8 +480,10 @@ export class MetaMaskConnectMultichain extends MultichainCore {
                   this.status = 'connected';
                   await this.storage.setTransport(TransportType.MWP);
                 } catch (error) {
+                  const { ProtocolError, ErrorCode } = await import(
+                    '@metamask/mobile-wallet-protocol-core'
+                  );
                   if (error instanceof ProtocolError) {
-                    // Ignore Request expired errors to allow modal to regenerate expired qr codes
                     if (error.code !== ErrorCode.REQUEST_EXPIRED) {
                       this.status = 'disconnected';
                       // Close the modal on error
@@ -586,6 +594,9 @@ export class MetaMaskConnectMultichain extends MultichainCore {
           resolve();
         })
         .catch(async (error) => {
+          const { ProtocolError } = await import(
+            '@metamask/mobile-wallet-protocol-core'
+          );
           if (error instanceof ProtocolError) {
             // In headless mode, we don't auto-regenerate QR codes
             // since there's no modal to display them
@@ -604,8 +615,8 @@ export class MetaMaskConnectMultichain extends MultichainCore {
   async #setupDefaultTransport(
     options: { persist?: boolean } = { persist: true },
   ): Promise<DefaultTransport> {
-    if (this.#transport instanceof DefaultTransport) {
-      return this.#transport;
+    if (this.#transportType === TransportType.Browser) {
+      return this.#transport as DefaultTransport;
     }
 
     if (options?.persist) {
@@ -616,6 +627,7 @@ export class MetaMaskConnectMultichain extends MultichainCore {
       this.#onTransportNotification.bind(this),
     );
     this.#transport = transport;
+    this.#transportType = TransportType.Browser;
     this.#providerTransportWrapper.setupTransportNotificationListener();
     return transport;
   }
@@ -763,7 +775,7 @@ export class MetaMaskConnectMultichain extends MultichainCore {
   ): Promise<void> {
     if (
       this.status === 'connecting' &&
-      this.transportType === TransportType.MWP
+      this.#transportType === TransportType.MWP
     ) {
       await this.#openConnectDeeplinkIfNeeded();
       throw new Error(
@@ -834,7 +846,7 @@ export class MetaMaskConnectMultichain extends MultichainCore {
             forceRequest,
           })
           .then(async () => {
-            if (this.#transport instanceof MWPTransport) {
+            if (this.#transportType === TransportType.MWP) {
               return this.storage.setTransport(TransportType.MWP);
             }
             return this.storage.setTransport(TransportType.Browser);
@@ -951,12 +963,13 @@ export class MetaMaskConnectMultichain extends MultichainCore {
 
       // We want to leave the DefaultTransport instance connected so that we can
       // still listen for wallet_sessionChanged events.
-      if (this.transportType !== TransportType.Browser) {
+      if (this.#transportType !== TransportType.Browser) {
         await this.#listener?.();
         this.#beforeUnloadListener?.();
         this.#listener = undefined;
         this.#beforeUnloadListener = undefined;
         this.#transport = undefined;
+        this.#transportType = undefined;
         this.#providerTransportWrapper.clearTransportNotificationListener();
         this.#dappClient = undefined;
       }
@@ -973,7 +986,7 @@ export class MetaMaskConnectMultichain extends MultichainCore {
       transport,
       rpcClient,
       options,
-      this.transportType,
+      this.#transportType ?? TransportType.UNKNOWN,
     );
     // TODO: need read only method support for solana
     return requestRouter.invokeMethod(request);
diff --git a/packages/connect-multichain/src/multichain/transports/mwp/KeyManager.ts b/packages/connect-multichain/src/multichain/transports/mwp/KeyManager.ts
@@ -4,38 +4,49 @@ import type {
   IKeyManager,
   KeyPair,
 } from '@metamask/mobile-wallet-protocol-core';
-import { decrypt, encrypt, PrivateKey, PublicKey } from 'eciesjs';
 
-class KeyManager implements IKeyManager {
-  generateKeyPair(): KeyPair {
-    const privateKey = new PrivateKey();
-    return {
-      privateKey: new Uint8Array(privateKey.secret),
-      publicKey: privateKey.publicKey.toBytes(true),
-    };
-  }
+/**
+ * Creates an {@link IKeyManager} backed by the `eciesjs` library.
+ *
+ * The factory dynamically imports `eciesjs` so the heavy crypto dependency is
+ * only loaded when MWP transport is actually used. The returned object closes
+ * over the imported symbols, allowing synchronous methods like
+ * `generateKeyPair` and `validatePeerKey` to work without a second await.
+ *
+ * @returns A ready-to-use key manager instance.
+ */
+export async function createKeyManager(): Promise<IKeyManager> {
+  const { decrypt, encrypt, PrivateKey, PublicKey } = await import('eciesjs');
 
-  async encrypt(
-    plaintext: string,
-    theirPublicKey: Uint8Array,
-  ): Promise<string> {
-    const plaintextBuffer = Buffer.from(plaintext, 'utf8');
-    const encryptedBuffer = encrypt(theirPublicKey, plaintextBuffer);
-    return encryptedBuffer.toString('base64');
-  }
+  return {
+    generateKeyPair(): KeyPair {
+      const privateKey = new PrivateKey();
+      return {
+        privateKey: new Uint8Array(privateKey.secret),
+        publicKey: privateKey.publicKey.toBytes(true),
+      };
+    },
 
-  async decrypt(
-    encryptedB64: string,
-    myPrivateKey: Uint8Array,
-  ): Promise<string> {
-    const encryptedBuffer = Buffer.from(encryptedB64, 'base64');
-    const decryptedBuffer = await decrypt(myPrivateKey, encryptedBuffer);
-    return Buffer.from(decryptedBuffer).toString('utf8');
-  }
+    async encrypt(
+      plaintext: string,
+      theirPublicKey: Uint8Array,
+    ): Promise<string> {
+      const plaintextBuffer = Buffer.from(plaintext, 'utf8');
+      const encryptedBuffer = encrypt(theirPublicKey, plaintextBuffer);
+      return encryptedBuffer.toString('base64');
+    },
 
-  validatePeerKey(key: Uint8Array): void {
-    PublicKey.fromHex(Buffer.from(key).toString('hex'));
-  }
-}
+    async decrypt(
+      encryptedB64: string,
+      myPrivateKey: Uint8Array,
+    ): Promise<string> {
+      const encryptedBuffer = Buffer.from(encryptedB64, 'base64');
+      const decryptedBuffer = await decrypt(myPrivateKey, encryptedBuffer);
+      return Buffer.from(decryptedBuffer).toString('utf8');
+    },
 
-export const keymanager = new KeyManager();
+    validatePeerKey(key: Uint8Array): void {
+      PublicKey.fromHex(Buffer.from(key).toString('hex'));
+    },
+  };
+}
diff --git a/packages/connect-multichain/src/multichain/transports/mwp/index.ts b/packages/connect-multichain/src/multichain/transports/mwp/index.ts
@@ -16,7 +16,6 @@ import type {
   Session,
   SessionRequest,
 } from '@metamask/mobile-wallet-protocol-core';
-import { SessionStore } from '@metamask/mobile-wallet-protocol-core';
 import type { DappClient } from '@metamask/mobile-wallet-protocol-dapp-client';
 import {
   type SessionProperties,
@@ -813,6 +812,9 @@ export class MWPTransport implements ExtendedTransport {
 
   async getActiveSession(): Promise<Session | undefined> {
     const { kvstore } = this;
+    const { SessionStore } = await import(
+      '@metamask/mobile-wallet-protocol-core'
+    );
     const sessionStore = await SessionStore.create(kvstore);
 
     try {
