use-gateway

概要

Circle Gateway は、複数のブロックチェーンにまたがる統合 USDC 残高を提供し、即時（500 ms 未満）のクロスチェーン送金を実現します。ユーザーは対応チェーンのいずれかで Gateway Wallet に USDC を預け入れた後、ソースチェーンでバーンし、ソースチェーンのファイナリティを待たずに宛先チェーンでミントできます。

前提条件／セットアップ

Gateway はコントラクトレベルの統合であり、インストールする SDK はありません。オンチェーンの Gateway Wallet および Gateway Minter コントラクトと、アテステーション用の Gateway REST API を直接操作します。

チェーン設定

デフォルトでは、別の設定ファイルを読み込まないでください。ほとんどの Gateway タスクでは、ユーザーのウォレットモデルと送信元／宛先ネットワークに合ったシナリオリファレンスを直接参照してください。

まずシナリオリファレンスを使用し、次の項目を確認する必要がある場合に限り、追加の検証を行ってください。

• Gateway REST のベース URL
  • テストネット：https://gateway-api-testnet.circle.com/v1/
  • メインネット：https://gateway-api.circle.com/v1/
• チェーンごとの USDC アドレス：https://developers.circle.com/stablecoins/usdc-contract-addresses.md
• Circle Wallet のブロックチェーン識別子：https://developers.circle.com/wallets/supported-blockchains.md

検証用の正式なソースドキュメント：

• Gateway のハウツー：
  • https://developers.circle.com/gateway/howtos/create-unified-usdc-balance.md
  • https://developers.circle.com/gateway/howtos/manage-delegates.md
  • https://developers.circle.com/gateway/howtos/transfer-unified-usdc-balance.md
• Gateway のクイックスタート：
  • https://developers.circle.com/gateway/quickstarts/unified-balance-evm.md
  • https://developers.circle.com/gateway/quickstarts/unified-balance-solana.md
• Arc チュートリアル：https://docs.arc.io/arc/tutorials/access-usdc-crosschain.md

クイックリファレンス

主要なアドレス

EVM メインネット（全チェーン）

• Gateway Wallet：0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE
• Gateway Minter：0x2222222d7164433c4C09B0b0D809a9b52C04C205

EVM テストネット（全チェーン）

• Gateway Wallet：0x0077777d7EBA4688BDeF3E311b846F25870A19B9
• Gateway Minter：0x0022222ABE238Cc2C7Bb1f21003F0a260052475B

Solana メインネット

• Gateway Wallet：GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ
• Gateway Minter：GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ

Solana Devnet

• Gateway Wallet：GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu
• Gateway Minter：GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr
• USDC Mint：4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU

ドメイン ID（メインネット）

チェーン	ドメイン
Ethereum	0
Avalanche	1
OP	2
Arbitrum	3
Solana	5
Base	6
Polygon PoS	7
Unichain	10
Sonic	13
World Chain	14
Sei	16
HyperEVM	19
Arc	26

ドメイン ID（テストネット）

チェーン	ドメイン
Ethereum Sepolia	0
Avalanche Fuji	1
OP Sepolia	2
Arbitrum Sepolia	3
Solana Devnet	5
Base Sepolia	6
Polygon Amoy	7
Unichain Sepolia	10
Sonic Testnet	13
World Chain Sepolia	14
Sei Atlantic	16
HyperEVM Testnet	19
Arc Testnet	26

コアコンセプト

統合残高

Gateway は、対応するすべてのチェーンに預け入れられた USDC を集約し、単一の統合残高として扱います。これは会計上の抽象化であり、実際の USDC トークンは引き続き特定のブロックチェーン上に存在します。残高が統合されているように見えても、送金では必ず sourceDomain（バーン元のチェーン）と destinationDomain（ミント先のチェーン）を指定する必要があります。

複数通貨の銀行口座のようなものだと考えてください。合計額は一つに見えますが、引き出しは特定の保有分から行われます。統合残高内のどのチェーンからでもバーンでき、対応する任意のチェーンにミントできます。

