用 OnchainKit 构建链上应用时的组件编排与状态处理

在 React 应用中用 OnchainKit SDK 集成身份、钱包、交易、Swap 和 Frame 组件时的实现与错误处理规范。

适用场景

解决思路

1. 在应用根节点用 OnchainKitProvider 包裹所有 OnchainKit 组件，并通过 apiKey 和 chain 参数配置 API key 与链（示例：apiKey={process.env.NEXT_PUBLIC_ONCHAINKIT_API_KEY}、chain={base}）。
2. 身份（Identity）组件：使用 Avatar、Name、Badge 展示用户身份；为 ENS/Basename 解析选择正确的链；处理加载状态与 fallback；通过与 Identity provider 组合实现可复用模式。
3. 钱包（Wallet）组件：正确配置 ConnectWallet，搭配 WalletDropdown 提供额外选项；正确处理钱包连接状态；配置 Wallet provider 与链。
4. 交易（Transaction）组件：用 Transaction 组件发起链上交易；处理错误与状态更新；配置 gas 估算与赞助（sponsorship）；管理交易生命周期状态。
5. Swap 组件：实现代币选择与金额输入；处理报价（quote）与价格更新；配置滑点（slippage）设置；管理 swap 交易状态。
6. Frame 组件：用 FrameMetadata 做正确的 frame 配置；处理并校验 frame message；处理 frame 响应；遵循安全最佳实践。
7. 遵循组件层级与组合模式：把子组件（如 Avatar、Name）放进父组件（如 ConnectWallet、Wallet）内部，不要打平或跨层组合。
8. 处理组件所有可能的状态，包括加载态、错误态与空/回退态，不要只渲染成功路径。
9. 为 props 与状态使用明确的变量名和正确的 TypeScript 类型。
10. 实现错误边界（error boundary）以捕获渲染期异常。
11. 优雅处理 API 错误，不要让其直接冒泡到 UI。
12. 向用户展示可读的错误信息，而非原始错误对象。
13. 使用正确的 TypeScript 错误类型来标注 catch/错误分支。
14. 恰当处理边界情况（如钱包未连接、链不匹配、报价过期）。
15. 提供准确的 TypeScript 代码示例，并聚焦于 OnchainKit 的具体实现细节。
16. 始终遵循安全最佳实践，尤其是 frame 消息校验与 API key 的使用方式。

适用边界 · 注意事项

• 项目不是 React 前端，或无法使用 @coinbase/onchainkit 包时。
• 没有 OnchainKit API key（需在 Coinbase 开发者后台申请）时，无法完成 provider 配置。
• 目标链不在 OnchainKit 支持的链列表中，或不想依赖 Coinbase 生态服务时。