use-developer-controlled-wallets

概述

开发者控制的钱包可让您的应用代表终端用户创建和管理钱包，并通过加密的实体密钥全面保护私钥。Circle 负责安全、交易监控和区块链基础设施，而您则通过 Wallets SDK 保留程序化控制权。

前置条件 / 设置

安装

npm install @circle-fin/developer-controlled-wallets

环境变量

CIRCLE_API_KEY=      # Circle API key (format: PREFIX:ID:SECRET)
ENTITY_SECRET=       # 32-byte hex entity secret

实体密钥注册

使用 SDK 前，开发者必须注册实体密钥。请引导他们访问 https://developers.circle.com/wallets/dev-controlled/register-entity-secret，或提供代码步骤。

阅读 references/register-secret.md，了解生成和注册代码片段。

重要：请勿代替开发者注册密钥——他们必须自行生成、注册并安全存储密钥和恢复文件。

SDK 初始化

import { initiateDeveloperControlledWalletsClient } from '@circle-fin/developer-controlled-wallets';

const circleDeveloperSdk = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY,
  entitySecret: process.env.ENTITY_SECRET,
});

SDK 会为每个 API 请求自动生成新的实体密钥密文。

核心概念

• 钱包集：由单个实体密钥管理的一组钱包。集合中的钱包可分布在不同区块链上，但在 EVM 链上共享同一地址。
• 实体密钥：用于保护开发者控制的钱包的 32 字节私钥。生成、加密并注册一次即可。Circle 绝不会以明文形式存储该密钥。
• 实体密钥密文：使用 Circle 公钥加密的实体密钥。每个 API 请求都必须使用唯一密文，以防止重放攻击。SDK 会自动处理此事。
• 幂等键：所有更改请求都需要 UUID v4 格式的 idempotencyKey，以确保恰好执行一次。
• 账户类型：
  • EOA（外部拥有账户）——默认选择。无创建费用，出站 TPS 更高，链支持范围最广（所有 EVM 链，以及 Solana、Aptos、NEAR）。需要原生代币支付 Gas（在 Arc 上，Gas 资产为 USDC，而非单独的原生代币）。
  • SCA（智能合约账户）——符合 ERC-4337 标准。支持通过 Circle Gas Station 赞助 Gas、批量操作和灵活的密钥管理。仅支持 EVM（不适用于 Solana、Aptos、NEAR）。由于 Gas 成本高昂，应避免在 Ethereum 主网上使用；建议优先选择 L2。
• 支持的区块链：EVM 链（Ethereum、Polygon、Avalanche、Arbitrum、Base、Monad、Optimism、Unichain）、Solana、Aptos、NEAR 和 Arc。最新信息请参阅 https://developers.circle.com/wallets/account-types。

交易生命周期

所有链上操作（转账、合约执行、钱包升级）都遵循同一异步状态机。使用 circleDeveloperSdk.getTransaction({ id }) 轮询，直到达到终态。

正常流程： INITIATED -> CLEARED -> QUEUED -> SENT -> CONFIRMED -> COMPLETE

终态：

• COMPLETE -- 交易成功，并已在链上最终确认。
• FAILED -- 交易已回滚或遇到无法恢复的错误。
• DENIED -- 交易被风险筛查拒绝。
• CANCELLED -- 交易在提交到链上之前已取消。

中间状态：

• INITIATED -- 请求已接受，但尚未验证或检查。
• WAITING -- 正在队列中等待验证和合规检查。
• QUEUED -- 已排队，等待提交到区块链。
• CLEARED -- 已通过合规检查。
• SENT -- 已提交到区块链，等待确认。
• STUCK -- 已提交交易的费用参数低于区块链当前要求的费用，开发者需要取消或加速此交易。
• CONFIRMED -- 已包含在区块中，等待最终确认。

建议：订阅 Webhook 通知，而不是轮询。交易达到终态时，Circle 会发送 webhook 事件，从而无需反复调用 getTransaction。在 Circle Developer Console 的 Webhooks 下注册一个公开的 HTTPS 端点。每个 webhook 都包含 X-Circle-Signature 和 X-Circle-Key-Id 标头，用于验证签名。

