@multiplatform.one/web3 5.0.27

package/src/hooks/useContractWrite.spec.ts

@@ -0,0 +1,212 @@
+// @vitest-environment happy-dom
+import { act, renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { mockUseSimulateContract, mockUseWriteContract, mockUseWaitForTransactionReceipt } =
+  vi.hoisted(() => ({
+    mockUseSimulateContract: vi.fn(),
+    mockUseWriteContract: vi.fn(),
+    mockUseWaitForTransactionReceipt: vi.fn(),
+  }));
+
+vi.mock("wagmi", () => ({
+  useSimulateContract: mockUseSimulateContract,
+  useWriteContract: mockUseWriteContract,
+  useWaitForTransactionReceipt: mockUseWaitForTransactionReceipt,
+}));
+
+import { useContractWrite } from "./useContractWrite";
+
+const testAbi = [] as any;
+const baseConfig = {
+  address: "0x1234567890abcdef1234567890abcdef12345678" as any,
+  abi: testAbi,
+  functionName: "withdraw",
+};
+
+describe("useContractWrite", () => {
+  const mockWriteContractAsync = vi.fn();
+  const mockResetWrite = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    mockUseSimulateContract.mockReturnValue({ error: null });
+    mockUseWriteContract.mockReturnValue({
+      writeContractAsync: mockWriteContractAsync,
+      data: undefined,
+      isPending: false,
+      reset: mockResetWrite,
+      error: null,
+    });
+    mockUseWaitForTransactionReceipt.mockReturnValue({
+      data: undefined,
+      isLoading: false,
+      isSuccess: false,
+      error: null,
+    });
+  });
+
+  it("starts with idle status and all false flags", () => {
+    const { result } = renderHook(() => useContractWrite(baseConfig));
+
+    expect(result.current.status).toBe("idle");
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.isSuccess).toBe(false);
+    expect(result.current.isError).toBe(false);
+    expect(result.current.hash).toBeUndefined();
+    expect(result.current.receipt).toBeUndefined();
+    expect(result.current.error).toBeNull();
+    expect(result.current.simulationError).toBeNull();
+  });
+
+  it("write() sets simulating status immediately before the delay", () => {
+    // Never resolves so we can inspect the intermediate simulating state
+    mockWriteContractAsync.mockReturnValue(new Promise(() => {}));
+
+    const { result } = renderHook(() => useContractWrite(baseConfig));
+
+    act(() => {
+      result.current.write(); // don't await — pauses at the internal setTimeout
+    });
+
+    expect(result.current.status).toBe("simulating");
+  });
+
+  it("write() ends in pending-confirmation on success", async () => {
+    const txHash = "0xdeadbeef" as any;
+    mockWriteContractAsync.mockResolvedValue(txHash);
+
+    const { result } = renderHook(() => useContractWrite(baseConfig));
+
+    await act(async () => {
+      await result.current.write();
+    });
+
+    expect(result.current.status).toBe("pending-confirmation");
+  });
+
+  it("write() returns the transaction hash", async () => {
+    const txHash = "0xdeadbeef" as any;
+    mockWriteContractAsync.mockResolvedValue(txHash);
+
+    const { result } = renderHook(() => useContractWrite(baseConfig));
+
+    let returnedHash: any;
+    await act(async () => {
+      returnedHash = await result.current.write();
+    });
+
+    expect(returnedHash).toBe(txHash);
+  });
+
+  it("write() sets error status when writeContractAsync throws", async () => {
+    mockWriteContractAsync.mockRejectedValue(new Error("user rejected"));
+    const onError = vi.fn();
+
+    const { result } = renderHook(() => useContractWrite({ ...baseConfig, onError }));
+
+    await act(async () => {
+      await result.current.write();
+    });
+
+    expect(result.current.status).toBe("error");
+    expect(onError).toHaveBeenCalledWith(expect.any(Error));
+  });
+
+  it("write() aborts early with error when simError is present and simulate=true", async () => {
+    mockUseSimulateContract.mockReturnValue({ error: new Error("simulation failed") });
+    const onError = vi.fn();
+
+    const { result } = renderHook(() => useContractWrite({ ...baseConfig, onError }));
+
+    await act(async () => {
+      await result.current.write();
+    });
+
+    expect(result.current.status).toBe("error");
+    expect(result.current.simulationError).toBeInstanceOf(Error);
+    expect(mockWriteContractAsync).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalled();
+  });
+
+  it("write() does NOT abort on simError when simulate=false", async () => {
+    mockUseSimulateContract.mockReturnValue({ error: new Error("sim error") });
+    mockWriteContractAsync.mockResolvedValue("0xhash" as any);
+
+    const { result } = renderHook(() => useContractWrite({ ...baseConfig, simulate: false }));
+
+    await act(async () => {
+      await result.current.write();
+    });
+
+    expect(mockWriteContractAsync).toHaveBeenCalled();
+    expect(result.current.simulationError).toBeNull();
+  });
+
+  it("reset() returns to idle status and calls wagmi reset", async () => {
+    mockWriteContractAsync.mockRejectedValue(new Error("fail"));
+
+    const { result } = renderHook(() => useContractWrite(baseConfig));
+
+    await act(async () => {
+      await result.current.write();
+    });
+
+    expect(result.current.status).toBe("error");
+
+    act(() => {
+      result.current.reset();
+    });
+
+    expect(result.current.status).toBe("idle");
+    expect(result.current.simulationError).toBeNull();
+    expect(mockResetWrite).toHaveBeenCalled();
+  });
+
+  it("transitions to success status when receipt is confirmed", () => {
+    const receipt = { transactionHash: "0xhash", blockNumber: 100n } as any;
+
+    mockUseWaitForTransactionReceipt.mockReturnValue({
+      data: receipt,
+      isLoading: false,
+      isSuccess: true,
+      error: null,
+    });
+
+    const { result } = renderHook(() => useContractWrite(baseConfig));
+
+    expect(result.current.status).toBe("success");
+    expect(result.current.isSuccess).toBe(true);
+    expect(result.current.receipt).toBe(receipt);
+  });
+
+  it("calls onSuccess callback when receipt is confirmed", () => {
+    const receipt = { transactionHash: "0xhash" } as any;
+    const onSuccess = vi.fn();
+
+    mockUseWaitForTransactionReceipt.mockReturnValue({
+      data: receipt,
+      isLoading: false,
+      isSuccess: true,
+      error: null,
+    });
+
+    renderHook(() => useContractWrite({ ...baseConfig, onSuccess }));
+
+    expect(onSuccess).toHaveBeenCalledWith(receipt);
+  });
+
+  it("isLoading is true when write is pending", () => {
+    mockUseWriteContract.mockReturnValue({
+      writeContractAsync: mockWriteContractAsync,
+      data: undefined,
+      isPending: true,
+      reset: mockResetWrite,
+      error: null,
+    });
+
+    const { result } = renderHook(() => useContractWrite(baseConfig));
+    expect(result.current.isLoading).toBe(true);
+  });
+});

