@rango-dev/provider-walletconnect-2 0.57.0 → 0.57.1-next.0

package/src/adapter/modal.ts

@@ -0,0 +1,121 @@
+import type { WalletConnectNamespace } from '../types.js';
+import type { AppKitNetwork } from '@reown/appkit-common';
+import type UniversalProvider from '@walletconnect/universal-provider';
+
+import { createAppKit } from '@reown/appkit/core';
+
+import { bitcoin, mainnet } from './networks.js';
+
+export type AppKitModal = ReturnType<typeof createAppKitModal>;
+
+const DEFAULT_MODAL_Z_INDEX = 999_999_999;
+
+export type ModalParams = {
+  projectId: string;
+  universalProvider: UniversalProvider;
+  themeMode?: 'light' | 'dark';
+  zIndex?: number;
+};
+
+/*
+ * Every WalletConnect namespace shares one AppKit instance with all networks
+ * registered up front. A per-namespace instance had to be rebuilt on each
+ * switch, and every rebuild re-ran AppKit init against its module-level
+ * singleton controllers - leaving router history from the previous open mixed
+ * into the next (a stray back button in the modal header). The active network
+ * is chosen per connect with `switchNetwork` instead.
+ *
+ * The active network is now shared mutable state, so this is only safe while
+ * connects are serialized (the adapter's `#sessionQueue`): the switch/open/close
+ * for one namespace never interleaves with another's. A connect path that
+ * bypassed that queue would race this switch.
+ */
+const NETWORKS: [AppKitNetwork, ...AppKitNetwork[]] = [mainnet, bitcoin];
+
+/**
+ * The network to make active before opening the modal for a namespace. Keyed by
+ * `WalletConnectNamespace` so a future namespace is a compile error until mapped.
+ */
+const NAMESPACE_NETWORK: Record<WalletConnectNamespace, AppKitNetwork> = {
+  evm: mainnet,
+  utxo: bitcoin,
+};
+
+/**
+ * Make a namespace's network active before opening the shared modal.
+ *
+ * `open()` compares the requested namespace against AppKit's active chain: if
+ * they differ it treats the open as a network switch and pushes an extra step
+ * onto the router, which leaves a stray back button in the modal header. One
+ * shared instance keeps whatever chain the previous connect left active, so we
+ * switch it to the target here first - then `open()` sees a matching chain and
+ * takes its clean, non-switching path.
+ *
+ * `ready()` first so AppKit init has registered the networks `switchNetwork`
+ * looks up.
+ */
+export async function prepareModalForNamespace(
+  web3Modal: AppKitModal,
+  namespace: WalletConnectNamespace
+): Promise<void> {
+  await web3Modal.ready();
+  await web3Modal.switchNetwork(NAMESPACE_NETWORK[namespace]);
+}
+
+export function createAppKitModal({
+  projectId,
+  universalProvider,
+  themeMode = 'light',
+  zIndex = DEFAULT_MODAL_Z_INDEX,
+}: ModalParams) {
+  return createAppKit({
+    projectId,
+    networks: NETWORKS,
+    universalProvider,
+    /*
+     * AppKit is intentionally kept out of the WalletConnect session lifecycle -
+     * it renders the modal (QR + wallet list), nothing more. We drive the
+     * handshake ourselves with `client.connect()` (see `session/lifecycle.ts`).
+     *
+     * Why: AppKit models one unified, multi-chain session with a single active
+     * chain and its own reconnect/sync. The hub needs the opposite - EVM and
+     * UTXO as independent sessions that connect, disconnect and eager-restore
+     * separately (the adapter keeps one cache entry per namespace). Letting
+     * AppKit drive via `provider.connect()` accumulates namespaces into a single
+     * proposal, so connecting BTC after EVM asks the wallet for Ethereum - it was
+     * tried and reverted. `manualWCControl: true` is AppKit's supported flag for
+     * exactly this "you render, I connect" split.
+     *
+     * The visible cost: because we own the lifecycle, `provider.session` is never
+     * set. With `enableReconnect: false`, AppKit init runs
+     * `unSyncExistingConnection()`, whose `provider.disconnect()` hits a
+     * `if (!this.session) throw` guard and AppKit logs the caught error as
+     * `UniversalAdapter:disconnect - error: Please call connect() before
+     * enable()`. It is expected and harmless - AppKit looking for a session to
+     * clean up, finding none.
+     *
+     * Do NOT "fix" the log. Enabling reconnect makes AppKit actively restore/sync
+     * connections it doesn't own, racing our own restore path and serialize
+     * queue. Assigning `provider.session` removes the guard so that disconnect
+     * (and every other AppKit-initiated disconnect) succeeds for real, tearing
+     * down a live session on AppKit's schedule instead of ours. Both trade a
+     * cosmetic log for real state conflicts.
+     */
+    enableReconnect: false,
+    defaultNetwork: mainnet,
+    defaultAccountTypes: { bip122: 'payment' },
+    manualWCControl: true,
+    /*
+     * We register only one EVM network (`mainnet`) but the session approves every
+     * EVM chain, so a network switch can land on a chain AppKit considers
+     * "unsupported" and it auto-opens its UnsupportedChain modal
+     * (ChainController.showUnsupportedChainUI). Allow it so AppKit doesn't police
+     * the network we manage ourselves.
+     */
+    allowUnsupportedChain: true,
+    themeMode,
+    themeVariables: {
+      '--apkt-z-index': zIndex,
+    },
+  });
+}

