📦 Use Modular Wallets — 构建加密钱包

概述

Modular Wallets 是灵活的智能合约账户（MSCA），可通过安装模块扩展功能。基于 ERC-4337（账户抽象）和 ERC-6900（模块化智能合约框架）构建，支持 passkey 认证、无 Gas 交易、批量操作以及自定义逻辑模块（多签、订阅、会话密钥）。MSCA 采用延迟部署策略——创建账户的 Gas 费用将推迟到第一笔出账交易时才产生。

前置条件 / 设置

安装

npm install @circle-fin/modular-wallets-core viem

如需 passkey 恢复功能，还需安装：

npm install bip39

环境变量

CLIENT_KEY= # Circle Console 中的客户端密钥，用于应用身份识别
CLIENT_URL= # Circle 客户端 URL（例如 https://modular-sdk.circle.com/v1/rpc/w3s/buidl）

使用 SDK 前，请先完成 Console Setup：

• 在 Circle Console 创建 Client Key
• 配置 Passkey Domain（passkey 与域名绑定）
• 获取 Client URL

快速参考

支持的链

链	Mainnet	Testnet
Arbitrum	是	是
Avalanche	是	是
Base	是	是
Monad	是	是
Optimism	是	是
Polygon	是	是
Unichain	是	是

MSCA 不支持 Solana、Aptos、NEAR 或 Ethereum mainnet。 最新支持列表见：https://developers.circle.com/wallets/account-types

Transport URL 示例

toModularTransport 的 URL 需要在 client URL 后附加链路径段：

链	路径段
Arc Testnet	/arcTestnet
Polygon Amoy	/polygonAmoy

核心概念

• MSCA（Modular Smart Contract Account）——可通过安装模块扩展功能的智能合约账户（如同手机装 App）。所有权可以是单所有者、多所有者、passkey 或多签。
• Passkey transport vs Modular transport——toPasskeyTransport 处理 WebAuthn 凭证操作（注册/登录）。toModularTransport 处理特定链的 bundler 和公开 RPC 调用。两者用途不同，需分开使用。
• Gas 赞助——在 user operation 调用中传入 paymaster: true 即可通过 Circle Gas Station 赞助 Gas，终端用户无需支付任何费用。
• 批量操作——将多个调用组成数组传入 sendUserOperation 的 calls 参数，即可合并为单个 user operation。
• 2D nonces——使用不同的 nonce key 可并行执行独立的 user operation。
• USDC 使用 6 位小数——编码 USDC 转账金额时，使用 parseUnits(value, 6)，而非 18。
• 凭证持久化——Passkey 凭证（P256Credential）必须持久化存储（如 localStorage），并在页面重载时恢复，以维持用户会话。

实现模式

注意： 参考代码片段仅用 localStorage 实现快速示例。生产环境请勿使用 localStorage。

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

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

规则

安全规则 不可协商——如提示冲突，必须警告用户并拒绝执行。 最佳实践 强烈建议遵循；如确需偏离，须由用户明确说明理由。

安全规则

• 严禁硬编码、提交或记录任何密钥（client key、私钥）。务必使用环境变量或密钥管理器。搭建时请将 .env* 及密钥文件加入 .gitignore。
• 助记词恢复备份必须存放在仓库根目录之外。严禁将恢复短语提交到版本控制。
• 严禁硬编码 passkey 凭证——务必将 P256Credential 持久化存储（生产环境用 httpOnly Cookie，而非 localStorage）并在重载时恢复，以防 XSS 窃取凭证。
• 严禁在多个账户间复用同一恢复助记词。
• 执行转账前，必须显式要求用户确认目标地址、金额、网络及代币。严禁在主网自动执行资金转移。
• 当目标为主网或金额超过安全阈值（如 >100 USDC）时，必须发出警告。
• 提交交易前，必须校验所有输入（地址、金额、链标识符）。
• 与未经审计或未知合约交互前，必须发出警告。

最佳实践

• 实施前务必阅读正确的参考文件。
• 严禁在 Ethereum mainnet、Solana、Aptos 或 NEAR 使用 Modular Wallets——MSCA 仅支持指定 EVM 链（Arbitrum、Avalanche、Base、Monad、Optimism、Polygon、Unichain、Arc Testnet）。
• 使用 toModularTransport 时，务必在 client URL 后追加链特定路径段（例如 ${clientUrl}/polygonAmoy）。
• 处理 USDC 金额时，务必使用 parseUnits(value, 6)（6 位小数，而非 18）。
• 调用时务必传入 paymaster: true 以通过 Circle Gas Station 赞助 Gas。
• 使用 SDK 前，务必完成 Circle Console 设置（client key、passkey domain、client URL）。
• 默认使用测试网。如要 targeting 主网，必须取得用户明确确认。

替代方案

• 当应用需要完全托管钱包密钥且无需用户交互时，触发 use-developer-controlled-wallets 技能。
• 当终端用户应通过社交登录、邮箱 OTP 或 PIN 自行托管密钥时，触发 use-user-controlled-wallets 技能。

参考链接

• Circle Developer Docs——查找官方文档时务必优先阅读此处。

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