bridge-tokens

概述

此技能通过 Circle 的 App Kit 或 Bridge Kit 在链之间转移代币。USDC 通过跨链传输协议（CCTP）转移——在源链上销毁，在目标链上铸造。CCTPx 代币使用注册表别名（例如 wETH、cirBTC 或 EURC）或注册表中列出的代币 ID。两种方式都通过同一个 kit.bridge() 调用完成——直接将别名或代币 ID 作为 token 传入，SDK 会自动路由；无需选择协议。App Kit（@circle-fin/app-kit）是 Circle 的一体化 SDK，在一个软件包中涵盖桥接、兑换和转账；独立的 Bridge Kit（@circle-fin/bridge-kit）则以更轻量的软件包提供相同的桥接 API。除非用户只需要桥接功能，否则建议使用 App Kit。桥接操作无需 kit 密钥。

这两个 SDK 都可在浏览器和服务端应用中运行。在客户端代码中使用浏览器钱包提供程序适配器，并在服务端保管私钥和 Circle Wallets 凭据。App Kit >=1.11.0 和 Bridge Kit >=1.12.2 的浏览器构建无需使用者提供 Node 或 Buffer polyfill。CCTPx 代币需要 App Kit 或 Bridge Kit >=1.15.0；在浏览器应用中桥接 CCTPx 代币，则需要 App Kit >=1.15.2 或 Bridge Kit >=1.15.1。

支持的代币和路由

在 kit.bridge() 和 kit.estimateBridge()（App Kit）/ kit.estimate()（Bridge Kit）中，直接将注册表别名或代币 ID 作为 token 传入；不要将其封装在提供程序选择器对象中。SDK 会自动将其路由到正确的协议。只有 USDC 支持 Solana；所有 CCTPx 路由都仅支持 EVM 到 EVM。别名区分大小写（"wETH"，而不是 "WETH"），代币 ID 是 bytes32 十六进制字符串（0x 后跟 64 个十六进制字符）。

代币选择器	支持的链
USDC	所有支持 CCTP 的链（EVM + Solana）——请参阅支持的链
EURC	主网上的 Ethereum、Base 和 Arc，以及符合条件的测试网路由
wETH	主网上 Ethereum <-> Arc 之间，以及符合条件的测试网路由
cirBTC	主网上 Ethereum <-> Arc 之间，以及符合条件的测试网路由
注册表中列出的代币 ID	注册表在源域和目标域上都列出了该代币的任意 EVM 路由

支持 CCTPx 的 EVM 链包括 Ethereum、Arc、Base、Arbitrum、Optimism、Polygon 和 Avalanche。链支持 CCTPx 并不意味着每种代币都能路由到其他所有链。SDK 会在运行时从 Circle 获取 CCTPx 代币注册表；如果所选代币未在源端和目标端同时列出，则会抛出 INPUT_UNSUPPORTED_ROUTE——不要对路由列表进行硬编码。

前提条件 / 设置

安装

选择一个基础套件——App Kit（推荐）或独立的 Bridge Kit——然后按需添加适配器。

App Kit 搭配 Viem 适配器（推荐）：

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

或者，对于仅支持桥接的应用，可使用独立的 Bridge Kit（更轻量的软件包）替代 App 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（推荐）——一个 SDK 即可涵盖桥接 + 兑换 + 转账，之后更容易扩展
• 不需要，只需桥接，且以后永远不会需要兑换或转账 -> Bridge Kit——独立且更轻量的软件包，适用于仅需桥接的场景

钱包 / 适配器选择

问题 2 —— 你如何管理钱包 / 密钥？

• 自行管理私钥（自行托管，存储在环境变量或密钥管理器中）-> 问题 3
• 使用 Circle 开发者控制的钱包（Circle 管理密钥存储和签名）-> 使用 Circle Wallets 适配器。阅读 references/adapter-circle-wallets.md
• 使用 EVM 浏览器钱包（wagmi、ConnectKit、RainbowKit 或任意 EIP-1193 provider）-> 使用 Viem provider 适配器。阅读 references/adapter-wagmi.md
• 使用 Solana 浏览器钱包（Wallet Standard provider，例如 Phantom、Solflare 或 Backpack）-> 使用 Solana provider 适配器。阅读 references/adapter-browser-wallet.md

问题 3 —— 你要在哪些链之间转账？

• EVM 到 EVM，或 EVM 到 Solana -> 使用 Viem 和 / 或 Solana Kit 适配器。阅读 references/adapter-private-key.md

代币选择