package/src/adapter/networks.ts

@@ -0,0 +1,85 @@
+import type { AppKitNetwork, CaipNetwork } from '@reown/appkit-common';
+
+/*
+ * The two networks AppKit renders the modal for, defined here instead of
+ * imported from `@reown/appkit/networks`.
+ *
+ * That entry point is `export * from 'viem/chains'` plus AppKit's own non-EVM
+ * chains, so importing a single name off it pulls every viem chain definition
+ * into the consumer's bundle. One of them (`tempo`) re-exports viem's tempo
+ * chainConfig, which reaches `ox`'s salt-mining worker pool - and that module
+ * routes `await import(id)` through a variable so bundlers skip
+ * `node:worker_threads` in the browser. webpack can't resolve the expression
+ * and warns "Critical dependency: the request of a dependency is an
+ * expression"; react-scripts promotes warnings to errors on CI, which fails
+ * the build for anyone consuming the widget through Create React App.
+ *
+ * viem publishes no per-chain subpath (`./chains` is the only export), so
+ * there is no narrower import to reach for - the definitions are plain data,
+ * so we carry the two we need.
+ *
+ * Keep these in sync with upstream if AppKit's `bitcoin` or viem's `mainnet`
+ * changes: `@reown/appkit/dist/esm/src/networks/bitcoin.js` and
+ * `viem/_esm/chains/definitions/mainnet.js`.
+ */
+
+/**
+ * Mirrors `defineChain` from both `viem/chains` and AppKit's networks module -
+ * they are the same three-key spread. Declaring the viem-only formatter fields
+ * keeps the objects structurally identical to the ones AppKit used to receive.
+ */
+function defineChain<const chain extends AppKitNetwork>(chain: chain) {
+  return {
+    formatters: undefined,
+    fees: undefined,
+    serializers: undefined,
+    ...chain,
+  };
+}
+
+/** viem's `mainnet`, the only EVM network we register. */
+export const mainnet = defineChain({
+  id: 1,
+  caipNetworkId: 'eip155:1',
+  chainNamespace: 'eip155',
+  name: 'Ethereum',
+  nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: ['https://eth.merkle.io'],
+    },
+  },
+  blockExplorers: {
+    default: {
+      name: 'Etherscan',
+      url: 'https://etherscan.io',
+      apiUrl: 'https://api.etherscan.io/api',
+    },
+  },
+  contracts: {
+    ensUniversalResolver: {
+      address: '0xeeeeeeee14d718c2b47d9923deab1335e144eeee',
+      blockCreated: 23_085_558,
+    },
+    multicall3: {
+      address: '0xca11bde05977b3631167028862be2a173976ca11',
+      blockCreated: 14_353_601,
+    },
+  },
+} satisfies CaipNetwork);
+
+/** AppKit's `bitcoin`, the only UTXO network we register. */
+export const bitcoin = defineChain({
+  id: '000000000019d6689c085ae165831e93',
+  caipNetworkId: 'bip122:000000000019d6689c085ae165831e93',
+  chainNamespace: 'bip122',
+  name: 'Bitcoin',
+  nativeCurrency: {
+    name: 'Bitcoin',
+    symbol: 'BTC',
+    decimals: 8,
+  },
+  rpcUrls: {
+    default: { http: ['https://rpc.walletconnect.org/v1'] },
+  },
+} satisfies CaipNetwork);

package/src/adapter/provider-client.ts

@@ -0,0 +1,13 @@
+import UniversalProvider from '@walletconnect/universal-provider';
+
+import { DEFAULT_APP_METADATA, RELAY_URL } from '../wcConstants.js';
+
+export async function createUniversalProvider(
+  projectId: string
+): Promise<UniversalProvider> {
+  return UniversalProvider.init({
+    relayUrl: RELAY_URL,
+    projectId,
+    metadata: DEFAULT_APP_METADATA,
+  });
+}

