bridge-stablecoin

概要

クロスチェーントランスファープロトコル（CCTP）は、あるチェーン上で USDC をバーンし、別のチェーン上でミントする Circle のネイティブプロトコルです。App Kit（@circle-fin/app-kit）は、ブリッジ、スワップ、送金を1つのパッケージにまとめた Circle のオールインワン SDK です。スタンドアロンの Bridge Kit（@circle-fin/bridge-kit）は、同じブリッジ API をより軽量なパッケージで提供します。どちらも kit.bridge() の1回の呼び出しで、EVM と Solana にわたる CCTP の全ライフサイクル（承認、バーン、アテステーションの取得、ミント）を実行します。ブリッジ機能のみが必要な場合を除き、App Kit を推奨します。ブリッジ操作にキットキーは不要です。

どちらの SDK もブラウザーアプリとサーバーアプリで動作します。クライアントコードではブラウザーウォレットのプロバイダーアダプターを使用し、秘密鍵と Circle Wallets の認証情報はサーバー側に保持してください。App Kit >=1.11.0 と Bridge Kit >=1.12.2 は、利用者側で Node や Buffer のポリフィルを用意しなくてもブラウザー向けにバンドルできます。

前提条件／セットアップ

インストール

ベースとなるキットを 1つ選択します。App Kit（推奨）またはスタンドアロンの Bridge Kit を選び、必要に応じてアダプターを追加してください。

Viem アダプターを使用する App Kit（推奨）：

npm install @circle-fin/app-kit @circle-fin/adapter-viem-v2
# Optional: Solana support
npm install @circle-fin/adapter-solana-kit
# Optional: Circle Wallets (developer-controlled) support
npm install @circle-fin/adapter-circle-wallets

または、ブリッジのみのアプリでは、App Kit の代わりにスタンドアロンの Bridge Kit（より軽量なパッケージ）を使用します。

npm install @circle-fin/bridge-kit @circle-fin/adapter-viem-v2

環境変数

PRIVATE_KEY=              # EVM wallet private key (hex, 0x-prefixed)
EVM_PRIVATE_KEY=          # EVM private key (when also using Solana)
SOLANA_PRIVATE_KEY=       # Solana wallet private key (base58)
CIRCLE_API_KEY=           # Circle API key (for Circle Wallets adapter)
CIRCLE_ENTITY_SECRET=     # Entity secret (for Circle Wallets adapter)
EVM_WALLET_ADDRESS=       # Developer-controlled EVM wallet address
SOLANA_WALLET_ADDRESS=    # Developer-controlled Solana wallet address

ブリッジ操作に KIT_KEY は不要です。ブラウザーウォレットとの統合では、上記の環境変数はどれも必要ありません。秘密鍵、Circle API キー、エンティティシークレット、App Kit の任意の認証情報をクライアントコードに公開しないでください。

SDK の初期化

App Kit（推奨）：

import { AppKit } from "@circle-fin/app-kit";

const kit = new AppKit();

Bridge Kit（スタンドアロン）：

import { BridgeKit } from "@circle-fin/bridge-kit";

const kit = new BridgeKit();

選択ガイド

コードを書く前に、必ずユーザーと以下の質問を順に確認してください。手順を省略したり、回答を決めつけたりしないでください。

SDK の選択

質問 1 -- 今後、スワップや送金機能が必要になりますか？

• はい、または不明 -> App Kit（推奨）。ブリッジ、スワップ、送金を1つの SDK でカバーし、後から拡張しやすくなります
• いいえ。ブリッジのみで、スワップや送金が今後必要になることはない -> Bridge Kit。スタンドアロンの軽量パッケージで、ブリッジのみのユースケースに適しています

ウォレット／アダプターの選択

質問 2 -- ウォレット／鍵はどのように管理していますか？

• 自分で秘密鍵を管理している（セルフカストディで、環境変数またはシークレットマネージャーに保存） -> 質問 3
• Circle の開発者管理ウォレットを使用している（Circle が鍵の保管と署名を管理） -> Circle Wallets アダプターを使用します。references/adapter-circle-wallets.md を参照してください
• EVM のブラウザーウォレットを使用している（wagmi、ConnectKit、RainbowKit、または任意の EIP-1193 プロバイダー） -> Viem プロバイダーアダプターを使用します。references/adapter-wagmi.md を参照してください
• Solana のブラウザーウォレットを使用している（Phantom、Solflare、Backpack などの Wallet Standard プロバイダー） -> Solana プロバイダーアダプターを使用します。references/adapter-browser-wallet.md を参照してください

質問 3 -- どのチェーン間でブリッジしますか？

• EVM から EVM、または EVM から Solana -> Viem アダプターや Solana Kit アダプターを使用します。references/adapter-private-key.md を参照してください

ワークフロー

