@naculus/connect-appkit-react 0.1.2

package/src/hooks/useValidateDestination.ts

@@ -0,0 +1,72 @@
+/**
+ * useValidateDestination — address blackhole prevention hook.
+ *
+ * Validates that a destination address is not a known burn/zero address
+ * before sending a transaction. Returns { isValid, warning, level }.
+ *
+ * Level: "safe" | "warning" | "blocked"
+ */
+
+import { useMemo } from "react";
+import { t } from "../utils/i18n";
+
+// ── Known burn / zero addresses ─────────────────────────────────
+
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+const DEAD_ADDRESSES = new Set([
+  ZERO_ADDRESS,
+  "0x0000000000000000000000000000000000000001",
+  "0x000000000000000000000000000000000000dead",
+  "0x000000000000000000000000000000000000dEaD",
+]);
+
+function isBurnAddress(addr: string): boolean {
+  const lower = addr.toLowerCase();
+  if (DEAD_ADDRESSES.has(lower)) return true;
+  return lower.includes("dead") && lower.length >= 40;
+}
+
+function isZeroAddress(addr: string): boolean {
+  return addr === ZERO_ADDRESS;
+}
+
+function isValidFormat(addr: string): boolean {
+  return /^0x[0-9a-fA-F]{40}$/.test(addr);
+}
+
+export type AddressValidationLevel = "safe" | "warning" | "blocked";
+
+export interface AddressValidationResult {
+  isValid: boolean;
+  level: AddressValidationLevel;
+  warning: string | null;
+}
+
+export function validateDestination(address: string): AddressValidationResult {
+  if (!address) {
+    return { isValid: false, level: "blocked", warning: t("address.empty") };
+  }
+  if (!isValidFormat(address)) {
+    return { isValid: false, level: "blocked", warning: t("address.invalid_format") };
+  }
+  if (isZeroAddress(address)) {
+    return { isValid: false, level: "blocked", warning: t("address.zero_address") };
+  }
+  if (isBurnAddress(address)) {
+    return { isValid: false, level: "blocked", warning: t("address.burn_address") };
+  }
+  return { isValid: true, level: "safe", warning: null };
+}
+
+export interface UseValidateDestinationOptions {
+  address: string;
+}
+
+export interface UseValidateDestinationReturn {
+  validation: AddressValidationResult;
+}
+
+export function useValidateDestination({ address }: UseValidateDestinationOptions): UseValidateDestinationReturn {
+  const validation = useMemo(() => validateDestination(address), [address]);
+  return { validation };
+}

package/src/hooks/useViemClient.test.ts

