use-gateway

概述

Circle Gateway 在多个区块链上提供统一的 USDC 余额，支持即时（<500 ms）跨链转账。用户可在任意受支持的链上将 USDC 存入 Gateway Wallet，然后在源链上销毁并在目标链上铸造，无需等待源链最终确认。

前置条件 / 设置

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，你可以从任意组合的源链销毁代币，但各链余额必须充足。

转账流程

1. 存入 -- 用户在任意链上将 USDC 存入 Gateway Wallet（加入统一余额）
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 存款（授权 + 存款）
• 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 -- EVM 上使用 EOA 代理为销毁意图签名的 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）钱包模式——自行管理或 Circle Wallets；（2）源网络系列——EVM 或 Solana；（3）目标网络系列——EVM 或 Solana。普通的 Circle Wallets EVM 到 EVM 转账使用 references/transfer-evm-circle-wallet.md。

代理流程属于一个范围狭窄的例外——SCA 源存款方通过单独的 EOA 代理签署销毁意图：

• Circle Developer-Controlled Wallets 中由 EOA 代理代表 SCA 存款方签名 -> references/transfer-evm-delegate.md。普通 Circle Wallets 转账请勿使用代理参考文件。
• 自行管理的 SCA -> 没有完全匹配的参考文件。请说明这一点，解释需要使用类似代理的 EOA 签名，并根据 Gateway 官方文档进行核验。除非用户明确说明其使用 Circle Developer-Controlled Wallets，否则请勿将 transfer-evm-delegate.md 用于自行管理的 SCA。

采用匹配的参考方案；如果已有参考文件涵盖该场景，请勿另行设计实现方案或从头搭建。

规则

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

安全规则

• 绝不要硬编码、提交或记录机密信息（私钥、签名密钥）。务必使用环境变量或机密管理器。搭建项目时，为 .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/provider 模式，而不是引入并行的钱包连接方案。
• 对于与框架无关的浏览器钱包流程，请使用浏览器钱包参考资料中的纯 TypeScript EIP-1193 模式。
• 务必默认使用测试网。目标为主网前，必须取得用户明确确认。

替代方案

• 对于不需要统一余额的简单点对点转账，请触发 bridge-tokens 技能（CCTP / Bridge Kit）。Bridge Kit 通过一次 kit.bridge() 调用处理 approve、burn、attestation 和 mint，并支持比 Gateway 更多的链。
• 对于不频繁或临时的转账，如果维护统一余额不值得预先存入资金，CCTP 更合适。
• 若需要即时（<500ms）转账、统一余额模型或跨链资金效率，请使用 Gateway。

警告：Gateway 对 Solana 钱包的兼容性有限。只有 Solflare 支持为 Gateway 销毁意图签署任意消息。Phantom 和大多数其他 Solana 钱包都会拒绝签名请求。

参考链接

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

---

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