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 リクエストごとに新しいエンティティシークレットの暗号文を自動的に生成します。

主な概念

• ウォレットセット：1 つのエンティティシークレットで管理されるウォレットのグループです。セット内のウォレットは異なるブロックチェーンにまたがることができますが、EVM チェーンでは同じアドレスを共有します。
• エンティティシークレット：開発者管理ウォレットを保護する 32 バイトの秘密鍵です。一度生成、暗号化、登録します。Circle が平文で保管することはありません。
• エンティティシークレットの暗号文：Circle の公開鍵を使用して RSA で暗号化されたエンティティシークレットです。リプレイ攻撃を防ぐため、API リクエストごとに一意である必要があります。SDK がこれを自動的に処理します。
• 冪等性キー：すべての変更リクエストには、処理を厳密に 1 回だけ実行するための UUID v4 idempotencyKey が必要です。
• アカウントタイプ：
  • EOA（Externally Owned Account）— デフォルトの選択肢です。作成手数料がなく、送信 TPS が高く、最も幅広いチェーンに対応しています（すべての EVM チェーンに加え、Solana、Aptos、NEAR）。ガス代にはネイティブトークンが必要です（Arc ではガス資産は USDC であり、別個のネイティブトークンではありません）。
  • SCA（Smart Contract Account）— ERC-4337 に準拠しています。Circle Gas Station によるガス代のスポンサー、バッチ操作、柔軟な鍵管理に対応しています。EVM のみで利用でき（Solana、Aptos、NEAR では利用できません）、ガス代が高いため 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 型付きデータ、raw トランザクション署名、NEAR 委任アクションについて説明しています。

5. スマートコントラクトを実行する

完全なガイドについては、references/contract-execution.md をお読みください。ABI ベースおよび raw calldata による実行、payable 関数、ガスの見積もりについて説明しています。

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 など）があることを必ず確認してください。Arc では USDC 自体がガス資産であり、別のネイティブトークンはありません。そのため、ウォレットに USDC を入金するとガス代も賄えます。
• 完了したと判断する前に、トランザクションのステータスが終端状態（COMPLETE、FAILED、DENIED、CANCELLED）になるまで、必ずポーリングしてください。
• 高額なガス代を避けるため、Ethereum メインネットより L2 上の SCA ウォレットを必ず優先してください。
• 必ずテストネットをデフォルトにしてください。メインネットを対象とする前に、ユーザーの明示的な確認を得てください。
• ユーザーが事前にガス代を把握できるよう、コントラクトの実行や大規模な送金の前に必ず手数料を見積もってください。
• 実行前に、ABI 関数シグネチャとパラメーターが対象のコントラクトと一致していることを必ず確認してください。シグネチャが正しくないと、トランザクションがリバートしてガス代が無駄になります。
• 可読性と監査可能性のため、信頼できるライブラリ（ethers、viem）で calldata を生成する場合を除き、生の callData よりも abiFunctionSignature と abiParameters を必ず優先してください。

代替手段

• エンドユーザーがソーシャルログイン、メール OTP、または PIN 認証を通じて自分のキーを保管する必要がある場合は、use-user-controlled-wallets スキルを起動してください。
• 拡張可能なモジュールアーキテクチャ（マルチシグ、セッションキーなど）を備えたパスキー対応のスマートアカウントには、use-modular-wallets スキルを起動してください。

リファレンスリンク

• Circle Developer Docs -- ソースウェブサイトから関連ドキュメントを探す際は、必ず最初にこちらをお読みください。

---

免責事項：このスキルは「現状有姿」で提供され、保証はありません。また、Circle Developer Terms が適用されます。生成された出力には誤りが含まれる場合や、手数料設定のオプション（Circle に支払われる手数料を含む）が含まれる場合があります。詳細は、リポジトリの README をご覧ください。