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

主な概念

2 クライアント構成

SCP のワークフローでは、2 つの SDK クライアントを組み合わせます。

• Smart Contract Platform SDK は、コントラクトのデプロイ、インポート、読み取りクエリ、イベント監視を処理します
• Developer-Controlled Wallets SDK は、書き込みトランザクションを処理し、デプロイ用ウォレットを提供します

書き込み操作には、SCP クライアントではなく、walletsClient.createContractExecutionTransaction() を使用します。

コントラクトの読み取り呼び出しと書き込み呼び出し

• 読み取りクエリ（view／pure 関数）には scpClient.queryContract() を使用し、ガス用ウォレットは不要です
• 書き込み実行（nonpayable／payable 関数）には walletsClient.createContractExecutionTransaction() を使用し、ガス資金のあるウォレット ID が必要です

署名の形式

• 関数の署名：空白なしの name(type1,type2,...)
• イベントの署名：空白なしの EventName(type1,type2,...)
• パラメーターの順序は ABI の定義と完全に一致している必要があります

冪等性キー

SCP のすべての変更操作では、有効な UUID v4 形式の文字列を idempotencyKey として指定する必要があります。Node.js では crypto.randomUUID() を使用してください。UUID 形式でないキーを指定すると、汎用的な API parameter invalid エラーが発生します。

デプロイの非同期モデル

コントラクトのデプロイは非同期です。レスポンスが示すのは処理の開始のみです。getContract() をポーリングして deploymentStatus を確認してください。

EVM バージョンの制約

PUSH0 オペコードを避けるため、Solidity は evmVersion: "paris" 以前を指定してコンパイルしてください。Solidity 0.8.20 以降のデフォルトは Shanghai です。バイトコードに PUSH0 が含まれていると、Arc やその他の Shanghai 非対応チェーンでは、ESTIMATION_ERROR／Create2: Failed on deploy が発生してデプロイに失敗します。

トランザクションのライフサイクル

書き込み操作（コントラクトのデプロイ、実行）では、Developer-Controlled Wallets と同じ非同期ステートマシンに従います。walletsClient.getTransaction({ id: txId }) で終端状態に達するまでポーリングしてください。

正常なフロー： INITIATED -> CLEARED -> QUEUED -> SENT -> CONFIRMED -> COMPLETE

終端状態：

• COMPLETE -- トランザクションが成功し、オンチェーンで確定しています。
• FAILED -- トランザクションがリバートされたか、回復不能なエラーが発生しました。
• DENIED -- リスク審査によってトランザクションが拒否されました。
• CANCELLED -- オンチェーンへの送信前にトランザクションがキャンセルされました。

中間状態：

• INITIATED -- リクエストは受け付けられましたが、まだ検証やチェックは行われていません。
• WAITING -- 検証とコンプライアンスチェックのためにキューで待機しています。
• QUEUED -- ブロックチェーンへの送信待ちのキューに入りました。
• CLEARED -- コンプライアンスチェックに合格しました。
• SENT -- ブロックチェーンに送信され、確認を待っています。
• STUCK -- 送信されたトランザクションの手数料パラメーターが、ブロックチェーンで現在必要とされる手数料を下回っています。開発者はこのトランザクションをキャンセルするか、処理を早める必要があります。
• CONFIRMED -- ブロックに含まれ、ファイナリティを待っています。

コントラクトのデプロイ状態は、deploymentStatus を使って scpClient.getContract() で別途追跡します。

失敗したトランザクションのデバッグについては、トランザクションの状態とエラーを参照してください。

エラー処理

