web3-frontend

Web3 前端技能

通过钱包集成、现代化库（viem/wagmi）和生产级 dApp 模式，精通 Web3 前端开发。

快速开始

# Invoke this skill for Web3 frontend development
Skill("web3-frontend", topic="wallet", framework="react")

涵盖主题

1. 钱包集成

将用户连接到 Web3：

• RainbowKit：美观的钱包弹窗
• WalletConnect：支持移动设备
• 账户抽象：ERC-4337
• 多链：切换网络

2. 交易管理

处理区块链交互：

• 写入操作：合约写入
• 状态跟踪：待处理、已确认
• Gas 估算：显示费用
• 错误处理：提供用户友好的消息

3. 签名与身份验证

验证用户身份：

• EIP-712：类型化数据签名
• SIWE：使用 Ethereum 登录
• Permit：免 Gas 授权
• 消息签名：个人签名

4. React Hooks

使用 wagmi 的现代模式：

• useAccount：连接状态
• useWriteContract：交易
• useReadContract：数据获取
• useWaitForTransactionReceipt：确认状态

代码示例

连接钱包

'use client';

import { ConnectButton } from '@rainbow-me/rainbowkit';
import { useAccount } from 'wagmi';

export function WalletConnect() {
  const { address, isConnected } = useAccount();

  return (
    <div>
      <ConnectButton />
      {isConnected && <p>Connected: {address}</p>}
    </div>
  );
}

写入合约

import { useWriteContract, useWaitForTransactionReceipt } from 'wagmi';
import { parseEther } from 'viem';

export function MintButton() {
  const { writeContract, data: hash, isPending } = useWriteContract();
  const { isLoading, isSuccess } = useWaitForTransactionReceipt({ hash });

  const mint = () => {
    writeContract({
      address: '0x...',
      abi: [...],
      functionName: 'mint',
      args: [1n],
      value: parseEther('0.08'),
    });
  };

  return (
    <button onClick={mint} disabled={isPending || isLoading}>
      {isPending ? 'Confirm in wallet...' :
       isLoading ? 'Minting...' :
       isSuccess ? 'Minted!' : 'Mint NFT'}
    </button>
  );
}

签署类型化数据（EIP-712）

import { useSignTypedData } from 'wagmi';

const DOMAIN = {
  name: 'My App',
  version: '1',
  chainId: 1,
  verifyingContract: '0x...',
};

export function useSignOrder() {
  const { signTypedDataAsync } = useSignTypedData();

  const sign = async (order: Order) => {
    return await signTypedDataAsync({
      domain: DOMAIN,
      types: { Order: [...] },
      primaryType: 'Order',
      message: order,
    });
  };

  return { sign };
}

错误处理

export function parseError(error: unknown): string {
  const msg = error instanceof Error ? error.message : String(error);

  if (msg.includes('user rejected')) return 'Transaction cancelled';
  if (msg.includes('insufficient funds')) return 'Insufficient balance';
  if (msg.includes('execution reverted')) {
    const reason = msg.match(/reason="([^"]+)"/)?.[1];
    return reason || 'Transaction would fail';
  }

  return 'Transaction failed';
}

包配置

npm install wagmi viem @rainbow-me/rainbowkit @tanstack/react-query

// providers/Web3.tsx
import { WagmiProvider } from 'wagmi';
import { RainbowKitProvider } from '@rainbow-me/rainbowkit';
import { QueryClientProvider, QueryClient } from '@tanstack/react-query';
import { config } from './config';

const queryClient = new QueryClient();

export function Web3Provider({ children }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <RainbowKitProvider>{children}</RainbowKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

常见模式

模式	使用场景	Hook
连接钱包	用户身份验证	useAccount
读取数据	显示余额	useReadContract
写入交易	铸造、转账	useWriteContract
等待交易	确认状态	useWaitForTransactionReceipt
签署消息	身份验证、授权	useSignMessage

常见问题

问题	影响	解决方案
水合错误	SSR 不匹配	使用 dynamic 并设置 ssr: false
BigInt 序列化	JSON.stringify	自定义序列化器
数据过期	缓存问题	使用 refetchInterval

故障排除

“钱包无法连接”

// Ensure client-side only
import dynamic from 'next/dynamic';

const ConnectButton = dynamic(
  () => import('./ConnectButton'),
  { ssr: false }
);

“交易一直处于待处理状态”

检查 Gas 设置或加快交易速度：

await wallet.sendTransaction({
  ...tx,
  maxFeePerGas: tx.maxFeePerGas * 120n / 100n,
});

安全检查清单

• 切勿公开私钥
• 验证合约地址
• 清理用户输入
• 使用适当的错误边界
• 实施 CSP 标头

交叉引用

• Bonded Agent：05-web3-frontend
• 相关技能：ethereum-development、solidity-development

版本历史

版本	日期	变更
2.0.0	2025-01	使用 wagmi v2、viem，达到生产级标准
1.0.0	2024-12	首次发布