@rango-dev/widget-embedded 0.0.0-experimental-936229e8-20251208

package/src/hooks/useStatefulConnect/useStatefulConnect.ts

@@ -0,0 +1,390 @@
+import type { HandleConnectOptions, Result } from './useStatefulConnect.types';
+import type { WalletInfoWithExtra } from '../../types';
+import type { Namespace } from '@rango-dev/wallets-core/namespaces/common';
+import type { NamespaceData } from '@rango-dev/wallets-shared';
+
+import { WalletState } from '@rango-dev/ui';
+import { useWallets } from '@rango-dev/wallets-react';
+import { useReducer } from 'react';
+
+import { isOnDetached } from '../../components/StatefulConnectModal';
+import { type ExtendedModalWalletInfo } from '../../utils/wallets';
+
+import {
+  isStateOnDerivationPathStep,
+  isStateOnNamespace,
+} from './useStatefulConnect.helpers';
+import { initState, reducer, type State } from './useStatefulConnect.state';
+import { ResultStatus } from './useStatefulConnect.types';
+
+export interface UseStatefulConnect {
+  handleConnect: (
+    wallet: WalletInfoWithExtra,
+    options?: HandleConnectOptions
+  ) => Promise<Result>;
+  handleNamespace: (
+    wallet: WalletInfoWithExtra,
+    selectedNamespaces: Namespace[]
+  ) => Promise<Result>;
+  handleDisconnect: (wallet: WalletInfoWithExtra) => Promise<Result>;
+  handleDerivationPath: (
+    wallet: ExtendedModalWalletInfo,
+    path: string,
+    options?: {
+      forceConnectToNamespaces?: Namespace[];
+    }
+  ) => Promise<Result>;
+  getState(): State;
+  resetState(section?: 'derivation'): void;
+}
+
+/**
+ *
+ * This hook maintains state of wallet and checks if additional information
+ * is required to call the `connect` method of `core` package properly.
+ *
+ * The final goal is running `runConnect` which calls `wallets/core`'s `connect` method.
+ * But sometimes it needs to get more information like what namespace it should be connected to,
+ * or what derivation path should be used for.
+ *
+ */
+export function useStatefulConnect(): UseStatefulConnect {
+  const { state, disconnect, connect } = useWallets();
+
+  const [connectState, dispatch] = useReducer(reducer, initState);
+
+  const runConnect = async (
+    wallet: ExtendedModalWalletInfo,
+    namespaces?: NamespaceData[],
+    options?: HandleConnectOptions & { disconnectOnError?: boolean }
+  ): Promise<{ status: ResultStatus }> => {
+    /*
+     * When running this function, it means all optional steps (like namespace and derivation path) has passed, or wallet doesn't need them at all.
+     * By resetting state, we will make sure when user tries to connect other wallets, it doesn't have unexpected states.
+     */
+    dispatch({
+      type: 'reset',
+    });
+
+    try {
+      const legacyNamespacesInput = namespaces?.map((namespaceInput) => ({
+        ...namespaceInput,
+        network: undefined,
+      }));
+      await connect(wallet.type, legacyNamespacesInput);
+      return { status: ResultStatus.Connected };
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } catch (e: any) {
+      const message = e?.message
+        ? `Error: ${e.message}`
+        : 'An unknown error happened during connecting wallet.';
+
+      if (options?.disconnectOnError) {
+        try {
+          await handleDisconnect(wallet);
+        } catch {
+          console.warn(
+            'An error happened during disconnecting wallet after error on connecting.'
+          );
+        }
+      }
+
+      throw new Error(message, { cause: e });
+    }
+  };
+
+  const handleConnect = async (
+    wallet: ExtendedModalWalletInfo,
+    options?: HandleConnectOptions
+  ): Promise<{
+    status: ResultStatus;
+  }> => {
+    const isDisconnected = wallet.state === WalletState.DISCONNECTED;
+    const forceConnectToNamespaces = options?.forceConnectToNamespaces;
+
+    if (isDisconnected) {
+      /*
+       * Currently, handling connect should be covered for 3 different types of target wallet:
+       * 1. Target wallet does not contain any namespaces, in this situation we should just try to connect to the related provider.
+       * 2. Target wallet contains more than one namespace, in this situation we should display namespaces modal to allow the user to choose from available namespaces.
+       * 3. Target wallet contains only one namespace, in this situation we should check if that namespace needs derivation path and based on that, try to connect to the related provider or display derivation path modal.
+       */
+
+      // Legacy and hub have different structure to handle each situation.
+      const isHub = !!wallet.isHub;
+      const needsNamespace = isHub
+        ? wallet.properties?.find((item) => item.name === 'namespaces')?.value
+        : wallet.needsNamespace;
+
+      const needsDerivationPath = isHub
+        ? wallet.properties?.find((item) => item.name === 'derivationPath')
+            ?.value
+        : wallet.needsDerivationPath;
+
+      // Forced namespaces are used to bypass namespace selection flow.
+      if (forceConnectToNamespaces) {
+        const notAvailableForcedNamespace = forceConnectToNamespaces.find(
+          (namespace) =>
+            !needsNamespace?.data?.map((item) => item.value).includes(namespace)
+        );
+        if (notAvailableForcedNamespace) {
+          throw new Error(
+            `One of the forced namespaces is not available in the wallet. Forced namespace: ${notAvailableForcedNamespace}`
+          );
+        }
+
+        if (forceConnectToNamespaces.length > 1 && needsDerivationPath) {
+          throw new Error(
+            'Derivation path is not supported when multiple namespaces are selected.'
+          );
+        }
+
+        if (
+          forceConnectToNamespaces.length === 1 &&
+          forceConnectToNamespaces[0] &&
+          needsDerivationPath
+        ) {
+          dispatch({
+            type: 'needsDerivationPath',
+            payload: {
+              providerType: wallet.type,
+              providerImage: wallet.image,
+              namespace: forceConnectToNamespaces[0],
+            },
+          });
+          return { status: ResultStatus.DerivationPath };
+        }
+        return await runConnect(
+          wallet,
+          forceConnectToNamespaces.map((namespace) => ({ namespace })),
+          { ...options, disconnectOnError: true }
+        );
+      }
+
+      // 1. Target wallet does not contain any namespaces
+      if (!needsNamespace?.data?.length) {
+        return await runConnect(wallet, undefined, options);
+      }
+
+      // 2. Target wallet contains more than one namespace
+      if (needsNamespace?.data.length && needsNamespace.data.length > 1) {
+        dispatch({
+          type: 'needsNamespace',
+          payload: {
+            targetWallet: wallet,
+            defaultSelectedChains: options?.defaultSelectedChains,
+          },
+        });
+        return { status: ResultStatus.Namespace };
+      }
+
+      // 3. Target wallet contains only one namespace
+      if (needsNamespace?.data.length === 1 && needsNamespace.data[0]) {
+        if (needsDerivationPath) {
+          const namespace = needsNamespace.data[0];
+
+          dispatch({
+            type: 'needsDerivationPath',
+            payload: {
+              providerType: wallet.type,
+              providerImage: wallet.image,
+              namespace: namespace.value,
+            },
+          });
+          return { status: ResultStatus.DerivationPath };
+        }
+        return await runConnect(
+          wallet,
+          needsNamespace?.data?.map((namespace) => ({
+            namespace: namespace.value,
+          })),
+          options
+        );
+      }
+    }
+
+    /*
+     * If the wallet is a hub wallet and it is connected (fully or partially),
+     * and it contains more than one namespace,
+     * and forced namespaces are not enabled,
+     * we should display detached modal
+     */
+    if (!!wallet.isHub && !options?.forceConnectToNamespaces) {
+      const needsNamespace = wallet.properties?.find(
+        (item) => item.name === 'namespaces'
+      )?.value;
+      if (needsNamespace?.data.length && needsNamespace.data.length > 1) {
+        dispatch({
+          type: 'detached',
+          payload: {
+            targetWallet: wallet,
+            selectedNamespaces: null,
+          },
+        });
+        return { status: ResultStatus.Detached };
+      }
+    }
+
+    if (options?.disconnectIfConnected) {
+      await handleDisconnect(wallet);
+      return { status: ResultStatus.Disconnected };
+    }
+
+    return { status: ResultStatus.DisconnectedUnhandled };
+  };
+
+  const handleNamespace = async (
+    wallet: ExtendedModalWalletInfo,
+    selectedNamespaces: Namespace[]
+  ): Promise<Result> => {
+    const isHub = !!wallet.isHub;
+    const needsNamespace = isHub
+      ? wallet.properties?.find((item) => item.name === 'namespaces')?.value
+      : wallet.needsNamespace;
+
+    const needsDerivationPath = isHub
+      ? wallet.properties?.find((item) => item.name === 'derivationPath')?.value
+      : wallet.needsDerivationPath;
+
+    const isSingleNamespace = needsNamespace?.selection === 'single';
+    const firstSelectedNamespace = selectedNamespaces[0];
+
+    if (!firstSelectedNamespace) {
+      throw new Error(
+        'To confirm a namespace, you should select at least one namespace.'
+      );
+    }
+
+    /*
+     * Currently we support derivation path only for single namespace wallets.
+     *
+     * Basically Single namespace is a list with radio buttons to let the user select one value within the list.
+     */
+    if (isSingleNamespace && needsDerivationPath) {
+      dispatch({
+        type: 'needsDerivationPath',
+        payload: {
+          providerType: wallet.type,
+          providerImage: wallet.image,
+          namespace: firstSelectedNamespace,
+        },
+      });
+
+      return { status: ResultStatus.DerivationPath };
+    }
+
+    /**
+     * If execution reaches here, means we don't have any more optional step (like namespace and derivation)
+     * So we should start connecting wallet.
+     */
+
+    if (!isStateOnNamespace(connectState)) {
+      // Unreachable code.
+      throw new Error(
+        'Something went wrong on handling namespace. Please retry.'
+      );
+    }
+
+    const namespaces = selectedNamespaces.map((namespace) => ({
+      namespace,
+    }));
+
+    dispatch({
+      type: 'detached',
+      payload: {
+        targetWallet: wallet,
+        selectedNamespaces: namespaces ?? null,
+      },
+    });
+    return { status: ResultStatus.Detached };
+  };
+
+  const handleDerivationPath = async (
+    wallet: ExtendedModalWalletInfo,
+    derivationPath: string,
+    options?: {
+      forceConnectToNamespaces?: Namespace[];
+    }
+  ): Promise<Result> => {
+    if (!derivationPath) {
+      throw new Error(
+        "Derivation path is empty. Please make sure you've filled the field correctly."
+      );
+    }
+
+    if (!isStateOnDerivationPathStep(connectState)) {
+      throw new Error(
+        'It seems you are filling derivation path without setting namespace before doing that. Please retry to connect.'
+      );
+    }
+    const selectedNamespace = connectState.derivationPath.namespace;
+    const namespaces = [{ namespace: selectedNamespace, derivationPath }];
+
+    const isHub = !!wallet.isHub;
+    const needsNamespace = isHub
+      ? wallet.properties?.find((item) => item.name === 'namespaces')?.value
+      : wallet.needsNamespace;
+
+    const namespaceIsAvailable =
+      !!needsNamespace?.data && needsNamespace.data.length > 1;
+    const forceConnectToNamespacesEnabled = !!options?.forceConnectToNamespaces;
+    // If forced namespaces are enabled, we should bypass detached modal and go directly to connect.
+    if (namespaceIsAvailable && !forceConnectToNamespacesEnabled) {
+      dispatch({
+        type: 'detached',
+        payload: {
+          targetWallet: wallet,
+          selectedNamespaces: namespaces ?? null,
+          derivationPath,
+        },
+      });
+      return { status: ResultStatus.Detached };
+    }
+
+    return await runConnect(wallet, namespaces);
+  };
+
+  const getState = () => connectState;
+
+  const handleDisconnect = async (
+    wallet: ExtendedModalWalletInfo
+  ): Promise<Result> => {
+    const walletState = state(wallet.type);
+    if (walletState.connected || walletState.connecting) {
+      await disconnect(wallet.type);
+
+      if (isOnDetached(getState)) {
+        dispatch({
+          type: 'needsNamespace',
+          payload: {
+            targetWallet: wallet,
+          },
+        });
+        return { status: ResultStatus.Namespace };
+      }
+
+      return { status: ResultStatus.Disconnected };
+    }
+
+    return { status: ResultStatus.Noop };
+  };
+
+  return {
+    handleConnect,
+    handleDisconnect,
+    handleNamespace,
+    handleDerivationPath,
+    getState,
+    resetState: (section?: 'derivation') => {
+      if (section === 'derivation') {
+        dispatch({
+          type: 'resetDerivation',
+        });
+      } else {
+        dispatch({
+          type: 'reset',
+        });
+      }
+    },
+  };
+}

