bridge-stablecoin

概述

跨链转账协议（CCTP）是 Circle 的原生协议，可在一条链上销毁 USDC，并在另一条链上铸造 USDC。App Kit（@circle-fin/app-kit）是 Circle 的全能 SDK，将桥接、兑换和发送整合在一个包中；独立的 Bridge Kit（@circle-fin/bridge-kit）则以更轻量的包提供相同的桥接 API。两者都可通过一次 kit.bridge() 调用，在 EVM 和 Solana 上完成整个 CCTP 生命周期——授权、销毁、获取证明、铸造。**除非用户只需要桥接功能，否则建议使用 App Kit。**桥接操作无需 kit 密钥。

这两个 SDK 都可运行于浏览器和服务端应用中。在客户端代码中使用浏览器钱包提供程序适配器，并将私钥和 Circle Wallets 凭据保留在服务端。App Kit >=1.11.0 和 Bridge Kit >=1.12.2 可在浏览器中打包，无需使用者提供 Node 或 Buffer polyfill。

前提条件 / 设置

安装

选择一个基础 Kit——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

或者，对于仅需桥接功能的应用，可使用独立的 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 提供程序）-> 使用 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. 安装并初始化——安装所选 Kit 和适配器，然后构建 Kit 和适配器（参见“前提条件 / 设置”）。
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）。
• 适配器：App Kit 和 Bridge Kit 都使用适配器对象来抽象钱包／签名器差异。每个生态都有自己的适配器工厂（createViemAdapterFromPrivateKey、createSolanaKitAdapterFromPrivateKey、createCircleWalletsAdapter）。在同一生态内进行跨链转账时，同一个适配器实例可同时用作源端和目标端。
• 转发服务：在目标端设置 useForwarder: true 后，Circle 的基础设施会处理证明获取和提交铸币交易。这就不需要目标钱包或轮询循环。每笔转账都会收取费用，具体费用因路线而异（见下文）。
• 转账速度：CCTP 快速模式（默认）约需 8–20 秒。标准模式约需 15–19 分钟。
• 链标识符：在 kit.bridge() 调用中，两个 SDK 都使用字符串形式的链名称（例如 "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

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() 恢复失败的转账时，请阅读 references/forwarding-events-recovery.md，了解可运行的模式（包括 Bridge Kit 的事件名称差异）。

错误处理与恢复

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

• 严重错误会抛出异常（验证、配置、身份验证）——使用 try/catch 捕获。
• 软错误会在转账过程中发生，但仍会返回包含部分步骤数据的结果对象，以便恢复。发生软错误后，切勿从头重新运行 kit.bridge()——kit.retry(result, ...) 会从失败步骤继续执行，避免重复支出；完整模式见 references/forwarding-events-recovery.md。

规则

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

安全规则

• 绝不硬编码、提交或记录机密信息（私钥、API 密钥、实体机密、套件密钥）。始终使用环境变量或机密管理器。搭建项目时，在 .gitignore 中添加 .env* 和机密文件条目。
• 绝不在浏览器代码或公开环境变量（VITE_*、NEXT_PUBLIC_* 等）中放入私钥、Circle API 密钥、实体机密或套件密钥。
• 绝不在浏览器中导入 @circle-fin/adapter-circle-wallets 主入口；它需要服务端 Circle 凭据。
• 绝不通过纯文本 CLI 参数传递私钥。优先使用加密密钥库或交互式导入。
• 在执行跨链转账前，始终显示源链／目标链、收款方、金额和代币。在 UI 中，用户点击已启用的 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 Documentation
• Circle Developer Docs -- 查找源网站上的相关文档时，始终先阅读此文档。

替代方案

以下情况请改用 swap-tokens skill：

• 需要在同一条链上兑换代币（例如，从 USDT 兑换为 USDC）。
• 需要通过直接跨链兑换路由，将非 USDC 代币转移到其他链。

以下情况请改用 use-gateway skill：

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

---

免责声明：此 skill 按“原样”提供，不附带任何保证，并受 Circle Developer Terms 约束；生成的输出可能包含错误，和／或包含费用配置选项（包括向 Circle 收取的费用）；详情请参阅仓库中的 README。