@multiplatform.one/web3 5.0.27

package/src/examples/LockContract.tsx

@@ -0,0 +1,273 @@
+import { useMemo } from "react";
+import type { Address } from "viem";
+import { formatEther } from "viem";
+import { YStack, XStack, Text, Button, Separator, Card } from "tamagui";
+import { useContractRead } from "../hooks/useContractRead";
+import { useContractWrite } from "../hooks/useContractWrite";
+import { TransactionStatus } from "../components/TransactionStatus";
+import { useBalance } from "wagmi";
+
+/**
+ * ABI for the Lock contract (hardhat example).
+ * This is a minimal ABI with only the functions we need.
+ */
+export const lockAbi = [
+  {
+    inputs: [],
+    name: "unlockTime",
+    outputs: [{ type: "uint256", name: "" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [],
+    name: "owner",
+    outputs: [{ type: "address", name: "" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [],
+    name: "withdraw",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function",
+  },
+  {
+    anonymous: false,
+    inputs: [
+      { indexed: false, name: "amount", type: "uint256" },
+      { indexed: false, name: "when", type: "uint256" },
+    ],
+    name: "Withdrawal",
+    type: "event",
+  },
+] as const;
+
+export interface LockContractProps {
+  address: Address;
+  chainId?: number;
+  explorerUrl?: string;
+}
+
+/**
+ * Example component demonstrating smart contract interaction patterns.
+ *
+ * This component shows how to:
+ * 1. Read contract state (unlockTime, owner, balance)
+ * 2. Write to a contract (withdraw)
+ * 3. Display transaction status
+ * 4. Handle errors gracefully
+ *
+ * @example
+ * ```tsx
+ * <LockContract
+ *   address="0x5FbDB2315678afecb367f032d93F642f64180aa3"
+ *   chainId={1}
+ *   explorerUrl="https://etherscan.io"
+ * />
+ * ```
+ */
+export function LockContract({ address, chainId, explorerUrl }: LockContractProps) {
+  // Read unlock time
+  const {
+    data: unlockTime,
+    isLoading: isLoadingUnlockTime,
+    error: unlockTimeError,
+    refetch: refetchUnlockTime,
+  } = useContractRead<bigint>({
+    address,
+    abi: lockAbi,
+    functionName: "unlockTime",
+    chainId,
+    watch: true,
+  });
+
+  // Read owner address
+  const {
+    data: owner,
+    isLoading: isLoadingOwner,
+    error: ownerError,
+  } = useContractRead<Address>({
+    address,
+    abi: lockAbi,
+    functionName: "owner",
+    chainId,
+  });
+
+  // Get contract balance
+  const { data: balanceData, isLoading: isLoadingBalance } = useBalance({
+    address,
+    query: { enabled: !!address },
+  });
+
+  // Withdraw function
+  const {
+    write: withdraw,
+    status: withdrawStatus,
+    hash: withdrawHash,
+    receipt: withdrawReceipt,
+    error: withdrawError,
+    reset: resetWithdraw,
+    isLoading: isWithdrawing,
+  } = useContractWrite({
+    address,
+    abi: lockAbi,
+    functionName: "withdraw",
+    chainId,
+    onSuccess: (receipt) => {
+      console.log("Withdrawal successful!", receipt);
+      refetchUnlockTime();
+    },
+    onError: (error) => {
+      console.error("Withdrawal failed:", error);
+    },
+  });
+
+  // Format unlock time
+  const formattedUnlockTime = useMemo(() => {
+    if (!unlockTime) return "Loading...";
+    const date = new Date(Number(unlockTime) * 1000);
+    return date.toLocaleString();
+  }, [unlockTime]);
+
+  // Check if unlock time has passed
+  const canWithdraw = useMemo(() => {
+    if (!unlockTime) return false;
+    return Date.now() >= Number(unlockTime) * 1000;
+  }, [unlockTime]);
+
+  // Time remaining
+  const timeRemaining = useMemo(() => {
+    if (!unlockTime) return null;
+    const unlockMs = Number(unlockTime) * 1000;
+    const now = Date.now();
+    if (now >= unlockMs) return null;
+
+    const diff = unlockMs - now;
+    const days = Math.floor(diff / (1000 * 60 * 60 * 24));
+    const hours = Math.floor((diff % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
+    const minutes = Math.floor((diff % (1000 * 60 * 60)) / (1000 * 60));
+
+    if (days > 0) return `${days}d ${hours}h ${minutes}m`;
+    if (hours > 0) return `${hours}h ${minutes}m`;
+    return `${minutes}m`;
+  }, [unlockTime]);
+
+  const handleWithdraw = async () => {
+    await withdraw();
+  };
+
+  const isLoading = isLoadingUnlockTime || isLoadingOwner || isLoadingBalance;
+  const hasError = unlockTimeError || ownerError;
+
+  return (
+    <Card padding="$4" borderWidth={1} borderColor="$borderColor">
+      <YStack gap="$4">
+        {/* Header */}
+        <YStack gap="$1">
+          <Text fontSize="$6" fontWeight="700">
+            Lock Contract
+          </Text>
+          <Text fontSize="$2" color="$gray10" fontFamily="$mono">
+            {address}
+          </Text>
+        </YStack>
+
+        <Separator />
+
+        {/* Contract State */}
+        <YStack gap="$3">
+          <Text fontSize="$4" fontWeight="600">
+            Contract State
+          </Text>
+
+          {isLoading ? (
+            <Text color="$gray10">Loading contract data...</Text>
+          ) : hasError ? (
+            <YStack gap="$2">
+              <Text color="$red10">Error loading contract data</Text>
+              <Text fontSize="$2" color="$red9">
+                {(unlockTimeError || ownerError)?.message}
+              </Text>
+            </YStack>
+          ) : (
+            <YStack gap="$3">
+              {/* Balance */}
+              <XStack justifyContent="space-between" alignItems="center">
+                <Text color="$gray11">Locked Balance</Text>
+                <Text fontWeight="600" fontSize="$4">
+                  {balanceData ? formatEther(balanceData.value) : "0"} ETH
+                </Text>
+              </XStack>
+
+              {/* Unlock Time */}
+              <XStack justifyContent="space-between" alignItems="center">
+                <Text color="$gray11">Unlock Time</Text>
+                <YStack alignItems="flex-end">
+                  <Text fontWeight="500">{formattedUnlockTime}</Text>
+                  {timeRemaining && (
+                    <Text fontSize="$2" color="$orange10">
+                      {timeRemaining} remaining
+                    </Text>
+                  )}
+                  {canWithdraw && (
+                    <Text fontSize="$2" color="$green10">
+                      Ready to withdraw
+                    </Text>
+                  )}
+                </YStack>
+              </XStack>
+
+              {/* Owner */}
+              <XStack justifyContent="space-between" alignItems="center">
+                <Text color="$gray11">Owner</Text>
+                <Text fontFamily="$mono" fontSize="$2">
+                  {owner ? `${owner.slice(0, 6)}...${owner.slice(-4)}` : "Unknown"}
+                </Text>
+              </XStack>
+            </YStack>
+          )}
+        </YStack>
+
+        <Separator />
+
+        {/* Withdraw Action */}
+        <YStack gap="$3">
+          <Text fontSize="$4" fontWeight="600">
+            Actions
+          </Text>
+
+          <Button
+            size="$4"
+            theme={canWithdraw ? "green" : "gray"}
+            disabled={!canWithdraw || isWithdrawing}
+            onPress={handleWithdraw}
+            opacity={canWithdraw ? 1 : 0.5}
+          >
+            <Text fontWeight="600">{isWithdrawing ? "Processing..." : "Withdraw Funds"}</Text>
+          </Button>
+
+          {!canWithdraw && unlockTime && (
+            <Text fontSize="$2" color="$gray10" textAlign="center">
+              Funds are locked until the unlock time passes
+            </Text>
+          )}
+        </YStack>
+
+        {/* Transaction Status */}
+        {withdrawStatus !== "idle" && (
+          <TransactionStatus
+            status={withdrawStatus}
+            hash={withdrawHash}
+            receipt={withdrawReceipt}
+            error={withdrawError}
+            onRetry={resetWithdraw}
+            onDismiss={resetWithdraw}
+            explorerUrl={explorerUrl}
+          />
+        )}
+      </YStack>
+    </Card>
+  );
+}

package/src/examples/index.ts

@@ -0,0 +1 @@
+export { LockContract, lockAbi, type LockContractProps } from "./LockContract";

package/src/hooks/index.ts

@@ -0,0 +1,33 @@
+export { useWallet, type UseWalletResult, type WalletActions, type WalletState } from "./useWallet";
+
+export {
+  useContractRead,
+  type ContractReadConfig,
+  type ContractReadResult,
+} from "./useContractRead";
+
+export {
+  useContractWrite,
+  type ContractWriteConfig,
+  type ContractWriteResult,
+  type TransactionStatus,
+} from "./useContractWrite";
+
+// Re-export commonly used wagmi hooks for convenience
+export {
+  useAccount,
+  useBalance,
+  useChainId,
+  useChains,
+  useConnect,
+  useDisconnect,
+  useEnsAvatar,
+  useEnsName,
+  useSignMessage,
+  useSwitchChain,
+  useBlockNumber,
+  useReadContract,
+  useWriteContract,
+  useSimulateContract,
+  useWaitForTransactionReceipt,
+} from "wagmi";

package/src/hooks/useContractRead.spec.ts

@@ -0,0 +1,134 @@
+// @vitest-environment happy-dom
+import { renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { mockUseBlockNumber, mockUseReadContract } = vi.hoisted(() => ({
+  mockUseBlockNumber: vi.fn(),
+  mockUseReadContract: vi.fn(),
+}));
+
+vi.mock("wagmi", () => ({
+  useBlockNumber: mockUseBlockNumber,
+  useReadContract: mockUseReadContract,
+}));
+
+import { useContractRead } from "./useContractRead";
+
+const testAbi = [
+  {
+    name: "getValue",
+    type: "function",
+    inputs: [],
+    outputs: [{ type: "uint256" }],
+    stateMutability: "view",
+  },
+] as any;
+
+const baseConfig = {
+  address: "0x1234567890abcdef1234567890abcdef12345678" as any,
+  abi: testAbi,
+  functionName: "getValue",
+};
+
+describe("useContractRead", () => {
+  const mockRefetch = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockUseBlockNumber.mockReturnValue({ data: undefined });
+    mockUseReadContract.mockReturnValue({
+      data: undefined,
+      isLoading: false,
+      isError: false,
+      error: null,
+      refetch: mockRefetch,
+      isRefetching: false,
+    });
+  });
+
+  it("returns initial state with no data", () => {
+    const { result } = renderHook(() => useContractRead(baseConfig));
+
+    expect(result.current.data).toBeUndefined();
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.isError).toBe(false);
+    expect(result.current.error).toBeNull();
+    expect(result.current.isRefetching).toBe(false);
+  });
+
+  it("returns data from useReadContract", () => {
+    mockUseReadContract.mockReturnValue({
+      data: 42n,
+      isLoading: false,
+      isError: false,
+      error: null,
+      refetch: mockRefetch,
+      isRefetching: false,
+    });
+
+    const { result } = renderHook(() => useContractRead(baseConfig));
+    expect(result.current.data).toBe(42n);
+  });
+
+  it("calls refetch when blockNumber changes with watch=true", () => {
+    mockUseBlockNumber.mockReturnValue({ data: 100n });
+
+    renderHook(() => useContractRead({ ...baseConfig, watch: true }));
+
+    expect(mockRefetch).toHaveBeenCalled();
+  });
+
+  it("does not call refetch when watch=false even if blockNumber is set", () => {
+    mockUseBlockNumber.mockReturnValue({ data: 100n });
+
+    renderHook(() => useContractRead({ ...baseConfig, watch: false }));
+
+    expect(mockRefetch).not.toHaveBeenCalled();
+  });
+
+  it("does not call refetch when watch=true but blockNumber is undefined", () => {
+    mockUseBlockNumber.mockReturnValue({ data: undefined });
+
+    renderHook(() => useContractRead({ ...baseConfig, watch: true }));
+
+    expect(mockRefetch).not.toHaveBeenCalled();
+  });
+
+  it("passes enabled=false to useReadContract query", () => {
+    renderHook(() => useContractRead({ ...baseConfig, enabled: false }));
+
+    expect(mockUseReadContract).toHaveBeenCalledWith(
+      expect.objectContaining({ query: { enabled: false } }),
+    );
+  });
+
+  it("passes enabled=true to useReadContract query by default", () => {
+    renderHook(() => useContractRead(baseConfig));
+
+    expect(mockUseReadContract).toHaveBeenCalledWith(
+      expect.objectContaining({ query: { enabled: true } }),
+    );
+  });
+
+  it("forwards useBlockNumber watch option", () => {
+    renderHook(() => useContractRead({ ...baseConfig, watch: true }));
+
+    expect(mockUseBlockNumber).toHaveBeenCalledWith(expect.objectContaining({ watch: true }));
+  });
+
+  it("returns error from useReadContract", () => {
+    const err = new Error("contract error");
+    mockUseReadContract.mockReturnValue({
+      data: undefined,
+      isLoading: false,
+      isError: true,
+      error: err,
+      refetch: mockRefetch,
+      isRefetching: false,
+    });
+
+    const { result } = renderHook(() => useContractRead(baseConfig));
+    expect(result.current.isError).toBe(true);
+    expect(result.current.error).toBe(err);
+  });
+});

package/src/hooks/useContractRead.ts

@@ -0,0 +1,81 @@
+import { useCallback, useMemo } from "react";
+import type { Abi, Address } from "viem";
+import { useReadContract, useBlockNumber } from "wagmi";
+
+export interface ContractReadConfig {
+  address: Address;
+  abi: Abi;
+  functionName: string;
+  args?: readonly unknown[];
+  chainId?: number;
+  enabled?: boolean;
+  watch?: boolean;
+}
+
+export interface ContractReadResult<TData = unknown> {
+  data: TData | undefined;
+  isLoading: boolean;
+  isError: boolean;
+  error: Error | null;
+  refetch: () => void;
+  isRefetching: boolean;
+}
+
+/**
+ * Hook for reading data from a smart contract.
+ * Supports watching for changes by refetching on new blocks.
+ *
+ * @example
+ * ```tsx
+ * const { data: unlockTime, isLoading, error } = useContractRead({
+ *   address: "0x...",
+ *   abi: lockAbi,
+ *   functionName: "unlockTime",
+ *   watch: true, // Automatically refetch on new blocks
+ * });
+ * ```
+ */
+export function useContractRead<TData = unknown>(
+  config: ContractReadConfig,
+): ContractReadResult<TData> {
+  const { address, abi, functionName, args, chainId, enabled = true, watch = false } = config;
+
+  // Watch for block changes if watch is enabled
+  const { data: blockNumber } = useBlockNumber({
+    watch,
+    query: { enabled: watch },
+  });
+
+  // Read contract data - use type assertion for wagmi's strict typing
+  const { data, isLoading, isError, error, refetch, isRefetching } = useReadContract({
+    address,
+    abi: abi as readonly unknown[],
+    functionName: functionName as string,
+    args: args as readonly unknown[] | undefined,
+    chainId,
+    query: {
+      enabled,
+    },
+  } as Parameters<typeof useReadContract>[0]);
+
+  // Auto-refetch on new block when watching
+  const handleRefetch = useCallback(() => {
+    refetch();
+  }, [refetch]);
+
+  // Trigger refetch when block number changes
+  useMemo(() => {
+    if (watch && blockNumber !== undefined) {
+      handleRefetch();
+    }
+  }, [blockNumber, watch, handleRefetch]);
+
+  return {
+    data: data as TData | undefined,
+    isLoading,
+    isError,
+    error: error as Error | null,
+    refetch: handleRefetch,
+    isRefetching,
+  };
+}