package/src/hooks/useContractWrite.ts

@@ -0,0 +1,206 @@
+import { useCallback, useState } from "react";
+import type { Abi, Address, Hash, TransactionReceipt } from "viem";
+import { useWriteContract, useWaitForTransactionReceipt, useSimulateContract } from "wagmi";
+
+export type TransactionStatus =
+  | "idle"
+  | "simulating"
+  | "pending-signature"
+  | "pending-confirmation"
+  | "success"
+  | "error";
+
+export interface ContractWriteConfig {
+  address: Address;
+  abi: Abi;
+  functionName: string;
+  chainId?: number;
+  value?: bigint;
+  simulate?: boolean;
+  onSuccess?: (receipt: TransactionReceipt) => void;
+  onError?: (error: Error) => void;
+}
+
+export interface ContractWriteResult {
+  write: (args?: readonly unknown[]) => Promise<Hash | undefined>;
+  reset: () => void;
+  status: TransactionStatus;
+  hash: Hash | undefined;
+  receipt: TransactionReceipt | undefined;
+  isLoading: boolean;
+  isPending: boolean;
+  isSuccess: boolean;
+  isError: boolean;
+  error: Error | null;
+  simulationError: Error | null;
+}
+
+/**
+ * Hook for writing data to a smart contract.
+ * Handles transaction simulation, signature, and confirmation.
+ *
+ * @example
+ * ```tsx
+ * const { write, status, isLoading, error, receipt } = useContractWrite({
+ *   address: "0x...",
+ *   abi: lockAbi,
+ *   functionName: "withdraw",
+ *   onSuccess: (receipt) => console.log("Withdrawal successful!", receipt),
+ *   onError: (error) => console.error("Transaction failed:", error),
+ * });
+ *
+ * // Call write with optional args
+ * await write();
+ * ```
+ */
+export function useContractWrite(config: ContractWriteConfig): ContractWriteResult {
+  const {
+    address,
+    abi,
+    functionName,
+    chainId,
+    value,
+    simulate = true,
+    onSuccess,
+    onError,
+  } = config;
+
+  const [status, setStatus] = useState<TransactionStatus>("idle");
+  const [currentArgs, setCurrentArgs] = useState<readonly unknown[] | undefined>();
+  const [simulationError, setSimulationError] = useState<Error | null>(null);
+
+  // Simulate contract call (optional) - use type assertion for wagmi's strict typing
+  const { error: simError } = useSimulateContract({
+    address,
+    abi: abi as readonly unknown[],
+    functionName: functionName as string,
+    args: currentArgs as readonly unknown[] | undefined,
+    chainId,
+    value,
+    query: {
+      enabled: simulate && !!currentArgs,
+    },
+  } as Parameters<typeof useSimulateContract>[0]);
+
+  // Write contract
+  const {
+    writeContractAsync,
+    data: hash,
+    isPending: isWritePending,
+    reset: resetWrite,
+    error: writeError,
+  } = useWriteContract();
+
+  // Wait for transaction receipt
+  const {
+    data: receipt,
+    isLoading: isWaitingForReceipt,
+    isSuccess: isConfirmed,
+    error: receiptError,
+  } = useWaitForTransactionReceipt({
+    hash,
+    query: {
+      enabled: !!hash,
+    },
+  });
+
+  // Combined error
+  const error = writeError || receiptError || null;
+
+  // Derived states
+  const isLoading = isWritePending || isWaitingForReceipt;
+  const isPending = status === "pending-signature" || status === "pending-confirmation";
+  const isSuccess = status === "success";
+  const isError = status === "error";
+
+  // Update status based on transaction state
+  const updateStatus = useCallback(() => {
+    if (receipt && isConfirmed) {
+      setStatus("success");
+      onSuccess?.(receipt);
+    } else if (error) {
+      setStatus("error");
+      onError?.(error as Error);
+    } else if (hash && isWaitingForReceipt) {
+      setStatus("pending-confirmation");
+    } else if (isWritePending) {
+      setStatus("pending-signature");
+    }
+  }, [receipt, isConfirmed, error, hash, isWaitingForReceipt, isWritePending, onSuccess, onError]);
+
+  // Call updateStatus when dependencies change
+  if (receipt && isConfirmed && status !== "success") {
+    updateStatus();
+  } else if (error && status !== "error") {
+    updateStatus();
+  } else if (hash && isWaitingForReceipt && status !== "pending-confirmation") {
+    updateStatus();
+  } else if (isWritePending && status !== "pending-signature") {
+    updateStatus();
+  }
+
+  const write = useCallback(
+    async (args?: readonly unknown[]): Promise<Hash | undefined> => {
+      try {
+        setCurrentArgs(args);
+        setSimulationError(null);
+
+        // Check simulation error
+        if (simulate && simError) {
+          setSimulationError(simError as Error);
+          setStatus("error");
+          onError?.(simError as Error);
+          return undefined;
+        }
+
+        setStatus("simulating");
+
+        // Small delay for simulation feedback
+        if (simulate) {
+          await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+
+        setStatus("pending-signature");
+
+        // Use type assertion for wagmi's strict typing
+        const txHash = await writeContractAsync({
+          address,
+          abi: abi as readonly unknown[],
+          functionName: functionName as string,
+          args: args as readonly unknown[] | undefined,
+          chainId,
+          value,
+        } as Parameters<typeof writeContractAsync>[0]);
+
+        setStatus("pending-confirmation");
+        return txHash;
+      } catch (err) {
+        setStatus("error");
+        onError?.(err as Error);
+        return undefined;
+      }
+    },
+    [address, abi, functionName, chainId, value, simulate, simError, writeContractAsync, onError],
+  );
+
+  const reset = useCallback(() => {
+    setStatus("idle");
+    setCurrentArgs(undefined);
+    setSimulationError(null);
+    resetWrite();
+  }, [resetWrite]);
+
+  return {
+    write,
+    reset,
+    status,
+    hash,
+    receipt,
+    isLoading,
+    isPending,
+    isSuccess,
+    isError,
+    error: error as Error | null,
+    simulationError,
+  };
+}

package/src/hooks/useWallet.spec.ts

@@ -0,0 +1,183 @@
+// @vitest-environment happy-dom
+import { act, renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  mockUseAccount,
+  mockUseChainId,
+  mockUseChains,
+  mockUseConnect,
+  mockUseDisconnect,
+  mockUseSwitchChain,
+  mockUseBalance,
+} = vi.hoisted(() => ({
+  mockUseAccount: vi.fn(),
+  mockUseChainId: vi.fn(),
+  mockUseChains: vi.fn(),
+  mockUseConnect: vi.fn(),
+  mockUseDisconnect: vi.fn(),
+  mockUseSwitchChain: vi.fn(),
+  mockUseBalance: vi.fn(),
+}));
+
+vi.mock("wagmi", () => ({
+  useAccount: mockUseAccount,
+  useChainId: mockUseChainId,
+  useChains: mockUseChains,
+  useConnect: mockUseConnect,
+  useDisconnect: mockUseDisconnect,
+  useSwitchChain: mockUseSwitchChain,
+  useBalance: mockUseBalance,
+}));
+
+import { useWallet } from "./useWallet";
+
+describe("useWallet", () => {
+  const mockConnect = vi.fn();
+  const mockDisconnectAsync = vi.fn();
+  const mockSwitchChainAsync = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockUseAccount.mockReturnValue({
+      address: undefined,
+      isConnected: false,
+      isConnecting: false,
+      isDisconnected: true,
+      isReconnecting: false,
+      chain: undefined,
+    });
+    mockUseChainId.mockReturnValue(1);
+    mockUseChains.mockReturnValue([]);
+    mockUseConnect.mockReturnValue({ connect: mockConnect, connectors: [] });
+    mockUseDisconnect.mockReturnValue({ disconnectAsync: mockDisconnectAsync });
+    mockUseSwitchChain.mockReturnValue({ switchChainAsync: mockSwitchChainAsync });
+    mockUseBalance.mockReturnValue({ data: undefined });
+  });
+
+  it("returns empty displayAddress when no address", () => {
+    const { result } = renderHook(() => useWallet());
+    expect(result.current.displayAddress).toBe("");
+  });
+
+  it("returns truncated displayAddress when address is set", () => {
+    mockUseAccount.mockReturnValue({
+      address: "0x1234567890abcdef1234" as any,
+      isConnected: true,
+      isConnecting: false,
+      isDisconnected: false,
+      isReconnecting: false,
+      chain: undefined,
+    });
+
+    const { result } = renderHook(() => useWallet());
+    expect(result.current.displayAddress).toBe("0x1234...1234");
+  });
+
+  it("connect() prefers injected connector", () => {
+    const injected = { id: "injected" };
+    const wc = { id: "walletConnect" };
+    const other = { id: "other" };
+    mockUseConnect.mockReturnValue({ connect: mockConnect, connectors: [other, wc, injected] });
+
+    const { result } = renderHook(() => useWallet());
+    act(() => {
+      result.current.connect();
+    });
+    expect(mockConnect).toHaveBeenCalledWith({ connector: injected });
+  });
+
+  it("connect() prefers walletConnect when no injected connector", () => {
+    const wc = { id: "walletConnect" };
+    const other = { id: "other" };
+    mockUseConnect.mockReturnValue({ connect: mockConnect, connectors: [other, wc] });
+
+    const { result } = renderHook(() => useWallet());
+    act(() => {
+      result.current.connect();
+    });
+    expect(mockConnect).toHaveBeenCalledWith({ connector: wc });
+  });
+
+  it("connect() falls back to first connector when no injected or walletConnect", () => {
+    const other = { id: "other" };
+    mockUseConnect.mockReturnValue({ connect: mockConnect, connectors: [other] });
+
+    const { result } = renderHook(() => useWallet());
+    act(() => {
+      result.current.connect();
+    });
+    expect(mockConnect).toHaveBeenCalledWith({ connector: other });
+  });
+
+  it("connect() does nothing when connectors list is empty", () => {
+    mockUseConnect.mockReturnValue({ connect: mockConnect, connectors: [] });
+
+    const { result } = renderHook(() => useWallet());
+    act(() => {
+      result.current.connect();
+    });
+    expect(mockConnect).not.toHaveBeenCalled();
+  });
+
+  it("disconnect() calls disconnectAsync", async () => {
+    const { result } = renderHook(() => useWallet());
+    await act(async () => {
+      await result.current.disconnect();
+    });
+    expect(mockDisconnectAsync).toHaveBeenCalled();
+  });
+
+  it("switchChain() calls switchChainAsync with given chainId", async () => {
+    const { result } = renderHook(() => useWallet());
+    await act(async () => {
+      await result.current.switchChain(137);
+    });
+    expect(mockSwitchChainAsync).toHaveBeenCalledWith({ chainId: 137 });
+  });
+
+  it("returns formatted balance data when available", () => {
+    mockUseAccount.mockReturnValue({
+      address: "0xabc" as any,
+      isConnected: true,
+      isConnecting: false,
+      isDisconnected: false,
+      isReconnecting: false,
+      chain: undefined,
+    });
+    mockUseBalance.mockReturnValue({
+      data: { value: 1000000000000000000n, symbol: "ETH", decimals: 18 },
+    });
+
+    const { result } = renderHook(() => useWallet());
+    expect(result.current.balance).toBe("1000000000000000000");
+    expect(result.current.balanceSymbol).toBe("ETH");
+    expect(result.current.balanceFormatted).toBe("1");
+  });
+
+  it("returns undefined balance fields when no balance data", () => {
+    const { result } = renderHook(() => useWallet());
+    expect(result.current.balance).toBeUndefined();
+    expect(result.current.balanceSymbol).toBeUndefined();
+    expect(result.current.balanceFormatted).toBeUndefined();
+  });
+
+  it("passes through account state fields", () => {
+    mockUseAccount.mockReturnValue({
+      address: "0xabc" as any,
+      isConnected: true,
+      isConnecting: false,
+      isDisconnected: false,
+      isReconnecting: true,
+      chain: { id: 1, name: "Ethereum" } as any,
+    });
+    mockUseChainId.mockReturnValue(1);
+    mockUseChains.mockReturnValue([{ id: 1 }, { id: 137 }] as any);
+
+    const { result } = renderHook(() => useWallet());
+    expect(result.current.isConnected).toBe(true);
+    expect(result.current.isReconnecting).toBe(true);
+    expect(result.current.chainId).toBe(1);
+    expect(result.current.chains).toHaveLength(2);
+  });
+});