@@ -0,0 +1,155 @@
+/// <reference types="vitest" />
+/// @vitest-environment jsdom
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+
+const mockUseAccount = vi.fn();
+vi.mock("./useAccount", () => ({
+  useAccount: () => mockUseAccount(),
+}));
+
+const mockUseChain = vi.fn();
+vi.mock("./useChain", () => ({
+  useChain: () => mockUseChain(),
+}));
+
+vi.mock("../utils/chains", () => ({
+  getDefaultChains: () => [
+    { id: 1, namespace: "eip155", name: "Ethereum", rpcUrl: "https://eth.llamarpc.com", token: "ETH" },
+  ],
+}));
+
+import { useViemClient } from "./useViemClient";
+
+describe("useViemClient", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should return null clients when not connected", () => {
+    mockUseAccount.mockReturnValue({
+      evmAccount: null,
+      isConnected: false,
+    });
+    mockUseChain.mockReturnValue({
+      currentChain: null,
+      chains: [{ id: 1, namespace: "eip155", name: "Ethereum", rpcUrl: "https://eth.llamarpc.com", token: "ETH" }],
+    });
+
+    const { result } = renderHook(() => useViemClient());
+
+    expect(result.current.publicClient).toBeNull();
+    expect(result.current.walletClient).toBeNull();
+    expect(result.current.chains).toHaveLength(1);
+  });
+
+  it("should create public client when chain has rpcUrl", () => {
+    mockUseAccount.mockReturnValue({
+      evmAccount: null,
+      isConnected: false,
+    });
+    mockUseChain.mockReturnValue({
+      currentChain: {
+        id: 1,
+        namespace: "eip155",
+        name: "Ethereum",
+        rpcUrl: "https://eth.llamarpc.com",
+        token: "ETH",
+      },
+    });
+
+    const { result } = renderHook(() => useViemClient());
+
+    expect(result.current.publicClient).not.toBeNull();
+    expect(result.current.publicClient?.chain?.id).toBe(1);
+    // walletClient should still be null since not connected
+    expect(result.current.walletClient).toBeNull();
+  });
+
+  it("should create both public and wallet client when connected with evm account", () => {
+    mockUseAccount.mockReturnValue({
+      evmAccount: "eip155:1:0x1234567890123456789012345678901234567890",
+      isConnected: true,
+    });
+    mockUseChain.mockReturnValue({
+      currentChain: {
+        id: 1,
+        namespace: "eip155",
+        name: "Ethereum",
+        rpcUrl: "https://eth.llamarpc.com",
+        token: "ETH",
+      },
+    });
+
+    const { result } = renderHook(() => useViemClient());
+
+    expect(result.current.publicClient).not.toBeNull();
+    expect(result.current.walletClient).not.toBeNull();
+    expect(result.current.walletClient?.account?.address).toBe("0x1234567890123456789012345678901234567890");
+  });
+
+  it("should handle plain address format (without eip155 prefix)", () => {
+    mockUseAccount.mockReturnValue({
+      evmAccount: "0xabcdef1234567890abcdef1234567890abcdef12",
+      isConnected: true,
+    });
+    mockUseChain.mockReturnValue({
+      currentChain: {
+        id: 137,
+        namespace: "eip155",
+        name: "Polygon",
+        rpcUrl: "https://polygon-rpc.com",
+        token: "MATIC",
+      },
+    });
+
+    const { result } = renderHook(() => useViemClient());
+
+    expect(result.current.publicClient).not.toBeNull();
+    expect(result.current.walletClient).not.toBeNull();
+    expect(result.current.walletClient?.account?.address).toBe("0xabcdef1234567890abcdef1234567890abcdef12");
+  });
+
+  it("should return null wallet client when not connected", () => {
+    mockUseAccount.mockReturnValue({
+      evmAccount: null,
+      isConnected: true,
+    });
+    mockUseChain.mockReturnValue({
+      currentChain: {
+        id: 1,
+        namespace: "eip155",
+        name: "Ethereum",
+        rpcUrl: "https://eth.llamarpc.com",
+        token: "ETH",
+      },
+    });
+
+    const { result } = renderHook(() => useViemClient());
+
+    expect(result.current.publicClient).not.toBeNull();
+    expect(result.current.walletClient).toBeNull();
+  });
+
+  it("should return null clients when no rpcUrl", () => {
+    mockUseAccount.mockReturnValue({
+      evmAccount: null,
+      isConnected: false,
+    });
+    mockUseChain.mockReturnValue({
+      currentChain: {
+        id: 1,
+        namespace: "eip155",
+        name: "Ethereum",
+        rpcUrl: undefined,
+        token: "ETH",
+      },
+    });
+
+    const { result } = renderHook(() => useViemClient());
+
+    expect(result.current.publicClient).toBeNull();
+    expect(result.current.walletClient).toBeNull();
+  });
+});

package/src/hooks/useViemClient.ts

@@ -0,0 +1,65 @@
+import { useMemo } from "react";
+import { createPublicClient, http, createWalletClient, type PublicClient, type WalletClient } from "viem";
+import type { WalletChain } from "../types";
+import { useAccount } from "./useAccount";
+import { useChain } from "./useChain";
+
+export function useViemClient(): {
+  publicClient: PublicClient | null;
+  walletClient: WalletClient | null;
+  chains: WalletChain[];
+} {
+  const { evmAccount, isConnected } = useAccount();
+  const { currentChain, chains } = useChain();
+
+  const publicClient = useMemo<PublicClient | null>(() => {
+    if (!currentChain?.rpcUrl) return null;
+
+    return createPublicClient({
+      transport: http(currentChain.rpcUrl),
+      chain: {
+        id: currentChain.id,
+        name: currentChain.name,
+        nativeCurrency: {
+          name: currentChain.token ?? "ETH",
+          symbol: currentChain.token ?? "ETH",
+          decimals: 18
+        },
+        rpcUrls: {
+          default: { http: [currentChain.rpcUrl] },
+          public: { http: [currentChain.rpcUrl] }
+        }
+      }
+    });
+  }, [currentChain]);
+
+  const walletClient = useMemo<WalletClient | null>(() => {
+    if (!isConnected || !evmAccount || !currentChain?.rpcUrl) return null;
+
+    const address = evmAccount.includes(":") ? evmAccount.split(":").pop()! : evmAccount;
+
+    return createWalletClient({
+      transport: http(currentChain.rpcUrl),
+      chain: {
+        id: currentChain.id,
+        name: currentChain.name,
+        nativeCurrency: {
+          name: currentChain.token ?? "ETH",
+          symbol: currentChain.token ?? "ETH",
+          decimals: 18
+        },
+        rpcUrls: {
+          default: { http: [currentChain.rpcUrl] },
+          public: { http: [currentChain.rpcUrl] }
+        }
+      },
+      account: address as `0x${string}`
+    });
+  }, [isConnected, evmAccount, currentChain]);
+
+  return {
+    publicClient,
+    walletClient,
+    chains
+  };
+}

