feat(walletconnect): add multichain routing and namespace approval for first non-EVM chain (Tron) by Olivier-BB · Pull Request #29428 · MetaMask/metamask-mobile

Olivier-BB · 2026-04-28T14:38:49Z

Description

This PR refactors WalletConnect multichain handling by introducing a per-chain ChainAdapter registry and moving non-EVM behavior behind that adapter layer (with Tron as the first implementation). The goal is to reduce coupling in WalletConnect session code and make additional non-EVM chains easier to add.

It also improves namespace approval and routing behavior for mixed EVM + Tron sessions by approving only requested namespaces/chains, preserving EVM chain selection, and normalizing Tron request/response mapping for compatibility with dapp expectations.

Changelog

CHANGELOG entry: Improved WalletConnect multichain compatibility by refining namespace approval and request routing for mixed EVM and Tron sessions.

Related issues

Fixes:

Manual testing steps

Feature: WalletConnect multichain routing and namespace approval

  Scenario: user connects to a dapp requesting mixed EVM and Tron namespaces
    Given the user has at least one EVM account and one Tron account available
    And a dapp initiates a WalletConnect v2 proposal with EVM and Tron requirements

    When user approves the WalletConnect connection
    Then the approved namespaces include only namespaces and chains requested by the dapp
    And existing EVM chain/account selection is preserved

  Scenario: user signs a Tron request through WalletConnect
    Given an active WalletConnect session for Tron
    When user approves a Tron signing request from the dapp
    Then the request is mapped through the Tron chain adapter
    And the response is normalized to WalletConnect format expected by the dapp

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **High Risk**
> High risk because it changes WalletConnect v2 session approval, chain permission checks, namespace updates, and request routing, including new Snap-based handling for non-EVM requests; mistakes could break existing EVM sessions or incorrectly permit/deny chains.
> 
> **Overview**
> Adds a new WalletConnect `multichain` adapter/registry layer and implements the first non-EVM adapter for **Tron**, including CAIP chain-id normalization (hex/decimal), request mapping to Snap RPC shapes, and response normalization for Tron dapp expectations.
> 
> Updates WalletConnect v2 flows to **approve and update only requested namespaces/chains**, preserve previously approved non-EVM namespaces during updates, normalize/validate session namespaces, and route non-EVM requests through `MultichainRoutingService` (with improved unauthorized-chain errors and redirect-methods keyed by namespace).
> 
> Extends permissions defaults and lookups to be **namespace-agnostic** (adds Tron optional scope behind feature flag; `getPermittedChains` now returns all non-`wallet` scopes), tightens network-selection expansion logic to avoid broadening explicit `eip155` chain requests, and adjusts logging/error handling plus related unit/e2e test coverage.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 72d4ea9ea37aa4d69f6efb36ea5ce3ea61393f36. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

github-actions · 2026-04-28T14:39:05Z

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

…ging

…compatibility Normalize WalletConnect Tron requests to canonical Snap methods and sanitize params for JSON-RPC validity. Expand Tron session chain/account compatibility to support both decimal and hex CAIP references so dapps and wallet stay interoperable. Made-with: Cursor

Ensure tron signTransaction requests execute with metamask origin and adapt signature-only Snap results into a full signed transaction payload expected by WalletConnect dapps. Made-with: Cursor

…apters

…Service

…on-EVM logic

…hain permission errors

…ount parsing

…ct chainChanged fallback he

…eat expectation

…nd handle missing caveats safely

…ation

jiexi · 2026-05-06T18:27:02Z

+        },
+        existingNamespaces: mergedNamespaces,
+      });
+      Object.assign(mergedNamespaces, adapterSlices);


it's not clear what this does on the surface level. Is this effectively filtering out namespaces without accounts?

jiexi · 2026-05-06T18:27:06Z

+        optionalNamespaces: {},
+      });
+      const missingRequiredAdapterNamespaces = requiredAdapterNamespaces.filter(
+        (ns) => !mergedNamespaces[ns]?.chains?.length,


I'm having trouble understanding what is going on here

requiredAdapterNamespaces returns adapter generated namespaces from this.session.requiredNamespaces that have a matching adapter, which effectively is requiredNamespaces with an adapter and accounts.

mergedNamespaces contains this.session.namespace, which contains this.requiredNamespace

missingRequiredAdapterNamespaces returns this.session.requiredNamespaces with matching adapter and non-empty accounts but are missing entirely or have no chains defined in mergedNamespaces.

Is this right? Can this be explained in simpler terms?

jiexi · 2026-05-06T18:27:10Z

+      // (a session previously approved eip155 should keep eip155 on update).
+      Object.keys(currentNamespaces).forEach((key) =>
+        allowedNamespaceKeys.add(key),
+      );


currentNamespaces is this.session.namespaces. Is this not the same set of keys as this.session.requiredNamespaces and this.session.optionalNamespaces?

jiexi · 2026-05-06T18:27:16Z

+    const redirectNamespace =
+      requestNamespace === KnownCaipNamespace.Wallet
+        ? KnownCaipNamespace.Eip155
+        : requestNamespace;


i don't think WC supports targeting the wallet or wallet:eip155 scopes. requestNamespace may be safe as is

jiexi · 2026-05-06T18:27:25Z

+        }
+        throw error;
+      }
+    };