例： Ethereum Sepolia に 10 USDC、Base Sepolia に 5 USDC、Solana Devnet に 5 USDC を預け入れた場合、統合残高は 20 USDC です。Arc Testnet に 10 USDC を送金するには、残高が十分にある送信元チェーンを任意に組み合わせてバーンできます。

Transfer Flow

1. 入金 -- ユーザーは任意のチェーン上の Gateway Wallet に USDC を入金します（統合残高に加算されます）。
2. バーンインテントの作成 -- 送信元ドメイン、送信先ドメイン、受取人、金額を指定します。
3. 署名 -- EVM の送信元では EIP-712、Solana の送信元では Ed25519 を使用します。
4. Gateway API に送信 -- バーンインテントを POST し、アテステーションを受け取ります。
5. 送信先でミント -- 送信先チェーンでアテステーションを指定して gatewayMint を呼び出します。

実装パターン

該当するシナリオのリファレンスファイルを必ず読んでください。

• セルフマネージド EVM のリファレンスでは、Node/TypeScript スクリプトで viem を使用します。
• セルフマネージド EVM のブラウザーウォレットのリファレンスでは、純粋な TypeScript と注入された EIP-1193 プロバイダーを使用します。
• Circle Wallets のリファレンスでは、@circle-fin/developer-controlled-wallets を使用します。
• Solana のリファレンスでは、Anchor と該当する Solana ツールを使用します。

入金

• references/deposit-evm.md -- セルフマネージド EVM の入金（approve + deposit）
• references/deposit-evm-browser-wallet.md -- 純粋な TypeScript を使用したブラウザーウォレットからのセルフマネージド EVM の入金
• references/deposit-evm-circle-wallet.md -- Circle Wallets の EVM 入金（開発者管理、サーバーサイド）
• references/deposit-solana.md -- セルフマネージド Solana の入金
• references/deposit-solana-circle-wallet.md -- Circle Wallets の Solana 入金

EVM からの転送

• references/evm-to-evm.md -- セルフマネージド EVM から EVM への転送
• references/evm-to-evm-browser-wallet.md -- 純粋な TypeScript を使用したブラウザーウォレットからのセルフマネージド EVM から EVM への転送
• references/transfer-evm-circle-wallet.md -- Circle Wallets の EVM から EVM への転送
• references/transfer-evm-delegate.md -- EOA デリゲートを使用してバーンインテントに署名する、EVM 上の SCA 入金者
• references/evm-to-solana.md -- セルフマネージド EVM から Solana への転送
• references/evm-to-solana-circle-wallet.md -- Circle Wallets の EVM から Solana への転送

Solana からの転送

• references/solana-to-evm.md -- セルフマネージド Solana から EVM への転送
• references/solana-to-evm-circle-wallet.md -- Circle Wallets の Solana から EVM への転送
• references/solana-to-solana.md -- セルフマネージド Solana から Solana への転送
• references/solana-to-solana-circle-wallet.md -- Circle Wallets の Solana から Solana への転送

残高照会

• references/query-balance.md -- チェーンをまたいだ Gateway の統合残高を照会します（POST /balances）。

次の順に基づいて、最も適合するリファレンスを1つ選んでください：（1）ウォレットモデル -- セルフマネージドまたは Circle Wallets、（2）送信元のネットワークファミリー -- EVM または Solana、（3）送信先のネットワークファミリー -- EVM または Solana。通常の Circle Wallets の EVM から EVM への転送には、references/transfer-evm-circle-wallet.md を使用します。

デリゲートフローは限定的な例外です。別の EOA デリゲートを介してバーンインテントに署名する、SCA の送信元入金者が対象です。

• Circle Developer-Controlled Wallets で、EOA デリゲートが SCA 入金者に代わって署名する場合 -> references/transfer-evm-delegate.md。通常の Circle Wallets の転送にデリゲートのリファレンスを使用しないでください。
• セルフマネージド SCA -> 正確に一致するリファレンスはありません。その旨を伝え、デリゲート形式の EOA 署名が必要であることを説明し、正規の Gateway ドキュメントで確認してください。ユーザーが Circle Developer-Controlled Wallets を使用すると明示していない限り、セルフマネージド SCA に transfer-evm-delegate.md を再利用しないでください。

