use-smart-contract-platform

概览

Circle Smart Contract Platform（SCP）提供 API 和 SDK，用于在受支持的网络上部署、导入、交互和监控智能合约。可通过原始字节码部署合约，使用经过审计的模板实现标准模式，执行基于 ABI 的合约调用，并通过 webhook 监控触发的事件。

前提条件 / 设置

安装

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

环境变量

CIRCLE_API_KEY=        # Circle API key (format: PREFIX:ID:SECRET)
ENTITY_SECRET=         # Registered entity secret for 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!,
});

快速参考

支持的区块链

链	主网	测试网
Arbitrum	ARB	ARB-SEPOLIA
Arc	ARC	ARC-TESTNET
Avalanche	AVAX	AVAX-FUJI
Base	BASE	BASE-SEPOLIA
Ethereum	ETH	ETH-SEPOLIA
Monad	MONAD	MONAD-TESTNET
OP Mainnet	OP	OP-SEPOLIA
Polygon PoS	MATIC	MATIC-AMOY
Unichain	UNI	UNI-SEPOLIA

references/ 中的示例使用 Arc Testnet（blockchain: 'ARC-TESTNET'）；如需使用 Arc 主网，请传入 blockchain: 'ARC'。Arc USDC 地址 0x3600000000000000000000000000000000000000 在两个网络上相同。

合约模板

模板	标准	模板 ID	用例
Token	ERC-20	a1b74add-23e0-4712-88d1-6b3009e85a86	同质化代币、忠诚度积分
NFT	ERC-721	76b83278-50e2-4006-8b63-5b1a2a814533	数字收藏品、游戏资产
Multi-Token	ERC-1155	aea21da6-0aa2-4971-9a1a-5098842b1248	混合的同质化 / 非同质化代币
Airdrop	N/A	13e322f2-18dc-4f57-8eed-4bddfc50f85e	批量分发代币

主要 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 负责写入交易，并提供部署钱包

写入操作使用 walletsClient.createContractExecutionTransaction()，而非 SCP 客户端。

合约调用：读取与写入

• 读取查询（view / pure 函数）使用 scpClient.queryContract()，不需要 Gas 钱包
• 写入执行（nonpayable / payable 函数）使用 walletsClient.createContractExecutionTransaction()，需要有 Gas 资金的钱包 ID

签名格式

• 函数签名：name(type1,type2,...)，不含空格
• 事件签名：EventName(type1,type2,...)，不含空格
• 参数顺序必须与 ABI 定义完全一致

幂等键

所有会修改状态的 SCP 操作都需要将 idempotencyKey 设置为有效的 UUID v4 字符串。在 Node.js 中使用 crypto.randomUUID()。非 UUID 键会导致通用的 API parameter invalid 错误。

异步部署模型

合约部署是异步的。响应仅表示已启动部署。请轮询 getContract() 以获取 deploymentStatus。

EVM 版本限制

编译 Solidity 时，请使用 evmVersion: "paris" 或更早版本，以避免 PUSH0 操作码。Solidity >= 0.8.20 默认使用 Shanghai 版本。如果字节码包含 PUSH0，Arc 和其他非 Shanghai 链会因 ESTIMATION_ERROR / Create2: Failed on deploy 而导致部署失败。

交易生命周期

写入操作（合约部署、执行）遵循与开发者控制的钱包相同的异步状态机。使用 walletsClient.getTransaction({ id: txId }) 轮询，直到达到终止状态。

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

终止状态：

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

中间状态：

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

合约部署状态通过 scpClient.getContract() 中的 deploymentStatus 单独跟踪。

如需调试失败的交易，请参阅交易状态和错误。

错误处理