if the session exists, then a permission should exist for it. Are you seeing this not be the case?

jiexi · 2026-05-06T18:27:33Z

+    const permittedChainsFromSession =
+      this.session.topic !== this.channelId
+        ? await getPermittedChainsSafe(this.session.topic)
+        : [];


won't this always be empty array because permissions are not key'ed by this.session.topic, but rather channelId / this.session.pairingTopic?

jiexi · 2026-05-06T18:27:39Z

+      (chainId) => activeSessionChains.includes(chainId),
+    );
+    const isPermittedRequestChain =
+      isPermittedByPermissionController || isPermittedByActiveSession;


the result from the PermissionController should be the source of truth ultimately. Both the activeSession and the permission are kept in sync - ish, so at minimum only one of these needs to be checked, not both. Unless you're seeing some reason otherwise?

jiexi · 2026-05-06T18:30:56Z

+}): Promise<unknown> =>
+  Engine.controllerMessenger.call('MultichainRoutingService:handleRequest', {
+    connectedAddresses,
+    origin: 'metamask',


this is an unsafe internal origin. The value used here should probably be the channelId

jiexi · 2026-05-06T18:39:44Z

      } catch (err) {
-        console.warn(`WC2::init can't update session ${sessionKey}`);
+        DevLogger.log(`WC2::init can't update session ${sessionKey}`);
+        await this.cleanupBrokenRestoredSession(session, err);


why is this needed now?

jiexi · 2026-05-06T18:43:37Z

+    const referencedAdapterNamespaces = proposalReferencedAdapterNamespaces(
+      proposal.params,
+    );
+    const isMultichainOrigin = referencedAdapterNamespaces.length > 0;


@adonesky1 . does it really matter what value this flag is now?

jiexi · 2026-05-06T18:46:02Z

+      const allProposalNamespaces = {
+        ...optionalNamespaces,
+        ...requiredNamespaces,
+      } as Record<
+        string,
+        { chains?: string[]; methods?: string[]; events?: string[] }
+      >;


keys can overlap here

jiexi · 2026-05-06T18:57:32Z

+        namespaces.wallet = {
+          chains: walletChains,
+          methods: namespaces.eip155.methods ?? [],
+          events: namespaces.eip155.events ?? [],
+          accounts: eip155Accounts.map((account) => {
+            const [, , address] = account.split(':');
+            return `wallet:eip155:${address}` as `${string}:${string}:${string}`;
+          }),


is this wallet namespace used later? I feel like i've already seen special handling of wallet:eip155 that would imply that namespaces['wallet'] is not used, but maybe I'm wrong

jiexi · 2026-05-06T18:57:47Z

+      const allowedNamespaceKeys = new Set<string>([
+        ...Object.keys(proposal.params.requiredNamespaces ?? {}),
+        ...Object.keys(proposal.params.optionalNamespaces ?? {}),
+      ]);


is key collision possible here?

jiexi · 2026-05-06T19:09:05Z

+        if (!session) {
+          const activeSession = this.getSession(sessionTopic);
+          if (activeSession) {
+            session = new WalletConnect2Session({
+              web3Wallet: this.web3Wallet,
+              channelId: activeSession.pairingTopic,
+              navigation: this.navigation,
+              deeplink: true,
+              session: activeSession,
+            });
+            this.sessions[sessionTopic] = session;
+          }
+        }


why is this needed now?

jiexi · 2026-05-06T19:09:32Z

+export const getChainChangedEmissionForWalletConnect = ({
+  namespaces,
+  fallbackEvmDecimal,
+  fallbackEvmHex,


it feels odd for the caller to be responsible to provide the evm chain id formatted in both decimal and hex

jiexi · 2026-05-06T19:11:30Z

+    return String(raw);
+  }
+}
+


confused on how the WC changes would warrant this change here

adonesky1 · 2026-05-07T16:35:21Z

    });
  });