package/src/adapter/registry.ts

@@ -0,0 +1,17 @@
+import type { WalletConnectAdapter } from './adapter.js';
+
+/**
+ * Holds the singleton adapter instance created in the provider's `init`.
+ *
+ * This lives in its own leaf module (importing nothing from `provider.ts` or the
+ * namespaces) to break the `provider -> namespace -> provider` import cycle that
+ * otherwise throws a TDZ error ("Cannot access 'getAdapter' before initialization")
+ * when the namespace module evaluates its top-level subscriber factories.
+ */
+let adapter: WalletConnectAdapter;
+
+export const getAdapter = () => adapter;
+
+export const setAdapter = (instance: WalletConnectAdapter) => {
+  adapter = instance;
+};

package/src/adapter/session-cache.ts

@@ -0,0 +1,38 @@
+import type { WalletConnectNamespace } from '../types.js';
+import type { SessionTypes } from '@walletconnect/types';
+
+export type SessionCache = {
+  get(namespace: WalletConnectNamespace): SessionTypes.Struct | null;
+  set(namespace: WalletConnectNamespace, session: SessionTypes.Struct): void;
+  clear(namespace: WalletConnectNamespace): void;
+  /**
+   * Drops every namespace holding `topic`. A wallet may approve more than was
+   * proposed, so one settled session can back both namespaces - tearing its topic
+   * down under one of them would otherwise leave the other pointing at a topic
+   * the relay has already dropped.
+   */
+  clearTopic(topic: string): void;
+  clearAll(): void;
+};
+
+export function createSessionCache(): SessionCache {
+  const sessions = new Map<WalletConnectNamespace, SessionTypes.Struct>();
+
+  return {
+    get: (namespace) => sessions.get(namespace) ?? null,
+
+    set: (namespace, session) => void sessions.set(namespace, session),
+
+    clear: (namespace) => void sessions.delete(namespace),
+
+    clearTopic: (topic) => {
+      for (const [namespace, session] of sessions) {
+        if (session.topic === topic) {
+          sessions.delete(namespace);
+        }
+      }
+    },
+
+    clearAll: () => sessions.clear(),
+  };
+}

package/src/adapter/task-queue.ts

@@ -0,0 +1,32 @@
+/**
+ * Runs tasks one at a time, in the order `run` was called.
+ *
+ * A task that rejects passes its rejection to its own caller and does not block
+ * the tasks behind it.
+ */
+export class TaskQueue {
+  /** Resolves once the task currently at the back of the queue has settled. */
+  #tail: Promise<void> = Promise.resolve();
+
+  async run<T>(task: () => Promise<T>): Promise<T> {
+    const ourTurn = this.#tail;
+
+    /*
+     * Take our place at the back of the queue before awaiting anything, so
+     * callers arriving in the same tick line up behind us rather than all
+     * reading the same `#tail`. `releaseOurTurn` never rejects, which is what
+     * lets the next task run even when this one throws.
+     */
+    let releaseOurTurn!: () => void;
+    this.#tail = new Promise<void>((resolve) => {
+      releaseOurTurn = resolve;
+    });
+
+    await ourTurn;
+    try {
+      return await task();
+    } finally {
+      releaseOurTurn();
+    }
+  }
+}

package/src/constants.ts