package/src/hooks/useWallet.test.ts

@@ -0,0 +1,133 @@
+/// <reference types="vitest" />
+/// @vitest-environment jsdom
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+
+// Mock useWeb3 before importing hooks
+const mockUseWeb3 = vi.fn();
+vi.mock("../provider/Web3ConnectProvider", () => ({
+  useWeb3: () => mockUseWeb3(),
+  Web3ConnectProvider: ({ children }: { children: React.ReactNode }) => children,
+}));
+
+import { useWallet } from "./useWallet";
+import type { Web3ContextValue } from "../provider/Web3ConnectProvider";
+
+function createMockWeb3(overrides: Partial<Web3ContextValue> = {}): Web3ContextValue {
+  const base: Web3ContextValue = {
+    status: "disconnected",
+    session: null,
+    accounts: [],
+    chainId: null,
+    error: null,
+    isConnected: false,
+    chains: [],
+    sessionManager: null,
+    clearError: () => {},
+    connect: vi.fn(),
+    disconnect: vi.fn(),
+    reconnect: vi.fn(),
+    switchChain: vi.fn(),
+    startPairing: vi.fn(),
+    completePairing: vi.fn(),
+    connectInjected: vi.fn(),
+    connectEmbedded: vi.fn(),
+    connectPasskeys: vi.fn(),
+    ...overrides,
+  };
+  return base;
+}
+
+describe("useWallet", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should return disconnected state by default", () => {
+    mockUseWeb3.mockReturnValue(createMockWeb3());
+    const { result } = renderHook(() => useWallet());
+
+    expect(result.current.isConnected).toBe(false);
+    expect(result.current.isConnecting).toBe(false);
+    expect(result.current.isReconnecting).toBe(false);
+    expect(result.current.status).toBe("disconnected");
+    expect(result.current.currentAccount).toBeNull();
+  });
+
+  it("should reflect connected state", () => {
+    mockUseWeb3.mockReturnValue(
+      createMockWeb3({
+        status: "connected",
+        isConnected: true,
+        accounts: ["eip155:1:0x1234"],
+        chainId: "eip155:1",
+      })
+    );
+    const { result } = renderHook(() => useWallet());
+
+    expect(result.current.isConnected).toBe(true);
+    expect(result.current.status).toBe("connected");
+    expect(result.current.currentAccount).toBe("eip155:1:0x1234");
+    expect(result.current.chainId).toBe("eip155:1");
+  });
+
+  it("should reflect connecting state", () => {
+    mockUseWeb3.mockReturnValue(
+      createMockWeb3({
+        status: "connecting",
+      })
+    );
+    const { result } = renderHook(() => useWallet());
+
+    expect(result.current.isConnecting).toBe(true);
+    expect(result.current.isConnected).toBe(false);
+  });
+
+  it("should reflect reconnecting state", () => {
+    mockUseWeb3.mockReturnValue(
+      createMockWeb3({
+        status: "reconnecting",
+      })
+    );
+    const { result } = renderHook(() => useWallet());
+
+    expect(result.current.isReconnecting).toBe(true);
+  });
+
+  it("should pass through connect function", () => {
+    const connect = vi.fn();
+    mockUseWeb3.mockReturnValue(createMockWeb3({ connect }));
+    const { result } = renderHook(() => useWallet());
+
+    result.current.connect();
+    expect(connect).toHaveBeenCalledTimes(1);
+  });
+
+  it("should pass through disconnect function", () => {
+    const disconnect = vi.fn();
+    mockUseWeb3.mockReturnValue(createMockWeb3({ disconnect }));
+    const { result } = renderHook(() => useWallet());
+
+    result.current.disconnect();
+    expect(disconnect).toHaveBeenCalledTimes(1);
+  });
+
+  it("should return null currentAccount when no accounts", () => {
+    mockUseWeb3.mockReturnValue(createMockWeb3({ accounts: [] }));
+    const { result } = renderHook(() => useWallet());
+
+    expect(result.current.currentAccount).toBeNull();
+  });
+
+  it("should use first account as currentAccount", () => {
+    mockUseWeb3.mockReturnValue(
+      createMockWeb3({
+        accounts: ["eip155:1:0xabc", "eip155:137:0xdef"],
+      })
+    );
+    const { result } = renderHook(() => useWallet());
+
+    expect(result.current.currentAccount).toBe("eip155:1:0xabc");
+  });
+});

package/src/hooks/useWallet.ts

@@ -0,0 +1,39 @@
+import { useWeb3 } from "../provider/Web3ConnectProvider";
+
+export function useWallet() {
+  const {
+    status,
+    session,
+    accounts,
+    chainId,
+    error,
+    connect,
+    disconnect,
+    reconnect,
+    switchChain
+  } = useWeb3();
+
+  const isConnected = status === "connected";
+  const isConnecting = status === "connecting";
+  const isReconnecting = status === "reconnecting";
+
+  const currentAccount = accounts[0] ?? null;
+  const isDisconnected = status === "disconnected";
+
+  return {
+    status,
+    session,
+    accounts,
+    chainId,
+    error,
+    isConnected,
+    isConnecting,
+    isReconnecting,
+    isDisconnected,
+    currentAccount,
+    connect,
+    disconnect,
+    reconnect,
+    switchChain
+  };
+}

package/src/hooks/useWeb3ErrorHandler.ts

@@ -0,0 +1,102 @@
+"use client";
+
+import { useCallback, useMemo } from "react";
+import { useWeb3 } from "../provider/Web3ConnectProvider";
+import {
+  getUserFriendlyError,
+  isRetryableError,
+} from "../utils/errorMessages";
+
+export interface UserFriendlyError {
+  title: string;
+  description: string;
+  code?: string;
+}
+
+export interface UseWeb3ErrorHandlerReturn {
+  /** Current error from the provider */
+  error: Error | null;
+  /** User-friendly representation of the current error */
+  friendlyError: UserFriendlyError | null;
+  /** Clear the current error */
+  clearError: () => void;
+  /** Check if current error is retryable */
+  isRetryable: boolean;
+  /** Get a user-friendly version of any error */
+  formatError: (error: unknown) => UserFriendlyError;
+  /** Wraps an async function with error formatting */
+  wrapAsync: <T>(fn: () => Promise<T>) => () => Promise<T>;
+}
+
+/**
+ * Hook that provides user-friendly error handling for web3 operations.
+ *
+ * Features:
+ * - Maps WalletError codes to human-readable messages
+ * - Provides retry detection for transient errors
+ * - Wraps async operations with consistent error formatting
+ * - Exposes the current error state from Web3ConnectProvider
+ *
+ * @example
+ * ```tsx
+ * const { friendlyError, clearError, isRetryable, wrapAsync } = useWeb3ErrorHandler();
+ *
+ * // Show error in UI
+ * if (friendlyError) {
+ *   return <ErrorDisplay title={friendlyError.title} message={friendlyError.description} />;
+ * }
+ *
+ * // Wrap an operation
+ * const safeConnect = wrapAsync(() => connect());
+ * await safeConnect();
+ * ```
+ */
+export function useWeb3ErrorHandler(): UseWeb3ErrorHandlerReturn {
+  const { error, clearError: providerClearError } = useWeb3();
+
+  const friendlyError: UserFriendlyError | null = useMemo(
+    () => (error ? getUserFriendlyError(error) : null),
+    [error]
+  );
+
+  const isRetryable = useMemo(
+    () => (error ? isRetryableError(error) : false),
+    [error]
+  );
+
+  const clearError = useCallback(() => {
+    providerClearError();
+  }, [providerClearError]);
+
+  const formatError = useCallback(
+    (err: unknown): UserFriendlyError => getUserFriendlyError(err),
+    []
+  );
+
+  const wrapAsync = useCallback(
+    <T,>(fn: () => Promise<T>): (() => Promise<T>) => {
+      return async () => {
+        try {
+          return await fn();
+        } catch (err) {
+          // Re-throw with user-friendly information attached
+          const friendly = getUserFriendlyError(err);
+          const enhanced = new Error(friendly.description) as unknown as Record<string, unknown>;
+          enhanced.title = friendly.title;
+          enhanced.code = friendly.code;
+          throw enhanced;
+        }
+      };
+    },
+    []
+  );
+
+  return {
+    error,
+    friendlyError,
+    clearError,
+    isRetryable,
+    formatError,
+    wrapAsync,
+  };
+}