@rango-dev/provider-metamask 0.0.0-experimental-936229e8-20251208

package/readme.md

@@ -0,0 +1,26 @@
+# MetaMask
+MetaMask Wallet integration for hub.  
+[Homepage](https://metamask.io/) | [Docs](https://docs.metamask.io/)
+
+More about implementation status can be found [here](../readme.md).
+
+## Implementation notes/limitations
+
+### Group
+MetaMask supports both **EVM** and **Solana**.
+
+### Feature
+
+#### ⚠️ Switch Account
+
+In MetaMask, you can have only one active account at a time, which may belong to either the Solana or EVM namespace. When you connect to MetaMask, it connects to the currently active account—this account could belong to either namespace. Additionally, MetaMask may also establish a random connection to another account from the opposite namespace.
+
+When a user switches accounts in MetaMask, the wallet emits an update event tied to the currently active namespace—either EVM or Solana.
+The switchAccount notification is scoped to that active namespace, meaning only the relevant provider will receive the update.
+
+Regardless of which namespace triggers the event, MetaMask always executes transactions using the correct account for the selected chain.
+This ensures consistent behavior and prevents cross-namespace conflicts between Solana and EVM contexts.
+
+---
+
+More wallet information can be found in [readme.md](../readme.md).

package/src/actions/solana.ts

@@ -0,0 +1,42 @@
+import type { WalletStandardSolanaInstance } from '../types.js';
+import type { Context, FunctionWithContext } from '@rango-dev/wallets-core';
+
+import {
+  type SolanaActions,
+  utils,
+} from '@rango-dev/wallets-core/namespaces/solana';
+
+function connect(
+  getInstance: () => WalletStandardSolanaInstance
+): FunctionWithContext<SolanaActions['connect'], Context> {
+  return async () => {
+    const solanaInstance = getInstance();
+    const connectResult = await solanaInstance.features[
+      'standard:connect'
+    ].connect();
+    return utils.formatAccountsToCAIP(
+      connectResult.accounts.map((account) => account.address)
+    );
+  };
+}
+function canEagerConnect(getInstance: () => WalletStandardSolanaInstance) {
+  return async () => {
+    const solanaInstance = getInstance();
+
+    if (!solanaInstance) {
+      throw new Error(
+        'Trying to eagerly connect to your Solana wallet, but it seems that its instance is not available.'
+      );
+    }
+
+    try {
+      const result = await solanaInstance.features['standard:connect'].connect({
+        silent: true,
+      });
+      return !!result.accounts.length;
+    } catch {
+      return false;
+    }
+  };
+}
+export const solanaActions = { connect, canEagerConnect };

package/src/builders/solana.ts

@@ -0,0 +1,36 @@
+import type { WalletStandardSolanaInstance } from '../types.js';
+import type { StandardEventsChangeProperties } from '@wallet-standard/features';
+
+import { ChangeAccountSubscriberBuilder } from '@rango-dev/wallets-core/namespaces/common';
+import {
+  type SolanaActions,
+  utils,
+} from '@rango-dev/wallets-core/namespaces/solana';
+
+// Hooks
+const changeAccountSubscriber = (
+  getInstance: () => WalletStandardSolanaInstance
+) =>
+  new ChangeAccountSubscriberBuilder<
+    StandardEventsChangeProperties,
+    WalletStandardSolanaInstance,
+    SolanaActions
+  >()
+    .getInstance(getInstance)
+    .onSwitchAccount((event, context) => {
+      if (!event.payload.accounts?.length) {
+        context.action('disconnect');
+        event.preventDefault();
+      }
+    })
+    .format(async (_, event) =>
+      utils.formatAccountsToCAIP(
+        event.accounts!.map((account) => account.address)
+      )
+    )
+    .addEventListener((instance, callback) => {
+      instance.features['standard:events'].on('change', callback);
+    })
+    .removeEventListener((_, __) => {});
+
+export const solanaBuilders = { changeAccountSubscriber };

package/src/constants.ts

@@ -0,0 +1,56 @@
+import { type ProviderMetadata } from '@rango-dev/wallets-core';
+import {
+  type BlockchainMeta,
+  evmBlockchains,
+  solanaBlockchain,
+} from 'rango-types';
+
+import getSigners from './signer.js';
+import { getInstanceOrThrow } from './utils.js';
+
+export const WALLET_ID = 'metamask';
+export const WALLET_STANDARD_NAME = 'MetaMask';
+export const SOLANA_WALLET_STANDARD_MAINNET = 'solana:mainnet';
+export const metadata: ProviderMetadata = {
+  name: 'MetaMask',
+  icon: 'https://raw.githubusercontent.com/rango-exchange/assets/main/wallets/metamask/icon.svg',
+  extensions: {
+    chrome:
+      'https://chrome.google.com/webstore/detail/metamask/nkbihfbeogaeaoehlefnkodbefgpgknn?hl=en',
+    brave:
+      'https://chrome.google.com/webstore/detail/metamask/nkbihfbeogaeaoehlefnkodbefgpgknn?hl=en',
+    firefox: 'https://addons.mozilla.org/en-US/firefox/addon/ether-metamask',
+    edge: 'https://microsoftedge.microsoft.com/addons/detail/metamask/ejbalbakoplchlghecdalmeeeajnimhm?hl=en-US',
+    homepage: 'https://metamask.io/download/',
+  },
+  properties: [
+    {
+      name: 'namespaces',
+      value: {
+        selection: 'multiple',
+        data: [
+          {
+            label: 'EVM',
+            value: 'EVM',
+            id: 'ETH',
+            getSupportedChains: (allBlockchains: BlockchainMeta[]) =>
+              evmBlockchains(allBlockchains),
+          },
+          {
+            label: 'Solana',
+            value: 'Solana',
+            id: 'SOLANA',
+            getSupportedChains: (allBlockchains: BlockchainMeta[]) =>
+              solanaBlockchain(allBlockchains),
+          },
+        ],
+      },
+    },
+    {
+      name: 'signers',
+      value: {
+        getSigners: async () => getSigners(getInstanceOrThrow()),
+      },
+    },
+  ],
+};

package/src/legacy/index.ts

@@ -0,0 +1,91 @@
+import type { LegacyProviderInterface } from '@rango-dev/wallets-core/legacy';
+import type {
+  CanEagerConnect,
+  CanSwitchNetwork,
+  Connect,
+  Subscribe,
+  SwitchNetwork,
+  WalletInfo,
+} from '@rango-dev/wallets-shared';
+import type { BlockchainMeta, SignerFactory } from 'rango-types';
+
+import {
+  canEagerlyConnectToEvm,
+  canSwitchNetworkToEvm,
+  getEvmAccounts,
+  subscribeToEvm,
+  switchNetworkForEvm,
+  WalletTypes,
+} from '@rango-dev/wallets-shared';
+import { evmBlockchains } from 'rango-types';
+
+import signer from '../signer.js';
+import { metamask as metamask_instance } from '../utils.js';
+
+const WALLET = WalletTypes.META_MASK;
+
+export const config = {
+  type: WALLET,
+};
+
+export const getInstance = metamask_instance;
+export const connect: Connect = async ({ instance }) => {
+  /*
+   * Note: We need to get `chainId` here, because for the first time
+   * after opening the browser, wallet is locked, and don't give us accounts and chainId
+   * on `check` phase, so `network` will be null. For this case we need to get chainId
+   * whenever we are requesting accounts.
+   */
+  const { accounts, chainId } = await getEvmAccounts(instance);
+
+  return {
+    accounts,
+    chainId,
+  };
+};
+
+export const subscribe: Subscribe = subscribeToEvm;
+
+export const switchNetwork: SwitchNetwork = switchNetworkForEvm;
+
+export const canSwitchNetworkTo: CanSwitchNetwork = canSwitchNetworkToEvm;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Provider = any;
+export const getSigners: (provider: Provider) => Promise<SignerFactory> =
+  signer;
+
+export const canEagerConnect: CanEagerConnect = canEagerlyConnectToEvm;
+
+export const getWalletInfo: (allBlockChains: BlockchainMeta[]) => WalletInfo = (
+  allBlockChains
+) => {
+  const evms = evmBlockchains(allBlockChains);
+  return {
+    name: 'MetaMask',
+    img: 'https://raw.githubusercontent.com/rango-exchange/assets/main/wallets/metamask/icon.svg',
+    installLink: {
+      CHROME:
+        'https://chrome.google.com/webstore/detail/metamask/nkbihfbeogaeaoehlefnkodbefgpgknn?hl=en',
+      BRAVE:
+        'https://chrome.google.com/webstore/detail/metamask/nkbihfbeogaeaoehlefnkodbefgpgknn?hl=en',
+
+      FIREFOX: 'https://addons.mozilla.org/en-US/firefox/addon/ether-metamask',
+      EDGE: 'https://microsoftedge.microsoft.com/addons/detail/metamask/ejbalbakoplchlghecdalmeeeajnimhm?hl=en-US',
+      DEFAULT: 'https://metamask.io/download/',
+    },
+    color: '#dac7ae',
+    supportedChains: evms,
+  };
+};
+const buildLegacyProvider: () => LegacyProviderInterface = () => ({
+  config,
+  getInstance,
+  connect,
+  subscribe,
+  getSigners,
+  getWalletInfo,
+  canSwitchNetworkTo,
+  canEagerConnect,
+});
+
+export { buildLegacyProvider };

package/src/mod.ts

@@ -0,0 +1,12 @@
+import { defineVersions } from '@rango-dev/wallets-core/utils';
+
+import { buildLegacyProvider } from './legacy/index.js';
+import { buildProvider } from './provider.js';
+
+const versions = () =>
+  defineVersions()
+    .version('0.0.0', buildLegacyProvider())
+    .version('1.0.0', buildProvider())
+    .build();
+
+export { versions };

package/src/namespaces/evm.ts

@@ -0,0 +1,81 @@
+import type { EvmActions } from '@rango-dev/wallets-core/namespaces/evm';
+
+import { ActionBuilder, NamespaceBuilder } from '@rango-dev/wallets-core';
+import {
+  builders as commonBuilders,
+  connectAndUpdateStateForMultiNetworks,
+  intoConnecting,
+  intoConnectionFinished,
+  standardizeAndThrowError,
+} from '@rango-dev/wallets-core/namespaces/common';
+import {
+  actions,
+  builders,
+  utils,
+} from '@rango-dev/wallets-core/namespaces/evm';
+
+import { WALLET_ID } from '../constants.js';
+import { evmMetamask } from '../utils.js';
+
+const [changeAccountSubscriber, changeAccountCleanup] = builders
+  .changeAccountSubscriber(evmMetamask)
+  /*
+   * Metamask returns an array of connected accounts with the active one first.
+   * Since we only need the active account, we take the first element as a workaround.
+   */
+  .format(async (instance, accounts) => {
+    const chainId = await instance.request({ method: 'eth_chainId' });
+    return utils.formatAccountsToCAIP([accounts[0]], chainId);
+  })
+  .build();
+
+const connect = new ActionBuilder<EvmActions, 'connect'>('connect')
+  .action(actions.connect(evmMetamask))
+  /*
+   * Metamask Wallet's `connect` returns a list where the currently selected account
+   * is always the first item. We're directly taking this first item as the active account.
+   *
+   * ***NOTE***: Please keep it synced with `wallets/core/src/namespaces/solana/builders.ts`.
+   *
+   */
+  .and((_, connectResult) => ({
+    ...connectResult,
+    accounts: [connectResult.accounts[0]],
+  }))
+  .and(connectAndUpdateStateForMultiNetworks)
+  .before(intoConnecting)
+  .before(changeAccountSubscriber)
+  .or(changeAccountCleanup)
+  .or(standardizeAndThrowError)
+  .after(intoConnectionFinished)
+  .build();
+
+const canEagerConnect = builders
+  .canEagerConnect()
+  .action(actions.canEagerConnect(evmMetamask))
+  .build();
+
+const disconnect = commonBuilders
+  .disconnect<EvmActions>()
+  .after(changeAccountCleanup)
+  .build();
+
+const canSwitchNetwork = builders
+  .canSwitchNetwork()
+  .action(actions.canSwitchNetwork())
+  .build();
+
+const getChainId = builders
+  .getChainId()
+  .action(actions.getChainId(evmMetamask))
+  .build();
+
+const evm = new NamespaceBuilder<EvmActions>('EVM', WALLET_ID)
+  .action(connect)
+  .action(disconnect)
+  .action(canSwitchNetwork)
+  .action(canEagerConnect)
+  .action(getChainId)
+  .build();
+
+export { evm };

package/src/namespaces/solana.ts

@@ -0,0 +1,45 @@
+import { ActionBuilder, NamespaceBuilder } from '@rango-dev/wallets-core';
+import {
+  builders as commonBuilders,
+  standardizeAndThrowError,
+} from '@rango-dev/wallets-core/namespaces/common';
+import {
+  builders,
+  type SolanaActions,
+} from '@rango-dev/wallets-core/namespaces/solana';
+
+import { solanaActions } from '../actions/solana.js';
+import { solanaBuilders } from '../builders/solana.js';
+import { WALLET_ID } from '../constants.js';
+import { solanaMetamask } from '../utils.js';
+
+const [changeAccountSubscriber, changeAccountCleanup] = solanaBuilders
+  .changeAccountSubscriber(solanaMetamask)
+  .build();
+
+const connect = builders
+  .connect()
+  .action(solanaActions.connect(solanaMetamask))
+  .before(changeAccountSubscriber)
+  .or(changeAccountCleanup)
+  .or(standardizeAndThrowError)
+  .build();
+
+const canEagerConnect = new ActionBuilder<SolanaActions, 'canEagerConnect'>(
+  'canEagerConnect'
+)
+  .action(solanaActions.canEagerConnect(solanaMetamask))
+  .build();
+
+const disconnect = commonBuilders
+  .disconnect<SolanaActions>()
+  .after(changeAccountCleanup)
+  .build();
+
+const solana = new NamespaceBuilder<SolanaActions>('Solana', WALLET_ID)
+  .action(connect)
+  .action(disconnect)
+  .action(canEagerConnect)
+  .build();
+
+export { solana };

package/src/provider.ts

@@ -0,0 +1,23 @@
+import { ProviderBuilder } from '@rango-dev/wallets-core';
+
+import { metadata, WALLET_ID } from './constants.js';
+import { evm } from './namespaces/evm.js';
+import { solana } from './namespaces/solana.js';
+import { metamask as metamask } from './utils.js';
+
+const buildProvider = () =>
+  new ProviderBuilder(WALLET_ID)
+    .init(function (context) {
+      const [, setState] = context.state();
+
+      if (metamask()) {
+        setState('installed', true);
+        console.debug('[metamask] instance detected.', context);
+      }
+    })
+    .config('metadata', metadata)
+    .add('evm', evm)
+    .add('solana', solana)
+    .build();
+
+export { buildProvider };

package/src/signer.ts

@@ -0,0 +1,29 @@
+import type { Provider } from './types.js';
+import type { SignerFactory } from 'rango-types';
+
+import { LegacyNetworks as Networks } from '@rango-dev/wallets-core/legacy';
+import {
+  dynamicImportWithRefinedError,
+  getNetworkInstance,
+} from '@rango-dev/wallets-shared';
+import { DefaultSignerFactory, TransactionType as TxType } from 'rango-types';
+
+import { MetamaskSolanaSigner } from './signers/solana.js';
+
+export default async function getSigners(
+  provider: Provider
+): Promise<SignerFactory> {
+  const ethProvider = getNetworkInstance(provider, Networks.ETHEREUM);
+  const solanaProvider = getNetworkInstance(provider, Networks.SOLANA);
+
+  const signers = new DefaultSignerFactory();
+  const { DefaultEvmSigner } = await dynamicImportWithRefinedError(
+    async () => await import('@rango-dev/signer-evm')
+  );
+  signers.registerSigner(TxType.EVM, new DefaultEvmSigner(ethProvider));
+  signers.registerSigner(
+    TxType.SOLANA,
+    new MetamaskSolanaSigner(solanaProvider)
+  );
+  return signers;
+}

package/src/signers/solana.ts

@@ -0,0 +1,88 @@
+import type { WalletStandardSolanaInstance } from '../types.js';
+
+import {
+  generalSolanaTransactionExecutor,
+  type SolanaWeb3Signer,
+} from '@rango-dev/signer-solana';
+import base58 from 'bs58';
+import {
+  type GenericSigner,
+  SignerError,
+  SignerErrorCode,
+  type SolanaTransaction,
+} from 'rango-types';
+
+async function executeSolanaTransaction(
+  tx: SolanaTransaction,
+  solanaProvider: WalletStandardSolanaInstance
+): Promise<string> {
+  const DefaultSolanaSigner: SolanaWeb3Signer = async (
+    solanaWeb3Transaction
+  ) => {
+    const [currentAccount] = solanaProvider.accounts;
+    if (!currentAccount.publicKey) {
+      throw new SignerError(
+        SignerErrorCode.SIGN_TX_ERROR,
+        'Please make sure the required account is connected properly.'
+      );
+    }
+
+    if (tx.from !== currentAccount.address) {
+      throw new SignerError(
+        SignerErrorCode.SIGN_TX_ERROR,
+        `Your connected account doesn't match with the required account. Please ensure that you are connected with the correct account and try again.`
+      );
+    }
+
+    try {
+      const [signOutput] = await solanaProvider.features[
+        'solana:signTransaction'
+      ].signTransaction({
+        account: currentAccount,
+        transaction: solanaWeb3Transaction.serialize(),
+      });
+      return signOutput.signedTransaction;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } catch (e: any) {
+      const REJECTION_CODE = 4001;
+      if (e && Object.hasOwn(e, 'code') && e.code === REJECTION_CODE) {
+        throw new SignerError(SignerErrorCode.REJECTED_BY_USER, undefined, e);
+      }
+      throw new SignerError(SignerErrorCode.SIGN_TX_ERROR, undefined, e);
+    }
+  };
+  return await generalSolanaTransactionExecutor(tx, DefaultSolanaSigner);
+}
+
+export class MetamaskSolanaSigner implements GenericSigner<SolanaTransaction> {
+  private _provider: WalletStandardSolanaInstance;
+
+  constructor(provider: WalletStandardSolanaInstance) {
+    this._provider = provider;
+  }
+
+  get provider(): WalletStandardSolanaInstance {
+    return this._provider;
+  }
+
+  async signMessage(msg: string): Promise<string> {
+    try {
+      const encodedMessage = new TextEncoder().encode(msg);
+      const [account] = this.provider.accounts;
+      const [signOutput] = await this._provider.features[
+        'solana:signMessage'
+      ].signMessage({
+        message: encodedMessage,
+        account,
+      });
+      return base58.encode(signOutput.signature);
+    } catch (error) {
+      throw new SignerError(SignerErrorCode.SIGN_TX_ERROR, undefined, error);
+    }
+  }
+
+  async signAndSendTx(tx: SolanaTransaction): Promise<{ hash: string }> {
+    const hash = await executeSolanaTransaction(tx, this._provider);
+    return { hash };
+  }
+}

package/src/types.ts

@@ -0,0 +1,54 @@
+import type { LegacyNetworks } from '@rango-dev/wallets-core/legacy';
+import type { ProviderAPI as EvmProviderApi } from '@rango-dev/wallets-core/namespaces/evm';
+import type { WalletWithFeatures as StandardWalletWithFeatures } from '@wallet-standard/base';
+
+import {
+  type SolanaSignMessageFeature,
+  type SolanaSignTransactionFeature,
+} from '@solana/wallet-standard-features';
+import {
+  type StandardConnectFeature,
+  type StandardEventsFeature,
+} from '@wallet-standard/features';
+
+export type WalletStandardSolanaInstance = StandardWalletWithFeatures<
+  StandardConnectFeature &
+    StandardEventsFeature &
+    SolanaSignTransactionFeature &
+    SolanaSignMessageFeature
+>;
+export type MetamaskEvmProviderApi = EvmProviderApi & {
+  isMetaMask?: boolean;
+  isBraveWallet?: boolean;
+  _events?: boolean;
+  _state?: boolean;
+  isApexWallet?: boolean;
+  isAvalanche?: boolean;
+  isBitKeep?: boolean;
+  isBlockWallet?: boolean;
+  isCoin98?: boolean;
+  isFordefi?: boolean;
+  __XDEFI?: boolean;
+  isMathWallet?: boolean;
+  isOkxWallet?: boolean;
+  isOKExWallet?: boolean;
+  isOneInchIOSWallet?: boolean;
+  isOneInchAndroidWallet?: boolean;
+  isOpera?: boolean;
+  isPortal?: boolean;
+  isRabby?: boolean;
+  isDefiant?: boolean;
+  isTokenPocket?: boolean;
+  isTokenary?: boolean;
+  isZeal?: boolean;
+  isZerion?: boolean;
+  isSafePal?: boolean;
+};
+export type ProviderObject = {
+  [LegacyNetworks.ETHEREUM]: MetamaskEvmProviderApi;
+  [LegacyNetworks.SOLANA]: WalletStandardSolanaInstance;
+};
+export type Provider = Map<
+  keyof ProviderObject,
+  ProviderObject[keyof ProviderObject]
+>;