+  it('passes EVM chains to permissions hook for mixed wallet:eip155 + tron requests', () => {


right?

Suggested change

it('passes EVM chains to permissions hook for mixed wallet:eip155 + tron requests', () => {

it('passes EVM chains and Tron to permissions hook for mixed wallet:eip155 + tron requests', () => {

adonesky1 · 2026-05-07T16:38:24Z

+      ...Object.keys(requestedCaip25CaveatValue.optionalScopes ?? {}),
+    ];
+
+    // CAIP-25 may encode delegated namespace requests (for example wallet:eip155).


I'm not sure what encode delegated namespace requests means?

adonesky1 · 2026-05-07T16:53:17Z

+    // Expand only namespaces that were requested without explicit chains
+    // (e.g. wallet:eip155 delegated requests in mixed namespace proposals).
+    // Intentionally restrictive: if explicit eip155 chains are requested, treat
+    // that list as authoritative and do not expand to all eip155 networks. This
+    // prevents approving more chains than requested. Delegated namespace
+    // expansion still applies when no explicit chain ids are provided.
+    // TODO: check if this restrictive logic has already been applied in the past or if this modifies previous behavior.


I think this makes sense for this pass. Just noting that we are probably going to be loosening chain permissions quite a bit in the near future: i.e. you ask for 1 EVM chain you get all EVM chains. But TBD

adonesky1 · 2026-05-07T17:03:43Z


 /**
 * Returns a default CAIP-25 caveat value.
+ * Each chain appends its optional scope below (feature-flagged).


[nit]

Suggested change

* Each chain appends its optional scope below (feature-flagged).

* Each ecosystem (i.e. EVM, Tron) appends its optional scope below (feature-flagged).

adonesky1 · 2026-05-07T17:18:35Z

+  ///: BEGIN:ONLY_INCLUDE_IF(tron)
+  optionalScopes[TrxScope.Mainnet] = { accounts: [] };
+  ///: END:ONLY_INCLUDE_IF


not sure I'm following why this would be added as a default namespace for permissions? I'm struggling to figure out how to test this properly and I'm not totally remembering or understanding how this helper function is used but its name implies that this addition will mean Tron network permissions will be granted by default? TBH I'm not sure how that would be the case... but either way I'm not sure I understand the purpose of this addition.

adonesky1 · 2026-05-07T17:24:50Z

- * @returns An array containing permitted chains for the specified host.
+ * @returns An array containing permitted CAIP chain IDs for the specified host.
 */
 export const getPermittedChains = async (


Suggested change

export const getPermittedChains = async (

export const getPermittedCaipChainIds = async (

Yes the typing gives this context, but the sibling getPermittedAccounts is currently only returning EVM accounts... so this could get confusing

adonesky1 · 2026-05-07T17:25:56Z

+
+export const normalizeCaipChainIdInboundForWalletConnectTron = (
+  caipChainId: string,
+): string => {


[nit] shouldn't the return type also be caipChainId?

adonesky1 · 2026-05-07T19:29:47Z

+const TRON_PREFIX = 'tron:';
+const DEFAULT_TRON_CHAIN_ID = 'tron:0x2b6653dc';
+
+export const normalizeCaipChainIdInboundForWalletConnectTron = (


We should add a comment explaining why this normalization is required? I asked Claude to explain why this was necessary because it's nonobvious when just looking at it. WalletConnect tends to encode the Tron chainIds with hex values for the reference i.e. tron:0x2b6653dc while we use decimals for the reference tron:728126428

adonesky1 · 2026-05-07T19:31:22Z

+  return caipChainId;
+};
+
+export const getCompatibleTronCaipChainIdsForWalletConnect = (


Lets please add some JSdocs to explain why this utility function is necessary?

Looking at where this is used, I'm not understanding why we need this encoded in both hex and decimal formats side by side ever?

adonesky1 · 2026-05-07T19:36:39Z

+const listTronEoaAddresses = (): string[] =>
+  Engine.context.AccountsController.listAccounts()
+    .filter((account: { type: string }) => account.type === TrxAccountType.Eoa)
+    .map((account: { address: string }) => account.address);


Just so I'm clear do we support Tron SCAs?

adonesky1 · 2026-05-07T19:40:40Z

+ * Shape of a single namespace slice in WalletConnect's approved
+ * namespaces map. Mirrors `SessionTypes.Namespace` but kept loose.
+ */
+export interface TronNamespaceSlice {


hmmm this seems tied to a mixed version of CAIP-25. Can you point me to the docs where this type is described?

adonesky1 · 2026-05-07T19:53:07Z

+   * matches `SessionTypes.Namespace.accounts` which is a plain string[].
+   */
+  accounts: string[];
+}


Do we have two different versions of this same interface? https://github.com/MetaMask/metamask-mobile/pull/29428/changes#diff-09c1410947d91a7bf8ff2bd7a39a10ad19c1b4d40083abfdc2c8b86d08580f73R47

Also TronNamespaceSlice is awfully similar...?

adonesky1 · 2026-05-07T19:58:49Z

+  const originalTransaction =
+    typeof transactionContainer === 'object' &&
+    transactionContainer !== null &&
+    !Array.isArray(transactionContainer) &&
+    typeof (transactionContainer as Record<string, unknown>).transaction ===
+      'object' &&
+    (transactionContainer as Record<string, unknown>).transaction !== null
+      ? ((transactionContainer as Record<string, unknown>)
+          .transaction as Record<string, unknown>)
+      : typeof transactionContainer === 'object' &&
+          transactionContainer !== null &&
+          !Array.isArray(transactionContainer)
+        ? (transactionContainer as Record<string, unknown>)
+        : undefined;


ummm this can't be reasoned about in any meaningful way

adonesky1 · 2026-05-07T20:05:45Z

+    .filter((account: { type: string }) => account.type === TrxAccountType.Eoa)
+    .map((account: { address: string }) => account.address);
+
+export const buildTronScopedPermissionsNamespace = ({


When a function gets this long I find it can help to add some inline comments explain what is going on at each step

0xEdouardEth and others added 14 commits April 29, 2026 14:43

doc

0775bb3

WIP Wallet-connect

bdd7ee3

refactor(walletconnect): stabilize tron multichain flow and clean log…

dc7091d

…ging

fix(walletconnect): normalize tron signing response for WalletConnect

ac40253

Ensure tron signTransaction requests execute with metamask origin and adapt signature-only Snap results into a full signed transaction payload expected by WalletConnect dapps. Made-with: Cursor

refactor(walletconnect): split multichain connector into per-chain ad…

4eca361

…apters

fix: preserve EVM chain selection in mixed Tron WalletConnect requests

a6620f3

fix(wallet-connect): only approve namespaces the dapp requested

ebd1289

refactor(walletconnect): route non-EVM requests via MultichainRouting…

1c5c033

…Service

refactor(walletconnect): introduce ChainAdapter registry to isolate n…

2a63d5a

…on-EVM logic

chore(walletconnect): remove unrelated QRScanner and Braze changes

f411910

chore(walletconnect): drop unrelated changes and trim debug logs

e9e2b6f

fix(walletconnect): remove duplicate chain-change relay and clarify c…

567fd8d

…hain permission errors

chore(walletconnect): enforce multichain caveat origin and harden acc…

c22d169

…ount parsing

Olivier-BB force-pushed the wallet-connect-4o branch from 3e5c974 to c22d169 Compare April 29, 2026 12:54

Olivier-BB marked this pull request as ready for review April 29, 2026 12:54

Olivier-BB requested review from a team as code owners April 29, 2026 12:54

metamaskbotv2 Bot added the INVALID-PR-TEMPLATE PR's body doesn't match template label Apr 29, 2026

github-actions Bot added the size-XL label Apr 29, 2026

cursor Bot reviewed Apr 29, 2026

View reviewed changes

Comment thread app/core/WalletConnect/WalletConnect2Session.ts

Comment thread app/core/WalletConnect/WalletConnect2Session.ts Outdated

Comment thread app/core/WalletConnect/WalletConnect2Session.ts Outdated

Olivier-BB added team-mobile-platform Mobile Platform team team-accounts labels Apr 29, 2026

Olivier-BB changed the title ~~Feature: WalletConnect multichain routing and namespace approval~~ feat(walletconnect): add multichain routing and namespace approval for first non-EVM chain (Tron) Apr 29, 2026

Olivier-BB added 2 commits April 29, 2026 15:11

fix(walletconnect): avoid optional non-EVM blocking updates and corre…

c79d2f2

…ct chainChanged fallback he

test(permissions): include default Tron optional scope in CAIP-25 cav…

1857154

…eat expectation

cursor Bot reviewed Apr 29, 2026

View reviewed changes

Comment thread app/core/WalletConnect/wc-utils.ts Outdated

Olivier-BB added 2 commits April 29, 2026 15:41

refactor(walletconnect): move Tron scoped permissions to multichain a…

4ac9e55

…nd handle missing caveats safely

test(walletconnect): stabilize invalid chainId session request expect…

c96d410

…ation

jiexi reviewed May 6, 2026

View reviewed changes

adonesky1 reviewed May 7, 2026

View reviewed changes

	it('passes EVM chains to permissions hook for mixed wallet:eip155 + tron requests', () => {
	it('passes EVM chains and Tron to permissions hook for mixed wallet:eip155 + tron requests', () => {

	* Each chain appends its optional scope below (feature-flagged).
	* Each ecosystem (i.e. EVM, Tron) appends its optional scope below (feature-flagged).

	export const getPermittedChains = async (
	export const getPermittedCaipChainIds = async (

Uh oh!

Conversation

Olivier-BB commented Apr 28, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changelog

Related issues

Manual testing steps

Uh oh!

github-actions Bot commented Apr 28, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adonesky1 May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Olivier-BB commented Apr 28, 2026 •

edited by cursor Bot

Loading

adonesky1 May 7, 2026 •

edited

Loading