问题 4 —— 你要转账哪种代币？

• USDC -> 任意 CCTP 路由（EVM 或 Solana）。
• wETH、cirBTC、EURC 或 CCTPx 代币 ID -> 仅限 EVM 到 EVM。阅读 references/non-usdc-cctpx.md。如果目标链是 Solana，或注册表未列出该路由，请停止并提供 swap-tokens；不要替换为其他链组合。

工作流

1. 遵循决策指南 —— 在编写任何代码之前，与用户确定 SDK（App Kit 还是 Bridge Kit）以及钱包 / 适配器。
2. 安装并初始化 —— 安装所选 kit 和适配器，然后构建 kit 和适配器（参见先决条件 / 设置）。
3. 确认转账 —— 确认代币、金额、源链和目标链，以及接收方。验证链名称和地址。默认使用测试网；使用主网前必须获得明确确认。
4. 对于 CCTPx 代币，先获取报价 —— 确认注册表支持所选 EVM 路由，与用户确定使用 FAST 还是 SLOW，调用 kit.estimateBridge()（App Kit）或 kit.estimate()（Bridge Kit），并在执行前展示报价费用。报价重用仅尽力而为：如果结果中出现 QUOTE_NOT_REUSED 警告，请向用户说明。
5. 执行跨链转账 —— 仅在用户明确操作后调用 kit.bridge({ token, from, to, amount, ... })（不得自动调用）。确切代码请阅读适配器参考。
6. 跟踪并恢复 —— 检查 result.state / result.steps，使用 kit.on() 订阅；如果出现软失败，使用 kit.retryBridge(result, ...)（App Kit）或 kit.retry(result, ...)（Bridge Kit）恢复——绝不能从头重新运行 kit.bridge()。

核心概念

• CCTP 步骤（USDC）：每笔 USDC 跨链转账都会依次执行四个步骤——approve（ERC-20 授权额度）、burn（在源链销毁 USDC）、fetchAttestation（等待 Circle 为销毁证明签名）和 mint（在目标链创建 USDC）。
• CCTPx 转账：调用方式相同，都是 kit.bridge({ token, from, to, amount })；直接将注册表别名或代币 ID 作为 token 传入。步骤依次为 approve -> transfer -> fetchAttestation -> forward；仅当费用为 ERC-20 时，才会在 transfer 前执行 approveFee 步骤（Circle 的中继器会自动在目标链铸造，无需目标链 Gas，也无需切换 useForwarder）。每笔 CCTPx 转账都需以源链的原生代币支付中继器费用；FAST（默认）会增加一笔最终确认前费用，而 SLOW 会等待源链最终确认并免除此费用。跨链转账前，先调用 kit.estimateBridge()（App Kit）或 kit.estimate()（Bridge Kit），并向用户展示报价费用；只有用户明确确认后才能发起跨链转账。检查 result.state === "success"，确认操作是否完成。CCTPx 路由不支持自定义费用、feePayment: "destination" 和 useForwarder: false。
• 适配器：App Kit 和 Bridge Kit 都使用适配器对象来抽象钱包和签名器之间的差异。每个生态系统都有自己的适配器工厂（createViemAdapterFromPrivateKey、createSolanaKitAdapterFromPrivateKey、createCircleWalletsAdapter）。在同一生态系统内跨链转账时，同一个适配器实例可同时用作源链和目标链适配器。
• 转发服务：当目标链设置了 useForwarder: true 时，Circle 的基础设施会负责获取证明并提交铸造交易。这样便无需目标链钱包或轮询循环。每笔转账都需支付费用，具体金额因路由而异（见下文）。
• 转账速度：CCTP 快速模式（默认）约需 8-20 秒完成。标准模式需 15-19 分钟。
• 链标识符：两个 SDK 在 kit.bridge() 调用中都使用字符串形式的链名称（例如 "Arc"、"Arc_Testnet"、"Base_Sepolia"、"Solana_Devnet"），而非数字链 ID。
• 浏览器安全的软件包：当前版本的 App Kit、Bridge Kit 和 Solana 适配器已内置所需的浏览器兼容性。浏览器请求会省略仅适用于 Node 的标头，Solana 操作也无需使用者提供 Buffer 垫片。请升级过时的软件包，而不是添加 polyfill。

实现模式

根据用户的请求，阅读相应的参考文档：

