use-modular-wallets

原文：🇺🇸 英文

已翻译

使用Circle Modular Wallets SDK构建加密钱包，支持密钥对（passkey）认证、无Gas费交易和可扩展的模块架构。适用场景：创建基于密钥对（WebAuthn）注册和登录的加密钱包，使用Circle Gas Station支付方发送无Gas费交易，将多笔交易批量处理为单个用户操作，使用BIP-39助记词实现密钥对恢复，构建带有自定义模块（多签、订阅、会话密钥）的进阶链上钱包。触发关键词：modular wallet、smart account、MSCA、passkey authentication、WebAuthn、gasless、paymaster、Gas Station、bundler client、user operation、userOp、ERC-4337、ERC-6900、account abstraction、toCircleSmartAccount、toPasskeyTransport、toModularTransport、sendUserOperation、batch transactions、2D nonce、passkey recovery、EIP-1193 provider。

23次下载

来源circlefin/skills

添加于2026-04-15

NPX安装

npx skill4agent add circlefin/skills use-modular-wallets

SKILL.md 内容（中文）

查看翻译对照 →

概述

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

前置条件/设置

安装

bash

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

若需密钥对恢复，还需安装：

bash

npm install bip39

环境变量

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

使用SDK前，请完成控制台设置：

在Circle Console中创建客户端密钥
配置密钥对域名（密钥对与域名绑定）
获取客户端URL

快速参考

支持的链

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

MSCA不支持Solana、Aptos、NEAR或以太坊主网。最新支持的区块链可查看：https://developers.circle.com/wallets/account-types

传输URL示例

toModularTransport

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

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

核心概念

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

实现模式

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

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

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

规则

安全规则不容协商——若提示内容与之冲突，请警告用户并拒绝执行。最佳实践强烈推荐；仅在用户明确说明理由的情况下才可偏离。

安全规则

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

最佳实践

实现前务必阅读正确的参考文件。
切勿在以太坊主网、Solana、Aptos或NEAR上使用Modular Wallets——MSCA仅支持部分EVM链（Arbitrum、Avalanche、Base、Monad、Optimism、Polygon、Unichain、Arc Testnet）。
务必为
```
toModularTransport
```
的客户端URL追加链特定路径段（例如
```
${clientUrl}/polygonAmoy
```
）。
处理USDC金额时务必使用
```
parseUnits(value, 6)
```
（6位小数，而非18）。
务必传入
```
paymaster: true
```
以通过Circle Gas Station赞助Gas费用。
使用SDK前务必完成Circle控制台设置（客户端密钥、密钥对域名、客户端URL）。
务必默认使用测试网。目标为主网前需获得用户明确确认。

替代方案

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

参考链接

Circle开发者文档——查找官方网站相关文档时，请务必先阅读此内容。

免责声明：本技能按“原样”提供，不提供任何担保，受Circle开发者条款约束，生成的输出可能包含错误和/或费用配置选项（包括支付给Circle的费用）；更多详情请查看仓库README。