用途
Wagmi v3 技能用于在 React/Next.js 应用中集成 EVM 链钱包，并完成智能合约的读取与写入。它适合需要连接钱包、查询链上数据、发起交易并跟踪交易状态的场景。
主要能力
- 使用 Wagmi v3.x 钩子管理钱包状态：useAccount、useWriteContract、useReadContract、useWaitForTransactionReceipt、useSimulateContract。
- 使用 viem v2 进行地址校验（getAddress）和交易工具处理（parseEther、parseGwei）。
- 为特定合约交互创建自定义钩子。
- 显式处理连接状态：disconnected、connecting、connected、reconnecting。
- 使用 OpenAPI 规范生成的合约 ABI 与类型。
- 通过 Wagmi 使用 TanStack Query 进行合约数据的缓存与重新获取。
- 写入前模拟合约以校验并估算 gas。
- 使用 enabled 标志进行条件查询，避免不必要的请求。
- 在 SSR 场景下使用 cookie 存储保持钱包状态。
使用方式
该技能要求使用 Wagmi v3.3.2+、viem v2.44.4、React 18+ 或 Next.js 14+、TypeScript v5+（strict 模式）、TanStack Query v5+（Wagmi 的 peer dependency），WalletConnect v2+ 为可选项（用于 WalletConnect 连接器）。
必须遵守的约束：
- 使用 Wagmi v3.x，而非 v1 或 v2，因为 v1/v2 模式不兼容。
- 使用 viem 的 getAddress() 校验地址，绝不直接进行字符串类型断言。
- 在 Next.js 中正确处理 SSR，钱包组件使用 dynamic 并设置 ssr: false。
建议做法：
- 为合约交互创建自定义钩子。
- 写入前使用 useSimulateContract 模拟合约。
- 使用 enabled 标志进行条件查询。
- 使用 cookie 存储实现 SSR 持久化。
- 显式处理所有连接状态。
应避免：
- 除非确有必要进行抽象，否则不要包装 OpenAPI 客户端生成的钩子。
- 不要在组件中暴露私钥或敏感钱包数据。
- 不要跳过地址校验。
适用场景
适用于 React/Next.js 前端中的 EVM 链钱包连接、合约读写、交易状态管理与错误处理，以及基于合约的自定义钩子封装。
限制
该技能不覆盖 Solana 前端开发、后端 RPC 交互和智能合约开发。更多模式与代码示例见 PATTERNS.md。