web3-frontend

用途

Web3 Frontend 是一个面向 Web3 前端开发的技能，用于帮助开发者构建生产级去中心化应用（dApp）前端。它围绕钱包集成、现代 Web3 库（viem/wagmi）以及 dApp 用户体验展开，适合需要将区块链交互能力接入 React 前端的开发场景。

主要能力

该技能覆盖以下主题：

1. 钱包集成：将用户连接到 Web3，包括 RainbowKit 钱包弹窗、WalletConnect 移动端支持、ERC-4337 账户抽象以及多链网络切换。

2. 交易管理：处理区块链交互，包括合约写入操作、交易状态跟踪（pending、confirmed）、Gas 估算与费用展示，以及面向用户的错误信息处理。

3. 签名与认证：验证用户身份，包括 EIP-712 类型化数据签名、SIWE（Sign-In with Ethereum）、Permit 无 Gas 授权以及个人消息签名。

4. React Hooks：使用 wagmi 的现代模式，包括 useAccount（连接状态）、useWriteContract（交易）、useReadContract（数据获取）、useWaitForTransactionReceipt（确认）等。

使用方式

通过技能调用方式使用，例如：

Skill("web3-frontend", topic="wallet", framework="react")

安装依赖：

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

技能提供了 Provider 配置示例（WagmiProvider、RainbowKitProvider、QueryClientProvider 组合）、连接钱包组件示例、写入合约组件示例、EIP-712 签名 Hook 示例以及错误解析函数示例。

适用场景

适用于构建需要钱包连接、合约读写、交易确认、用户签名认证的 React dApp 前端。技能中列出了常见模式对照表，将连接钱包、读取数据、写入交易、等待交易、签名消息等用例映射到对应的 wagmi Hook。

限制与注意事项

技能列出了常见陷阱：SSR 水合错误（建议使用 dynamic 配合 ssr: false）、BigInt 序列化问题（需自定义序列化器）、数据陈旧（可使用 refetchInterval）。故障排查部分涉及钱包无法连接（确保仅客户端渲染）和交易长时间 pending（检查 Gas 设置或加速）。安全清单要求：绝不暴露私钥、验证合约地址、清理用户输入、使用错误边界、实现 CSP 头。

版本历史显示 2.0.0（2025-01）为基于 wagmi v2、viem 的生产级版本，1.0.0（2024-12）为初始版本。相关技能包括 ethereum-development、solidity-development。