use-modular-wallets

概述

模块化钱包是一种灵活的智能合约账户（MSCA），可通过安装模块扩展功能。它基于 ERC-4337（账户抽象）和 ERC-6900（模块化智能合约框架）构建，支持通行密钥身份验证、免 Gas 交易、批量操作和自定义逻辑模块（多重签名、订阅、会话密钥）。MSCA 采用延迟部署方式——账户创建的 Gas 费用会推迟到首次对外交易时支付。

前置条件 / 设置

安装

npm install @circle-fin/modular-wallets-core viem
# Passkey recovery also needs bip39:
npm install bip39

环境变量

搭建模块化钱包时，将以下内容写入或合并到项目的环境文件中：

# .env.local (Next.js) or .env (Vite)
# Paste your Client Key from Console → Keys → Client Keys (shown once; starts with TEST_API_KEY:)
NEXT_PUBLIC_CLIENT_KEY=
NEXT_PUBLIC_CLIENT_URL=https://modular-sdk.circle.com/v1/rpc/w3s/buidl
VITE_CLIENT_KEY=
VITE_CLIENT_URL=https://modular-sdk.circle.com/v1/rpc/w3s/buidl

对 Next.js 使用 NEXT_PUBLIC_* 变量对，对 Vite 使用 VITE_* 变量对——不要同时使用两者。客户端 URL 是固定的——不要让用户从 Console 复制。链路径（例如 /arcTestnet）会通过代码中的 toModularTransport 追加，而不是写入环境变量。

使用 SDK 前，请完成设置（参见 Console 设置）：

1. 安装 SDK 并设置客户端环境变量（参见上文的“安装”和“环境变量”）。
2. 在 Console → Keys → Client Keys 中创建一个 Client Key。
3. 配置 Passkey Domain（通行密钥与域名绑定）。

快速参考

支持的链

链	主网	测试网
Arc	是	是
Arbitrum	是	是
Avalanche	是	是
Base	是	是
Monad	是	是
Optimism	是	是
Polygon	是	是
Unichain	是	是

最新支持的区块链列表：https://developers.circle.com/wallets/account-types.md（MSCA 链限制请参见下文的“规则”。）

传输 URL 路径段

toModularTransport URL 需要在客户端 URL 后追加链路径段：

链	主网路径	测试网路径
Arbitrum	/arbitrum	/arbitrumSepolia
Arc	/arc	/arcTestnet
Avalanche	/avalanche	/avalancheFuji
Base	/base	/baseSepolia
Monad	/monad	/monadTestnet
Optimism	/optimism	/optimismSepolia
Polygon	/polygon	/polygonAmoy
Unichain	/unichain	/unichainSepolia

