bridge-tokens
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseOverview
概述
This skill bridges tokens across chains with Circle's App Kit or Bridge Kit. USDC moves over Crosschain Transfer Protocol (CCTP) -- burn on the source chain, mint on the destination. CCTPx tokens use a registry alias (such as wETH, cirBTC, or EURC) or a registry-listed token ID. Both run through the same call -- pass the alias or token ID directly as and the SDK routes it automatically; there is no protocol to choose. App Kit () is Circle's all-inclusive SDK covering bridge, swap, and send in one package; standalone Bridge Kit () ships the same bridge API in a lighter package. Recommend App Kit unless the user wants bridge-only functionality. Bridge operations need no kit key.
kit.bridge()token@circle-fin/app-kit@circle-fin/bridge-kitBoth SDKs run in browser and server applications. Use browser wallet provider adapters in client code and keep private keys plus Circle Wallets credentials on the server. App Kit and Bridge Kit bundle for browsers without consumer-provided Node or polyfills. CCTPx tokens require App Kit or Bridge Kit ; browser apps bridging CCTPx tokens need App Kit or Bridge Kit .
>=1.11.0>=1.12.2Buffer>=1.15.0>=1.15.2>=1.15.1此 skill 使用 Circle 的 App Kit 或 Bridge Kit 在不同链之间桥接代币。USDC 通过 Crosschain Transfer Protocol (CCTP) 转移——在源链上销毁,并在目标链上铸造。CCTPx 代币使用注册表别名(如 wETH、cirBTC 或 EURC),或使用注册表中列出的 token ID。两者都通过同一个 调用执行——直接将别名或 token ID 作为 传入,SDK 会自动选择相应路由;无需选择协议。App Kit()是 Circle 的一体化 SDK,在一个包中涵盖 bridge、swap 和 send;独立的 Bridge Kit()则在更轻量的包中提供相同的桥接 API。**除非用户只需要桥接功能,否则推荐 App Kit。**桥接操作无需 kit key。
kit.bridge()token@circle-fin/app-kit@circle-fin/bridge-kit两个 SDK 均可运行在浏览器和服务器应用中。在客户端代码中使用浏览器钱包 provider adapters,并将私钥及 Circle Wallets 凭据保存在服务器上。App Kit 和 Bridge Kit 的版本已内置浏览器所需的兼容能力,无需使用者提供 Node 或 polyfills。CCTPx 代币要求使用 App Kit 或 Bridge Kit ;在浏览器应用中桥接 CCTPx 代币时,需要 App Kit 或 Bridge Kit 。
>=1.11.0>=1.12.2Buffer>=1.15.0>=1.15.2>=1.15.1Supported tokens & routes
支持的代币与路由
Pass a registry alias or token ID directly as in and (App Kit) / (Bridge Kit); do not wrap it in a provider-selector object. The SDK routes it to the correct protocol automatically. Only USDC supports Solana; every CCTPx route is EVM-to-EVM. Aliases are case-sensitive (, not ), and a token ID is a bytes32 hex string ( followed by 64 hex characters).
tokenkit.bridge()kit.estimateBridge()kit.estimate()"wETH""WETH"0x| Token selector | Supported chains |
|---|---|
| All CCTP-supported chains (EVM + Solana) -- see supported chains |
| Ethereum, Base, and Arc on mainnet, plus eligible testnet routes |
| Ethereum <-> Arc on mainnet, plus eligible testnet routes |
| Ethereum <-> Arc on mainnet, plus eligible testnet routes |
| Registry-listed token ID | Any EVM route where the CCTPx registry lists that token on both endpoint domains |
CCTPx-enabled EVM chains are Ethereum, Arc, Base, Arbitrum, Optimism, Polygon, and Avalanche. A chain being CCTPx-enabled does not make every token routable to every other chain. The SDK fetches the CCTPx token registry from Circle at runtime and throws when the selected token is not listed on both endpoints -- do not hardcode route lists.
INPUT_UNSUPPORTED_ROUTE在 和 (App Kit)/ (Bridge Kit)的 参数中直接传入注册表别名或 token ID;不要将其包装在 provider-selector 对象中。SDK 会自动将其路由到正确的协议。仅 USDC 支持 Solana;所有 CCTPx 路由均为 EVM 到 EVM。别名区分大小写(,而不是 ),token ID 是一个 bytes32 十六进制字符串(以 开头,后跟 64 个十六进制字符)。
kit.bridge()kit.estimateBridge()kit.estimate()token"wETH""WETH"0x| 代币选择器 | 支持的链 |
|---|---|
| 所有 CCTP 支持链(EVM + Solana)——参见支持的链 |
| 以太坊、Base 和 Arc 主网,以及符合条件的测试网路由 |
| 以太坊 <-> Arc 主网,以及符合条件的测试网路由 |
| 以太坊 <-> Arc 主网,以及符合条件的测试网路由 |
| 注册表中列出的 token ID | 任意 EVM 路由,其中 CCTPx 注册表在两个端点域上均列出了该代币 |
支持 CCTPx 的 EVM 链包括 Ethereum、Arc、Base、Arbitrum、Optimism、Polygon 和 Avalanche。某条链支持 CCTPx,并不意味着每个代币都能桥接到其他任意链。SDK 会在运行时从 Circle 获取 CCTPx 代币注册表;当所选代币未在两个端点上列出时,会抛出 ——不要硬编码路由列表。
INPUT_UNSUPPORTED_ROUTEPrerequisites / Setup
前提条件 / 设置
Installation
安装
Pick one base kit — App Kit (recommended) or the standalone Bridge Kit — then add adapters as needed.
App Kit with Viem adapter (recommended):
bash
npm install @circle-fin/app-kit @circle-fin/adapter-viem-v2选择一个基础 kit——App Kit(推荐)或独立的 Bridge Kit——然后根据需要添加 adapters。
使用 Viem adapter 的 App Kit(推荐):
bash
npm install @circle-fin/app-kit @circle-fin/adapter-viem-v2Optional: Solana support
Optional: Solana support
npm install @circle-fin/adapter-solana-kit
npm install @circle-fin/adapter-solana-kit
Optional: Circle Wallets (developer-controlled) support
Optional: Circle Wallets (developer-controlled) support
npm install @circle-fin/adapter-circle-wallets
Or, for bridge-only apps, the standalone Bridge Kit (lighter package) instead of App Kit:
```bash
npm install @circle-fin/bridge-kit @circle-fin/adapter-viem-v2npm install @circle-fin/adapter-circle-wallets
或者,对于只需要桥接功能的应用,可以改用更轻量的独立版 Bridge Kit,而不是 App Kit:
```bash
npm install @circle-fin/bridge-kit @circle-fin/adapter-viem-v2Environment Variables
环境变量
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 addressNo is needed for bridge operations. Browser-wallet integrations need none of the variables above. Never expose a private key, Circle API key, entity secret, or optional App Kit credential to client code.
KIT_KEYPRIVATE_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桥接操作不需要 。浏览器钱包集成也不需要上述任何变量。切勿将私钥、Circle API key、entity secret 或可选的 App Kit 凭据暴露给客户端代码。
KIT_KEYSDK Initialization
SDK 初始化
App Kit (recommended):
ts
import { AppKit } from "@circle-fin/app-kit";
const kit = new AppKit();Bridge Kit (standalone):
ts
import { BridgeKit } from "@circle-fin/bridge-kit";
const kit = new BridgeKit();App Kit(推荐):
ts
import { AppKit } from "@circle-fin/app-kit";
const kit = new AppKit();Bridge Kit(独立版):
ts
import { BridgeKit } from "@circle-fin/bridge-kit";
const kit = new BridgeKit();Decision Guide
决策指南
ALWAYS walk through these questions with the user before writing any code. Do not skip steps or assume answers.
编写任何代码前,务必与用户逐一讨论以下问题。不要跳过步骤,也不要假设答案。
SDK Choice
SDK 选择
Question 1 -- Will you need swap or send functionality in the future?
- Yes, or unsure -> App Kit (recommended) -- single SDK covers bridge + swap + send, easier to extend later
- No, bridge-only and will never need swap or send -> Bridge Kit -- standalone, lighter package for bridge-only use cases
问题 1 -- 未来是否需要 swap 或 send 功能?
- 是,或尚不确定 -> App Kit(推荐)——单个 SDK 涵盖 bridge + swap + send,便于以后扩展
- 否,仅需 bridge,且永远不会需要 swap 或 send -> Bridge Kit——独立且轻量,适合纯桥接用例
Wallet / Adapter Choice
钱包 / Adapter 选择
Question 2 -- How do you manage your wallet/keys?
- Managing your own private key (self-custodied, stored in env var or secrets manager) -> Question 3
- Using Circle developer-controlled wallets (Circle manages key storage and signing) -> Use Circle Wallets adapter. READ
references/adapter-circle-wallets.md - Using an EVM browser wallet (wagmi, ConnectKit, RainbowKit, or any EIP-1193 provider) -> Use the Viem provider adapter. READ
references/adapter-wagmi.md - Using a Solana browser wallet (Wallet Standard provider such as Phantom, Solflare, or Backpack) -> Use the Solana provider adapter. READ
references/adapter-browser-wallet.md
Question 3 -- Which chains are you bridging between?
- EVM-to-EVM or EVM-to-Solana -> Use Viem and/or Solana Kit adapters. READ
references/adapter-private-key.md
问题 2 -- 如何管理你的钱包/密钥?
- 管理自己的私钥(自托管,存储在环境变量或 secrets manager 中)-> 进入问题 3
- 使用 Circle developer-controlled wallets(由 Circle 管理密钥存储和签名)-> 使用 Circle Wallets adapter。阅读
references/adapter-circle-wallets.md - 使用 EVM 浏览器钱包(wagmi、ConnectKit、RainbowKit 或任意 EIP-1193 provider)-> 使用 Viem provider adapter。阅读
references/adapter-wagmi.md - 使用 Solana 浏览器钱包(Wallet Standard provider,例如 Phantom、Solflare 或 Backpack)-> 使用 Solana provider adapter。阅读
references/adapter-browser-wallet.md
问题 3 -- 要在哪些链之间进行桥接?
- EVM 到 EVM,或 EVM 到 Solana -> 使用 Viem 和/或 Solana Kit adapters。阅读
references/adapter-private-key.md
Token Choice
代币选择
Question 4 -- Which token are you bridging?
- USDC -> any CCTP route (EVM or Solana).
- wETH, cirBTC, EURC, or a CCTPx token ID -> EVM-to-EVM only. READ . If the destination is Solana or the registry does not list the route, stop and offer
references/non-usdc-cctpx.md; do not substitute a different chain pair.swap-tokens
问题 4 -- 要桥接哪种代币?
- USDC -> 任意 CCTP 路由(EVM 或 Solana)。
- wETH、cirBTC、EURC 或 CCTPx token ID -> 仅限 EVM 到 EVM。阅读 。如果目标链是 Solana,或注册表中未列出该路由,请停止流程并建议使用
references/non-usdc-cctpx.md;不要替换为其他链组合。swap-tokens
Workflow
工作流
- Walk the Decision Guide -- settle the SDK (App Kit vs Bridge Kit) and the wallet/adapter with the user before writing any code.
- Install and initialize -- install the chosen kit plus adapter, then construct the kit and adapter (see Prerequisites / Setup).
- Confirm the transfer -- token, amount, source and destination chains, and recipient. Validate chain names and addresses. Default to testnet; require explicit confirmation before mainnet.
- For CCTPx tokens, quote first -- confirm that the registry supports the selected EVM route, settle vs
FASTwith the user, callSLOW(App Kit) orkit.estimateBridge()(Bridge Kit), and surface the quoted fee before executing. Quote reuse is best-effort: surface akit.estimate()warning on the result.QUOTE_NOT_REUSED - Execute the bridge -- call , only from an explicit user action (never auto-invoke). READ the adapter reference for the exact code.
kit.bridge({ token, from, to, amount, ... }) - Track and recover -- inspect /
result.state, subscribe withresult.steps, and on a soft failure resume withkit.on()(App Kit) orkit.retryBridge(result, ...)(Bridge Kit) -- never re-runkit.retry(result, ...)from scratch.kit.bridge()
- 完成决策指南——在编写任何代码前,与用户确定 SDK(App Kit 或 Bridge Kit)以及钱包/adapter。
- 安装并初始化——安装所选 kit 和 adapter,然后创建 kit 与 adapter(参见“前提条件 / 设置”)。
- 确认转账——确认代币、金额、源链、目标链和收款地址。验证链名称和地址。默认使用测试网;使用主网前必须取得明确确认。
- 对于 CCTPx 代币,先获取报价——确认注册表支持所选 EVM 路由,与用户确定 或
FAST,调用SLOW(App Kit)或kit.estimateBridge()(Bridge Kit),并在执行前向用户展示报价费用。报价复用属于尽力而为:如果结果中出现kit.estimate()警告,应将其展示给用户。QUOTE_NOT_REUSED - 执行桥接——调用 ,且仅可在用户明确操作时调用(绝不要自动调用)。阅读 adapter 参考文档以获取准确代码。
kit.bridge({ token, from, to, amount, ... }) - 跟踪与恢复——检查 /
result.state,使用result.steps订阅事件;发生软失败时,使用kit.on()(App Kit)或kit.retryBridge(result, ...)(Bridge Kit)恢复——绝不要从头重新运行kit.retry(result, ...)。kit.bridge()
Core Concepts
核心概念
- CCTP steps (USDC): Every USDC bridge transfer executes four sequential steps -- (ERC-20 allowance),
approve(destroy USDC on source chain),burn(wait for Circle to sign the burn proof), andfetchAttestation(create USDC on destination chain).mint - CCTPx transfers: the same call; pass a registry alias or token ID directly as
kit.bridge({ token, from, to, amount }). The steps aretoken, with anapprove -> transfer -> fetchAttestation -> forwardstep beforeapproveFeeonly when the fee is an ERC-20 (Circle's relayer mints on the destination automatically -- no destination gas ortransfertoggle needed). Every CCTPx transfer pays a relayer fee in the source chain's native token;useForwarder(default) adds a pre-finality fee, whileFASTwaits for source-chain finality and skips it. CallSLOW(App Kit) orkit.estimateBridge()(Bridge Kit) first and surface the quoted fee to the user before bridging; the bridge call stays behind the user's explicit confirm action. Checkkit.estimate()for completion. CCTPx routes reject custom fees,result.state === "success", andfeePayment: "destination".useForwarder: false - Adapters: Both App Kit and Bridge Kit use adapter objects to abstract wallet/signer differences. Each ecosystem has its own adapter factory (,
createViemAdapterFromPrivateKey,createSolanaKitAdapterFromPrivateKey). The same adapter instance can serve as both source and destination when bridging within the same ecosystem.createCircleWalletsAdapter - Forwarding Service: When is set on the destination, Circle's infrastructure handles attestation fetching and mint submission. This removes the need for a destination wallet or polling loop. There is a per-transfer fee that varies by route (see below).
useForwarder: true - Transfer speed: CCTP fast mode (default) completes in ~8-20 seconds. Standard mode takes ~15-19 minutes.
- Chain identifiers: Both SDKs use string chain names (e.g., ,
"Arc","Arc_Testnet","Base_Sepolia"), not numeric chain IDs, in the"Solana_Devnet"call.kit.bridge() - Browser-safe packages: Current App Kit, Bridge Kit, and Solana adapters ship the required browser compatibility internally. Browser requests omit Node-only headers, and Solana operations need no consumer shim. Upgrade stale packages instead of adding polyfills.
Buffer
- CCTP 步骤(USDC):每次 USDC 桥接转账都会依次执行四个步骤——(ERC-20 allowance)、
approve(在源链上销毁 USDC)、burn(等待 Circle 为销毁证明签名)和fetchAttestation(在目标链上创建 USDC)。mint - CCTPx 转账:使用相同的 调用;直接将注册表别名或 token ID 作为
kit.bridge({ token, from, to, amount })传入。步骤依次为token,且仅当费用为 ERC-20 时,才会在approve -> transfer -> fetchAttestation -> forward之前增加transfer步骤(Circle 的 relayer 会在目标链上自动铸造——无需目标链 gas,也无需设置approveFee)。每笔 CCTPx 转账都需要使用源链原生代币支付 relayer 费用;默认的useForwarder会增加预最终确认费,而FAST会等待源链达到最终确定性,因此不收取该费用。桥接前先调用SLOW(App Kit)或kit.estimateBridge()(Bridge Kit),并将报价费用展示给用户;bridge 调用必须置于用户明确确认操作之后。完成时检查kit.estimate()。CCTPx 路由不支持自定义费用、result.state === "success"和feePayment: "destination"。useForwarder: false - Adapters:App Kit 和 Bridge Kit 均使用 adapter 对象来抽象钱包/signer 之间的差异。每个生态系统都有自己的 adapter factory(、
createViemAdapterFromPrivateKey、createSolanaKitAdapterFromPrivateKey)。在同一生态系统内进行桥接时,同一个 adapter 实例可同时作为源端和目标端。createCircleWalletsAdapter - Forwarding Service:在目标端设置 时,由 Circle 的基础设施处理 attestation 获取和 mint 提交。这样无需目标链钱包或轮询循环。每次转账都会收取费用,费用因路由而异(参见下文)。
useForwarder: true - 转账速度:CCTP 快速模式(默认)约需 8-20 秒。标准模式约需 15-19 分钟。
- 链标识符:两个 SDK 在 调用中都使用字符串链名称(例如
kit.bridge()、"Arc"、"Arc_Testnet"、"Base_Sepolia"),而不是数字 chain ID。"Solana_Devnet" - 浏览器兼容包:当前版本的 App Kit、Bridge Kit 和 Solana adapters 已内置所需的浏览器兼容能力。浏览器请求会省略 Node 专用标头,Solana 操作也不需要使用者提供 shim。应升级过时的包,而不是添加 polyfills。
Buffer
Implementation Patterns
实现模式
READ the corresponding reference based on the user's request:
- -- EVM-to-EVM and EVM-to-Solana bridging with private key adapters (Viem + Solana Kit). Includes App Kit and Bridge Kit examples.
references/adapter-private-key.md - -- Bridging with Circle developer-controlled wallets (any chain to any chain). Includes App Kit and Bridge Kit examples.
references/adapter-circle-wallets.md - -- Browser wallet integration using wagmi (ConnectKit, RainbowKit, etc.). Includes App Kit and Bridge Kit examples.
references/adapter-wagmi.md - -- Solana browser wallet integration using a Wallet Standard provider, with no manual polyfills
references/adapter-browser-wallet.md - -- bridging CCTPx registry aliases and token IDs on supported EVM routes: route validation, quote-then-confirm flow, and FAST/SLOW transfer speed
references/non-usdc-cctpx.md
请根据用户请求阅读相应的参考文档:
- ——使用私钥 adapters(Viem + Solana Kit)在 EVM 到 EVM、EVM 到 Solana 之间进行桥接。包含 App Kit 和 Bridge Kit 示例。
references/adapter-private-key.md - ——使用 Circle developer-controlled wallets 在任意链之间进行桥接。包含 App Kit 和 Bridge Kit 示例。
references/adapter-circle-wallets.md - ——使用 wagmi(ConnectKit、RainbowKit 等)集成浏览器钱包。包含 App Kit 和 Bridge Kit 示例。
references/adapter-wagmi.md - ——使用 Wallet Standard provider 集成 Solana 浏览器钱包,无需手动添加 polyfills。
references/adapter-browser-wallet.md - ——在受支持的 EVM 路由上桥接 CCTPx 注册表别名和 token ID:包括路由验证、先报价后确认流程,以及 FAST/SLOW 转账速度。
references/non-usdc-cctpx.md
Sample Response from kit.bridge()
kit.bridge() 的示例响应
json
{
"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..."
}
]
}json
{
"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..."
}
]
}Forwarding Service, events, and recovery
Forwarding Service、事件与恢复
When the task uses (no destination wallet / no attestation polling), subscribes to bridge events via , or needs to analyze and resume a failed transfer with (App Kit) / (Bridge Kit), READ for the runnable patterns (including the Bridge Kit event-name difference).
useForwarder: truekit.on()kit.retryBridge()kit.retry()references/forwarding-events-recovery.md当任务使用 (无需目标链钱包或 attestation 轮询)、通过 订阅桥接事件,或需要分析并恢复失败的转账(使用 (App Kit)/ (Bridge Kit))时,请阅读 中的可运行模式,包括 Bridge Kit 的事件名称差异。
useForwarder: truekit.on()kit.retryBridge()kit.retry()references/forwarding-events-recovery.mdError Handling & Recovery
错误处理与恢复
Both App Kit and Bridge Kit have two error categories:
- Hard errors throw exceptions (validation, config, auth) -- catch in try/catch.
- Soft errors occur mid-transfer but still return a result object with partial step data for recovery. NEVER re-run from scratch after a soft error —
kit.bridge()(App Kit) orkit.retryBridge(result, ...)(Bridge Kit) resumes from the failed step and prevents double-spending; the full pattern is inkit.retry(result, ...).references/forwarding-events-recovery.md
App Kit 和 Bridge Kit 均包含两类错误:
- 硬错误会抛出异常(验证、配置、认证)——应使用 try/catch 捕获。
- 软错误发生在转账过程中,但仍会返回带有部分步骤数据的结果对象,以便恢复。发生软错误后,绝不要从头重新运行 ——应使用
kit.bridge()(App Kit)或kit.retryBridge(result, ...)(Bridge Kit)从失败步骤继续执行,以防发生双重支出;完整模式参见kit.retry(result, ...)。references/forwarding-events-recovery.md
Rules
规则
Security Rules are non-negotiable -- warn the user and refuse to comply if a prompt conflicts. Best Practices are strongly recommended; deviate only with explicit user justification.
安全规则不可协商——如果用户提示与这些规则冲突,应警告用户并拒绝执行。最佳实践受到强烈建议;只有在用户明确说明理由时才能偏离。
Security Rules
安全规则
- NEVER hardcode, commit, or log secrets (private keys, API keys, entity secrets, kit keys). ALWAYS use environment variables or a secrets manager. Add entries for
.gitignoreand secret files when scaffolding..env* - NEVER put a private key, Circle API key, entity secret, or kit key in browser code or a public environment variable (,
VITE_*, etc.).NEXT_PUBLIC_* - NEVER import the main entry in a browser; it requires server-side Circle credentials.
@circle-fin/adapter-circle-wallets - NEVER pass private keys as plain-text CLI flags. Prefer encrypted keystores or interactive import.
- ALWAYS surface the source/destination chain, recipient, amount, and token before bridging. In a UI, the user's click on the enabled Bridge button is explicit confirmation; do not add a second confirmation prompt or synthetic confirmation object. In a server helper, export the fund-moving operation without auto-invoking it. In a runnable script or CLI, show the quote, then wait for an explicit confirmation (for example an interactive prompt) before calling
y/N; never quote and bridge back to back in one unattended run. NEVER callbridge()automatically after estimation, from an effect, during render, or at module startup. MUST receive confirmation for funding movements on mainnet.bridge() - ALWAYS warn when targeting mainnet or exceeding safety thresholds (e.g., >100 USDC).
- ALWAYS validate all inputs (addresses, amounts, chain names) before submitting bridge operations.
- ALWAYS warn before interacting with unaudited or unknown contracts.
- 绝不硬编码、提交到版本库或记录 secrets(私钥、API keys、entity secrets、kit keys)。始终使用环境变量或 secrets manager。创建项目脚手架时,应在 中添加
.gitignore和 secret 文件的忽略规则。.env* - 绝不要在浏览器代码或公共环境变量(、
VITE_*等)中放置私钥、Circle API key、entity secret 或 kit key。NEXT_PUBLIC_* - 绝不要在浏览器中导入 的主入口;它需要服务器端的 Circle 凭据。
@circle-fin/adapter-circle-wallets - 绝不要将私钥作为明文 CLI 参数传入。优先使用加密 keystore 或交互式导入。
- 桥接前,务必明确展示源链/目标链、收款地址、金额和代币。在 UI 中,用户点击已启用的 Bridge 按钮即构成明确确认;不要添加第二次确认提示或合成 confirmation object。在服务端 helper 中,应导出资金转移操作,但不要自动调用。在可运行脚本或 CLI 中,应先展示报价,然后等待明确确认(例如交互式 提示),再调用
y/N;在一次无人值守的运行中,绝不能连续执行报价和桥接。绝不要在估算后自动调用bridge(),也不要在 effect 执行期间、render 期间或模块启动时调用。对于主网上的资金转移,必须取得确认。bridge() - 当目标是主网或金额超过安全阈值(例如 >100 USDC)时,务必发出警告。
- 提交桥接操作前,务必验证所有输入(地址、金额、链名称)。
- 与未经审计或未知合约交互前,务必发出警告。
Best Practices
最佳实践
- ALWAYS walk the user through the Decision Guide questions before writing any code. Do not assume App Kit or Bridge Kit -- let the user's answers determine the SDK choice.
- ALWAYS read the correct reference files before implementing.
- For browser apps, require browser-safe package versions, use provider-based adapters, and do not add Node/polyfills.
Buffer - ALWAYS switch the wallet to the source chain before calling with browser wallets (wagmi/ConnectKit/RainbowKit) if the Forwarding Service is NOT used.
kit.bridge() - ALWAYS wrap bridge operations in try/catch and save the result object for recovery. Check before retrying to see which steps completed.
result.steps - ALWAYS use exponential backoff for retry logic in production.
- ALWAYS use string chain names (e.g., ,
"Arc","Arc_Testnet"), not numeric chain IDs."Base_Sepolia" - ALWAYS default to testnet. Require explicit user confirmation before targeting mainnet.
- ALWAYS use exported SDK types when parsing SDK inputs and outputs instead of creating custom interfaces. This minimizes type errors.
- 编写任何代码前,务必与用户逐一完成决策指南中的问题。不要自行决定使用 App Kit 或 Bridge Kit——应根据用户的回答确定 SDK。
- 实现前,务必阅读正确的参考文档。
- 对于浏览器应用,要求使用具备浏览器兼容性的包版本、基于 provider 的 adapters,并且不要添加 Node/polyfills。
Buffer - 使用浏览器钱包(wagmi/ConnectKit/RainbowKit)时,如果未使用 Forwarding Service,务必在调用 前将钱包切换到源链。
kit.bridge() - 务必使用 try/catch 包裹桥接操作,并保存结果对象以便恢复。重试前检查 ,以确定哪些步骤已经完成。
result.steps - 生产环境中的重试逻辑务必使用指数退避。
- 务必使用字符串链名称(例如 、
"Arc"、"Arc_Testnet"),而不是数字 chain ID。"Base_Sepolia" - 务必默认使用测试网。切换到主网前必须取得用户明确确认。
- 解析 SDK 输入和输出时,务必使用 SDK 导出的类型,而不是创建自定义 interfaces。这样可以最大限度减少类型错误。
Reference Links
参考链接
- Circle App Kit SDK
- Circle Bridge Kit SDK
- CCTP Documentation
- Circle Developer Docs -- Always read this first when looking for relevant documentation from the source website.
- Circle App Kit SDK
- Circle Bridge Kit SDK
- CCTP 文档
- Circle 开发者文档——从源网站查找相关文档时,务必先阅读此文档。
Alternatives
替代方案
Trigger the skill instead when:
swap-tokens- You need to swap tokens (e.g., USDT to USDC) on the same chain.
- You need to move a token across chains that this skill does not bridge directly. This skill bridges USDC across CCTP chains and CCTPx aliases or token IDs on their registry-supported EVM routes; can route other tokens or chains via a cross-chain swap.
swap-tokens
Trigger the skill instead when:
use-gateway- You want a unified crosschain balance rather than point-to-point transfers.
- Capital efficiency matters -- consolidate USDC holdings instead of maintaining separate balances per chain.
- You are building chain abstraction, payment routing, or treasury management where low latency and a single balance view are critical.
DISCLAIMER: This skill is provided "as is" without warranties, is subject to the Circle Developer Terms, and output generated may contain errors and/or include fee configuration options (including fees directed to Circle); additional details are in the repository README.
出现以下情况时,改为触发 skill:
swap-tokens- 需要在同一链上交换代币(例如将 USDT 换为 USDC)。
- 需要在当前 skill 无法直接桥接的链之间移动代币。当前 skill 可在 CCTP 链之间桥接 USDC,并可在注册表支持的 EVM 路由上桥接 CCTPx 别名或 token ID;可以通过跨链 swap 为其他代币或链寻找路由。
swap-tokens
出现以下情况时,改为触发 skill:
use-gateway- 想要统一的跨链余额,而不是点对点转账。
- 资本效率很重要——希望整合 USDC 持仓,而不是在每条链上分别维护余额。
- 正在构建链抽象、支付路由或资金管理功能,并且对低延迟和统一余额视图有严格要求。
免责声明:本 skill 按“原样”提供,不附带任何保证,并受 Circle Developer Terms 约束;生成的结果可能包含错误和/或费用配置选项(包括指向 Circle 的费用);更多细节请参阅仓库中的 README。