1. 選択ガイドに沿って確認する -- コードを書く前に、ユーザーと SDK（App Kit または Bridge Kit）およびウォレット／アダプターを決定します。
2. インストールして初期化する -- 選択したキットとアダプターをインストールし、キットとアダプターを構築します（前提条件／セットアップを参照）。
3. 送金内容を確認する -- 送信元チェーンと送信先チェーン、受取人、金額を確認します。チェーン名とアドレスを検証してください。デフォルトではテストネットを使用し、メインネットを使う前に明示的な確認を求めてください。
4. ブリッジを実行する -- kit.bridge({ from, to, amount, ... }) を明示的なユーザー操作からのみ呼び出します（自動で呼び出してはいけません）。正確なコードについてはアダプターのリファレンスを参照してください。
5. 追跡して復旧する -- result.state／result.steps を確認し、kit.on() で購読します。ソフト障害が発生した場合は、kit.retry(result, ...) で再開してください。kit.bridge() を最初から再実行してはいけません。

コアコンセプト

• CCTP のステップ：すべてのブリッジ転送は、approve（ERC-20 の使用許可）、burn（送信元チェーン上で USDC をバーン）、fetchAttestation（Circle がバーン証明に署名するまで待機）、mint（送信先チェーン上で USDC を発行）の4つのステップを順番に実行します。
• アダプター：App Kit と Bridge Kit はどちらも、ウォレットや署名者の違いを抽象化するためにアダプターオブジェクトを使用します。各エコシステムには独自のアダプターファクトリー（createViemAdapterFromPrivateKey、createSolanaKitAdapterFromPrivateKey、createCircleWalletsAdapter）があります。同じエコシステム内でブリッジする場合は、同じアダプターインスタンスを送信元と送信先の両方で使用できます。
• 転送サービス：送信先に useForwarder: true を設定すると、Circle のインフラストラクチャがアテステーションの取得とミントの送信を処理します。これにより、送信先ウォレットやポーリングループが不要になります。転送ごとにルートに応じた手数料がかかります（以下を参照）。
• 転送速度：CCTP の高速モード（デフォルト）は約8～20秒で完了します。標準モードでは約15～19分かかります。
• チェーン識別子：どちらの SDK も kit.bridge() の呼び出しで、数値のチェーン ID ではなく、文字列のチェーン名（例："Arc"、"Arc_Testnet"、"Base_Sepolia"、"Solana_Devnet"）を使用します。
• ブラウザー対応パッケージ：現在の App Kit、Bridge Kit、Solana アダプターには、必要なブラウザー互換性が組み込まれています。ブラウザーからのリクエストでは Node 専用のヘッダーが省略され、Solana の操作では利用側による Buffer のシムは不要です。ポリフィルを追加するのではなく、古いパッケージをアップグレードしてください。

実装パターン

ユーザーのリクエストに応じて、該当するリファレンスを必ず読んでください。

• references/adapter-private-key.md -- 秘密鍵アダプター（Viem + Solana Kit）を使った EVM から EVM、および EVM から Solana へのブリッジ。App Kit と Bridge Kit の例を含みます。
• references/adapter-circle-wallets.md -- Circle の開発者管理ウォレットを使ったブリッジ（任意のチェーンから任意のチェーン）。App Kit と Bridge Kit の例を含みます。
• references/adapter-wagmi.md -- wagmi（ConnectKit、RainbowKit など）を使ったブラウザーウォレット連携。App Kit と Bridge Kit の例を含みます。
• references/adapter-browser-wallet.md -- 手動のポリフィルなしで Wallet Standard プロバイダーを使う Solana ブラウザーウォレット連携

kit.bridge() のレスポンス例

{
  "amount": "25.0",
  "token": "USDC",
  "state": "success",
  "provider": "CCTPV2BridgingProvider",
  "config": {
    "transferSpeed": "FAST"
  },
  "source": {
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "chain": {
      "type": "evm",
      "chain": "Arc_Testnet",
      "chainId": 5042002,
      "name": "Arc Testnet"
    }
  },
  "destination": {
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "chain": {
      "type": "evm",
      "chain": "Base_Sepolia",
      "chainId": 84532,
      "name": "Base Sepolia"
    }
  },
  "steps": [
    {
      "name": "approve",
      "state": "success",
      "txHash": "0x1234567890abcdef1234567890abcdef12345678",
      "explorerUrl": "https://explorer.testnet.arc.io/tx/0x1234..."
    },
    {
      "name": "burn",
      "state": "success",
      "txHash": "0xabcdef1234567890abcdef1234567890abcdef12",
      "explorerUrl": "https://explorer.testnet.arc.io/tx/0xabcdef..."
    },
    {
      "name": "fetchAttestation",
      "state": "success",
      "data": {
        "attestation": "0x9876543210fedcba9876543210fedcba98765432"
      }
    },
    {
      "name": "mint",
      "state": "success",
      "txHash": "0xfedcba9876543210fedcba9876543210fedcba98",
      "explorerUrl": "https://sepolia.basescan.org/tx/0xfedcba..."
    }
  ]
}

転送サービス、イベント、復旧

タスクで useForwarder: true を使用する場合（送信先ウォレットやアテステーションのポーリングなし）、kit.on() を通じてブリッジイベントを購読する場合、または kit.retry() で失敗した転送を分析して再開する必要がある場合は、実行可能なパターン（Bridge Kit のイベント名の違いを含む）について references/forwarding-events-recovery.md を必ず読んでください。