@@ -1,77 +1,42 @@
-import { Networks } from '@rango-dev/wallets-shared';
-
-export const DEFAULT_NETWORK = Networks.ETHEREUM;
-export const PING_TIMEOUT = 10_000;
-
-export enum NAMESPACES {
-  ETHEREUM = 'eip155',
-  SOLANA = 'solana',
-  POLKADOT = 'polkadot',
-  CARDANO = 'cip34',
-  ERLOND = 'elrond',
-  MULTIVERSX = 'multiversx',
-}
-
-export const CHAIN_ID_STORAGE = 'wc@2:client//namespaces';
-
-// Refrence: https://docs.walletconnect.com/2.0/advanced/rpc-reference/solana-rpc
-export enum SolanaRPCMethods {
-  GET_ACCOUNTS = 'solana_getAccounts',
-  REQUEST_ACCOUNTS = 'solana_requestAccounts',
-  SIGN_TRANSACTION = 'solana_signTransaction',
-  SIGN_MESSAGE = 'solana_signMessage',
-}
-
-// Refrence: https://docs.walletconnect.com/2.0/advanced/rpc-reference/ethereum-rpc
-export enum EthereumRPCMethods {
-  PERSONAL_SIGN = 'personal_sign',
-  SIGN = 'eth_sign',
-  SIGN_TYPED_DATA = 'eth_signTypedData',
-  SIGN_TRANSACTION = 'eth_signTransaction',
-  SEND_TRANSACTION = 'eth_sendTransaction',
-  SEND_RAW_TRANSACTION = 'eth_sendRawTransaction',
-  SWITCH_CHAIN = 'wallet_switchEthereumChain',
-  ADD_CHAIN = 'wallet_addEthereumChain',
-  GET_CHAIN = 'eth_chainId',
-}
-
-export enum StarknetRPCMethods {
-  REQUEST_ADD_INVOKE_TRANSACTION = 'starknet_requestAddInvokeTransaction',
-  SIGN_TYPED_DATA = 'starknet_signTypedData',
-}
-
-export enum EthereumEvents {
-  CHAIN_CHANGED = 'chainChanged',
-  ACCOUNTS_CHANGED = 'accountsChanged',
-}
-
-export const DEFAULT_ETHEREUM_EVENTS: EthereumEvents[] = [
-  EthereumEvents.CHAIN_CHANGED,
-  EthereumEvents.ACCOUNTS_CHANGED,
-];
-
-export const DEFAULT_ETHEREUM_METHODS = [
-  EthereumRPCMethods.PERSONAL_SIGN,
-  EthereumRPCMethods.SEND_TRANSACTION,
-  EthereumRPCMethods.SIGN_TRANSACTION,
-  EthereumRPCMethods.SWITCH_CHAIN,
-  EthereumRPCMethods.ADD_CHAIN,
-  EthereumRPCMethods.GET_CHAIN,
-];
-
-export const DEFAULT_SOLANA_METHODS = [
-  SolanaRPCMethods.SIGN_TRANSACTION,
-  SolanaRPCMethods.SIGN_MESSAGE,
-];
-
-// refrence: https://github.com/ChainAgnostic/namespaces/blob/main/solana/caip2.md
-export const DEFAULT_SOLANA_CHAIN_ID = '4sGjMW1sUnHzSxGspuhpqLDx6wiyjNtZ';
-
-export const DEFAULT_APP_METADATA = {
-  name: 'Rango Exchange',
-  description: 'The Ultimate Cross-Chain Solution',
-  url: 'https://app.rango.exchange/',
-  icons: ['https://app.rango.exchange/logo-rounded.png'],
+import type { ProviderMetadata } from '@hub3js/core';
+
+import { isEvmNamespace } from '@hub3js/evm';
+
+import getSigners from './signer.js';
+
+export const WALLET_ID = 'wallet-connect-2';
+
+export const metadata: ProviderMetadata = {
+  name: 'WalletConnect',
+  icon: 'https://raw.githubusercontent.com/rango-exchange/assets/main/wallets/walletconnect/icon.svg',
+  extensions: {
+    homepage: 'https://walletconnect.com/',
+  },
+  properties: [
+    {
+      name: 'namespaces',
+      value: {
+        selection: 'single',
+        data: [
+          {
+            label: 'EVM',
+            value: 'EVM',
+            id: 'ETH',
+            isChainSupported: isEvmNamespace,
+          },
+        ],
+      },
+    },
+    {
+      name: 'signers',
+      value: { getSigners: async () => getSigners() },
+    },
+    {
+      name: 'details',
+      value: {
+        mobileWallet: true,
+        showOnMobile: true,
+      },
+    },
+  ],
 };
-
-export const RELAY_URL = 'wss://relay.walletconnect.com';

package/src/mod.ts

@@ -0,0 +1,10 @@
+import { defineVersions } from '@hub3js/core/utils';
+
+import { buildProvider } from './provider.js';
+
+export type { Environments } from './types.js';
+
+const versions = () =>
+  defineVersions().version('1.0.0', buildProvider()).build();
+
+export { versions };

package/src/namespaces/evm/hooks.ts

@@ -0,0 +1,148 @@
+import type { EvmActions } from '@hub3js/evm';
+
+import { utils } from '@hub3js/evm';
+import { ChainId } from 'caip';
+
+import {
+  extractAddress,
+  getAccountsFromEvent,
+} from '../../session/accounts.js';
+import {
+  getPersistedChainId,
+  persistCurrentChainId,
+} from '../../session/chain-state.js';
+import { filterEvmAccounts } from '../../session/evm.js';
+import { expireWalletConnectTopic } from '../../session/teardown.js';
+import { chainReferenceToHex, parseChainReference } from '../../utils.js';
+import { EthereumEvents, NAMESPACES } from '../../wcConstants.js';
+import { createSessionSubscriber } from '../subscriber.js';
+
+/**
+ * WC signals an account switch via `session_update` (re-shared namespaces with the
+ * newly-selected account first), so the active account is published from this event.
+ */
+export function sessionUpdateSubscriber() {
+  return createSessionSubscriber<'session_update', EvmActions>(
+    'evm',
+    'session_update',
+    async ({ args, session, adapter, context }) => {
+      /*
+       * Keep the cached struct in step with what the wallet just re-shared.
+       * `switchEvmNetwork` reads the authorized chains and methods back out
+       * of it, so a stale copy rejects a chain the wallet has since added
+       * (`wallet_addEthereumChain` lands here as a `session_update`) with
+       * "Chain X is not configured".
+       */
+      if (args.params.namespaces[NAMESPACES.ETHEREUM]) {
+        adapter.cacheSession('evm', {
+          ...session,
+          namespaces: args.params.namespaces,
+        });
+      }
+
+      const allAccounts = getAccountsFromEvent(args);
+      if (!allAccounts.length) {
+        return;
+      }
+
+      const entries = allAccounts.map((accountsWithChain) => ({
+        address: accountsWithChain.accounts[0],
+        chainId: accountsWithChain.chainId,
+      }));
+
+      const [getState, setState] = context.state();
+      const hubNetwork = getState().network;
+      const persistedChain = await getPersistedChainId(
+        await adapter.getClient()
+      );
+      const activeReference =
+        parseChainReference(hubNetwork ?? undefined) ?? persistedChain;
+
+      let evmAccounts = filterEvmAccounts(entries, activeReference);
+      if (!evmAccounts.length) {
+        evmAccounts = filterEvmAccounts(entries);
+      }
+      if (!evmAccounts.length) {
+        return;
+      }
+
+      const chainIdHex = chainReferenceToHex(evmAccounts[0].chainId);
+      setState(
+        'accounts',
+        utils.formatAccountsToCAIP([evmAccounts[0].accounts[0]], chainIdHex)
+      );
+      setState('network', chainIdHex);
+    }
+  );
+}
+
+/**
+ * Addresses out of an `accountsChanged` payload. Spec says `string[]`, but wallets
+ * forwarding the EIP-1193 event as-is send a bare value, so the shape is coerced
+ * before anything reads it.
+ */
+function eventAccounts(data: unknown): string[] {
+  return (Array.isArray(data) ? data : [data])
+    .filter((entry): entry is string => typeof entry === 'string' && !!entry)
+    .map(extractAddress);
+}
+
+/**
+ * Handles WC `session_event` payloads: EIP-1193 `accountsChanged` (publish the new
+ * accounts, or disconnect when the wallet revokes them all) and `chainChanged`
+ * (update and persist the active chain). Any other event is ignored.
+ */
+export function sessionEventSubscriber() {
+  return createSessionSubscriber<'session_event', EvmActions>(
+    'evm',
+    'session_event',
+    ({ args, adapter, context }) => {
+      const [, setState] = context.state();
+
+      if (args.params.event.name === EthereumEvents.ACCOUNTS_CHANGED) {
+        const accounts = eventAccounts(args.params.event.data);
+        /*
+         * An empty payload is the wallet revoking access (locked, or the account
+         * unlinked from this dApp), not a switch - there is nothing to publish.
+         */
+        if (!accounts.length) {
+          void context.action('disconnect');
+          return;
+        }
+
+        const chainIdHex = chainReferenceToHex(
+          ChainId.parse(args.params.chainId).reference
+        );
+        setState('network', chainIdHex);
+        setState('accounts', utils.formatAccountsToCAIP(accounts, chainIdHex));
+        return;
+      }
+
+      if (args.params.event.name === EthereumEvents.CHAIN_CHANGED) {
+        const chainIdHex = chainReferenceToHex(args.params.event.data);
+        setState('network', chainIdHex);
+        void adapter
+          .getClient()
+          .then(async (client) => persistCurrentChainId(client, chainIdHex));
+      }
+    }
+  );
+}
+
+/**
+ * Reflects a wallet-initiated `session_delete` into the hub: clears the cached
+ * session, expires the WC topic, and runs the hub `disconnect` action.
+ */
+export function sessionDeleteSubscriber() {
+  return createSessionSubscriber<'session_delete', EvmActions>(
+    'evm',
+    'session_delete',
+    ({ args, adapter, context }) => {
+      adapter.clearSession('evm');
+      void adapter
+        .getClient()
+        .then(async (client) => expireWalletConnectTopic(client, args.topic));
+      context.action('disconnect');
+    }
+  );
+}