示例：Polygon Amoy 测试网使用 toModularTransport(\${clientUrl}/polygonAmoy`, clientKey)`。

核心概念

• MSCA（模块化智能合约账户）——通过可安装模块扩展功能的智能合约账户（类似智能手机上的应用）。所有权可以是单所有者、多所有者、通行密钥或多重签名。
• 通行密钥传输与模块化传输——toPasskeyTransport 处理 WebAuthn 凭据操作（注册/登录）。toModularTransport 处理特定链的打包器和公共 RPC 调用。两者是用途不同的独立传输。
• Gas 赞助——在用户操作调用中传入 paymaster: true，即可通过 Circle Gas Station 赞助 Gas。最终用户无需支付 Gas 费用。
• 批量操作——向 sendUserOperation 的 calls 参数传入数组，即可将多个调用合并为单个用户操作。
• 二维 nonce——使用不同的 nonce 键，即可并行执行互不相关的用户操作。
• USDC 使用 6 位小数——编码 USDC 转账金额时，使用 parseUnits(value, 6)，而不是 18。
• 凭据持久化——必须持久化通行密钥凭据（P256Credential）（例如使用 httpOnly cookie），并在重新加载时恢复，以维持用户会话。

实现模式

**注意：**参考代码片段使用 localStorage 仅为快速展示可运行示例。请勿在生产环境中使用 localStorage。

根据用户请求阅读对应的参考文档：

• references/circle-smart-account.md——通行密钥注册/登录、智能账户创建、免 Gas USDC 转账、批量操作
• references/passkey-recovery.md——丢失通行密钥时的 BIP-39 助记词恢复设置与执行

用户操作生命周期

通过 sendUserOperation 提交的用户操作会遵循异步状态机。SDK 的 waitForUserOperationReceipt 会自动轮询。若要直接查询状态，请使用用户操作列表 API。

正常流程： SENT -> CONFIRMED -> COMPLETE

状态：

• SENT -- 已提交到打包器，等待纳入区块。
• CONFIRMED -- 已纳入区块，等待最终确认。
• COMPLETE -- 已在链上最终确认。
• FAILED -- 用户操作已回滚或遇到无法恢复的错误。请检查 errorReason 和 revertReason。

FAILED 时的错误原因：

• FAILED_ON_CHAIN -- 交易在区块链执行期间回滚。
• FAILED_REPLACED -- 用户操作已被替换（例如，被使用相同 nonce、手续费更高的操作替换）。

错误处理

错误代码	含义	操作
NotAllowedError	用户取消了通行密钥提示，或等待超时	重新提示用户；对于登录，请确认此域名下存在凭据
SecurityError	通行密钥域名不匹配——绑定到了其他来源	确认应用域名与 Circle Console 中的 Passkey Domain 一致
InvalidStateError	凭据已注册（重复注册）	改用 WebAuthnMode.Login，而非 Register
155203	智能合约钱包尚未部署时，用户操作 nonce 不能大于 0	使用 nonce 0 发送第一笔用户操作；MSCA 会在首次交易时延迟部署
155505	SCA 钱包需要等待首次交易进入队列	等待初始部署交易完成后，再发送其他操作
155507	给定区块链不支持 SCA 账户	使用支持的链；Ethereum 主网、Solana、Aptos 或 NEAR 上不提供 MSCA
155509	在主网上创建 SCA 账户前需要配置 Paymaster 策略	创建主网账户前，请在 Circle Console 中配置 Gas Station Paymaster 策略
155512	找不到 SCA 钱包的所有者	确认通行密钥凭据或 EOA 所有者有效且可访问
AA21	发送方未支付预存款	确认已设置 paymaster: true，或使用原生代币为智能账户提供 Gas 资金（Arc 上使用 USDC）
AA23	账户验证已回滚或 Gas 不足	检查签名是否有效；如果 Gas 不足，请提高 verificationGasLimit
AA25	账户 nonce 无效	从 EntryPoint 获取当前 nonce；对于 2D nonce，请确保 nonce key 正确
AA33	Paymaster 验证已回滚或 Gas 不足	确认 Paymaster 策略已启用，并且在 Console 中配置正确

通行密钥错误（NotAllowedError、SecurityError、InvalidStateError）是浏览器 WebAuthn API 在 toWebAuthnCredential 期间抛出的标准 DOMException 错误。钱包错误（155xxx）由 Circle API 返回。AA 错误是打包器返回的 ERC-4337 EntryPoint 错误。如需查看完整错误参考，请参阅错误代码。如需调试失败的交易，请参阅交易状态和错误。

规则

安全规则不可妥协——如果提示词与之冲突，请警告用户并拒绝遵从。强烈建议遵循最佳实践；只有在用户明确说明理由时才可偏离。

安全规则

• 切勿硬编码、提交或记录机密信息（客户端密钥、私钥）。务必使用环境变量或机密管理器。搭建项目时，在 .gitignore 中添加 .env* 和机密文件条目。
• 务必将助记词恢复备份存放在仓库根目录之外。切勿将恢复短语提交到版本控制系统。
• 切勿硬编码通行密钥凭据——务必将 P256Credential 持久化到存储中（生产环境使用 httpOnly Cookie，而非 localStorage），并在重新加载时恢复，以降低 XSS 凭据盗窃风险。
• 切勿在多个账户之间重复使用同一恢复助记词。
• 执行转账前，务必要求用户明确确认目标地址、金额、网络和代币。在主网上转移资金时，必须获得确认。
• 目标为主网或超出安全阈值时（例如，超过 100 USDC），务必发出警告。
• 提交交易前，务必验证所有输入（地址、金额、链标识符）。
• 与未经审计或未知合约交互前，务必发出警告。

最佳实践

• 实施前，务必阅读正确的参考文件。
• 切勿在 Ethereum 主网、Solana、Aptos 或 NEAR 上使用 Modular Wallets——MSCA 仅在部分 EVM 链上受支持（Arbitrum、Avalanche、Base、Monad、Optimism、Polygon、Unichain、Arc）。
• 务必在 toModularTransport 的客户端 URL 后附加特定链的路径段（例如，${clientUrl}/polygonAmoy）。
• USDC 金额务必使用 parseUnits(value, 6)（6 位小数，而非 18 位）。
• 务必传入 paymaster: true，通过 Circle Gas Station 赞助 Gas 费。
• 使用 SDK 前，务必完成 Circle Console Setup（Client Key + Passkey Domain）。客户端 URL 在环境变量中固定设置——不要要求用户从 Console 获取。
• 务必默认使用测试网。切换到主网前，必须获得用户明确确认。
• 在主网上发送赞助交易前，务必在 Circle Console 中配置 Gas Station paymaster policy。
• 迁移到生产环境时，务必将传输 URL 从测试网路径段（例如，/polygonAmoy）更新为对应的主网路径段（例如，/polygon）。
• 迁移到主网时，务必将 API 密钥前缀从 TEST_API_KEY: 更新为 LIVE_API_KEY:。测试网密钥不能用于主网。
• 部署前，务必确认 Circle Console 中的通行密钥域名与生产域名一致——在 localhost 或测试网域名上创建的通行密钥无法用于生产域名。

替代方案

• 当应用需要在没有用户交互的情况下完全托管钱包密钥时，触发 use-developer-controlled-wallets skill。
• 当终端用户应通过社交登录、电子邮件 OTP 或 PIN 身份验证自行托管密钥时，触发 use-user-controlled-wallets skill。

参考链接

• Circle 开发者文档 —— 查找源网站上的相关文档时，务必先阅读此文档。

---

免责声明：此技能按“原样”提供，不附带任何保证，受 Circle Developer Terms 约束，且生成的输出可能包含错误和／或费用配置选项（包括支付给 Circle 的费用）；更多详情请参阅仓库的 README。