該当するリファレンスを応用してください。既存のリファレンスが対象ケースをカバーしている場合、並行する実装や新しいひな形を独自に作成しないでください。

ルール

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

セキュリティルール

• 秘密情報（秘密鍵、署名鍵）をハードコード、コミット、またはログに記録しないでください。必ず環境変数またはシークレットマネージャーを使用してください。足場を作成する際は、.env* とシークレットファイルを .gitignore に追加してください。
• 参照ファイルに記載された EIP-712 型定義、ドメインセパレーター、構造体ハッシュ、Solana の署名ペイロード、またはブロックチェーン固有の値を変更しないでください。記載どおりにそのまま使用してください。フィールド名、型、順序を変更したり、フィールドを省略したりすると、無効な署名が生成されます。
• 生の Solana ウォレットアドレスを destinationRecipient として使用しないでください。必ず USDC トークンアカウント（ATA または SPL Token Account）を指定してください。ATA を導出する前に、@solana/spl-token の getAccount() を使って、そのアドレスがすでに USDC トークンアカウントかどうかを確認してください。該当する場合は、そのアドレスをそのまま使用してください。アドレス自体がトークンアカウントである状態で、そのアドレスから ATA を導出すると、資金が永久に失われます。
• Solana のバーンインテントに署名する際は、Ed25519 署名の前に、ペイロードの先頭に 16 バイト（0xff + 15 個のゼロバイト）を必ず付加してください。
• 送金を実行する前に、送金先、金額、送金元／送金先ネットワーク、トークンについて、必ずユーザーの明示的な確認を求めてください。メインネットで資金移動を自動実行しないでください。
• メインネットを対象とする場合、または安全基準値（例：100 USDC 超）を超える場合は、必ず警告してください。
• トランザクションを送信する前に、すべての入力値（アドレス、金額、ドメイン ID）を必ず検証してください。
• 監査されていない、または未知のコントラクトを操作する前に、必ず警告してください。

ベストプラクティス

• 実装前に、必ず正しい参照ファイルを読んでください。
• 追加の検証コンテキストを読み込む前に、必ずシナリオの参照先を確認してください。
• 統合残高を使用する場合でも、sourceDomain と destinationDomain を省略しないでください。すべての送金で両方が必要です。
• USDC に 18 桁の小数桁数を使用しないでください。必ず 6 桁を使用してください（parseUnits(amount, 6)）。
• すでに wagmi を使用している React アプリでは、別のウォレット接続スタックを導入するのではなく、既存の wagmi／プロバイダーパターンを優先してください。
• フレームワークに依存しないブラウザーウォレットフローでは、browser-wallet refs にある純粋な TypeScript の EIP-1193 パターンを使用してください。
• 必ずテストネットをデフォルトにしてください。メインネットを対象にする前に、ユーザーの明示的な確認を求めてください。

代替手段

• 統合残高を使わないシンプルなポイントツーポイント送金には、bridge-tokens スキル（CCTP／Bridge Kit）を起動してください。Bridge Kit は、1 回の kit.bridge() 呼び出しで approve、burn、attestation、mint を処理し、Gateway より多くのチェーンに対応しています。
• 統合残高を維持するための初期入金に見合う価値がない、頻度の低い、または都度発生する送金には、CCTP が適しています。
• 即時（<500ms）送金、統合残高モデル、またはチェーン間の資本効率が必要な場合は、Gateway を使用してください。

警告：Gateway での Solana ウォレットの互換性には制限があります。Gateway のバーンインテントに対する任意メッセージへの署名をサポートしているのは Solflare のみです。Phantom やほとんどの他の Solana ウォレットでは、署名リクエストが拒否されます。

参照リンク

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

---

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