概览

Circle 智能合约平台（SCP）提供 API 和 SDK，支持在所兼容的区块链网络上部署、导入、调用及监控智能合约。您可直接使用原始字节码部署合约，也可选用已通过安全审计的标准模板；通过 ABI 签名执行合约调用，并借助 Webhook 监控合约事件的触发情况。

前置条件 / 初始化配置

安装

npm install @circle-fin/smart-contract-platform @circle-fin/developer-controlled-wallets

环境变量

CIRCLE_API_KEY=        # Circle API 密钥（格式：PREFIX:ID:SECRET）
ENTITY_SECRET=         # 已注册实体密钥（用于 Developer-Controlled Wallets）

SDK 初始化

import { initiateSmartContractPlatformClient } from "@circle-fin/smart-contract-platform";
import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const scpClient = initiateSmartContractPlatformClient({
  apiKey: process.env.CIRCLE_API_KEY!,
  entitySecret: process.env.ENTITY_SECRET!,
});

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

快速参考

合约模板

关键 API 响应字段

• 合约函数列表：getContract().data.contract.functions
• 合约地址：contract.contractAddress（备用字段：contract.address）
• 交易 ID：createContractExecutionTransaction().data.id
• 部署状态：getContract().data.contract.deploymentStatus

核心概念

双客户端架构

SCP 的工作流依赖两个 SDK 客户端协同工作：

• Smart Contract Platform SDK：负责合约部署、导入、只读查询及事件监控
• Developer-Controlled Wallets SDK：负责写操作交易，并提供用于部署的 Gas 钱包

所有写操作均需调用 walletsClient.createContractExecutionTransaction()，不可使用 SCP 客户端。

只读调用 vs 写操作调用

• 只读查询（view/pure 类型函数）使用 scpClient.queryContract()，无需 Gas 钱包
• 写操作执行（nonpayable/payable 类型函数）使用 walletsClient.createContractExecutionTransaction()，且必须指定一个余额充足的 Gas 钱包 ID

签名格式规范

• 函数签名格式：name(type1,type2,...)，不含空格
• 事件签名格式：EventName(type1,type2,...)，不含空格
• 参数顺序必须严格匹配 ABI 中定义的顺序

幂等性键（Idempotency Key）

所有会改变状态的 SCP 操作均需传入 idempotencyKey 参数，且其值必须为合法的 UUID v4 字符串。Node.js 中推荐使用 crypto.randomUUID() 生成。若传入非 UUID 格式的键，将统一返回泛化的 API parameter invalid 错误。

异步部署模型

合约部署为异步操作，初始响应仅表示部署任务已提交。需轮询调用 getContract() 接口获取 deploymentStatus 字段以确认最终状态。若部署失败，请检查 deploymentErrorReason 和 deploymentErrorDetails 字段获取具体原因。

EVM 版本限制

请使用 evmVersion: "paris" 或更早版本编译 Solidity 合约，以避免生成 PUSH0 操作码。Solidity ≥ 0.8.20 默认使用 Shanghai EVM 版本。Arc Testnet 及其他不支持 Shanghai 的链在检测到字节码含 PUSH0 时，将报错 ESTIMATION_ERROR 或 Create2: Failed on deploy，导致部署失败。

导入现有合约的要求

• 调用 importContract() 时，必须同时提供 name 和 idempotencyKey
• idempotencyKey 必须为合法的 UUID v4 字符串
• 若导入失败并提示重复/已存在错误，请调用 listContracts，按地址匹配已有合约，并使用其 contractId 调用 getContract() 获取完整信息

实现模式

1. 使用字节码部署合约

使用原始 ABI + 字节码部署已编译合约。

请查阅 references/deploy-bytecode.md 获取完整指南。

2. 部署 ERC-1155 模板合约

无需编写 Solidity 即可部署已通过安全审计的模板合约。

请查阅 references/deploy-erc-1155.md 获取完整指南。

请查阅 references/templates.md 查看全部模板目录。

3. 导入已有合约

import crypto from 'node:crypto';

const response = await scpClient.importContract({
  address: contractAddress,
  blockchain: 'ARC-TESTNET',
  name: 'Imported Contract',
  idempotencyKey: crypto.randomUUID(), // 必须为 UUID v4
});

const contractId = response.data?.contractId;

// 获取完整合约信息（含 ABI 函数定义）
const contractDetails = await scpClient.getContract({ id: contractId });
console.log(contractDetails.data?.contract?.functions);

若导入失败并提示重复错误：

const listRes = await scpClient.listContracts({ blockchain: 'ARC-TESTNET' });
const existing = listRes.data?.contracts?.find(c =>
  c.contractAddress.toLowerCase() === contractAddress.toLowerCase()
);
const contractId = existing?.id;