package/src/hooks/useStatefulConnect/useStatefulConnect.types.ts

@@ -0,0 +1,72 @@
+import type { ExtendedModalWalletInfo } from '../../utils/wallets';
+import type { Namespace } from '@rango-dev/wallets-core/namespaces/common';
+
+export interface HandleConnectOptions {
+  // To have a switch between connect and disconnect when user is clicking on a button, this option can be helpful.
+  forceConnectToNamespaces?: Namespace[];
+  disconnectIfConnected?: boolean;
+  defaultSelectedChains?: string[];
+}
+
+export interface NeedsNamespacesState {
+  targetWallet: ExtendedModalWalletInfo;
+  defaultSelectedChains?: string[];
+}
+
+export interface DetachedPayload {
+  targetWallet: ExtendedModalWalletInfo;
+  selectedNamespaces:
+    | { namespace: Namespace; derivationPath?: string }[]
+    | null;
+  derivationPath?: string;
+}
+
+export interface NeedsDerivationPathState {
+  providerType: string;
+  providerImage: string;
+  namespace: Namespace;
+}
+
+export enum ResultStatus {
+  Connected = 'connected',
+  Namespace = 'namespace',
+  DerivationPath = 'derivation-path',
+  Disconnected = 'disconnected',
+  DisconnectedUnhandled = 'disconnected-unhandled',
+  Noop = 'noop',
+  Detached = 'Detached',
+}
+
+export type Result = { status: ResultStatus };
+
+// State types
+
+interface UpdateNamespaceAction {
+  type: 'needsNamespace';
+  payload: NeedsNamespacesState;
+}
+
+interface UpdateDerivationPathAction {
+  type: 'needsDerivationPath';
+  payload: NeedsDerivationPathState;
+}
+
+interface UpdateDetachedAction {
+  type: 'detached';
+  payload: DetachedPayload;
+}
+
+interface ResetAction {
+  type: 'reset';
+}
+
+interface ResetDerivationAction {
+  type: 'resetDerivation';
+}
+
+export type Actions =
+  | ResetAction
+  | ResetDerivationAction
+  | UpdateDerivationPathAction
+  | UpdateNamespaceAction
+  | UpdateDetachedAction;

