jaw-sdk-best-practices

JAW SDK 最佳实践

使用 JAW SDK，在 EVM 链上构建采用通行密钥认证、具有可编程权限的智能账户应用的指南。

适用场景

在以下情况下，请参考这些指南：

• 安装或设置 @jaw.id/wagmi、@jaw.id/core 或 @jaw.id/ui
• 配置 JAW 连接器或提供程序（API 密钥、模式、支付主导方、ENS）
• 使用通行密钥认证连接或断开钱包
• 通过 JAW 智能账户发送交易（单笔或批量）
• 签署消息或类型化数据（EIP-191、EIP-712、ERC-7871）
• 授予、查询或撤销权限（ERC-7715）
• 实现订阅付款或定期扣款
• 使用支付主导方设置 Gas 赞助（ERC-7677）
• 在用户引导过程中向用户签发 ENS 子名称
• 实现以太坊登录（SIWE）
• 构建无头集成、服务端操作或 AI Agent 钱包
• 直接使用 Account 类（不使用 UI）
• 通过 EIP-7702 将 EOA 升级为智能账户（保留现有地址）
• 集成嵌入式钱包提供商（Privy、Turnkey 等），以支持 EIP-7702
• 构建稳定币支付流程（USDC Gas、批量付款）
• 在 CrossPlatform 和 AppSpecific 认证模式之间进行选择
• 为 AppSpecific 模式实现自定义 UI 处理程序
• 使用通行密钥认证的智能账户构建 React Native / Expo 应用
• 审查或调试使用 JAW SDK 的代码

关键事实

• 软件包： @jaw.id/wagmi（React）、@jaw.id/core（原生 JS / 服务端）、@jaw.id/ui（AppSpecific 模式 UI）
• API 密钥： 必需。请访问 https://dashboard.jaw.id 获取
• 兼容 EIP-1193： 可直接替代 MetaMask 或任何钱包
• 智能账户： 使用通行密钥签名者的 ERC-4337、免 Gas 交易、批量操作、权限
• EIP-7702： EOA 可以在保留原地址的同时升级为智能账户，方式为 Account.fromLocalAccount(config, localAccount, { eip7702: true })
• EntryPoint： 仅限 v0.8（用于支付主导方）

规则索引

1. 设置与配置

• <rules/installation.md> - 软件包安装、对等依赖项、选择 wagmi 或 core
• <rules/configuration.md> - 所有配置选项：apiKey、appName、ens、mode、paymasters、preference
• <rules/auth-modes.md> - CrossPlatform 与 AppSpecific 模式及各自的适用场景

2. Wagmi 集成（React）

• <rules/wagmi-setup.md> - Wagmi 连接器设置、提供程序，以及将标准 wagmi 钩子与 JAW 搭配使用
• <rules/connect-disconnect.md> - useConnect、useDisconnect，以及使用 capabilities 进行连接
• <rules/reown-appkit.md> - 通过 WagmiAdapter 将 JAW 添加到现有 Reown AppKit 项目

3. 核心操作

• <rules/transactions.md> - 发送交易、批量调用、Gas 估算、检查状态
• <rules/signing.md> - 个人签名、类型化数据、统一的 wallet_sign、跨链签名

4. 权限与付款

• <rules/permissions.md> - 授予、查询、撤销权限（ERC-7715）
• <rules/subscription-payments.md> - 使用权限进行定期订阅付款
• <rules/stablecoin-payments.md> - 无头 USDC 付款、批量付款、ERC-20 Gas

5. 身份与认证

• <rules/ens-identity.md> - ENS 子名称签发、个人资料解析、文本记录
• <rules/siwe.md> - 以太坊登录（SIWE）实现
• <rules/gas-sponsoring.md> - 支付主导方设置、赞助政策、多链配置

6. EIP-7702

• <rules/eip7702-upgrade.md> - 将 EOA 升级为智能账户、提供商集成、授权签名

7. 高级主题

• <rules/account-api.md> - 面向 AI Agent、服务端和嵌入式钱包的无头 Account 类
• <rules/react-native.md> - React Native（Expo bare）- 通行密钥适配器、原生依赖项、AASA/assetlinks、存储
• <rules/custom-ui-handler.md> - 为 AppSpecific 模式构建自定义 UIHandler
• <rules/provider-api.md> - 直接提供程序 RPC 方法参考与模式

8. 参考

• <rules/error-handling.md> - EIP-1193 错误代码、常见错误和调试
• <rules/typescript-types.md> - 关键 TypeScript 接口和类型模式

使用方法

阅读各规则文件，了解详细指南。每个文件都包含： 正确用法示例、应避免的常见错误和关键要求。