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

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@rango-dev/provider-phantom",
+  "version": "0.0.0-experimental-936229e8-20251208",
+  "license": "MIT",
+  "type": "module",
+  "source": "./src/mod.ts",
+  "main": "./dist/mod.js",
+  "exports": {
+    ".": "./dist/mod.js"
+  },
+  "typings": "dist/mod.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/build/command.mjs --path wallets/provider-phantom --inputs src/mod.ts",
+    "ts-check": "tsc --declaration --emitDeclarationOnly -p ./tsconfig.json",
+    "clean": "rimraf dist",
+    "format": "prettier --write '{.,src}/**/*.{ts,tsx}'",
+    "lint": "eslint \"**/*.{ts,tsx}\""
+  },
+  "dependencies": {
+    "@bitcoinerlab/secp256k1": "^1.2.0",
+    "@mysten/sui": "^1.21.2",
+    "@mysten/wallet-standard": "^0.13.26",
+    "@rango-dev/signer-solana": "^0.46.1",
+    "@rango-dev/signer-sui": "^0.8.0",
+    "@rango-dev/wallets-core": "^0.0.0-experimental-936229e8-20251208",
+    "@rango-dev/wallets-shared": "^0.0.0-experimental-936229e8-20251208",
+    "bitcoinjs-lib": "^6.1.7",
+    "rango-types": "^0.1.89"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/readme.md

@@ -0,0 +1,25 @@
+# Phantom Provider
+Phantom integration for hub.  
+[Homepage](https://phantom.com/) | [Docs](https://docs.phantom.com/)
+
+More about implementation status can be found [here](../readme.md).
+
+## Implementation notes/limitation
+
+### Group
+
+#### ⚠️ UTXO
+Only supports Bitcoin.
+
+#### ⚠️ EVM
+Only supports Ethereum, Base, and Polygon.
+
+### Feature
+
+#### ⚠️ Auto Connect
+On Sui, Phantom uses Solana's auto-connect mechanism.  
+This means if Solana is not connected simultaneously, the auto-connect feature on Sui will not work properly.
+
+---
+
+More wallet information can be found in [readme.md](../readme.md).

package/src/constants.ts

@@ -0,0 +1,86 @@
+import { type ProviderMetadata } from '@rango-dev/wallets-core';
+import { LegacyNetworks } from '@rango-dev/wallets-core/legacy';
+import { Networks } from '@rango-dev/wallets-shared';
+import {
+  type BlockchainMeta,
+  type EvmBlockchainMeta,
+  isEvmBlockchain,
+  solanaBlockchain,
+  type SuiBlockchainMeta,
+  TransactionType,
+  type TransferBlockchainMeta,
+} from 'rango-types';
+
+import getSigners from './signer.js';
+import { getInstanceOrThrow } from './utils.js';
+
+export const EVM_SUPPORTED_CHAINS = [
+  LegacyNetworks.ETHEREUM,
+  LegacyNetworks.POLYGON,
+  LegacyNetworks.BASE,
+];
+
+export const WALLET_ID = 'phantom';
+export const WALLET_NAME_IN_WALLET_STANDARD = 'Phantom';
+
+export const metadata: ProviderMetadata = {
+  name: 'Phantom',
+  icon: 'https://raw.githubusercontent.com/rango-exchange/assets/main/wallets/phantom/icon.svg',
+  extensions: {
+    chrome:
+      'https://chrome.google.com/webstore/detail/phantom/bfnaelmomeimhlpmgjnjophhpkkoljpa',
+    homepage: 'https://phantom.app/',
+  },
+  properties: [
+    {
+      name: 'namespaces',
+      value: {
+        selection: 'multiple',
+        data: [
+          {
+            label: 'EVM',
+            value: 'EVM',
+            id: 'ETH',
+            getSupportedChains: (allBlockchains: BlockchainMeta[]) =>
+              allBlockchains.filter(
+                (chain): chain is EvmBlockchainMeta =>
+                  isEvmBlockchain(chain) &&
+                  EVM_SUPPORTED_CHAINS.includes(chain.name as Networks)
+              ),
+          },
+          {
+            label: 'Solana',
+            value: 'Solana',
+            id: 'SOLANA',
+            getSupportedChains: (allBlockchains: BlockchainMeta[]) =>
+              solanaBlockchain(allBlockchains),
+          },
+          {
+            label: 'BTC',
+            value: 'UTXO',
+            id: 'BTC',
+            getSupportedChains: (allBlockchains: BlockchainMeta[]) =>
+              allBlockchains.filter(
+                (chain): chain is TransferBlockchainMeta =>
+                  chain.name === Networks.BTC
+              ),
+          },
+          {
+            label: 'Sui',
+            value: 'Sui',
+            id: 'SUI',
+            getSupportedChains: (allBlockchains: BlockchainMeta[]) =>
+              allBlockchains.filter(
+                (chain): chain is SuiBlockchainMeta =>
+                  chain.type === TransactionType.SUI
+              ),
+          },
+        ],
+      },
+    },
+    {
+      name: 'signers',
+      value: { getSigners: async () => getSigners(getInstanceOrThrow()) },
+    },
+  ],
+};

package/src/legacy/index.ts

@@ -0,0 +1,175 @@
+import type { LegacyProviderInterface } from '@rango-dev/wallets-core/legacy';
+import type {
+  CanEagerConnect,
+  CanSwitchNetwork,
+  Connect,
+  Subscribe,
+  WalletInfo,
+} from '@rango-dev/wallets-shared';
+import type {
+  BlockchainMeta,
+  EvmBlockchainMeta,
+  SignerFactory,
+  SuiBlockchainMeta,
+  TransferBlockchainMeta,
+} from 'rango-types';
+
+import { LegacyNetworks as Networks } from '@rango-dev/wallets-core/legacy';
+import {
+  chooseInstance,
+  getSolanaAccounts,
+  WalletTypes,
+} from '@rango-dev/wallets-shared';
+import {
+  isEvmBlockchain,
+  solanaBlockchain,
+  TransactionType,
+} from 'rango-types';
+
+import { EVM_SUPPORTED_CHAINS } from '../constants.js';
+import signer from '../signer.js';
+import { phantom as phantom_instance, type Provider } from '../utils.js';
+
+const WALLET = WalletTypes.PHANTOM;
+
+export const config = {
+  type: WALLET,
+};
+
+export const getInstance = phantom_instance;
+
+/*
+ * NOTE: Phantom's Hub version has support for EVM as well since we are deprecating the legacy,
+ * we just want to keep the implementation for some time and then legacy provider will be removed soon.
+ * So we don't add new namespaces (like EVM) to legacy.
+ */
+const connect: Connect = async ({ instance, meta }) => {
+  const solanaInstance = instance.get(Networks.SOLANA);
+  const result = await getSolanaAccounts({
+    instance: solanaInstance,
+    meta,
+  });
+
+  return result;
+};
+
+export const subscribe: Subscribe = ({ instance, updateAccounts, connect }) => {
+  const handleAccountsChanged = async (publicKey: string) => {
+    const network = Networks.SOLANA;
+    if (publicKey) {
+      const account = publicKey.toString();
+      updateAccounts([account]);
+    } else {
+      connect(network);
+    }
+  };
+  instance?.on?.('accountChanged', handleAccountsChanged);
+
+  return () => {
+    instance?.off?.('accountChanged', handleAccountsChanged);
+  };
+};
+const canSwitchNetworkTo: CanSwitchNetwork = ({ network }) => {
+  return EVM_SUPPORTED_CHAINS.includes(network as Networks);
+};
+export const getSigners: (provider: Provider) => Promise<SignerFactory> =
+  signer;
+
+const canEagerConnect: CanEagerConnect = async ({ instance, meta }) => {
+  const solanaInstance = chooseInstance(instance, meta, Networks.SOLANA);
+  try {
+    const result = await solanaInstance.connect({ onlyIfTrusted: true });
+    return !!result;
+  } catch {
+    return false;
+  }
+};
+export const getWalletInfo: (allBlockChains: BlockchainMeta[]) => WalletInfo = (
+  allBlockChains
+) => {
+  let supportedChains: BlockchainMeta[] = [];
+  const sui = allBlockChains.filter(
+    (blockchain) => blockchain.type === TransactionType.SUI
+  );
+  const solana = solanaBlockchain(allBlockChains);
+  const evms = allBlockChains.filter(
+    (chain): chain is EvmBlockchainMeta =>
+      isEvmBlockchain(chain) &&
+      EVM_SUPPORTED_CHAINS.includes(chain.name as Networks)
+  );
+  const btc = allBlockChains.find((chain) => chain.name === Networks.BTC);
+  supportedChains = supportedChains.concat(solana, evms, sui);
+  if (btc) {
+    supportedChains.push(btc);
+  }
+
+  return {
+    name: 'Phantom',
+    img: 'https://raw.githubusercontent.com/rango-exchange/assets/main/wallets/phantom/icon.svg',
+    installLink: {
+      CHROME:
+        'https://chrome.google.com/webstore/detail/phantom/bfnaelmomeimhlpmgjnjophhpkkoljpa',
+
+      DEFAULT: 'https://phantom.app/',
+    },
+    color: '#4d40c6',
+    // if you are adding a new namespace, don't forget to also update `properties`
+    needsNamespace: {
+      selection: 'multiple',
+      data: [
+        {
+          label: 'EVM',
+          value: 'EVM',
+          id: 'ETH',
+          getSupportedChains: (allBlockchains: BlockchainMeta[]) =>
+            allBlockchains.filter(
+              (chain): chain is EvmBlockchainMeta =>
+                isEvmBlockchain(chain) &&
+                EVM_SUPPORTED_CHAINS.includes(chain.name as Networks)
+            ),
+        },
+        {
+          label: 'Solana',
+          value: 'Solana',
+          id: 'SOLANA',
+          getSupportedChains: (allBlockchains: BlockchainMeta[]) =>
+            solanaBlockchain(allBlockchains),
+        },
+        {
+          label: 'BTC',
+          value: 'UTXO',
+          id: 'BTC',
+          getSupportedChains: (allBlockchains: BlockchainMeta[]) =>
+            allBlockchains.filter(
+              (chain): chain is TransferBlockchainMeta =>
+                chain.name === Networks.BTC
+            ),
+        },
+        {
+          label: 'Sui',
+          value: 'Sui',
+          id: 'SUI',
+          getSupportedChains: (allBlockchains: BlockchainMeta[]) =>
+            allBlockchains.filter(
+              (chain): chain is SuiBlockchainMeta =>
+                chain.type === TransactionType.SUI
+            ),
+        },
+      ],
+    },
+    supportedChains,
+  };
+};
+
+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,62 @@
+import type { EvmActions } from '@rango-dev/wallets-core/namespaces/evm';
+
+import { NamespaceBuilder } from '@rango-dev/wallets-core';
+import {
+  builders as commonBuilders,
+  standardizeAndThrowError,
+} from '@rango-dev/wallets-core/namespaces/common';
+import {
+  actions,
+  builders,
+  hooks,
+} from '@rango-dev/wallets-core/namespaces/evm';
+
+import { WALLET_ID } from '../constants.js';
+import { evmPhantom } from '../utils.js';
+
+const [changeAccountSubscriber, changeAccountCleanup] =
+  hooks.changeAccountSubscriber(evmPhantom);
+
+/*
+ * TODO: If user imported a private key for EVM, it hasn't solana.
+ * when trying to connect to solana for this user we go through `-32603` which is an internal error.
+ * If phantom added an specific error code for this situation, we can consider handling the error here.
+ * @see https://docs.phantom.app/solana/errors
+ */
+const connect = builders
+  .connect()
+  .action(actions.connect(evmPhantom))
+  .before(changeAccountSubscriber)
+  .or(changeAccountCleanup)
+  .or(standardizeAndThrowError)
+  .build();
+
+const disconnect = commonBuilders
+  .disconnect<EvmActions>()
+  .after(changeAccountCleanup)
+  .build();
+
+const canEagerConnect = builders
+  .canEagerConnect()
+  .action(actions.canEagerConnect(evmPhantom))
+  .build();
+
+const canSwitchNetwork = builders
+  .canSwitchNetwork()
+  .action(actions.canSwitchNetwork())
+  .build();
+
+const getChainId = builders
+  .getChainId()
+  .action(actions.getChainId(evmPhantom))
+  .build();
+
+const evm = new NamespaceBuilder<EvmActions>('EVM', WALLET_ID)
+  .action(connect)
+  .action(disconnect)
+  .action(canEagerConnect)
+  .action(canSwitchNetwork)
+  .action(getChainId)
+  .build();
+
+export { evm };

package/src/namespaces/solana.ts

@@ -0,0 +1,80 @@
+import type { CaipAccount } from '@rango-dev/wallets-core/namespaces/common';
+import type { SolanaActions } from '@rango-dev/wallets-core/namespaces/solana';
+
+import { ActionBuilder, NamespaceBuilder } from '@rango-dev/wallets-core';
+import {
+  builders as commonBuilders,
+  standardizeAndThrowError,
+} from '@rango-dev/wallets-core/namespaces/common';
+import {
+  actions,
+  builders,
+  CAIP_NAMESPACE,
+  CAIP_SOLANA_CHAIN_ID,
+  hooks,
+} from '@rango-dev/wallets-core/namespaces/solana';
+import { CAIP } from '@rango-dev/wallets-core/utils';
+import { getSolanaAccounts } from '@rango-dev/wallets-shared';
+
+import { WALLET_ID } from '../constants.js';
+import { solanaPhantom } from '../utils.js';
+
+const [changeAccountSubscriber, changeAccountCleanup] =
+  hooks.changeAccountSubscriber(solanaPhantom);
+
+/*
+ * TODO: If user imported a private key for EVM, it hasn't solana.
+ * when trying to connect to solana for this user we go through `-32603` which is an internal error.
+ * If phantom added an specific error code for this situation, we can consider handling the error here.
+ * @see https://docs.phantom.app/solana/errors
+ */
+const connect = builders
+  .connect()
+  .action(async function () {
+    const solanaInstance = solanaPhantom();
+    const result = await getSolanaAccounts({
+      instance: solanaInstance,
+      meta: [],
+    });
+    if (Array.isArray(result)) {
+      throw new Error(
+        'Expecting solana response to be a single value, not an array.'
+      );
+    }
+
+    const formatAccounts = result.accounts.map(
+      (account) =>
+        CAIP.AccountId.format({
+          address: account,
+          chainId: {
+            namespace: CAIP_NAMESPACE,
+            reference: CAIP_SOLANA_CHAIN_ID,
+          },
+        }) as CaipAccount
+    );
+
+    return formatAccounts;
+  })
+  .before(changeAccountSubscriber)
+  .or(changeAccountCleanup)
+  .or(standardizeAndThrowError)
+  .build();
+
+const disconnect = commonBuilders
+  .disconnect<SolanaActions>()
+  .after(changeAccountCleanup)
+  .build();
+
+const canEagerConnect = new ActionBuilder<SolanaActions, 'canEagerConnect'>(
+  'canEagerConnect'
+)
+  .action(actions.canEagerConnect(solanaPhantom))
+  .build();
+
+const solana = new NamespaceBuilder<SolanaActions>('Solana', WALLET_ID)
+  .action(connect)
+  .action(disconnect)
+  .action(canEagerConnect)
+  .build();
+
+export { solana };

package/src/namespaces/sui.ts

@@ -0,0 +1,51 @@
+import type { SolanaActions } from '@rango-dev/wallets-core/namespaces/solana';
+import type { SuiActions } from '@rango-dev/wallets-core/namespaces/sui';
+
+import { ActionBuilder, NamespaceBuilder } from '@rango-dev/wallets-core';
+import {
+  builders as commonBuilders,
+  standardizeAndThrowError,
+} from '@rango-dev/wallets-core/namespaces/common';
+import { actions as solanaActions } from '@rango-dev/wallets-core/namespaces/solana';
+import { builders, hooks } from '@rango-dev/wallets-core/namespaces/sui';
+
+import { WALLET_ID, WALLET_NAME_IN_WALLET_STANDARD } from '../constants.js';
+import { solanaPhantom } from '../utils.js';
+
+const [changeAccountSubscriber, changeAccountCleanup] =
+  hooks.changeAccountSubscriber({
+    name: WALLET_NAME_IN_WALLET_STANDARD,
+  });
+
+const connect = builders
+  .connect({
+    name: WALLET_NAME_IN_WALLET_STANDARD,
+  })
+  .before(changeAccountSubscriber)
+  .or(changeAccountCleanup)
+  .or(standardizeAndThrowError)
+  .build();
+
+const disconnect = commonBuilders
+  .disconnect<SuiActions>()
+  .after(changeAccountCleanup)
+  .build();
+
+/*
+ * TODO: We are currently using `solanaCanEagerConnectAction` to establish an eager connection to the Sui instance.
+ * This is a temporary workaround due to Phantom's limitation in silently connecting to a Sui account.
+ * Once Phantom introduces support for silent Sui connections, this implementation should be updated accordingly.
+ */
+const canEagerConnect = new ActionBuilder<SolanaActions, 'canEagerConnect'>(
+  'canEagerConnect'
+)
+  .action(solanaActions.canEagerConnect(solanaPhantom))
+  .build();
+
+const sui = new NamespaceBuilder<SuiActions>('Sui', WALLET_ID)
+  .action(connect)
+  .action(disconnect)
+  .action(canEagerConnect)
+  .build();
+
+export { sui };

package/src/namespaces/utxo.ts

@@ -0,0 +1,171 @@
+import type {
+  ProviderAPI,
+  UtxoActions,
+} from '@rango-dev/wallets-core/namespaces/utxo';
+
+import {
+  ActionBuilder,
+  NamespaceBuilder,
+  type Subscriber,
+  type SubscriberCleanUp,
+} from '@rango-dev/wallets-core';
+import {
+  type CaipAccount,
+  standardizeAndThrowError,
+} from '@rango-dev/wallets-core/namespaces/common';
+import { builders as commonBuilders } from '@rango-dev/wallets-core/namespaces/common';
+import {
+  actions as solanaActions,
+  type SolanaActions,
+} from '@rango-dev/wallets-core/namespaces/solana';
+import {
+  builders,
+  CAIP_BITCOIN_CHAIN_ID,
+  CAIP_NAMESPACE,
+} from '@rango-dev/wallets-core/namespaces/utxo';
+import { CAIP } from '@rango-dev/wallets-core/utils';
+import {
+  Networks,
+  type ProviderConnectResult,
+} from '@rango-dev/wallets-shared';
+
+import { WALLET_ID } from '../constants.js';
+import { bitcoinPhantom, solanaPhantom } from '../utils.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyFunction = (...args: any[]) => any;
+
+type BtcAccount = {
+  address: string;
+  publicKey: string;
+  addressType: 'p2tr' | 'p2wpkh' | 'p2sh' | 'p2pkh';
+  purpose: 'payment' | 'ordinals';
+};
+
+const getBitcoinAccounts: () => Promise<ProviderConnectResult> = async () => {
+  const instance = bitcoinPhantom();
+  const accounts = await instance.requestAccounts();
+
+  return {
+    accounts: accounts
+      .filter((account: BtcAccount) => account.purpose === 'payment')
+      .map((account: BtcAccount) => account.address),
+    chainId: Networks.BTC,
+  };
+};
+
+function getChangeAccountSubscriber(
+  instance: () => ProviderAPI | undefined
+): [Subscriber<UtxoActions>, SubscriberCleanUp<UtxoActions>] {
+  let eventCallback: AnyFunction;
+
+  // subscriber can be passed to `or`, it will get the error and should rethrow error to pass the error to next `or` or throw error.
+  return [
+    (context, err) => {
+      const bitcoinInstance = instance();
+
+      if (!bitcoinInstance) {
+        throw new Error(
+          'Trying to subscribe to your Solana wallet, but seems its instance is not available.'
+        );
+      }
+
+      const [, setState] = context.state();
+
+      eventCallback = (accounts: BtcAccount[]) => {
+        /*
+         * In Phantom, when user is switching to an account which is not connected to dApp yet, it returns an empty array on `accountsChanged`.
+         * So empty array means we don't have access to account and we need to disconnect and let the user connect the account.
+         */
+        if (!accounts.length) {
+          context.action('disconnect');
+          return;
+        }
+
+        const formatAccounts = accounts
+          .filter((account) => account.purpose === 'payment')
+          .map(
+            (account: BtcAccount) =>
+              CAIP.AccountId.format({
+                address: account.address,
+                chainId: {
+                  namespace: CAIP_NAMESPACE,
+                  reference: CAIP_BITCOIN_CHAIN_ID,
+                },
+              }) as CaipAccount
+          );
+
+        setState('accounts', formatAccounts);
+      };
+      bitcoinInstance.on('accountsChanged', eventCallback);
+
+      if (err instanceof Error) {
+        throw err;
+      }
+    },
+    (_context, err) => {
+      const bitcoinInstance = instance();
+
+      if (eventCallback && bitcoinInstance) {
+        bitcoinInstance.off('accountsChanged', eventCallback);
+      }
+
+      return err;
+    },
+  ];
+}
+
+const [changeAccountSubscriber, changeAccountCleanup] =
+  getChangeAccountSubscriber(bitcoinPhantom);
+
+const connect = builders
+  .connect()
+  .action(async function () {
+    const result = await getBitcoinAccounts();
+    if (Array.isArray(result)) {
+      throw new Error(
+        'Expecting bitcoin response to be a single value, not an array.'
+      );
+    }
+
+    const formatAccounts = result.accounts.map(
+      (account) =>
+        CAIP.AccountId.format({
+          address: account,
+          chainId: {
+            namespace: CAIP_NAMESPACE,
+            reference: CAIP_BITCOIN_CHAIN_ID,
+          },
+        }) as CaipAccount
+    );
+
+    return formatAccounts;
+  })
+  .before(changeAccountSubscriber)
+  .or(changeAccountCleanup)
+  .or(standardizeAndThrowError)
+  .build();
+
+const disconnect = commonBuilders
+  .disconnect<UtxoActions>()
+  .after(changeAccountCleanup)
+  .build();
+
+/*
+ * TODO: We are currently using `solanaCanEagerConnectAction` to establish an eager connection to the BTC instance.
+ * This is a temporary workaround due to Phantom's limitation in silently connecting to a BTC account.
+ * Once Phantom introduces support for silent BTC connections, this implementation should be updated accordingly.
+ */
+const canEagerConnect = new ActionBuilder<SolanaActions, 'canEagerConnect'>(
+  'canEagerConnect'
+)
+  .action(solanaActions.canEagerConnect(solanaPhantom))
+  .build();
+
+const utxo = new NamespaceBuilder<UtxoActions>('UTXO', WALLET_ID)
+  .action(connect)
+  .action(disconnect)
+  .action(canEagerConnect)
+  .build();
+
+export { utxo };