エラーコード	意味	対処方法
175001	コントラクトが見つかりません	コントラクト ID が存在することを確認してください。インポート済みの場合は、アーカイブされていないことを確認してください
175003	コンストラクターのパラメーターが一致しません	パラメーターの数と型がコントラクトの ABI 定義と正確に一致することを確認してください
175004	コントラクトが重複しています	listContracts({ blockchain }) を呼び出し、contractAddress（大文字と小文字を区別しない）で照合して、既存の contractId を使用してください
175009	デプロイがまだ保留中です	deploymentStatus を取得するために getContract() のポーリングを続けてください。デプロイは非同期で、複数のブロックにわたる場合があります
175201	テンプレートが見つかりません	Quick Reference の Contract Templates テーブルにあるテンプレート ID を確認してください
175301	イベントサブスクリプションが見つかりません	イベントモニター ID を確認してください。モニターを作成する前にコントラクトがインポートされていることを確認してください
175302	イベントサブスクリプションが重複しています	既存のサブスクリプションを照会して再利用してください。フローを失敗させないでください
175303	イベント署名が無効です	空白を入れず、正確な形式 EventName(type1,type2,...) を使用してください。パラメーターの順序は ABI と一致している必要があります
175402	ブロックチェーンがサポートされていないか、非推奨です	Supported Blockchains テーブルを確認してください。SCP は Solana、Aptos、NEAR では利用できません
175404	メインネットで TEST_API キーが使われているか、テストネットで LIVE_API キーが使われています	API キーのプレフィックス（TEST_API_KEY: または LIVE_API_KEY:）が対象ネットワークと一致するようにしてください
177015	コントラクトのデプロイに必要なバイトコードがありません	0x プレフィックス付きのコンパイル済みバイトコードを指定してください。PUSH0 を避けるには evmVersion: "paris" でコンパイルしてください

デプロイに失敗した場合は、getContract() から deploymentErrorReason と deploymentErrorDetails を確認してください。

実装パターン

1. バイトコードからコントラクトをデプロイする

生の ABI とバイトコードを使用して、コンパイル済みコントラクトをデプロイします。

完全なガイドについては references/deploy-bytecode.md を参照してください。

2. テンプレートからデプロイする

Solidity を記述せずに、監査済みのテンプレートコントラクトをデプロイします。

テンプレートカタログとデプロイガイドについては references/deploy-template.md を参照してください。

3. 既存のコントラクトをインポートする

すでにデプロイされているコントラクトを SCP にインポートし、操作やイベント監視を行います。

完全なガイドについては references/import-contract.md を参照してください。

4. デプロイ済みコントラクトを操作する

ABI シグネチャを使用して、読み取り関数を呼び出し、書き込み関数を実行します。

完全なガイドについては references/interact.md を参照してください。

5. コントラクトイベントを監視する

発行されたイベントの Webhook 通知を設定し、過去のログを取得します。

完全なガイドについては 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' } } を使用してください。
• wagmi で window.ethereum を直接使用してはなりません。connector.getProvider() を使用してください。
• デフォルトの EVM バージョンで Solidity >= 0.8.20 をコンパイルしてはなりません。PUSH0 オペコードを避けるため、必ず evmVersion: "paris" を設定してください。
• importContract() を呼び出す際は、必ず name と idempotencyKey の両方を含めてください。
• デプロイが同期的に完了すると想定してはなりません。必ず getContract() をポーリングして deploymentStatus を確認してください。
• バイトコードには必ず 0x を付け、コンストラクターのパラメーターの型と順序を正確に一致させてください。
• 小数桁が18桁の金額には、必ず整数安全な計算を使用してください（BigInt(10 ** 18) ではなく 10n ** 18n）。
• イベントモニターを作成する前に、必ずコントラクトをインポートしてください。
• 特に指定がなければ、デモでは必ず Arc Testnet をデフォルトとして使用してください。
• 必ずテストネットをデフォルトとして使用してください。メインネットを対象とする前に、ユーザーから明示的な確認を得てください。

参考リンク

• Circle 開発者向けドキュメント -- ソースウェブサイトの関連ドキュメントを探す際は、必ず最初にこちらを読んでください。

---

免責事項：このスキルは「現状有姿」で提供され、いかなる保証もありません。また、Circle 開発者規約が適用されます。生成された出力には誤りが含まれる可能性があり、手数料設定オプション（Circle に支払われる手数料を含む）が含まれる場合があります。詳細は、リポジトリの README を参照してください。