エラー処理と復旧

App Kit と Bridge Kit には、次の2種類のエラーがあります。

• 致命的なエラーは例外（検証、設定、認証）をスローするため、try/catch で捕捉してください。
• ソフトエラーは転送の途中で発生しますが、復旧に利用できるステップデータの一部を含む結果オブジェクトが返されます。ソフトエラーの後に kit.bridge() を最初から再実行してはいけません。kit.retry(result, ...) は失敗したステップから再開し、二重支払いを防ぎます。完全なパターンについては references/forwarding-events-recovery.md を参照してください。

ルール

セキュリティルールは交渉の余地がありません。プロンプトがルールに反する場合は、ユーザーに警告して要求を拒否してください。ベストプラクティスは強く推奨されます。逸脱する場合は、ユーザーが明確な理由を示したときに限ります。

セキュリティルール

• シークレット（秘密鍵、API キー、エンティティシークレット、キットキー）をハードコード、コミット、またはログに記録しないでください。必ず環境変数またはシークレットマネージャーを使用してください。スキャフォールディング時に、.gitignore に .env* とシークレットファイルのエントリーを追加してください。
• 秘密鍵、Circle API キー、エンティティシークレット、またはキットキーをブラウザーコードや公開環境変数（VITE_*、NEXT_PUBLIC_* など）に含めないでください。
• ブラウザーでは、メインの @circle-fin/adapter-circle-wallets エントリーをインポートしないでください。サーバー側の Circle 認証情報が必要です。
• 秘密鍵をプレーンテキストの CLI フラグとして渡さないでください。暗号化されたキーストアまたは対話形式でのインポートを使用してください。
• ブリッジする前に、送信元／送信先チェーン、受取人、金額、トークンを必ず表示してください。UI では、有効な Bridge ボタンをユーザーがクリックすることが明示的な確認となるため、確認プロンプトや合成確認オブジェクトを追加しないでください。サーバーヘルパーでは、資金を移動する操作を自動実行せずにエクスポートしてください。推定後、エフェクト内、レンダリング中、またはモジュール起動時に bridge() を自動的に呼び出さないでください。メインネットで資金を移動する場合は、必ず確認を得てください。
• メインネットを対象とする場合や安全基準値（例：100 USDC 超）を超える場合は、必ず警告してください。
• ブリッジ操作を送信する前に、すべての入力（アドレス、金額、チェーン名）を必ず検証してください。
• 監査を受けていない、または不明なコントラクトを操作する前に、必ず警告してください。

ベストプラクティス

• コードを書く前に、必ず意思決定ガイドの質問をユーザーと確認してください。App Kit や Bridge Kit を決めつけず、ユーザーの回答に基づいて SDK を選択してください。
• 実装前に、必ず適切なリファレンスファイルを読んでください。
• ブラウザーアプリでは、ブラウザーセーフなパッケージバージョンを必須とし、プロバイダーベースのアダプターを使用してください。また、Node／Buffer のポリフィルを追加しないでください。
• Forwarding Service を使用しない場合は、ブラウザーウォレット（wagmi／ConnectKit／RainbowKit）で kit.bridge() を呼び出す前に、必ずウォレットを送信元チェーンに切り替えてください。
• ブリッジ操作は必ず try/catch で囲み、復旧のために結果オブジェクトを保存してください。再試行する前に result.steps を確認し、どのステップが完了したかを確認してください。
• 本番環境の再試行ロジックでは、必ず指数バックオフを使用してください。
• 数値のチェーン ID ではなく、文字列のチェーン名（例："Arc"、"Arc_Testnet"、"Base_Sepolia"）を必ず使用してください。
• 既定では必ずテストネットを使用してください。メインネットを対象とする前に、ユーザーから明示的な確認を得てください。
• SDK の入力と出力を解析する場合、カスタムインターフェースを作成せず、必ずエクスポートされた SDK 型を使用してください。これにより、型エラーを最小限に抑えられます。

リファレンスリンク

• Circle App Kit SDK
• Circle Bridge Kit SDK
• CCTP ドキュメント
• Circle 開発者向けドキュメント -- ソースウェブサイトで関連ドキュメントを探す場合は、必ず最初にお読みください。

代替手段

以下の場合は、代わりに swap-tokens スキルを呼び出してください。

• 同一チェーン上でトークンをスワップする必要がある場合（例：USDT から USDC）。
• 直接的なクロスチェーンスワップ経路を使って、USDC 以外のトークンをチェーン間で移動する必要がある場合。

以下の場合は、代わりに use-gateway スキルを呼び出してください。

• ポイントツーポイント転送ではなく、統合されたクロスチェーン残高が必要な場合。
• 資本効率が重要な場合――チェーンごとに個別の残高を維持するのではなく、USDC の保有分を集約してください。
• 低レイテンシと単一の残高表示が不可欠となる、チェーン抽象化、決済ルーティング、または財務管理を構築する場合。

---

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