fix: add modal abstraction, platform detection and onboarding

[elribonazo]

Explanation

PR is introducing:

1. The UI abstraction and the existing modals with no UI changes (install, pending, select)
2. Checking platform detection when SDK starts
3. Transport + Session restoration when SDK initialize

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've highlighted breaking changes using the "BREAKING" category above as appropriate

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 74.93%. Comparing base (0ad4c95) to head (18e08d2).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1325   +/-   ##
=======================================
  Coverage   74.93%   74.93%           
=======================================
  Files         184      184           
  Lines        4513     4513           
  Branches     1105     1105           
=======================================
  Hits         3382     3382           
  Misses       1131     1131           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cursor]

Bug: Callback Context Issue and Global Variable Conflict

The onTransportNotification method is passed as a callback to __transport.onNotification without binding its this context, causing this.emit() to fail when invoked. Additionally, the SDK uses global __provider and __transport variables, which breaks encapsulation. A disconnect() call from one SDK instance will clear these globals, inadvertently breaking other active SDK instances.

packages/sdk-multichain/src/multichain/index.ts#L33-L337

metamask-sdk/packages/sdk-multichain/src/multichain/index.ts

Lines 33 to 337 in 8bb171f

	let __provider: MultichainApiClient<RPCAPI> | undefined;
	let __transport: Transport | undefined;
	export class MultichainSDK extends MultichainCore {
	public state: SDKState;
	private listeners: (() => void)[] = [];
	/**
	* Static method to reset global state - useful for testing
	* @internal
	*/
	static resetGlobals() {
	__provider = undefined;
	__transport = undefined;
	}
	private get client() {
	const platformType = getPlatformType();
	const sdkInfo = `Sdk/Javascript SdkVersion/${packageJson.version} Platform/${platformType} dApp/${this.options.dapp.url ?? this.options.dapp.name} dAppTitle/${this.options.dapp.name}`;
	return new RPCClient(this.provider, this.options.api, sdkInfo);
	}
	get provider() {
	if (!__provider) {
	throw new Error('Provider not initialized, establish connection first');
	}
	return __provider;
	}
	get transport() {
	if (!__transport) {
	throw new Error('Transport not initialized, establish connection first');
	}
	return __transport;
	}
	private async getCurrentSession(): Promise<SessionData | undefined> {
	try {
	//TODO: We should report to the multichain api team that when there's no extension installed
	// getSession timeouts and should be just undefined
	// Thats why we need this function, to compensate that
	let validSession: SessionData | undefined;
	const session = await this.provider.getSession();
	if (Object.keys(session?.sessionScopes ?? {}).length > 0) {
	validSession = session;
	}
	return validSession;
	} catch (err) {
	logger('MetaMaskSDK error during getCurrentSession', err);
	return undefined;
	}
	}
	get storage() {
	return this.options.storage;
	}
	private constructor(options: MultichainOptions) {
	const withInfuraRPCMethods = setupInfuraProvider(options);
	const withDappMetadata = setupDappMetadata(withInfuraRPCMethods);
	const allOptions = {
	...withDappMetadata,
	ui: {
	...withDappMetadata.ui,
	preferExtension: withDappMetadata.ui.preferExtension ?? true,
	preferDesktop: withDappMetadata.ui.preferDesktop ?? false,
	headless: withDappMetadata.ui.headless ?? false,
	},
	analytics: {
	...(options.analytics ?? {}),
	enabled: options.analytics?.enabled !== undefined ? options.analytics.enabled : true,
	integrationType: 'unknown',
	},
	};
	super(allOptions);
	this.state = 'pending';
	}
	static async create(options: MultichainOptions) {
	const instance = new MultichainSDK(options);
	const isEnabled = await isLoggerEnabled('metamask-sdk:core', instance.options.storage);
	if (isEnabled) {
	enableDebug('metamask-sdk:core');
	}
	await instance.init();
	return instance;
	}
	private async setupAnalytics() {
	if (!this.options.analytics?.enabled) {
	return;
	}
	const platform = getPlatformType();
	const isBrowser = platform === PlatformType.MetaMaskMobileWebview || platform === PlatformType.DesktopWeb || platform === PlatformType.MobileWeb;
	const isReactNative = platform === PlatformType.ReactNative;
	if (!isBrowser && !isReactNative) {
	return;
	}
	const version = getVersion();
	const dappId = getDappId(this.options.dapp);
	const anonId = await getAnonId(this.options.storage);
	const integrationType = this.options.analytics.integrationType;
	analytics.setGlobalProperty('sdk_version', version);
	analytics.setGlobalProperty('dapp_id', dappId);
	analytics.setGlobalProperty('anon_id', anonId);
	analytics.setGlobalProperty('platform', platform);
	analytics.setGlobalProperty('integration_type', integrationType);
	analytics.enable();
	analytics.track('sdk_initialized', {});
	}
	private async onTransportNotification(data: any) {
	if (data.method === 'session_changed') {
	const session = data.params.session;
	//TODO: We also should report this as an issue, sessions with no sessionScopes should be undefined, is there any reason
	//why the object comes empty?
	if (Object.keys(session?.sessionScopes ?? {}).length > 0) {
	this.emit('sessionChanged', session);
	} else {
	this.emit('sessionChanged', undefined);
	}
	}
	}
	private async initialTransport() {
	const transportType = await this.storage.getTransport();
	if (transportType) {
	if (transportType === TransportType.Browser) {
	return getDefaultTransport(this.options.transport);
	} else if (transportType === TransportType.MPW) {
	return MWPClientTransport;
	} else {
	await this.storage.removeTransport();
	}
	}
	return undefined;
	}
	private async setupTransport() {
	const initialTransport = await this.initialTransport();
	if (initialTransport) {
	__transport = initialTransport;
	}
	if (__transport) {
	const listener = __transport.onNotification(this.onTransportNotification);
	if (!__transport.isConnected()) {
	await __transport.connect();
	}
	__provider = getMultichainClient({ transport: __transport });
	this.listeners.push(listener);
	const session = await this.getCurrentSession();
	if (Object.keys(session?.sessionScopes ?? {}).length > 0) {
	this.emit('sessionChanged', session);
	}
	}
	}
	async init() {
	try {
	if (typeof window !== 'undefined' && window.mmsdk?.isInitialized) {
	logger('MetaMaskSDK: init already initialized');
	} else {
	await this.setupAnalytics();
	await this.setupTransport();
	this.state = 'loaded';
	if (typeof window !== 'undefined') {
	window.mmsdk = this;
	}
	}
	} catch (error) {
	logger('MetaMaskSDK error during initialization', error);
	}
	}
	private get hasExtension() {
	if (typeof window !== 'undefined') {
	return window.ethereum?.isMetaMask ?? false;
	}
	return false;
	}
	private async onConnectionSuccess(type: TransportType, transport: Transport, params: ModalFactoryConnectOptions) {
	if (!transport.isConnected()) {
	await transport.connect();
	}
	__transport = transport;
	__provider = getMultichainClient({ transport });
	await this.storage.setTransport(type);
	const session = await this.getCurrentSession();
	const currentScopes = Object.keys(session?.sessionScopes ?? {}) as Scope[];
	const proposedScopes = params.scopes;
	const isSameScopes = currentScopes.every((scope) => proposedScopes.includes(scope)) && proposedScopes.every((scope) => currentScopes.includes(scope));
	if (isSameScopes) {
	this.emit('sessionChanged', session);
	return;
	}
	if (session) {
	await this.provider.revokeSession();
	}
	const { scopes, caipAccountIds } = params;
	const optionalScopes = addValidAccounts(getOptionalScopes(scopes), getValidAccounts(caipAccountIds));
	const sessionRequest: CreateSessionParams<RPCAPI> = { optionalScopes };
	const newSession = await this.provider.createSession(sessionRequest);
	this.emit('sessionChanged', newSession);
	}
	private getTransportForPlatformType(platformType: PlatformType) {
	if (__transport) {
	return __transport;
	}
	if (platformType === PlatformType.MetaMaskMobileWebview || platformType === PlatformType.DesktopWeb || platformType === PlatformType.MobileWeb) {
	return getDefaultTransport(this.options.transport);
	}
	return MWPClientTransport;
	}
	async connect(scopes: Scope[], caipAccountIds: CaipAccountId[]): Promise<void> {
	const {
	ui: { factory, ...uiProperties },
	} = this.options;
	const { preferExtension = false, preferDesktop = false, headless = false } = uiProperties;
	const platformType = getPlatformType();
	const transport = await this.getTransportForPlatformType(platformType);
	const isWeb = platformType === PlatformType.MetaMaskMobileWebview || platformType === PlatformType.DesktopWeb || platformType === PlatformType.MobileWeb;
	const existingSession = await this.getCurrentSession();
	if (isWeb) {
	if (existingSession) {
	return this.onConnectionSuccess(TransportType.Browser, transport, {
	scopes,
	caipAccountIds,
	});
	}
	if (this.hasExtension && preferExtension) {
	return this.onConnectionSuccess(TransportType.Browser, transport, {
	scopes,
	caipAccountIds,
	});
	}
	const link = this.options.dapp.url ?? this.options.dapp.name ?? 'dummy';
	if (!this.hasExtension) {
	if (preferExtension) {
	// render install modal with extension tab selected
	return factory.renderInstallModal(link, false);
	}
	// Doesn't have extension so we show install modal in the preferDesktop value
	return factory.renderInstallModal(link, preferDesktop);
	}
	if (!preferExtension) {
	// Has extension but we don't automatically chooose extension so we should show
	return factory.renderSelectModal(link, true, async () => {
	//This callback is after the user clicked extension in the select tab
	return this.onConnectionSuccess(TransportType.Browser, transport, {
	scopes,
	caipAccountIds,
	});
	});
	}
	//We have extension and extension is the prefferred
	return this.onConnectionSuccess(TransportType.Browser, transport, {
	scopes,
	caipAccountIds,
	});
	} else if (platformType === PlatformType.NonBrowser) {
	return this.onConnectionSuccess(TransportType.MPW, transport, {
	scopes,
	caipAccountIds,
	});
	}
	throw new Error('Not implemented');
	}
	async disconnect(): Promise<void> {
	await __transport?.disconnect();
	await __provider?.revokeSession();
	this.listeners.forEach((listener) => listener());
	__transport = undefined;
	__provider = undefined;
	this.emit('sessionChanged', undefined);
	this.listeners = [];
	await this.storage.removeTransport();
	}

Fix in Cursor • Fix in Web

---

Bug: SDK Instances Share Global Variables

The global variables __provider and __transport are shared across all MultichainSDK instances. This causes multiple SDK instances to interfere, leading to race conditions and unexpected behavior, as connect and disconnect operations from one instance can overwrite the connection state of others.

packages/sdk-multichain/src/multichain/index.ts#L33-L35

metamask-sdk/packages/sdk-multichain/src/multichain/index.ts

Lines 33 to 35 in 8bb171f

	let __provider: MultichainApiClient<RPCAPI> | undefined;
	let __transport: Transport | undefined;

Fix in Cursor • Fix in Web

---

Was this report helpful? Give feedback by reacting with 👍 or 👎

[chakra-guy]

• please fix the base64 and rpc stuff as well

[cursor]

Bug: Callback Context Error in SDK Method

The onTransportNotification method is passed as a callback to __transport.onNotification without binding its this context. When the callback is invoked, this does not refer to the MultichainSDK instance, causing this.emit to fail.

Locations (1)

• packages/sdk-multichain/src/multichain/index.ts#L149-L184

Fix in Cursor • Fix in Web

[cursor]

Bug: SDK Overwrites User Integration Type

The MultichainSDK constructor unconditionally sets integrationType to 'unknown', overwriting any user-provided value in options.analytics. This prevents users from customizing the integration type. The implementation should prioritize the user's integrationType and default to 'unknown' only if not provided.

Locations (1)

• packages/sdk-multichain/src/multichain/index.ts#L104-L106

Fix in Cursor • Fix in Web

[cursor]

Bug: Modal Initialization Timing Issue

A race condition exists in the modal mount logic due to a fragile 100ms setTimeout delay for the updateQRCode call. This timing-dependent approach can cause updateQRCode to execute before the modal element is fully initialized in the DOM or after the modal has been unmounted, potentially leading to display issues.

Locations (1)

• packages/sdk-multichain/src/ui/web/select.ts#L15-L16

Fix in Cursor • Fix in Web

[cursor]

Bug: Callback Method Fails Without Proper Binding

The onTransportNotification method is passed as a callback to __transport.onNotification() without binding its this context. This will cause this.emit() calls within the method to fail when invoked by the transport. The method should be bound (e.g., this.onTransportNotification.bind(this)) or defined as an arrow function.

Locations (1)

• packages/sdk-multichain/src/multichain/index.ts#L164-L166

Fix in Cursor • Fix in Web

[elribonazo]

• please fix the base64 and rpc stuff as well

Duplicate RPC stuff has been removed.
Base64 files too, they were not in use yet so we're good to remove those

[cursor]

Bug: Unnecessary process Check Causes Compatibility Issues

The condition if ('process' in globalThis && process?.env?.DEBUG) is less robust than the original process?.env?.DEBUG. It introduces an unnecessary check that can cause issues in environments where the process object exists but is not directly accessible via globalThis (e.g., certain bundled environments). The original optional chaining was more broadly compatible and sufficient.

Locations (1)

• packages/sdk-multichain/src/domain/logger/index.ts#L66-L67

Fix in Cursor • Fix in Web

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud