@naculus/connect-appkit-react 0.1.2

package/src/hooks/useTokenBalance.test.ts

@@ -0,0 +1,337 @@
+/// <reference types="vitest" />
+/// @vitest-environment jsdom
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import type { Address } from "viem";
+
+const mockUseWeb3 = vi.fn();
+vi.mock("../provider/Web3ConnectProvider", () => ({
+  useWeb3: () => mockUseWeb3(),
+}));
+
+const mockUseAccount = vi.fn();
+vi.mock("./useAccount", () => ({
+  useAccount: () => mockUseAccount(),
+}));
+
+const mockReadContract = vi.fn();
+const mockCreatePublicClient = vi.fn();
+const mockFormatUnits = vi.fn((value: bigint, decimals: number) => {
+  const str = value.toString();
+  const padded = str.padStart(decimals + 1, "0");
+  const intPart = padded.slice(0, padded.length - decimals) || "0";
+  const fracPart = padded.slice(padded.length - decimals).replace(/0+$/, "");
+  return fracPart ? intPart + "." + fracPart : intPart;
+});
+
+vi.mock("viem", () => ({
+  createPublicClient: (...args: unknown[]) => mockCreatePublicClient(...args),
+  http: (url: string) => ({ transport: "http", url }),
+  formatUnits: (...args: [bigint, number]) => mockFormatUnits(...args),
+}));
+
+import { useTokenBalance } from "./useTokenBalance";
+import type { TokenInfo } from "./useTokenBalance";
+
+const USDC: TokenInfo = {
+  address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" as Address,
+  symbol: "USDC",
+  decimals: 6,
+  name: "USD Coin",
+};
+
+const DAI: TokenInfo = {
+  address: "0x6B175474E89094C44Da98b954EedeAC495271d0F" as Address,
+  symbol: "DAI",
+  decimals: 18,
+  name: "Dai Stablecoin",
+};
+
+describe("useTokenBalance", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCreatePublicClient.mockImplementation(({ chain }) => ({
+      chain,
+      readContract: mockReadContract,
+    }));
+  });
+
+  it("should fetch a single token balance", async () => {
+    mockReadContract.mockResolvedValue(BigInt("1000000"));
+    mockUseWeb3.mockReturnValue({
+      chainId: "eip155:1",
+      chains: [{ id: 1, namespace: "eip155", name: "Ethereum", rpcUrl: "https://eth.llamarpc.com", token: "ETH" }],
+    });
+    mockUseAccount.mockReturnValue({
+      evmAccount: "eip155:1:0x1234567890123456789012345678901234567890",
+      isConnected: true,
+    });
+
+    const { result } = renderHook(() => useTokenBalance({ tokens: [USDC] }));
+
+    await waitFor(() => {
+      expect(mockReadContract).toHaveBeenCalledTimes(1);
+    });
+
+    await waitFor(() => {
+      expect(result.current.tokenBalances).toHaveLength(1);
+    });
+    expect(result.current.tokenBalances[0].balance).toBe("1000000");
+    expect(result.current.tokenBalances[0].formatted).toBe("1");
+    expect(result.current.tokenBalances[0].symbol).toBe("USDC");
+    expect(result.current.tokenBalances[0].address).toBe(USDC.address);
+  });
+
+  it("should fetch multiple token balances", async () => {
+    mockReadContract
+      .mockResolvedValueOnce(BigInt("1000000"))
+      .mockResolvedValueOnce(BigInt("5000000000000000000"));
+    mockUseWeb3.mockReturnValue({
+      chainId: "eip155:1",
+      chains: [{ id: 1, namespace: "eip155", name: "Ethereum", rpcUrl: "https://eth.llamarpc.com", token: "ETH" }],
+    });
+    mockUseAccount.mockReturnValue({
+      evmAccount: "eip155:1:0x1234567890123456789012345678901234567890",
+      isConnected: true,
+    });
+
+    const { result } = renderHook(() => useTokenBalance({ tokens: [USDC, DAI] }));
+
+    await waitFor(() => {
+      expect(mockReadContract).toHaveBeenCalledTimes(2);
+    });
+
+    await waitFor(() => {
+      expect(result.current.tokenBalances).toHaveLength(2);
+    });
+
+    expect(result.current.tokenBalances[0].symbol).toBe("USDC");
+    expect(result.current.tokenBalances[0].balance).toBe("1000000");
+    expect(result.current.tokenBalances[0].formatted).toBe("1");
+    expect(result.current.tokenBalances[1].symbol).toBe("DAI");
+    expect(result.current.tokenBalances[1].balance).toBe("5000000000000000000");
+    expect(result.current.tokenBalances[1].formatted).toBe("5");
+  });
+
+  it("should handle readContract error for a single token", async () => {
+    mockReadContract.mockRejectedValue(new Error("RPC error"));
+    mockUseWeb3.mockReturnValue({
+      chainId: "eip155:1",
+      chains: [{ id: 1, namespace: "eip155", name: "Ethereum", rpcUrl: "https://eth.llamarpc.com", token: "ETH" }],
+    });
+    mockUseAccount.mockReturnValue({
+      evmAccount: "eip155:1:0x1234567890123456789012345678901234567890",
+      isConnected: true,
+    });
+
+    const { result } = renderHook(() => useTokenBalance({ tokens: [USDC] }));
+
+    await waitFor(() => {
+      expect(result.current.tokenBalances[0]).toBeDefined();
+    });
+
+    expect(result.current.tokenBalances[0].balance).toBeNull();
+    expect(result.current.tokenBalances[0].formatted).toBeNull();
+    expect(result.current.tokenBalances[0].symbol).toBe("USDC");
+  });
+
+  it("should handle partial failure with multiple tokens", async () => {
+    mockReadContract
+      .mockResolvedValueOnce(BigInt("1000000"))
+      .mockRejectedValueOnce(new Error("DAI error"));
+    mockUseWeb3.mockReturnValue({
+      chainId: "eip155:1",
+      chains: [{ id: 1, namespace: "eip155", name: "Ethereum", rpcUrl: "https://eth.llamarpc.com", token: "ETH" }],
+    });
+    mockUseAccount.mockReturnValue({
+      evmAccount: "eip155:1:0x1234567890123456789012345678901234567890",
+      isConnected: true,
+    });
+
+    const { result } = renderHook(() => useTokenBalance({ tokens: [USDC, DAI] }));
+
+    await waitFor(() => {
+      expect(result.current.tokenBalances).toHaveLength(2);
+    });
+
+    expect(result.current.tokenBalances[0].symbol).toBe("USDC");
+    expect(result.current.tokenBalances[0].balance).toBe("1000000");
+    expect(result.current.tokenBalances[1].symbol).toBe("DAI");
+    expect(result.current.tokenBalances[1].balance).toBeNull();
+    expect(result.current.tokenBalances[1].formatted).toBeNull();
+  });
+
+  it("should return empty array when no tokens specified", async () => {
+    mockUseWeb3.mockReturnValue({
+      chainId: "eip155:1",
+      chains: [{ id: 1, namespace: "eip155", name: "Ethereum", rpcUrl: "https://eth.llamarpc.com", token: "ETH" }],
+    });
+    mockUseAccount.mockReturnValue({
+      evmAccount: "eip155:1:0x1234567890123456789012345678901234567890",
+      isConnected: true,
+    });
+
+    const { result } = renderHook(() => useTokenBalance({ tokens: [] }));
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    });
+
+    expect(mockReadContract).not.toHaveBeenCalled();
+    expect(result.current.tokenBalances).toEqual([]);
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it("should return empty array when not connected", async () => {
+    mockUseWeb3.mockReturnValue({
+      chainId: null,
+      chains: [],
+    });
+    mockUseAccount.mockReturnValue({
+      evmAccount: null,
+      isConnected: false,
+    });
+
+    const { result } = renderHook(() => useTokenBalance({ tokens: [USDC] }));
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    });
+
+    expect(mockReadContract).not.toHaveBeenCalled();
+    expect(result.current.tokenBalances).toEqual([]);
+  });
+
+  it("should expose getTokenBalance helper", async () => {
+    mockReadContract.mockResolvedValue(BigInt("1000000"));
+    mockUseWeb3.mockReturnValue({
+      chainId: "eip155:1",
+      chains: [{ id: 1, namespace: "eip155", name: "Ethereum", rpcUrl: "https://eth.llamarpc.com", token: "ETH" }],
+    });
+    mockUseAccount.mockReturnValue({
+      evmAccount: "eip155:1:0x1234567890123456789012345678901234567890",
+      isConnected: true,
+    });
+
+    const { result } = renderHook(() => useTokenBalance({ tokens: [USDC, DAI] }));
+
+    await waitFor(() => {
+      expect(mockReadContract).toHaveBeenCalledTimes(2);
+    });
+
+    await waitFor(() => {
+      expect(result.current.tokenBalances).toHaveLength(2);
+    });
+
+    const usdcResult = result.current.getTokenBalance(USDC.address);
+    expect(usdcResult).toBeDefined();
+    expect(usdcResult!.symbol).toBe("USDC");
+    expect(usdcResult!.balance).toBe("1000000");
+
+    const unknown = result.current.getTokenBalance("0x0000000000000000000000000000000000000000" as Address);
+    expect(unknown).toBeUndefined();
+  });
+
+  it("should auto-refresh at specified interval", async () => {
+    vi.useFakeTimers();
+    mockReadContract.mockResolvedValue(BigInt("1000000"));
+    mockUseWeb3.mockReturnValue({
+      chainId: "eip155:1",
+      chains: [{ id: 1, namespace: "eip155", name: "Ethereum", rpcUrl: "https://eth.llamarpc.com", token: "ETH" }],
+    });
+    mockUseAccount.mockReturnValue({
+      evmAccount: "eip155:1:0x1234567890123456789012345678901234567890",
+      isConnected: true,
+    });
+
+    renderHook(() => useTokenBalance({ tokens: [USDC], refreshInterval: 10000 }));
+
+    await act(async () => {
+      vi.advanceTimersByTime(0);
+    });
+    expect(mockReadContract).toHaveBeenCalledTimes(1);
+
+    mockReadContract.mockResolvedValue(BigInt("2000000"));
+    await act(async () => {
+      vi.advanceTimersByTime(10000);
+    });
+    expect(mockReadContract).toHaveBeenCalledTimes(2);
+
+    await act(async () => {
+      vi.advanceTimersByTime(10000);
+    });
+    expect(mockReadContract).toHaveBeenCalledTimes(3);
+
+    vi.useRealTimers();
+  });
+
+  it("should clear interval on unmount", async () => {
+    vi.useFakeTimers();
+    mockReadContract.mockResolvedValue(BigInt("1000000"));
+    mockUseWeb3.mockReturnValue({
+      chainId: "eip155:1",
+      chains: [{ id: 1, namespace: "eip155", name: "Ethereum", rpcUrl: "https://eth.llamarpc.com", token: "ETH" }],
+    });
+    mockUseAccount.mockReturnValue({
+      evmAccount: "eip155:1:0x1234567890123456789012345678901234567890",
+      isConnected: true,
+    });
+
+    const { unmount } = renderHook(() =>
+      useTokenBalance({ tokens: [USDC], refreshInterval: 5000 })
+    );
+
+    await act(async () => {
+      vi.advanceTimersByTime(0);
+    });
+    const callsAfterMount = mockReadContract.mock.calls.length;
+
+    unmount();
+
+    vi.advanceTimersByTime(10000);
+    expect(mockReadContract).toHaveBeenCalledTimes(callsAfterMount);
+
+    vi.useRealTimers();
+  });
+
+  it("should not auto-refresh when refreshInterval is 0", async () => {
+    vi.useFakeTimers();
+    mockReadContract.mockResolvedValue(BigInt("1000000"));
+    mockUseWeb3.mockReturnValue({
+      chainId: "eip155:1",
+      chains: [{ id: 1, namespace: "eip155", name: "Ethereum", rpcUrl: "https://eth.llamarpc.com", token: "ETH" }],
+    });
+    mockUseAccount.mockReturnValue({
+      evmAccount: "eip155:1:0x1234567890123456789012345678901234567890",
+      isConnected: true,
+    });
+
+    renderHook(() => useTokenBalance({ tokens: [USDC], refreshInterval: 0 }));
+
+    await act(async () => {
+      vi.advanceTimersByTime(0);
+    });
+    const callsAfterInit = mockReadContract.mock.calls.length;
+
+    vi.advanceTimersByTime(30000);
+    expect(mockReadContract).toHaveBeenCalledTimes(callsAfterInit);
+
+    vi.useRealTimers();
+  });
+
+  it("should use chain token symbol as default when no tokens match", () => {
+    mockUseWeb3.mockReturnValue({
+      chainId: "eip155:1",
+      chains: [{ id: 1, namespace: "eip155", name: "Ethereum", rpcUrl: "https://eth.llamarpc.com", token: "ETH" }],
+    });
+    mockUseAccount.mockReturnValue({
+      evmAccount: null,
+      isConnected: false,
+    });
+
+    const { result } = renderHook(() => useTokenBalance({ tokens: [] }));
+    expect(result.current.chain).toBeDefined();
+    expect(result.current.chain!.name).toBe("Ethereum");
+  });
+});

package/src/hooks/useTokenBalance.ts

@@ -0,0 +1,210 @@
+import { useState, useEffect, useCallback, useMemo, useRef } from "react";
+import { useWeb3 } from "../provider/Web3ConnectProvider";
+import { useAccount } from "./useAccount";
+import {
+  createPublicClient,
+  http,
+  formatUnits,
+  type PublicClient,
+  type Address,
+} from "viem";
+
+export interface TokenInfo {
+  /** ERC-20 token contract address */
+  address: Address;
+  /** Token symbol (e.g. "USDC", "LINK") */
+  symbol: string;
+  /** Token decimals (e.g. 6 for USDC, 18 for most) */
+  decimals: number;
+  /** Optional display name */
+  name?: string;
+}
+
+export interface UseTokenBalanceOptions {
+  /** ERC-20 token(s) to query */
+  tokens: TokenInfo[];
+  /** Auto-refresh interval in milliseconds. Default: undefined (no auto-refresh). */
+  refreshInterval?: number;
+}
+
+export interface TokenBalanceResult {
+  address: Address;
+  symbol: string;
+  decimals: number;
+  name?: string;
+  /** Raw balance as string (in smallest unit), or null if not loaded */
+  balance: string | null;
+  /** Human-readable formatted balance, or null if not loaded */
+  formatted: string | null;
+}
+
+export function useTokenBalance(options: UseTokenBalanceOptions) {
+  const { evmAccount, isConnected } = useAccount();
+  const { chainId, chains } = useWeb3();
+  const [tokenBalances, setTokenBalances] = useState<TokenBalanceResult[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const { tokens, refreshInterval } = options;
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  // Stable key for tokens to avoid infinite loops when array reference changes
+  const tokensKey = useMemo(
+    () => tokens.map(t => t.address.toLowerCase() + "|" + t.decimals + "|" + t.symbol).join(","),
+    [tokens]
+  );
+
+  const currentChain = useMemo(() => {
+    if (!chainId || !chains.length) return null;
+    const namespace = chainId.startsWith("eip155:") ? "eip155" : null;
+    if (!namespace) return null;
+    const chainNum = parseInt(chainId.split(":")[1], 10);
+    return chains.find((c) => c.namespace === namespace && c.id === chainNum) ?? null;
+  }, [chainId, chains]);
+
+  const [client, setClient] = useState<PublicClient | null>(null);
+
+  useEffect(() => {
+    if (!currentChain?.rpcUrl) {
+      setClient(null);
+      return;
+    }
+
+    const publicClient = 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] },
+        },
+      },
+    });
+
+    setClient(publicClient);
+  }, [currentChain]);
+
+  // ERC-20 ABI fragment for balanceOf
+  const erc20Abi = [
+    {
+      name: "balanceOf",
+      type: "function",
+      stateMutability: "view",
+      inputs: [{ name: "owner", type: "address" }],
+      outputs: [{ name: "balance", type: "uint256" }],
+    },
+  ] as const;
+
+  const fetchTokenBalances = useCallback(async () => {
+    if (!evmAccount || !client || tokens.length === 0) {
+      setTokenBalances([]);
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const address = evmAccount.includes(":")
+        ? (evmAccount.split(":").pop() as Address)
+        : (evmAccount as Address);
+
+      // Query all token balances with individual error handling
+      const results = await Promise.allSettled(
+        tokens.map(async (token) => {
+          try {
+            const balance = await client.readContract({
+              address: token.address,
+              abi: erc20Abi,
+              functionName: "balanceOf",
+              args: [address],
+            });
+            return {
+              address: token.address,
+              symbol: token.symbol,
+              decimals: token.decimals,
+              name: token.name,
+              balance: balance.toString(),
+              formatted: formatUnits(balance, token.decimals),
+            } as TokenBalanceResult;
+          } catch {
+            return {
+              address: token.address,
+              symbol: token.symbol,
+              decimals: token.decimals,
+              name: token.name,
+              balance: null,
+              formatted: null,
+            } as TokenBalanceResult;
+          }
+        })
+      );
+
+      const balances: TokenBalanceResult[] = results.map((r) => {
+        if (r.status === "fulfilled") {
+          return r.value;
+        }
+        // Fallback for rejected promises (shouldn't happen with inner catch)
+        return {
+          address: "" as Address,
+          symbol: "?",
+          decimals: 0,
+          balance: null,
+          formatted: null,
+        };
+      });
+
+      setTokenBalances(balances);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error("Failed to fetch token balances"));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [evmAccount, client, tokensKey]);
+
+  // Initial fetch
+  useEffect(() => {
+    if (isConnected && evmAccount && tokens.length > 0) {
+      fetchTokenBalances();
+    }
+  }, [isConnected, evmAccount, tokensKey, fetchTokenBalances]);
+
+  // Auto-refresh interval
+  useEffect(() => {
+    if (refreshInterval && refreshInterval > 0 && isConnected && evmAccount && tokens.length > 0) {
+      intervalRef.current = setInterval(fetchTokenBalances, refreshInterval);
+    }
+    return () => {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+        intervalRef.current = null;
+      }
+    };
+  }, [refreshInterval, isConnected, evmAccount, tokensKey, fetchTokenBalances]);
+
+  // Helper: get a single token balance by address
+  const getTokenBalance = useCallback(
+    (tokenAddress: Address): TokenBalanceResult | undefined => {
+      return tokenBalances.find(
+        (tb) => tb.address.toLowerCase() === tokenAddress.toLowerCase()
+      );
+    },
+    [tokenBalances]
+  );
+
+  return {
+    /** Array of token balance results */
+    tokenBalances,
+    isLoading,
+    error,
+    /** Re-fetch all token balances */
+    refetch: fetchTokenBalances,
+    /** Get a specific token balance by contract address */
+    getTokenBalance,
+    chain: currentChain,
+  };
+}