错误代码	含义	操作
175001	未找到合约	验证合约 ID 是否存在；如果是导入的合约，请检查其是否已归档
175003	构造函数参数不匹配	检查参数数量和类型是否与合约 ABI 定义完全一致
175004	合约重复	调用 listContracts({ blockchain })，按 contractAddress（不区分大小写）匹配，并使用现有的 contractId
175009	部署仍在等待中	继续轮询 getContract() 获取 deploymentStatus；部署是异步的，可能需要多个区块
175201	未找到模板	在快速参考的合约模板表格中验证模板 ID
175301	未找到事件订阅	验证事件监控 ID；确保先导入合约，再创建监控
175302	事件订阅重复	查询现有订阅并重复使用；不要因此中断流程
175303	事件签名无效	使用精确格式 EventName(type1,type2,...)，不带空格；参数顺序必须与 ABI 一致
175402	区块链不受支持或已弃用	查看支持的区块链表格；SCP 不支持 Solana、Aptos 或 NEAR
175404	在主网上使用了 TEST_API 密钥，或在测试网上使用了 LIVE_API 密钥	确保 API 密钥前缀（TEST_API_KEY: 或 LIVE_API_KEY:）与目标网络匹配
177015	合约部署缺少字节码	提供带 0x 前缀的编译后字节码；使用 evmVersion: "paris" 编译以避免 PUSH0

部署失败时，请检查 getContract() 返回的 deploymentErrorReason 和 deploymentErrorDetails。

实现模式

1. 从字节码部署合约

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

READ references/deploy-bytecode.md 查看完整指南。

2. 从模板部署

无需编写 Solidity，即可部署经过审计的模板合约。

READ references/deploy-template.md 查看模板目录和部署指南。

3. 导入现有合约

将已部署的合约导入 SCP，以便进行交互和事件监控。

READ references/import-contract.md 查看完整指南。

4. 与已部署的合约交互

通过 ABI 签名查询读取函数并执行写入函数。

READ references/interact.md 查看完整指南。

5. 监控合约事件

为已触发的事件设置 Webhook 通知，并检索历史日志。

READ references/monitor-events.md 查看完整指南。

规则

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

安全规则

• 绝不硬编码、提交或记录机密信息（API 密钥、实体机密、私钥）。始终使用环境变量或机密管理器。搭建项目脚手架时，为 .env*、*.pem 和恢复文件添加 .gitignore 条目。
• 绝不通过纯文本 CLI 标志传递私钥（例如，--private-key $KEY）。优先使用加密密钥库或交互式导入（例如，Foundry 的 cast wallet import）。
• 始终在服务器端保管 API 密钥和实体机密。绝不在前端代码中暴露。
• 绝不在不同的 API 请求之间重复使用 idempotencyKey 值。
• 在执行会转移资金的写入交易前，始终要求用户明确确认目的地、金额、网络和代币。主网上的资金转移必须获得确认。
• 针对主网或超出安全阈值（例如，超过 100 USDC）时，始终发出警告。
• 提交交易前，始终验证所有输入（合约地址、金额、链标识符）。
• 存在模板合约时，始终优先使用经过审计的模板合约，而不是自定义字节码。部署前，警告用户自定义字节码未经安全审计。
• 绝不部署旨在欺骗、钓鱼或转移资金的合约。
• 与未经审计或未知的合约交互前，始终发出警告。

最佳实践

• 绝不在 SCP 客户端上调用写入操作。写入操作始终使用 walletsClient.createContractExecutionTransaction()。
• 绝不在 deployContract 的 name 字段中使用特殊字符（冒号、括号）——仅使用字母数字字符。
• 绝不使用扁平的 feeLevel 属性。始终使用嵌套的 fee: { type: 'level', config: { feeLevel: 'MEDIUM' } }。
• 绝不将 window.ethereum 直接与 wagmi 配合使用——请使用 connector.getProvider()。
• 绝不使用默认 EVM 版本编译 Solidity >= 0.8.20。始终设置 evmVersion: "paris"，以避免 PUSH0 操作码。
• 调用 importContract() 时，始终同时包含 name 和 idempotencyKey。
• 绝不假定部署会同步完成。始终轮询 getContract()，以检查 deploymentStatus。
• 始终为字节码添加 0x 前缀，并确保构造函数参数类型和顺序完全匹配。
• 对 18 位小数的金额始终使用整数安全的数学运算（10n ** 18n，而非 BigInt(10 ** 18)）。
• 创建事件监视器前，始终先导入合约。
• 除非另有说明，演示始终默认使用 Arc Testnet。
• 始终默认使用测试网。切换至主网前，必须获得用户明确确认。

参考链接

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

---

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