package/src/hooks/useSubscribeToWidgetEvents/index.ts

@@ -0,0 +1 @@
+export { useSubscribeToWidgetEvents } from './useSubscribeToWidgetEvents';

package/src/hooks/useSubscribeToWidgetEvents/useSubscribeToWidgetEvents.ts

@@ -0,0 +1,134 @@
+import type { ConnectedWallet, RouteEventData, StepEventData } from '../..';
+import type { Asset } from 'rango-types';
+
+import {
+  isApprovalTX,
+  RouteEventType,
+  StepEventType,
+  StepExecutionEventStatus,
+  WidgetEvents,
+} from '@rango-dev/queue-manager-rango-preset';
+import { useEffect } from 'react';
+
+import { eventEmitter } from '../../services/eventEmitter';
+import { useAppStore } from '../../store/AppStore';
+import { useNotificationStore } from '../../store/notification';
+
+export function useSubscribeToWidgetEvents() {
+  const setNotification = useNotificationStore.use.setNotification();
+  const {
+    connectedWallets,
+    fetchBalances,
+    customTokens: getCustomTokens,
+  } = useAppStore();
+
+  useEffect(() => {
+    const handleStepEvent = (widgetEvent: StepEventData) => {
+      const { event, step, route } = widgetEvent;
+
+      /**
+       * Determine if we should refetch balances:
+       * - When a transaction is sent (TX_SENT) and it's not an approval transaction.
+       * - When a step succeeds.
+       */
+      const shouldRefetchBalance =
+        (event.type === StepEventType.TX_EXECUTION &&
+          event.status === StepExecutionEventStatus.TX_SENT &&
+          !isApprovalTX(step)) ||
+        event.type === StepEventType.SUCCEEDED;
+
+      if (shouldRefetchBalance) {
+        const fetchBalanceAccounts: ConnectedWallet[] = [];
+
+        /**
+         * Identify the wallet corresponding to the `from` blockchain and match it with a connected wallet.
+         * If found, add it to the balance fetch list.
+         */
+        const fromWallet = route.wallets[step?.fromBlockchain];
+        if (fromWallet) {
+          const fromAccount = connectedWallets.find(
+            (connectedWallet) =>
+              connectedWallet.address?.toLocaleLowerCase() ===
+                fromWallet.address?.toLocaleLowerCase() &&
+              connectedWallet.walletType === fromWallet.walletType &&
+              connectedWallet.chain === step?.fromBlockchain
+          );
+          if (fromAccount) {
+            fetchBalanceAccounts.push(fromAccount);
+          }
+        }
+
+        /**
+         * If the transaction is cross-chain (`fromBlockchain !== toBlockchain`),
+         * find and add the `to` blockchain wallet to the balance fetch list.
+         */
+        if (step?.fromBlockchain !== step?.toBlockchain) {
+          const toWallet = route.wallets[step?.toBlockchain];
+          if (toWallet) {
+            const toAccount = connectedWallets.find(
+              (connectedWallet) =>
+                connectedWallet.address?.toLocaleLowerCase() ===
+                  toWallet.address?.toLocaleLowerCase() &&
+                connectedWallet.walletType === toWallet.walletType &&
+                connectedWallet.chain === step?.toBlockchain
+            );
+            if (toAccount) {
+              fetchBalanceAccounts.push(toAccount);
+            }
+          }
+        }
+
+        if (fetchBalanceAccounts.length > 0) {
+          const customTokens = getCustomTokens();
+          const stepAssets: Asset[] = [
+            {
+              blockchain: step.fromBlockchain,
+              address: step.fromSymbolAddress,
+              symbol: step.fromSymbol,
+            },
+            {
+              blockchain: step.toBlockchain,
+              address: step.toSymbolAddress,
+              symbol: step.toSymbol,
+            },
+          ];
+          const selectedCustomTokens = stepAssets.filter((asset) =>
+            customTokens.some(
+              (token) =>
+                token.blockchain === asset.blockchain &&
+                token.address?.toLocaleLowerCase() ===
+                  asset.address?.toLocaleLowerCase() &&
+                token.symbol?.toLocaleLowerCase() ===
+                  asset.symbol?.toLocaleLowerCase()
+            )
+          );
+
+          void fetchBalances(fetchBalanceAccounts, {
+            selectedCustomTokens,
+            shouldFetchCustomTokens: selectedCustomTokens.length > 0,
+          });
+        }
+      }
+
+      setNotification(event, route);
+    };
+    eventEmitter.on(WidgetEvents.StepEvent, handleStepEvent);
+    return () => eventEmitter.off(WidgetEvents.StepEvent, handleStepEvent);
+  }, [eventEmitter, connectedWallets]);
+
+  useEffect(() => {
+    const handleRouteEvent = (widgetEvent: RouteEventData) => {
+      const { event, route } = widgetEvent;
+
+      if (
+        event.type === RouteEventType.FAILED ||
+        event.type === RouteEventType.SUCCEEDED
+      ) {
+        setNotification(event, route);
+      }
+    };
+    eventEmitter.on(WidgetEvents.RouteEvent, handleRouteEvent);
+
+    return () => eventEmitter.off(WidgetEvents.RouteEvent, handleRouteEvent);
+  }, [eventEmitter]);
+}