@rango-dev/wallets-react 0.0.0-experimental-1cc1923b-20260930 → 0.0.0-experimental-767249ce-20261007

package/src/events.ts

@@ -0,0 +1,99 @@
+import type { WalletType } from '@hub3js/core';
+import type { Namespace } from '@hub3js/namespaces';
+import type { BlockchainMeta } from 'rango-types';
+
+import { getBlockChainNameFromId } from '@rango-dev/internal-blockchains';
+
+import { WALLET_DETECTED_SKIPPED_IDS } from './hub/constants.js';
+
+export const WalletEventChannel = 'walletEvent';
+
+export enum WalletEventTypes {
+  WALLET_DETECTED = 'walletDetected',
+  WALLET_CONNECT_INITIATED = 'walletConnectInitiated',
+  WALLET_CONNECTED = 'walletConnected',
+  WALLET_CONNECT_FAILED = 'walletConnectFailed',
+  WALLET_DISCONNECTED = 'walletDisconnected',
+}
+
+export type WalletConnectOrigin = 'manual' | 'auto';
+
+type WalletConnectEventPayload = {
+  /** Wallet type id, e.g. `metamask`. */
+  walletName: WalletType;
+  namespace: Namespace;
+  /** Rango blockchain name (e.g. `ETH`), or `null` when it isn't known. */
+  chain: string | null;
+  origin: WalletConnectOrigin;
+};
+
+export type WalletDetectedEventPayload = {
+  walletName: WalletType;
+};
+export type WalletConnectInitiatedEventPayload = WalletConnectEventPayload;
+export type WalletConnectedEventPayload = WalletConnectEventPayload;
+export type WalletConnectFailedEventPayload = WalletConnectEventPayload;
+export type WalletDisconnectedEventPayload = {
+  walletName: WalletType;
+  namespace: Namespace;
+};
+
+type EventData<T extends WalletEventTypes, U> = { type: T; payload: U };
+
+export type WalletEventData =
+  | EventData<WalletEventTypes.WALLET_DETECTED, WalletDetectedEventPayload>
+  | EventData<
+      WalletEventTypes.WALLET_CONNECT_INITIATED,
+      WalletConnectInitiatedEventPayload
+    >
+  | EventData<WalletEventTypes.WALLET_CONNECTED, WalletConnectedEventPayload>
+  | EventData<
+      WalletEventTypes.WALLET_CONNECT_FAILED,
+      WalletConnectFailedEventPayload
+    >
+  | EventData<
+      WalletEventTypes.WALLET_DISCONNECTED,
+      WalletDisconnectedEventPayload
+    >;
+
+export type WalletEvents = {
+  [WalletEventChannel]: WalletEventData;
+};
+
+export interface Emitter<Events extends Record<string, unknown>> {
+  emit<K extends keyof Events>(type: K, event: Events[K]): void;
+}
+
+export type WalletEventEmitter = Emitter<WalletEvents>;
+
+const detectedWallets = new Set<WalletType>();
+
+export function emitWalletDetectedOnce(
+  walletName: WalletType,
+  emitter?: WalletEventEmitter
+): void {
+  if (
+    detectedWallets.has(walletName) ||
+    WALLET_DETECTED_SKIPPED_IDS.includes(walletName)
+  ) {
+    return;
+  }
+  detectedWallets.add(walletName);
+  emitter?.emit(WalletEventChannel, {
+    type: WalletEventTypes.WALLET_DETECTED,
+    payload: { walletName },
+  });
+}
+
+/**
+ * Connect results may carry an EVM chain id (e.g. `0x1`); events always carry a Rango blockchain name.
+ */
+export function toBlockchainName(
+  network: string | null | undefined,
+  allBlockChains: BlockchainMeta[] | undefined
+): string | null {
+  if (!network) {
+    return null;
+  }
+  return getBlockChainNameFromId(network, allBlockChains || []);
+}

package/src/hub/autoConnect.ts

@@ -7,14 +7,34 @@ import type { Accounts, AccountsWithActiveChain } from '@hub3js/std/types';
 
 import { Result } from 'ts-results';
 