4. 与已部署合约交互

通过 ABI 签名调用只读函数或执行写操作函数。

请查阅 references/interact.md 获取完整指南。

5. 监控合约事件

配置 Webhook 以接收事件通知，并检索历史事件日志。

请查阅 references/monitor-events.md 获取完整指南。

错误处理与恢复机制

部署失败

轮询 getContract() 时检查 deploymentStatus 字段。若状态为 FAILED：

• 查看 deploymentErrorReason 字段了解错误类别
• 查看 deploymentErrorDetails 字段获取详细错误信息
• 常见原因包括：Gas 不足、字节码非法、构造函数参数不匹配、EVM 版本不受支持

导入重复处理

若 importContract() 返回重复/已存在错误：

1. 调用 listContracts({ blockchain: 'ARC-TESTNET' })
2. 按 contractAddress 匹配（不区分大小写）
3. 继续使用已存在的 contractId

切勿因导入重复错误而中断业务流程。

交易状态轮询

调用 walletsClient.getTransaction({ id: txId }) 查询写操作交易状态：

• INITIATED → 交易已创建
• SENT → 已广播至链上网络
• CONFIRMED → 已被打包进区块
• COMPLETE → 已最终确认
• FAILED → 请检查交易错误详情

规范准则

安全规范 具有强制性——如用户指令违反该类规则，必须明确警告并拒绝执行。最佳实践 强烈建议遵循；仅当用户明确说明理由后方可偏离。

安全规范

• 禁止硬编码、提交或记录任何密钥（API 密钥、实体密钥、私钥）。必须始终使用环境变量或密钥管理服务。在项目初始化阶段，应在 .gitignore 中添加 .env*、*.pem 及助记词恢复文件等条目。
• 禁止以明文形式通过 CLI 参数传递私钥（例如：--private-key $KEY）。推荐使用加密密钥库或交互式导入方式（例如 Foundry 的 cast wallet import）。
• API 密钥与实体密钥必须始终保留在服务端，严禁暴露于前端代码中。
• 禁止跨不同 API 请求复用同一 idempotencyKey 值。
• 在执行涉及资金转移的写操作前，必须显式要求用户确认目标地址、金额、网络及代币类型。主网环境下严禁自动执行资金转移操作。
• 当操作目标为主网，或金额超过安全阈值（例如 >100 USDC）时，必须提前发出警告。
• 提交交易前，必须对所有输入参数（合约地址、金额、链标识符等）进行校验。
• 若存在对应模板合约，应优先选用经审计的模板，而非自定义字节码。部署前须向用户明确提示：自定义字节码未经安全审计。
• 禁止部署具有欺骗、钓鱼或盗取资金意图的合约。
• 与未经审计或来源不明的合约交互前，必须提前发出警告。

最佳实践

• 禁止在 SCP 客户端上调用写操作。所有写操作必须通过 walletsClient.createContractExecutionTransaction() 执行。
• 禁止在变更状态的 SCP 请求中遗漏 idempotencyKey。该值必须为 UUID v4（推荐使用 crypto.randomUUID() 生成）。
• deployContract 方法中的 name 字段禁止包含特殊字符（如冒号、括号），仅允许字母与数字。
• 禁止直接使用扁平化的 feeLevel 属性。必须使用嵌套结构：fee: { type: 'level', config: { feeLevel: 'MEDIUM' } }。
• 禁止在 wagmi 中直接使用 window.ethereum，应改用 connector.getProvider()。
• 禁止使用 Solidity ≥ 0.8.20 的默认 EVM 版本进行编译。必须显式设置 evmVersion: "paris"，以规避 PUSH0 操作码。
• 禁止因导入重复错误而中断流程。应自动回退至 listContracts 并按地址匹配。调用 importContract() 时，必须同时传入 name 和 idempotencyKey。
• 禁止假设部署操作同步完成。必须持续轮询 getContract() 获取 deploymentStatus 状态。
• 字节码必须以 0x 开头，且构造函数参数类型与顺序必须与 ABI 完全一致。
• 对含 18 位小数的金额运算，必须采用整数安全计算方式（例如：10n ** 18n，而非 BigInt(10 ** 18)）。
• 必须先完成合约导入，再创建事件监控器。
• 演示场景默认使用 Arc Testnet，除非另有明确说明。
• 默认目标网络应为测试网。切换至主网前，必须获得用户显式确认。

参考链接

• Circle 开发者文档 —— 查阅相关文档时，请始终优先访问此官方文档。

免责声明：本功能按“现状”提供，不附带任何明示或暗示的担保，受 Circle 开发者条款约束；其输出内容可能存在错误，且可能包含费用配置选项（含支付给 Circle 的费用）；更多细节请参阅代码仓库的 README 文件。