package/src/hooks/useWallet.ts

@@ -0,0 +1,96 @@
+import { useCallback } from "react";
+import { formatUnits } from "viem";
+import type { Address, Chain } from "viem";
+import {
+  useAccount,
+  useBalance,
+  useChainId,
+  useChains,
+  useConnect,
+  useDisconnect,
+  useSwitchChain,
+} from "wagmi";
+
+export interface WalletState {
+  address: Address | undefined;
+  isConnected: boolean;
+  isConnecting: boolean;
+  isDisconnected: boolean;
+  isReconnecting: boolean;
+  chain: Chain | undefined;
+  chainId: number | undefined;
+  chains: readonly Chain[];
+  balance: string | undefined;
+  balanceSymbol: string | undefined;
+  balanceFormatted: string | undefined;
+  displayAddress: string;
+}
+
+export interface WalletActions {
+  connect: () => void;
+  disconnect: () => Promise<void>;
+  switchChain: (chainId: number) => Promise<void>;
+}
+
+export interface UseWalletResult extends WalletState, WalletActions {}
+
+export function useWallet(): UseWalletResult {
+  const { address, isConnected, isConnecting, isDisconnected, isReconnecting, chain } =
+    useAccount();
+
+  const chainId = useChainId();
+  const chains = useChains();
+  const { connect, connectors } = useConnect();
+  const { disconnectAsync } = useDisconnect();
+  const { switchChainAsync } = useSwitchChain();
+
+  const { data: balanceData } = useBalance({
+    address,
+    query: {
+      enabled: !!address,
+    },
+  });
+
+  const handleConnect = useCallback(() => {
+    const injectedConnector = connectors.find((c) => c.id === "injected");
+    const wcConnector = connectors.find((c) => c.id === "walletConnect");
+    const connector = injectedConnector || wcConnector || connectors[0];
+
+    if (connector) {
+      connect({ connector });
+    }
+  }, [connectors, connect]);
+
+  const handleDisconnect = useCallback(async () => {
+    await disconnectAsync();
+  }, [disconnectAsync]);
+
+  const handleSwitchChain = useCallback(
+    async (targetChainId: number) => {
+      await switchChainAsync({ chainId: targetChainId });
+    },
+    [switchChainAsync],
+  );
+
+  const displayAddress = address ? `${address.slice(0, 6)}...${address.slice(-4)}` : "";
+
+  return {
+    address,
+    isConnected,
+    isConnecting,
+    isDisconnected,
+    isReconnecting,
+    chain,
+    chainId,
+    chains,
+    balance: balanceData?.value?.toString(),
+    balanceSymbol: balanceData?.symbol,
+    balanceFormatted: balanceData
+      ? formatUnits(balanceData.value, balanceData.decimals)
+      : undefined,
+    displayAddress,
+    connect: handleConnect,
+    disconnect: handleDisconnect,
+    switchChain: handleSwitchChain,
+  };
+}