• 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 浏览器钱包，无需手动添加 polyfill
• references/non-usdc-cctpx.md —— 在支持的 EVM 路由上跨链转账 CCTPx 注册表别名和代币 ID：路由验证、先报价再确认的流程，以及 FAST/SLOW 转账速度

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.retryBridge()（App Kit）/kit.retry()（Bridge Kit）分析并恢复失败的转账时，请阅读 references/forwarding-events-recovery.md，了解可运行的模式（包括 Bridge Kit 中不同的事件名称）。

错误处理与恢复

App Kit 和 Bridge Kit 都有两类错误：

• 硬错误会抛出异常（验证、配置、身份验证）——使用 try/catch 捕获。
• 软错误会在传输过程中发生，但仍会返回包含部分步骤数据的结果对象，以便恢复。发生软错误后，绝不要从头重新运行 kit.bridge()——使用 kit.retryBridge(result, ...)（App Kit）或 kit.retry(result, ...)（Bridge Kit）从失败步骤继续，并防止重复扣款；完整模式见 references/forwarding-events-recovery.md。

规则

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

安全规则

• 绝不要硬编码、提交或记录机密（私钥、API 密钥、实体机密、kit 密钥）。始终使用环境变量或机密管理器。搭建项目脚手架时，为 .env* 和机密文件添加 .gitignore 条目。
• 绝不要在浏览器代码或公开环境变量（VITE_*、NEXT_PUBLIC_* 等）中放置私钥、Circle API 密钥、实体机密或 kit 密钥。
• 绝不要在浏览器中导入主入口 @circle-fin/adapter-circle-wallets；它需要服务端 Circle 凭据。
• 绝不要将私钥作为纯文本 CLI 标志传递。优先使用加密密钥库或交互式导入。
• 始终在跨链转移前显示源链／目标链、收款方、金额和代币。在 UI 中，用户点击已启用的 Bridge 按钮即表示明确确认；不要再添加二次确认提示或合成确认对象。在服务端辅助函数中，导出资金转移操作，但不要自动调用它。在可运行脚本或 CLI 中，先显示报价，然后等待明确确认（例如交互式 y/N 提示）后再调用 bridge()；绝不要在一次无人值守运行中连续报价并跨链转移。绝不要在估算后、从 effect 中、在渲染期间或模块启动时自动调用 bridge()。主网资金转移必须获得确认。
• 以主网为目标或超出安全阈值（例如超过 100 USDC）时，始终发出警告。
• 提交跨链转移操作前，始终验证所有输入（地址、金额、链名称）。
• 与未经审计或未知的合约交互前，始终发出警告。

最佳实践

• 编写任何代码前，始终引导用户完成决策指南中的问题。不要假设使用 App Kit 还是 Bridge Kit——根据用户的回答选择 SDK。
• 实施前始终阅读正确的参考文件。
• 对于浏览器应用，必须使用适用于浏览器的程序包版本，并使用基于 provider 的适配器；不要添加 Node／Buffer polyfill。
• 如果未使用 Forwarding Service，通过浏览器钱包（wagmi／ConnectKit／RainbowKit）调用 kit.bridge() 前，始终先将钱包切换到源链。
• 始终使用 try/catch 包装跨链转移操作，并保存结果对象以便恢复。重试前检查 result.steps，确认哪些步骤已完成。
• 在生产环境中，重试逻辑始终使用指数退避。
• 始终使用字符串形式的链名称（例如 "Arc"、"Arc_Testnet"、"Base_Sepolia"），而不是数字链 ID。
• 始终默认使用测试网。以主网为目标前，必须获得用户明确确认。
• 解析 SDK 输入和输出时，始终使用 SDK 导出的类型，而不是创建自定义接口。这可以最大限度减少类型错误。

参考链接

• Circle App Kit SDK
• Circle Bridge Kit SDK
• CCTP 文档
• Circle 开发者文档——查找源网站上的相关文档时，始终先阅读此文档。

替代方案

在以下情况下，请改用 swap-tokens 技能：

• 你需要在同一条链上兑换代币（例如，将 USDT 兑换为 USDC）。
• 你需要跨链转移此技能无法直接桥接的代币。此技能可在 CCTP 链以及其注册表支持的 EVM 路由上的 CCTPx 别名或代币 ID 之间桥接 USDC；swap-tokens 则可通过跨链兑换路由其他代币或链。

在以下情况下，请改用 use-gateway 技能：

• 你想要统一的跨链余额，而不是点对点转账。
• 资本效率很重要——整合 USDC 持仓，而不是在各条链上分别维持余额。
• 你正在构建链抽象、支付路由或资金管理方案，且低延迟和统一的余额视图至关重要。

---

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