# @circle-fin/provider-cctp-v2 中文文档 规范地址：https://npmcn.com/package/%40circle-fin/provider-cctp-v2/ 版本：1\.14\.6 npm 元数据更新时间：2026-11-05T17:18:18.526Z 中文译文更新时间：2026-11-09T16:34:19.204Z 软件包许可：未声明 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40circle-fin/provider-cctp-v2 原文对照：https://npmcn.com/package/%40circle-fin/provider-cctp-v2/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：2.4 MB，11 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=20\.0\.0 - 运行依赖：12 个 - peer 依赖：@solana/web3\.js ^1\.98\.2 - 首次发布：2025-08-26T13:05:30.528Z - 最新版本发布：2026-11-05T17:18:18.298Z - 近 30 天下载量：57469（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：40（近 12 个月 35 个） ## 中文简介 Circle官方的Cross-Chain 传输协议 v2 本地 UDC 桥接供应商 ## 安装 ```sh npm install @circle-fin/provider-cctp-v2 ``` 也可以使用：`pnpm add @circle-fin/provider-cctp-v2`、`yarn add @circle-fin/provider-cctp-v2`、`bun add @circle-fin/provider-cctp-v2` ## README # CCTPv2 连接提供者 [![npm version](https://badge.fury.io/js/@circle-fin%2Fprovider-cctp-v2.svg)](https://badge.fury.io/js/@circle-fin%2Fprovider-cctp-v2) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Discord](https://img.shields.io/discord/473781666251538452?label=Discord&logo=discord)](https://discord.com/invite/buildoncircle) **Circle 的 Cross- Chin 传输协议 v2 桥 Kit 供应商** _使用Circle的战斗测试协议 跨越52个链条的本地USDC连接._ ## 目录 - [CCTPv2 连接提供者](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-cctpv2-bridging-provider) - [目录](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-table-of-contents) - [概览](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-overview) - [为什么是CCTPv2供应商?](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-why-cctpv2-provider) - [安装](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-installation) - [快速启动](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-quick-start) - [备选案文1:带桥套(建议)](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-option-1-with-bridge-kit-recommended) - [备选案文2:直接提供者的使用](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-option-2-direct-provider-usage) - [特征](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-features) - [支持的链路( R)](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-supported-chains--routes) - [主网链](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-mainnet-chains) - [测试网链](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-testnet-chains) - [处理错误](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-error-handling) - [桥梁进程](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-bridge-process) - [转发器集成](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-forwarder-integration) - [有转发器的标准桥](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-standard-bridge-with-forwarder) - [仅转发目标](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-forwarder-only-destination) - [中继费处理](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-relay-fee-handling) - [与桥基合并](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-integration-with-bridge-kit) - [发展](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-development) - [许可证](https://npmcn.com/package/%40circle-fin/provider-cctp-v2/#readme-license) ## 概览 CCTPv2 搭桥提供商是Circle's Cross-Chain Transfer Protocol(CCTP)版本2的强型执行,该版本使得 **本地USDC 连接** 在49个支持的区块链网络之间. 虽然主要设计为电力 [桥套](https://www.npmjs.com/package/@circle-fin/bridge-kit),该提供者也可以使用 **直接在应用程序中** 需要精细控制 CCTP 传输过程或想要整合 CCTP 没有完整的 App Kits 框架. ### 为什么是CCTPv2供应商? - **QQ Circle 的官方协议**: 使用 Circle 本地的 CCTP 基础设施以达到最大安全性 - **51个链式支持**: 启用连接所有 CCTPv2 支持的网络 - **原产地 USDC**: 桥梁 实际USDC 令牌,非包裹或合成版本 - **\* 类型安全操作**: 建有 TypeScript 严格模式并全面验证 - **\* 直接融合**: 使用独立或自定义的管弦逻辑 ## 安装 ```bash npm install @circle-fin/provider-cctp-v2 # or yarn add @circle-fin/provider-cctp-v2 ``` > **说明**: 默认情况下包含此提供者 [桥套](https://www.npmjs.com/package/@circle-fin/bridge-kit)。如果需要进行自定义的 CCTP 集成,可以导入此提供者. ## 快速启动 ### 备选案文1:带桥套(建议) ```typescript import { BridgeKit } from '@circle-fin/bridge-kit' // Provider included by default const kit = new BridgeKit() const result = await kit.bridge({ from: { adapter: sourceAdapter, chain: 'Ethereum' }, to: { adapter: destAdapter, chain: 'Base' }, amount: '100.50', }) ``` ### 备选案文2:直接提供者的使用 ```typescript import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2' import { ViemAdapter } from '@circle-fin/adapter-viem-v2' import { createPublicClient, createWalletClient, http } from 'viem' import { mainnet, base } from 'viem/chains' import { privateKeyToAccount } from 'viem/accounts' const account = privateKeyToAccount(process.env.PRIVATE_KEY) const provider = new CCTPV2BridgingProvider() // Create adapters const sourceAdapter = new ViemAdapter({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), walletClient: createWalletClient({ account, chain: mainnet, transport: http(), }), }) const destAdapter = new ViemAdapter({ publicClient: createPublicClient({ chain: base, transport: http() }), walletClient: createWalletClient({ account, chain: base, transport: http() }), }) // Check route support const isSupported = provider.supportsRoute('Ethereum', 'Base', 'USDC') // Get bridge estimate const estimate = await provider.estimate({ from: { adapter: sourceAdapter, chain: 'Ethereum' }, to: { adapter: destAdapter, chain: 'Base' }, amount: '100.50', config: { transferSpeed: 'FAST' }, }) // Execute bridge operation with custom logic const result = await provider.bridge({ from: { adapter: sourceAdapter, chain: 'Ethereum' }, to: { adapter: destAdapter, chain: 'Base' }, amount: '100.50', config: { transferSpeed: 'FAST' }, }) ``` ## 特征 - ✅ **原生的 USDC 桥接** - 在所支持的网络之间移动真正的USDC - ✅ **CCTP v2 集成** - 直接与 Circle 的 CCTP v2 协议合并 - ✅ **全面审定** - 路线验证和参数检查 - ✅ **多链支持** - 跨越所有52个CCTPv2支持链的工作 - ✅ **类型安全** - 包含详细错误处理的完整类型脚本支持 - ✅ **桥速** - 支持FAST和SLOW桥的配置 - ✅ **转发器集成** - 圆形轨道中继器自动处理验证和薄荷 - ✅ **仅转发目的地** - 不需要目的地适配器 ## 支持的链路( R) 提供者支持 **1300条桥梁路线总数** 跨越这些链条: ### 主网链 **坐标**, (中文(简体) ), **弧形**, (中文(简体) ), **雪崩**, (中文(简体) ), **基础**, (中文(简体) ), **代码**, (中文(简体) ), **克罗诺斯**, (中文(简体) ), **边缘**, (中文(简体) ), **以利亚**, (中文(简体) ), **超高频**, (中文(简体) ), **注射**, (中文(简体) ), **墨迹**, (中文(简体) ), **线性a**, (中文(简体) ), **修道院**, (中文(简体) ), **墨菲语**, (中文(简体) ), **OP 主要网**, (中文(简体) ), **法罗**, (中文(简体) ), **等离子体**, (中文(简体) ), **弹珠**, (中文(简体) ), **多边形 PoS**, (中文(简体) ), **谢**, (中文(简体) ), **索拉纳**, (中文(简体) ), **音响**, (中文(简体) ), **单链**, (中文(简体) ), **世界链**, (中文(简体) ), **XDC 数据交换中心**, (中文(简体) ), **X 层** ### 测试网链 **弧度测试网**, (中文(简体) ), **塞波利亚角**, (中文(简体) ), **富士雪崩**, (中文(简体) ), **塞波利亚基地**, (中文(简体) ), **代码测试网**, (中文(简体) ), **克罗诺斯测试网**, (中文(简体) ), **边缘测试网**, (中文(简体) ), **伊特鲁姆·塞波利亚**, (中文(简体) ), **超高频 测试网**, (中文(简体) ), **注射测试网**, (中文(简体) ), **墨子测试网**, (中文(简体) ), **塞波利亚线**, (中文(简体) ), **莫纳德测试网**, (中文(简体) ), **墨菲测试网**, (中文(简体) ), **OP 塞波利亚**, (中文(简体) ), **大西洋**, (中文(简体) ), **Plasma 测试网**, (中文(简体) ), **Plume 测试网**, (中文(简体) ), **多边形 PoS 模拟**, (中文(简体) ), **塞试网**, (中文(简体) ), **索拉纳·德夫内**, (中文(简体) ), **音效测试网**, (中文(简体) ), **单链塞波利亚**, (中文(简体) ), **世界链塞波利亚**, (中文(简体) ), **XDC 阿波瑟**, (中文(简体) ), **X 层测试网** ## 处理错误 提供者对不同的情景进行深思熟虑的错误处理: ```typescript // Using the same kit and adapters from the examples above const params = { from: { adapter: sourceAdapter, chain: 'Ethereum' }, to: { adapter: destAdapter, chain: 'Base' }, amount: '100.50', } try { const result = await provider.bridge(params) if (result.state === 'success') { console.log('Bridge completed successfully!') // Display explorer URLs for each step result.steps.forEach((step) => { if (step.explorerUrl) { console.log(`${step.name}: ${step.explorerUrl}`) } }) } else { // Handle partial completion const successfulSteps = result.steps.filter((s) => s.state === 'success') const failedStep = result.steps.find((s) => s.state === 'error') console.log('Successful steps:', successfulSteps) console.log('Failed at:', failedStep) } } catch (error) { // Handle validation or configuration errors console.error('Bridge failed:', error.message) } ``` ## 桥梁进程 CCTPv2供应商处理完整的跨链接通流: 1. **核准** - 核准USDC支出(如有需要) 2. **燃烧** - 通过源链焚烧USDC `depositForBurn` 3. **证明** - 把圆圈的证明拿来 4. **薄荷** - 使用证明书制作目的地链上的薄荷USDC 每一步都经过跟踪,可以通过提供商的活动系统进行监测. 每个步骤的交易细节包括探索者URL,以方便区块探索者验证. > **与转发器**: 当 `useForwarder: true`,则目的地薄荷呈文由 Circle's Orbit中继器,而中继费则从薄荷金额中扣除. ## 转发器集成 CCTPv2供应商支持Circle的轨道中继器进行自动验证和薄荷处理. 启用后,中继器会自动获取证明并提交薄荷交易, 取消了用户管理目的地链交易的需要. 您可以明确检查转发器路由支持 : ```typescript const canForward = provider.supportsRoute( 'Ethereum, 'Base, 'USDC', true, ) ``` ### 有转发器的标准桥 使用 `useForwarder: true` 当您有两条链子的适配器, 但想要圆形处理薄荷时: ```typescript const result = await kit.bridge({ from: { adapter: sourceAdapter, chain: 'Ethereum' }, to: { adapter: destAdapter, chain: 'Base', useForwarder: true, // Circle handles attestation + mint }, amount: '100.50', }) ``` ### 仅转发目标 当无法访问目的地链(没有钱包/适应器)时,只使用转发器模式. 这对服务器侧传输或用户在目的地链上没有钱包时有用: ```typescript const result = await kit.bridge({ from: { adapter: sourceAdapter, chain: 'Ethereum' }, to: { recipientAddress: '0x...', // Where to receive USDC chain: 'Base', useForwarder: true, // Required for forwarder-only }, amount: '100.50', }) ``` **与标准连接的关键区别 :** - 不需要目标适配器 - 通过IRIS API确认薄荷(不是链上接收) - 薄荷步骤 `data` 字段将会是 `undefined` ### 中继费处理 使用转发器时,在 `maxFee` 估计数: - 中继费来自 Circle 的 API , 其来源/ 目的地链 - 在薄荷时间从薄荷USDC中扣除费用 - 收到净额=燃烧额 -- -- 中继费 费用估算会自动说明: ```typescript const estimate = await provider.estimate({ from: { adapter: sourceAdapter, chain: 'Ethereum' }, to: { recipientAddress: '0x...', chain: 'Base', useForwarder: true, }, amount: '100.50', }) console.log(estimate.fees) // Includes both provider and forwarder fee entries ``` > 如果你提供 `config.maxFee` 手动确保它已经包含任何预期 选定路线和速度的转发器费用。 对于索拉纳目的地 转发费还包括创建收款人USDC代币账户. ## 与桥基合并 此提供者是专门为 [桥套](https://www.npmjs.com/package/@circle-fin/bridge-kit)数字 : ```typescript import { BridgeKit } from '@circle-fin/bridge-kit' import { ViemAdapter } from '@circle-fin/adapter-viem-v2' import { createPublicClient, createWalletClient, http } from 'viem' import { mainnet, base } from 'viem/chains' import { privateKeyToAccount } from 'viem/accounts' const account = privateKeyToAccount(process.env.PRIVATE_KEY) // Provider is included by default const kit = new BridgeKit() const sourceAdapter = new ViemAdapter({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), walletClient: createWalletClient({ account, chain: mainnet, transport: http(), }), }) const destAdapter = new ViemAdapter({ publicClient: createPublicClient({ chain: base, transport: http() }), walletClient: createWalletClient({ account, chain: base, transport: http() }), }) // Monitor transfer events kit.on('*', (event) => console.log('Event:', event)) // subscribe to all events kit.on('approve', (event) => console.log('Approval:', event.values.txHash)) kit.on('burn', (event) => console.log('Burn:', event.values.txHash)) kit.on('fetchAttestation', (event) => console.log('Attestation:', event.values.data), ) kit.on('mint', (event) => console.log('Mint:', event.values.txHash)) // Execute transfer const result = await kit.bridge({ from: { adapter: sourceAdapter, chain: 'Ethereum' }, to: { adapter: destAdapter, chain: 'Base' }, amount: '25.0', }) ``` ## 发展 这个包是App Kits monorepo的一部分. ```bash # Build nx build @circle-fin/provider-cctp-v2 # Test nx test @circle-fin/provider-cctp-v2 ``` ## 许可证 这个项目根据Apache 2.0许可证获得许可. 联系人 [支助](https://help.circle.com/s/submit-ticket) 详细情况. * * * **准备好跨链桥了吗?** [加入磁盘](https://discord.com/invite/buildoncircle) 二. 支助 [访问我们的救世主](https://help.circle.com/s/submit-ticket) _由 Circle 创建_ ## 常见问题 ### @circle-fin/provider-cctp-v2 是什么？ Circle官方的Cross-Chain 传输协议 v2 本地 UDC 桥接供应商 ### 如何安装 @circle-fin/provider-cctp-v2？ 在项目目录运行 npm install @circle-fin/provider-cctp-v2，或使用 pnpm add / yarn add / bun add。 ### @circle-fin/provider-cctp-v2 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @circle-fin/provider-cctp-v2 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @circle-fin/provider-cctp-v2 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @circle-fin/provider-cctp-v2 可以商用吗？ @circle-fin/provider-cctp-v2 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### @circle-fin/provider-cctp-v2 的下载量有多少？ 根据 npm 官方下载统计，@circle-fin/provider-cctp-v2 在 2026/10/10 – 2026/11/08 这 30 天内被下载 57,469 次，日均约 1,916 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @circle-fin/provider-cctp-v2 还在维护吗？ 最新版本 1\.14\.6 发布于 2026/11/06（3 天前）；至今共发布 40 个版本，其中过去 12 个月发布了 35 个；首次发布于 2025/08/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。