+import {
+  toBlockchainName,
+  WalletEventChannel,
+  type WalletEventEmitter,
+  WalletEventTypes,
+} from '../events.js';
+
 import { HUB_LAST_CONNECTED_WALLETS } from './constants.js';
 import { runSequentiallyWithoutFailure } from './helpers.js';
 import { LastConnectedWalletsFromStorage } from './lastConnectedWallets.js';
 import {
   convertNamespaceNetworkToEvmChainId,
   isEvmNamespace,
+  transformHubResultToLegacyResult,
 } from './utils.js';
 
+function createAutoConnectEventPayload(
+  walletName: WalletType,
+  namespaceInput: NamespaceInputForConnect
+) {
+  return {
+    walletName,
+    namespace: namespaceInput.namespace,
+    chain: namespaceInput.network || null,
+    origin: 'auto' as const,
+  };
+}
+
 function isEvmNamespaceInput(
   namespace: NamespaceInputForConnect
 ): namespace is NamespaceInputForConnect<'EVM'> {
@@ -35,9 +55,10 @@ async function eagerConnect(
   params: {
     getHub: () => Hub;
     allBlockChains: UseAdapterParams['allBlockChains'];
+    emitter?: WalletEventEmitter;
   }
 ) {
-  const { getHub, allBlockChains } = params;
+  const { getHub, allBlockChains, emitter } = params;
   const wallet = getHub().get(type);
   if (!wallet) {
     throw new Error(
@@ -81,10 +102,25 @@ async function eagerConnect(
         } else {
           connectNamespacePromise = async () => namespace.connect();
         }
+        const eventPayload = createAutoConnectEventPayload(type, info);
         try {
-          await connectNamespacePromise();
+          const result = await connectNamespacePromise();
+          emitter?.emit(WalletEventChannel, {
+            type: WalletEventTypes.WALLET_CONNECTED,
+            payload: {
+              ...eventPayload,
+              chain: toBlockchainName(
+                transformHubResultToLegacyResult(result).network,
+                allBlockChains
+              ),
+            },
+          });
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
         } catch (e: any) {
+          emitter?.emit(WalletEventChannel, {
+            type: WalletEventTypes.WALLET_CONNECT_FAILED,
+            payload: eventPayload,
+          });
           /*
            * Since we check for connect failures using `instanceof Error`
            * this check is added here to make sure the thrown error always is an instance of `Error`
@@ -182,8 +218,9 @@ export async function autoConnect(deps: {
   getHub: () => Hub;
   allBlockChains: UseAdapterParams['allBlockChains'];
   wallets?: (WalletType | Provider)[];
+  emitter?: WalletEventEmitter;
 }): Promise<void> {
-  const { getHub, allBlockChains, wallets } = deps;
+  const { getHub, allBlockChains, wallets, emitter } = deps;
   const lastConnectedWallets = lastConnectedWalletsFromStorage.list();
   const walletIds = Object.keys(lastConnectedWallets);
 
@@ -219,9 +256,23 @@ export async function autoConnect(deps: {
         return;
       }
 
+      lastConnectedNamespaces.forEach((namespace) => {
+        emitter?.emit(WalletEventChannel, {
+          type: WalletEventTypes.WALLET_CONNECT_INITIATED,
+          payload: createAutoConnectEventPayload(providerName, namespace),
+        });
+      });
+
       const { successNamespaces, failedNamespaces } =
         await tryRunCanEagerConnect(lastConnectedNamespaces, wallet);
 
+      failedNamespaces.forEach((namespace) => {
+        emitter?.emit(WalletEventChannel, {
+          type: WalletEventTypes.WALLET_CONNECT_FAILED,
+          payload: createAutoConnectEventPayload(providerName, namespace),
+        });
+      });
+
       if (!successNamespaces.length) {
         walletsToRemoveFromPersistence.push(providerName);
         return;
@@ -235,6 +286,7 @@ export async function autoConnect(deps: {
         eagerConnect(providerName, successNamespaces, {
           allBlockChains,
           getHub,
+          emitter,
         }).catch((error) => console.warn(error))
       );
     });

package/src/hub/constants.ts

@@ -1 +1,13 @@
+import { WalletTypes } from '@rango-dev/provider-all';
+
 export const HUB_LAST_CONNECTED_WALLETS = 'hub-v1-last-connected-wallets';
+
+// Wallets that always report themselves installed (hardware wallets and connection protocols).
+export const WALLET_DETECTED_SKIPPED_IDS: string[] = [
+  WalletTypes.LEDGER,
+  WalletTypes.TREZOR,
+  WalletTypes.LEDGER_WALLET,
+  WalletTypes.WALLET_CONNECT_2,
+  WalletTypes.TON_CONNECT,
+  WalletTypes.DEFAULT,
+];

package/src/hub/useHubAdapter.ts

@@ -1,11 +1,13 @@
 import type { AllProxiedNamespaces, ExtensionLink } from './types.js';
 import type {
   ConnectResult,
+  EventHandler,
   NamespaceInputForConnect,
   WalletInfo,
 } from '../legacy/mod.js';
 import type { ProviderContext, ProviderProps } from '../types.js';
 import type { Provider, WalletType } from '@hub3js/core';
+import type { Event } from '@hub3js/core/store';
 import type { Accounts, AccountsWithActiveChain } from '@hub3js/std/types';
 
 import { utils } from '@hub3js/evm';
@@ -16,7 +18,14 @@ import {
 import { useEffect, useRef, useState } from 'react';
 import { Ok, Result } from 'ts-results';
 
+import {
+  emitWalletDetectedOnce,
+  toBlockchainName,
+  WalletEventChannel,
+  WalletEventTypes,
+} from '../events.js';
 import { withErrorLoggingApi } from '../helpers.js';
+import { Events } from '../legacy/mod.js';
 
 import { autoConnect } from './autoConnect.js';
 import { HUB_LAST_CONNECTED_WALLETS } from './constants.js';
@@ -25,7 +34,6 @@ import { LastConnectedWalletsFromStorage } from './lastConnectedWallets.js';
 import { useAutoConnect } from './useAutoConnect.js';
 import { useHubRefs } from './useHubRefs.js';
 import {
-  findProviderByType,
   isEvmNamespace,
   isSolanaNamespace,
   isUtxoNamespace,
@@ -45,6 +53,7 @@ export function useHubAdapter(params: UseAdapterParams): ProviderContext {
   const dataRef = useRef({
     onUpdateState: params.onUpdateState,
     allBlockChains: params.allBlockChains,
+    emitter: params.emitter,
   });
   const hubInitiated = useRef(false);
 
@@ -75,30 +84,31 @@ export function useHubAdapter(params: UseAdapterParams): ProviderContext {
     dataRef.current = {
       onUpdateState: params.onUpdateState,
       allBlockChains: params.allBlockChains,
+      emitter: params.emitter,
     };
   }, [params]);
 
   useEffect(() => {
-    getStore()
-      .subscribe((event) => {
-        if (dataRef.current.onUpdateState) {
-          try {
-            mapHubEventsToLegacy(
-              getHub(),
-              event,
-              dataRef.current.onUpdateState,
-              {
-                allBlockChains: dataRef.current.allBlockChains,
-                lastConnectAttemptParams: lastConnectAttemptParamsRef.current,
-              }
-            );
-          } catch (e) {
-            console.error(e);
-          }
-        }
-        rerender((currentRender) => currentRender + 1);
-      })
-      .flushEvents();
+    const onUpdateState: EventHandler = (type, event, value, state, info) => {
+      if (event === Events.INSTALLED && state.installed) {
+        emitWalletDetectedOnce(type, dataRef.current.emitter);
+      }
+      dataRef.current.onUpdateState?.(type, event, value, state, info);
+    };
+
+    const onStoreEvent = (event: Event) => {
+      try {
+        mapHubEventsToLegacy(getHub(), event, onUpdateState, {
+          allBlockChains: dataRef.current.allBlockChains,
+          lastConnectAttemptParams: lastConnectAttemptParamsRef.current,
+        });
+      } catch (e) {
+        console.error(e);
+      }
+      rerender((currentRender) => currentRender + 1);
+    };
+
+    getStore().subscribe(onStoreEvent).flushEvents();
   }, []);
 
   // Initialize hub only after blockchain meta is available (e.g. WalletConnect needs it at init).
@@ -120,6 +130,7 @@ export function useHubAdapter(params: UseAdapterParams): ProviderContext {
         allBlockChains: params.allBlockChains,
         getHub,
         wallets: params.configs?.wallets,
+        emitter: dataRef.current.emitter,
       });
     },
   });
@@ -258,7 +269,46 @@ export function useHubAdapter(params: UseAdapterParams): ProviderContext {
                   },
                 };
               });
-          return queueTask(connectNamespaceProcess, type);
+
+          // Reconnecting an already connected namespace (e.g. only to switch its network) isn't reported.
+          const connectNamespaceProcessWithEvents = async () => {
+            if (namespace.state()[0]().connected) {
+              return connectNamespaceProcess();
+            }
+
+            const eventPayload = {
+              walletName: type,
+              namespace: namespaceInput.namespace,
+              origin: 'manual' as const,
+            };
+            const requestedChain = namespaceInput.network || null;
+
+            dataRef.current.emitter?.emit(WalletEventChannel, {
+              type: WalletEventTypes.WALLET_CONNECT_INITIATED,
+              payload: { ...eventPayload, chain: requestedChain },
+            });
+            try {
+              const result = await connectNamespaceProcess();
+              dataRef.current.emitter?.emit(WalletEventChannel, {
+                type: WalletEventTypes.WALLET_CONNECTED,
+                payload: {
+                  ...eventPayload,
+                  chain: toBlockchainName(
+                    result.response.network,
+                    params.allBlockChains
+                  ),
+                },
+              });
+              return result;
+            } catch (error) {
+              dataRef.current.emitter?.emit(WalletEventChannel, {
+                type: WalletEventTypes.WALLET_CONNECT_FAILED,
+                payload: { ...eventPayload, chain: requestedChain },
+              });
+              throw error;
+            }
+          };
+          return queueTask(connectNamespaceProcessWithEvents, type);
         }
       );
 
@@ -312,6 +362,10 @@ export function useHubAdapter(params: UseAdapterParams): ProviderContext {
           !namespaces || namespaces.includes(namespace.namespaceId);
         const namespaceIsConnected = namespace.state()[0]().connected;
         if (namespaceShouldBeDisconnected && namespaceIsConnected) {
+          dataRef.current.emitter?.emit(WalletEventChannel, {
+            type: WalletEventTypes.WALLET_DISCONNECTED,
+            payload: { walletName: type, namespace: namespace.namespaceId },
+          });
           return namespace.disconnect();
         }
       });
@@ -498,7 +552,12 @@ export function useHubAdapter(params: UseAdapterParams): ProviderContext {
       );
     },
     hubProvider(type) {
-      const provider = findProviderByType(params.providers, type);
+      /*
+       * Return the instance registered in the hub, which holds the store. A
+       * provider list can be rebuilt with the same ids, and the hub keeps the
+       * instances it registered first, so a rebuilt one would have no store.
+       */
+      const provider = getHub().get(type);
 
       if (!provider) {
         throw new Error(

package/src/index.ts

@@ -1,4 +1,16 @@
 export { default as Provider } from './provider.js';
 export { useWallets } from './hooks.js';
 export type * from './types.js';
+export { WalletEventChannel, WalletEventTypes } from './events.js';
+export type {
+  Emitter,
+  WalletConnectedEventPayload,
+  WalletConnectFailedEventPayload,
+  WalletConnectInitiatedEventPayload,
+  WalletConnectOrigin,
+  WalletDetectedEventPayload,
+  WalletDisconnectedEventPayload,
+  WalletEventData,
+  WalletEvents,
+} from './events.js';
 export * from './legacy/types.js';

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { Emitter, WalletEvents } from './events.js';
 import type {
   ConnectResult,
   EventHandler,
@@ -43,6 +44,8 @@ export type ProviderProps = PropsWithChildren<{
   allBlockChains?: BlockchainMeta[];
   autoConnect?: boolean;
   providers: Provider[];
+  /** Receives wallet events on the `walletEvent` channel. */
+  emitter?: Emitter<WalletEvents>;
   configs?: {
     wallets?: (WalletType | Provider)[];
     walletOptions?: {