add(SDKConnectV2) - Scaffolding (MetaMask#18305)

chakra-guy · adonesky1 · web-flow · commit 5f7cf82438f0 · 2025-08-22T21:57:29.000Z
## **Description** This PR scaffolds the architecture for the new **Mobile Wallet Protocol**, which will be housed within the `core/SDKConnectV2/` directory. The long-term goal is to replace the legacy `SDKConnect` system with a modern, robust, and multichain-first protocol. This PR represents the first step in a series of planned implementations. Specifically, this PR: * Creates the `core/SDKConnectV2/` directory structure. * Introduces the central orchestrator service, `ConnectionRegistry`. * Defines the key decoupling interface, `IHostApplicationAdapter`. * Makes a minimal, surgical modification to `handleMetaMaskDeeplink.ts` to identify and route `v=2` deeplinks to the new `ConnectionRegistry`. There are no user-facing changes in this pull request. Its sole purpose is to lay the groundwork and validate the control flow redirection from the legacy system to the new V2 module. **Upcoming pull-requests will be broken by business logic:** 1. Connection handling 2. Message handling 3. Disconnect 4. Connection resumption ## **Changelog**  CHANGELOG entry: null ## **Related issues** Fixes: ## **Manual testing steps** None. Scaffolding only. ## **Screenshots/Recordings**  ### **Before**  ### **After**  ## **Pre-merge author checklist** - [ ] I’ve followed [MetaMask Contributor Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile Coding Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md). - [ ] I've completed the PR template to the best of my ability - [ ] I’ve included tests if applicable - [ ] I’ve documented my code using [JSDoc](https://jsdoc.app/) format if applicable - [ ] I’ve applied the right labels on the PR (see [labeling guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)). Not required for external contributors. ## **Pre-merge reviewer checklist** - [ ] I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed). - [ ] I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots. --------- Co-authored-by: Alex Donesky <adonesky@gmail.com>
diff --git a/app/core/DeeplinkManager/ParseManager/handleMetaMaskDeeplink.test.ts b/app/core/DeeplinkManager/ParseManager/handleMetaMaskDeeplink.test.ts
@@ -5,6 +5,7 @@ import Device from '../../../util/device';
 import AppConstants from '../../AppConstants';
 import handleDeeplink from '../../SDKConnect/handlers/handleDeeplink';
 import SDKConnect from '../../SDKConnect/SDKConnect';
+import SDKConnectV2 from '../../SDKConnectV2';
 import WC2Manager from '../../WalletConnect/WalletConnectV2';
 import DeeplinkManager from '../DeeplinkManager';
 import extractURLParams from './extractURLParams';
@@ -13,6 +14,7 @@ import handleMetaMaskDeeplink from './handleMetaMaskDeeplink';
 jest.mock('../../../core/AppConstants');
 jest.mock('../../../core/SDKConnect/handlers/handleDeeplink');
 jest.mock('../../../core/SDKConnect/SDKConnect');
+jest.mock('../../../core/SDKConnectV2');
 jest.mock('../../../core/WalletConnect/WalletConnectV2');
 jest.mock('../../../core/NativeModules', () => ({
   Minimizer: {
@@ -110,6 +112,30 @@ describe('handleMetaMaskProtocol', () => {
     expect(handled).toHaveBeenCalled();
   });
 
+  describe('when url starts with ${PREFIXES.METAMASK}${ACTIONS.CONNECT}/mwp', () => {
+    const spyHandleConnectDeeplink = jest.spyOn(
+      SDKConnectV2,
+      'handleConnectDeeplink',
+    );
+    beforeEach(() => {
+      url = `${PREFIXES.METAMASK}${ACTIONS.CONNECT}/mwp`;
+      spyHandleConnectDeeplink.mockImplementation(jest.fn());
+    });
+
+    it('should call SDKConnectV2.handleConnectDeeplink', () => {
+      handleMetaMaskDeeplink({
+        instance,
+        handled,
+        params,
+        url,
+        origin,
+        wcURL,
+      });
+
+      expect(spyHandleConnectDeeplink).toHaveBeenCalledWith(url);
+    });
+  });
+
   describe('when url starts with ${PREFIXES.METAMASK}${ACTIONS.ANDROID_SDK}', () => {
     beforeEach(() => {
       url = `${PREFIXES.METAMASK}${ACTIONS.ANDROID_SDK}`;
diff --git a/app/core/DeeplinkManager/ParseManager/handleMetaMaskDeeplink.ts b/app/core/DeeplinkManager/ParseManager/handleMetaMaskDeeplink.ts
@@ -10,6 +10,8 @@ import WC2Manager from '../../WalletConnect/WalletConnectV2';
 import DeeplinkManager from '../DeeplinkManager';
 import parseOriginatorInfo from '../parseOriginatorInfo';
 import extractURLParams from './extractURLParams';
+import SDKConnectV2 from '../../SDKConnectV2';
+
 export function handleMetaMaskDeeplink({
   instance,
   handled,
@@ -26,6 +28,7 @@ export function handleMetaMaskDeeplink({
   url: string;
 }) {
   handled();
+
   if (url.startsWith(`${PREFIXES.METAMASK}${ACTIONS.ANDROID_SDK}`)) {
     DevLogger.log(
       `DeeplinkManager:: metamask launched via android sdk deeplink`,
@@ -38,6 +41,15 @@ export function handleMetaMaskDeeplink({
     return;
   }
 
+  if (url.startsWith(`${PREFIXES.METAMASK}${ACTIONS.CONNECT}/mwp`)) {
+    DevLogger.log(
+      `DeeplinkManager:: Mobile Wallet Protocol deeplink detected. Routing to SDKConnectV2.`,
+      url,
+    );
+    SDKConnectV2.handleConnectDeeplink(url);
+    return;
+  }
+
   if (url.startsWith(`${PREFIXES.METAMASK}${ACTIONS.CONNECT}`)) {
     if (params.redirect && origin === AppConstants.DEEPLINKS.ORIGIN_DEEPLINK) {
       SDKConnect.getInstance().state.navigation?.navigate(
diff --git a/app/core/SDKConnectV2/adapters/host-application-adapter.test.ts b/app/core/SDKConnectV2/adapters/host-application-adapter.test.ts
@@ -0,0 +1,24 @@
+import { HostApplicationAdapter } from './host-application-adapter';
+
+describe('HostApplicationAdapter', () => {
+  let adapter: HostApplicationAdapter;
+
+  beforeEach(() => {
+    adapter = new HostApplicationAdapter();
+  });
+
+  it('dummy tests for scaffolding, will be replaced with real tests', () => {
+    expect(adapter).toBeDefined();
+    expect(
+      adapter.showConnectionApproval('test-id', {
+        name: 'test-dapp-name',
+        url: 'test-dapp-url',
+        icon: 'test-dapp-icon',
+      }),
+    ).resolves.not.toThrow();
+    expect(() => adapter.showLoading()).not.toThrow();
+    expect(() => adapter.hideLoading()).not.toThrow();
+    expect(adapter.showOTPModal()).resolves.not.toThrow();
+    expect(() => adapter.syncConnectionList([])).not.toThrow();
+  });
+});
diff --git a/app/core/SDKConnectV2/adapters/host-application-adapter.ts b/app/core/SDKConnectV2/adapters/host-application-adapter.ts
@@ -0,0 +1,40 @@
+import { Connection } from '../types/connection';
+import { DappMetadata } from '../types/dapp-metadata';
+import { IHostApplicationAdapter } from '../types/host-application-adapter';
+
+export class HostApplicationAdapter implements IHostApplicationAdapter {
+  showConnectionApproval(
+    _connectionId: string,
+    _dappMetadata: DappMetadata,
+  ): Promise<void> {
+    console.warn(
+      '[SDKConnectV2] HostApplicationAdapter.showConnectionApproval called but is not yet implemented.',
+    );
+    return Promise.resolve();
+  }
+
+  showLoading(): void {
+    console.warn(
+      '[SDKConnectV2] HostApplicationAdapter.showLoading called but is not yet implemented.',
+    );
+  }
+
+  hideLoading(): void {
+    console.warn(
+      '[SDKConnectV2] HostApplicationAdapter.hideLoading called but is not yet implemented.',
+    );
+  }
+
+  showOTPModal(): Promise<void> {
+    console.warn(
+      '[SDKConnectV2] HostApplicationAdapter.showOTPModal called but is not yet implemented.',
+    );
+    return Promise.resolve();
+  }
+
+  syncConnectionList(_connections: Connection[]): void {
+    console.warn(
+      '[SDKConnectV2] HostApplicationAdapter.syncConnectionList called but is not yet implemented.',
+    );
+  }
+}
diff --git a/app/core/SDKConnectV2/index.ts b/app/core/SDKConnectV2/index.ts
@@ -0,0 +1,9 @@
+import { HostApplicationAdapter } from './adapters/host-application-adapter';
+import { ConnectionStore } from './store/connection-store';
+import { ConnectionRegistry } from './services/connection-registry';
+
+const hostapp = new HostApplicationAdapter();
+const store = new ConnectionStore();
+const registry = new ConnectionRegistry(hostapp, store);
+
+export default registry;
diff --git a/app/core/SDKConnectV2/services/connection-registry.test.ts b/app/core/SDKConnectV2/services/connection-registry.test.ts
@@ -0,0 +1,18 @@
+import { ConnectionRegistry } from './connection-registry';
+import { HostApplicationAdapter } from '../adapters/host-application-adapter';
+import { ConnectionStore } from '../store/connection-store';
+
+describe('ConnectionRegistry', () => {
+  let registry: ConnectionRegistry;
+
+  beforeEach(() => {
+    const hostapp = new HostApplicationAdapter();
+    const store = new ConnectionStore();
+    registry = new ConnectionRegistry(hostapp, store);
+  });
+
+  it('dummy tests for scaffolding, will be replaced with real tests', () => {
+    expect(registry).toBeDefined();
+    expect(() => registry.handleConnectDeeplink('test-deeplink')).not.toThrow();
+  });
+});
diff --git a/app/core/SDKConnectV2/services/connection-registry.ts b/app/core/SDKConnectV2/services/connection-registry.ts
@@ -0,0 +1,44 @@
+import { IHostApplicationAdapter } from '../types/host-application-adapter';
+import { IConnectionStore } from '../types/connection-store';
+
+/**
+ * The ConnectionRegistry is the central service responsible for managing the
+ * lifecycle of all SDKConnectV2 connections. It acts as the primary entry
+ * point and orchestrator for creating, managing, and tearing down secure
+ * dApp sessions.
+ */
+export class ConnectionRegistry {
+  private readonly hostapp: IHostApplicationAdapter;
+  private readonly store: IConnectionStore;
+
+  /**
+   * The constructor for the ConnectionRegistry.
+   *
+   * @param hostapp - An adapter that provides a bridge to the
+   * host MetaMask Mobile application's UI and state management systems.
+   * @param store - An adapter for the persistence layer, used to
+   * save and retrieve connection data.
+   */
+  constructor(hostapp: IHostApplicationAdapter, store: IConnectionStore) {
+    this.hostapp = hostapp;
+    this.store = store;
+  }
+
+  /**
+   * The primary entry point for handling a new connection request from a
+   * v2 deeplink (e.g., from a QR code).
+   * @param url - The full deeplink URL that triggered the connection.
+   */
+  public handleConnectDeeplink(url: string): void {
+    console.warn(
+      '[SDKConnectV2] ConnectionRegistry: handleConnectDeeplink successfully called with URL:',
+      url,
+    );
+
+    // In future, this method will be responsible for:
+    // 1. Parsing the URL to extract the ConnectionRequest.
+    // 2. Calling the hostapp to show the connection approval UI.
+    // 3. Initiating the cryptographic handshake upon user approval.
+    // 4. Saving the resulting connection to the store.
+  }
+}
diff --git a/app/core/SDKConnectV2/store/connection-store.test.ts b/app/core/SDKConnectV2/store/connection-store.test.ts
@@ -0,0 +1,18 @@
+import { ConnectionStore } from './connection-store';
+import { Connection } from '../types/connection';
+
+describe('ConnectionStore', () => {
+  let store: ConnectionStore;
+
+  beforeEach(() => {
+    store = new ConnectionStore();
+  });
+
+  it('dummy tests for scaffolding, will be replaced with real tests', () => {
+    expect(store).toBeDefined();
+    expect(store.save({} as Connection)).resolves.not.toThrow();
+    expect(store.get('test-id')).resolves.toBeNull();
+    expect(store.list()).resolves.toEqual([]);
+    expect(store.delete('test-id')).resolves.not.toThrow();
+  });
+});
diff --git a/app/core/SDKConnectV2/store/connection-store.ts b/app/core/SDKConnectV2/store/connection-store.ts
@@ -0,0 +1,38 @@
+import { Connection } from '../types/connection';
+import { IConnectionStore } from '../types/connection-store';
+
+/**
+ * Placeholder implementation of the IConnectionStore.
+ * For now, this class provides no-op implementations of the
+ * required storage methods to satisfy the dependency requirements
+ * of the ConnectionRegistry.
+ */
+export class ConnectionStore implements IConnectionStore {
+  save(_connection: Connection): Promise<void> {
+    console.warn(
+      '[SDKConnectV2] ConnectionStore.save called but is not yet implemented.',
+    );
+    return Promise.resolve();
+  }
+
+  get(_id: string): Promise<Connection | null> {
+    console.warn(
+      '[SDKConnectV2] ConnectionStore.get called but is not yet implemented.',
+    );
+    return Promise.resolve(null);
+  }
+
+  list(): Promise<Connection[]> {
+    console.warn(
+      '[SDKConnectV2] ConnectionStore.list called but is not yet implemented.',
+    );
+    return Promise.resolve([]);
+  }
+
+  delete(_id: string): Promise<void> {
+    console.warn(
+      '[SDKConnectV2] ConnectionStore.delete called but is not yet implemented.',
+    );
+    return Promise.resolve();
+  }
+}
diff --git a/app/core/SDKConnectV2/types/connection-request.ts b/app/core/SDKConnectV2/types/connection-request.ts
@@ -0,0 +1,22 @@
+import { SessionRequest } from '@metamask/mobile-wallet-protocol-core';
+import { DappMetadata } from './dapp-metadata';
+
+/**
+ * Represents an incoming connection request parsed from a QR code or deep link.
+ * This is the shared data contract between the dApp SDK and the mobile wallet,
+ * as defined in the technical proposal. It encapsulates all the information
+ * needed to initiate a new session.
+ */
+export interface ConnectionRequest {
+  /**
+   * The low-level protocol session request, containing cryptographic
+   * and channel information.
+   */
+  sessionRequest: SessionRequest;
+
+  /**
+   * Metadata about the decentralized application (dApp) that is
+   * requesting the connection.
+   */
+  dappMetadata: DappMetadata;
+}
diff --git a/app/core/SDKConnectV2/types/connection-store.ts b/app/core/SDKConnectV2/types/connection-store.ts
@@ -0,0 +1,38 @@
+import { Connection } from './connection';
+
+/**
+ * Defines the contract for the persistence layer that will act as the
+ * single source of truth for all SDKConnectV2 connections.
+ *
+ * This interface abstracts the underlying storage mechanism, allowing the
+ * core services to remain unaware of implementation details like AsyncStorage
+ * or Secure Keychain storage.
+ */
+export interface IConnectionStore {
+  /**
+   * Persists a new or updated connection object.
+   * @param connection The connection object to save.
+   * @returns A promise that resolves when the save operation is complete.
+   */
+  save(connection: Connection): Promise<void>;
+
+  /**
+   * Retrieves a single connection by its unique ID.
+   * @param id The ID of the connection to retrieve.
+   * @returns A promise that resolves with the Connection object, or null if not found.
+   */
+  get(id: string): Promise<Connection | null>;
+
+  /**
+   * Retrieves a list of all persisted connections.
+   * @returns A promise that resolves with an array of all Connection objects.
+   */
+  list(): Promise<Connection[]>;
+
+  /**
+   * Deletes a connection from storage by its unique ID.
+   * @param id The ID of the connection to delete.
+   * @returns A promise that resolves when the delete operation is complete.
+   */
+  delete(id: string): Promise<void>;
+}
diff --git a/app/core/SDKConnectV2/types/connection.ts b/app/core/SDKConnectV2/types/connection.ts
@@ -0,0 +1,47 @@
+import { Session } from '@metamask/mobile-wallet-protocol-core';
+import { WalletClient } from '@metamask/mobile-wallet-protocol-wallet-client';
+import { BackgroundBridge } from '../../BackgroundBridge/BackgroundBridge';
+import { DappMetadata } from './dapp-metadata';
+
+/**
+ * Represents a fully established, user-approved, and persisted connection.
+ * This is the primary domain object managed by the SDKConnectV2 system,
+ * combining the protocol-level session with application-level metadata and
+ * runtime clients.
+ */
+export interface Connection {
+  /**
+   * The unique identifier for this connection, used as the 'origin' for
+   * the permissions system. This ID is derived from the underlying
+   * protocol session's ID.
+   */
+  id: string;
+
+  /**
+   * The low-level, protocol-specific session object. It contains the
+   * cryptographic keys and channel information required for secure
+   * communication. This is the primary object to be persisted securely.
+   */
+  session: Session;
+
+  /**
+   * Metadata about the connected dApp. This data is persisted alongside
+   * the session.
+   */
+  dappMetadata: DappMetadata;
+
+  /**
+   * The live, in-memory client instance for this connection, provided by the
+   * vendored wallet-client library. This property is for runtime use only
+   * and is NOT persisted to storage.
+   */
+  client: WalletClient;
+
+  /**
+   * The dedicated RPC message handler for this specific connection. Each
+   * connection gets its own bridge to process dApp requests and route them
+   * to the core multichain engine. This property is for runtime use only
+   * and is NOT persisted.
+   */
+  bridge: BackgroundBridge;
+}
diff --git a/app/core/SDKConnectV2/types/dapp-metadata.ts b/app/core/SDKConnectV2/types/dapp-metadata.ts
@@ -0,0 +1,8 @@
+/**
+ * Metadata about the connected dApp.
+ */
+export interface DappMetadata {
+  name: string;
+  url: string;
+  icon?: string;
+}
diff --git a/app/core/SDKConnectV2/types/host-application-adapter.ts b/app/core/SDKConnectV2/types/host-application-adapter.ts
diff --git a/metro.config.js b/metro.config.js
diff --git a/package.json b/package.json
diff --git a/yarn.lock b/yarn.lock