getTransaction 轮询仍可作为备用方案，或用于简单脚本。

如需调试失败或被拒绝的交易，请参阅交易错误。

实现模式

1. 创建钱包

阅读 references/create-dev-wallet.md，查看完整指南。

2. 接收代币

阅读 references/receive-transfer.md，查看完整指南。

3. 转移代币 / 查看钱包余额

阅读 references/check-balance-and-transfer-tokens.md，查看完整指南。内容包括费用估算、交易加速和取消。

4. 签署消息

阅读 references/sign-with-wallet.md，查看完整指南。内容涵盖 EIP-191 消息签名、EIP-712 类型化数据、原始交易签名和 NEAR 委托操作。

5. 执行智能合约

阅读 references/contract-execution.md，查看完整指南。内容涵盖基于 ABI 和原始 calldata 的执行、可支付函数和 gas 估算。

6. 钱包管理（升级与派生）

阅读 references/wallet-management.md，查看完整指南。内容涵盖升级 SCA 钱包版本，以及将钱包派生到新的区块链。

规则

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

安全规则

• 绝不要硬编码、提交或记录机密信息（API 密钥、实体机密、私钥）。始终使用环境变量或机密管理器。搭建项目脚手架时，为 .env*、*.pem 和 *-recovery-file.json 添加 .gitignore 条目。
• 始终将恢复文件存放在仓库根目录之外。绝不要将其提交到版本控制中。
• 绝不要在 API 请求之间重复使用实体机密密文——每个密文都必须唯一，以防重放攻击。
• 在测试网（TEST）上注册实体机密时必须谨慎，确保将实体机密和恢复文件存放在安全的位置。
• 绝不要在主网（LIVE）上代替用户注册实体机密——用户必须自行生成、注册并存储。
• 执行转账前，始终要求用户明确确认目标地址、金额、网络和代币。主网上的资金转移必须获得确认。
• 当目标为主网或金额超过安全阈值（例如，>100 USDC）时，始终发出警告。
• 提交交易前，始终验证所有输入（地址、金额、链标识符）。
• 与未经审计或未知的合约交互前，始终发出警告。
• 签署消息或类型化数据前，始终要求用户明确确认——已签名的载荷可能会授权代币批准、交易或其他不可逆操作。

最佳实践

• 实施前始终阅读正确的参考文件。
• 绝不要使用 circleDeveloperSdk.getWallet 或 circleDeveloperSdk.getWallets 查询余额——这些端点永远不会返回余额数据。请参阅参考文件了解正确方法。
• 按照 API 规范，所有会修改数据的 API 请求都应包含 UUID v4 格式的 idempotencyKey。
• 执行出站交易前，始终确保 EOA 钱包持有原生代币（ETH、MATIC、SOL 等）以支付 Gas。Arc 上的 Gas 资产就是 USDC（而非单独的原生代币），因此为钱包注入 USDC 即可支付 Gas。
• 始终轮询交易状态，直到其进入终止状态（COMPLETE、FAILED、DENIED、CANCELLED），再视为完成。
• 始终优先在 L2 上使用 SCA 钱包，而非以太坊主网，以避免高额 Gas 费用。
• 始终默认使用测试网。指定主网前，必须获得用户明确确认。
• 执行合约或大额转账前，始终估算费用，让用户提前了解 Gas 成本。
• 执行前始终验证 ABI 函数签名和参数与目标合约相符。签名不正确会导致交易回退并浪费 Gas。
• 为了便于阅读和审计，始终优先使用 abiFunctionSignature + abiParameters，而非原始 callData，除非 calldata 由可信库（ethers、viem）生成。

替代方案

• 当最终用户应通过社交登录、电子邮件 OTP 或 PIN 身份验证自行保管密钥时，触发 use-user-controlled-wallets 技能。
• 对于采用可扩展模块架构（多签、会话密钥等）的通行密钥智能账户，触发 use-modular-wallets 技能。

参考链接

• Circle Developer 文档 ——查找源网站上的相关文档时，始终先阅读此文档。

---

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