# @circle-fin/provider-cctpx 中文文档

规范地址：https://npmcn.com/package/%40circle-fin/provider-cctpx/

版本：1\.0\.7
npm 元数据更新时间：2026-11-05T17:19:19.845Z
中文译文更新时间：2026-11-09T16:38:05.983Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40circle-fin/provider-cctpx
原文对照：https://npmcn.com/package/%40circle-fin/provider-cctpx/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.2 MB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：9 个
- 首次发布：2026-09-16T00:36:53.381Z
- 最新版本发布：2026-11-05T17:19:19.536Z
- 近 30 天下载量：38448（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

Circle 的 CCTPx 供应商,用于通过 CrossChainToken Service 进行非USDC 跨链令牌传输

## 安装

```sh
npm install @circle-fin/provider-cctpx
```

也可以使用：`pnpm add @circle-fin/provider-cctpx`、`yarn add @circle-fin/provider-cctpx`、`bun add @circle-fin/provider-cctpx`

## README

# CCTPx 连接提供者

[![npm version](https://badge.fury.io/js/@circle-fin%2Fprovider-cctpx.svg)](https://badge.fury.io/js/@circle-fin%2Fprovider-cctpx) [![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 桥基的 CCTPx 供应商**

_通过CrossChainTokenService系统跨链传输非USDC令牌._

## 目录

-   [CCTPx 连接提供者](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-cctpx-bridging-provider)
    -   [目录](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-table-of-contents)
    -   [概览](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-overview)
    -   [安装](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-installation)
    -   [使用量](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-usage)
        -   [与 Bridge Kit( 建议)](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-with-bridge-kit-recommended)
        -   [估计转移](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-estimating-a-transfer)
        -   [直接提供者的使用](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-direct-provider-usage)
    -   [公共 API](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-public-api)
    -   [支持的链条( T)](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-supported-chains--tokens)
    -   [IRIS API (英语)](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-the-iris-api)
    -   [观察性](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-observability)
        -   [连接运行时间后端](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-wiring-the-runtime-backends)
        -   [排放地点](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-emission-sites)
    -   [解决问题](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-troubleshooting)
    -   [发展](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-development)
    -   [许可证](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-license)

## 概览

CCTPx 搭桥提供商是 Circle 的 CCCTPx 的强型执行 协议。 这里 [CCTPv2 供应商](https://www.npmjs.com/package/@circle-fin/provider-cctp-v2) 移动本地 USDC, CCTPx 移动 **非USDC 代号** 跨链条 通过CrossChainToken服务。 哪些符号和路线可用 由 CCTPx 令牌登记册驱动; `KNOWN_TOKEN_SYMBOLS` 列出 提供者代表呼叫者解决.

用不透明的协议内在标识符(a)识别一个符号 `bytes32` id),而不是由绑在单一链式地址上的符号来表示. 提供者决定 已知符号(`'cirBTC'` 编号 : `'wETH'` 编号 : `'EURC'`对内部的id,验证 与 CCTPx 令牌登记簿相对的路由,获取服务器签名的收费报价,以及 (a) 运行全部核准程序.

虽然主要设计为电力 [桥套](https://www.npmjs.com/package/@circle-fin/bridge-kit), (中文(简体) ), 提供者可以直接用于需要精细控制的程序.

## 安装

```bash
npm install @circle-fin/provider-cctpx
# or
yarn add @circle-fin/provider-cctpx
```

> **说明**: 默认情况下包含此提供者 [桥套](https://www.npmjs.com/package/@circle-fin/bridge-kit)安装它 仅当您需要自定义的 CCTPx 集成时.

## 使用量

### 与 Bridge Kit( 建议)

Bridge Kit 默认在 CCTPv2 之后注册 CCTPx 提供者 供养. 一个赤裸的 `'USDC'` 符号继续通过 CCTPv2; 已知 CCTPx符号或字节32符id路由通过CCTPx. 以下示例使用a 测试网路线( e)`Ethereum_Sepolia → Arc_Testnet`:

```typescript
import { BridgeKit } from '@circle-fin/bridge-kit'

const kit = new BridgeKit()

const result = await kit.bridge({
  from: { adapter: sourceAdapter, chain: 'Ethereum_Sepolia' },
  to: { adapter: destAdapter, chain: 'Arc_Testnet' },
  amount: '0.05',
  token: 'wETH',
})

if (result.state === 'success') {
  console.log(result.steps.map((step) => step.name))
}
```

过 `'cirBTC'`, (中文(简体) ), `'wETH'`, (中文(简体) ), `'EURC'`,或者一个32字节的十六进制符号 id (`0x` 加64个 十六个字符). CCTPx 令牌登记册决定该id是否为routable. 未知符号、短/成形标识,以及 `{ provider, id }` 对象抛出 `bridge` 编号 : `estimate`。见 [支持的链条( T)](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-supported-chains--tokens) 给卢布链.

### 估计转移

`estimate` 返回服务器签名费 `quote` 与单入 `fees[]` 总结。 共享结果类型的叶子 `quote` 不透明,所以缩小到这里 供应商 `QuoteEnvelope` 读取细分。 CCTPx收费由报价驱动, 所以气费估计是空的:

```typescript
import type { QuoteEnvelope } from '@circle-fin/provider-cctpx'

const estimate = await kit.estimate({
  from: { adapter: sourceAdapter, chain: 'Ethereum_Sepolia' },
  to: { adapter: destAdapter, chain: 'Arc_Testnet' },
  amount: '0.05',
  token: 'wETH',
})

// `quote` is opaque on the shared result type. Narrow it to this provider's
// envelope to read the fee breakdown.
const quote = estimate.quote as QuoteEnvelope | undefined
console.log(quote?.totalAmount, estimate.fees[0]?.token)
```

传过去 `quote` 返回到 `bridge` 重新使用它。 CCTPx 重用引用时 尚未过期并匹配请求的速度;否则它会获取新的速度 添加一个 `QUOTE_NOT_REUSED` 警告对象 `result.warnings`。 。 。 .

### 直接提供者的使用

`supportsRoute` 需要两个连锁定义。 公布的链式定义 从 `@circle-fin/bridge-kit` (捆绑这个供应商),所以 直接整合者从那里进口:

```typescript
import { CCTPXBridgingProvider } from '@circle-fin/provider-cctpx'
import { EthereumSepolia, ArcTestnet } from '@circle-fin/bridge-kit'

const provider = new CCTPXBridgingProvider()

// Route checks read the CCTPx token registry (latency-bounded, cached).
const canRoute = await provider.supportsRoute(
  EthereumSepolia,
  ArcTestnet,
  'wETH',
)
```

路由检查确定为 `true`编号 :`false` 对于一个明确的答案。 如果那个标志 无法通过冷藏器获取登记册, `supportsRoute` 转而投出 **可重试** `KitError` (单位:千美元)`SERVICE_ROUTE_CHECK_UNAVAILABLE`——"无法检查", 不同于确定 `false` 因此,一个直接的整合者应该准备好 抓住它 抓住它 抓住它 Bridge Kit的路由图层可以重试 路由检查错误而不是误导性的"不支持的路由".

## 公共 API

Bridge Kit再出口 CCTPx 表面最需要的:

```typescript
import {
  CCTPXBridgingProvider,
  KNOWN_TOKEN_SYMBOLS,
  type CCTPXBridgingProviderConfig,
  type BridgeToken,
  type CCTPXTokenId,
  type CCTPXRouteToken,
  type KnownTokenSymbol,
  type CCTPXChainConfig,
  type ChainDefinitionWithCCTPX,
} from '@circle-fin/bridge-kit'
```

-   `CCTPXBridgingProvider` ——提供者类别(默认注册).
-   `KNOWN_TOKEN_SYMBOLS` ——运行时的符号列表可解而无 `bytes32` 页:1`['cirBTC', 'wETH', 'EURC']`) (中文(简体) ).
-   `CCTPXBridgingProviderConfig` ——用于接线提供者的构造器选项 明确而不是依赖默认登记.
-   `BridgeToken` ——"桥基"符号输入: `'USDC'`一个已知的CCTPx符号, 或一个字节32 CCTPx sorder id.
-   `CCTPXTokenId` - 那个 `bytes32` 代号类型 .
-   `CCTPXRouteToken` ——路由检查接受:a `CCTPXTokenId` 或一个 `KnownTokenSymbol`。哪个ID是routable,由IRIS登记处决定 调用时间,所以这是一个形状,而不是有效性的保证.
-   `KnownTokenSymbol` 这些符号的结合,从上面的列表中推导出来 类型和运行时间都永远不会漂移.
-   `CCTPXChainConfig` ——每链的CCTPx配置形状(即: CrossChainToken Service 地址和支持的令牌).
-   `ChainDefinitionWithCCTPX` - 范围缩小了 `ChainDefinition` 链条类型 经证实可携带CCTPx部署(a) `ChainDefinition` 谁 `cctpx` 配置是存在的,不是一个运行时的后卫.

供应商包还出口登记册获取者、收费报价 获取器,动作映射类型(`CCTPXActions`),向前状态和 证明-地位联盟,以及IRIS API路径常数. 见包裹 整个地表的入口.

## 支持的链条( T)

打电话 `provider.getSupportedChains()` 用于当前集而不是静态 列表中,它返回定义在 `@core/chains` (单位:千美元)`core/chains/src/definitions`(a) 携带 `cctpx.serviceAddress` (a) 已部署 CrossChainTokenService),同一个信号 `isCCTPXSupported` 报告。 链条 一旦定义得到此领域,即成为CCTPx资格.

资格是每个连锁店;资格是每个标志。 只接受一条路线 当两个端点都是同一网络上的EVM链时,两个端点都带有一个 CCTP 域名 和 CrossChainToken Service 的部署,登记簿列出代号,并附有 在两个端点的域上部署。 因此,合格的一对连锁店 本身不是给定的标志的可用路线.

**已知符号 :** 列出的符号 `KNOWN_TOKEN_SYMBOLS`符号 所以它只会在铁链之间 桥被注册在上;一个符号,将地图映射到一个以上的桥上 峡谷一. 任何登记证——包括一座非卡通桥 为已知的符号——经其 `bytes32` 编号.

## IRIS API (英语)

提供商与Circle的公众IRIS API谈了五件事:

-   **收件登记** —— 说 `GET /v2/cctpx/tokens` 列出 CCTPx 列表 符号及其每链部署。 路由检查读取此( 刻出 :, (b) 暂停生效; `provider.refreshTokenRegistry()` 强制刷新.
-   **收费报价** a 包括: `POST` 到 CCTPx 引用端点返回服务器签名 引出链上转移携带。 引文过期.
-   **快活津贴** —— 说 `GET /v2/cctpx/allowances` 其余报告 每人快速燃烧津贴。 FAST在签字前探测到这个 当剩余津贴无法进行转移时,可降解为SLOW 数量或探测器本身失败时;见 [观察性](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-observability) 对于信号的火.
-   **证明和前进状态** —— 说 `GET /v2/messages/{sourceDomain}` 返回时 来源传输的签名证明。 这个 目的地腿投票 同一端点 第二次中继器 `forwardState`; 见 [解决问题](https://npmcn.com/package/%40circle-fin/provider-cctpx/#readme-troubleshooting) 给那些词汇.
-   **重新测试** —— 说 `POST /v2/reattest/{nonce}` 请IRIS重新签署 他的证明从未到来. `provider.reAttest(source, txHash)` 是操作员逃出舱门:它通过证明解决了非ce 结束点, 张贴重新测试请求, 然后重投直到证明 值实际变化.

主机: 生产为 `https://iris-api.circle.com`; 沙盒为 `https://iris-api-sandbox.circle.com`中选择主机 来源于源链网络(测试网-沙盒,主网-生产). 两者 可以通过 `CCTPXBridgingProviderConfig`。 。 。 .

## 观察性

供应商在下面每个站点的3个频道发布——一个日志线, a 一个 `events.emit({ name, data })` 事件,和 a `metrics.counter(name).inc()` 递增。 全部三个默认值 没有操作,所以排放会下降,除非你给运行时间后端电线.

### 连接运行时间后端

通过工具箱的调用元数据 与您的后端通过运行时间,或者 直接用 `logger` 编号 : `events` 编号 : `metrics`数字 :

```typescript
import { CCTPXBridgingProvider } from '@circle-fin/provider-cctpx'

// Node — e.g. pino logs + an OpenTelemetry counter + your event bus.
const provider = new CCTPXBridgingProvider({
  logger: { warn: (msg, fields) => pino.warn(fields, msg) /* ...rest */ },
  metrics: { counter: (name) => ({ inc: () => otelCounter(name).add(1) }) },
  events: { emit: (event) => myBus.publish(event.name, event.data) },
})
```

```typescript
// Browser — e.g. forward warnings to Sentry and events to Datadog RUM.
const provider = new CCTPXBridgingProvider({
  logger: {
    warn: (msg, fields) => Sentry.captureMessage(msg, { extra: fields }),
  },
  events: { emit: (event) => datadogRum.addAction(event.name, event.data) },
})
```

套接字通过桥接线 `Runtime.{ logger, events, metrics }` 曾经捕捉到下面的每一个地点.

### 排放地点

每个排放点都发射以下一个或多个信号。 登记册和 收费网站额外给予更高优先级 `cctpx.registry.invalidpayload` 编号 : `cctpx.feequote.invalidpayload` 当一个 `200 OK` 身体不能被解析或验证.

| 事件名称 | 度量衡 | 当它起火时 | 行动 |
| --- | --- | --- | --- |
| `cctpx.registry.failed` | `cctpx.registry.errors` | 无法读取令牌注册, 缓存是冷的 . | 请检查IRIS可达性; 路由检查会丢出一个可重试错误, 直到注册可读为止. |
| `cctpx.feequote.failed` | `cctpx.feequote.errors` | 无法从IRIS获得收费报价. | 检查 IRIS 可达性; 引文获取失败, 有定向错误, 直到 IRIS 可读 . |
| `cctpx.quote.refetched` | `cctpx.quote.refetched` | 一份签名的引文在提交时被搁置并透明地被重新引用. | 信息;流会重建调用数据. 重复射击表明签署/提交缓慢. |
| `cctpx.allowance.failed` | `cctpx.allowance.errors` | 速燃活性探测器无法读取(network / HTTP / bad body). | 探测器将请求降解为 SLOW(安全选择);检查IRIS可达性. |
| `cctpx.allowance.degraded` | `cctpx.allowance.degraded` | 一次探测失败迫使FAST请求倒回了斯劳德. | 信息;转让在斯洛德进行。 与 `cctpx.allowance.failed`。 。 。 . |
| `cctpx.fastburn.unavailable` | `cctpx.fastburn.degraded` | Fast-burn尚未确认可用,因此一个FAST请求已退化为SLOW. | 信息;转让在斯洛德进行. |
| `cctpx.quote.reused` | `cctpx.quote.reused` | 一个呼叫者提供的报价通过再利用检查,并被逐字使用. | 信息; 登录于 `debug`。没有获取新的引文. |
| `cctpx.quote.reuserejected` | `cctpx.quote.reuserejected` | 调用者提供的引文无法被再用,因此取出新的引文. | 请检查access-date=中的日期值 (帮助) 引文的新鲜度和速度; 转出在新引文上的收益. |

## 解决问题

-   **一个 CCTPx 路由意外返回"不支持" .** 路线检查需要 两条链条都搭载 CrossChainTokenService 的部署 和要装的标志 在两个域注册。 若为 `cctpx.registry.failed` 被开除,IRIS是 无法以冷的缓存到达 —— 路由检查丢出可重试 `SERVICE_ROUTE_CHECK_UNAVAILABLE` 错误( 非定义 ) `false`直至 登记册可以读取。 打电话 `provider.refreshTokenRegistry()` 强制更新 读取在运行中的实例.
    
-   **引文会不断重写( A)`cctpx.quote.refetched`) (中文(简体) ).** 引文过期; a 提交时的 stale 引文被透明地重提。 频繁 re-fetches 通常表示签名或提交相对于引文来说是缓慢的 TTL (英语).
    
-   **A FAST Transfer 运行在 SLOW(`cctpx.fastburn.unavailable`) (中文(简体) ).** 快烧 无法确认是否有可用——其余的津贴也不足 或者探测器失败了 所以它退化成斯劳德 这是预期的行为,不是 错误.
    
-   **探测器出错后, FAST 传输在 SLOW 运行(`cctpx.allowance.failed` 编号 : `cctpx.allowance.degraded`) (中文(简体) ).** 无法读取快烧活度探测器 因此 请求已降解为 Slow。 不拒绝超限的 FAST 传输 链上,它最终与 `PRE_FINALITY` 已经溢价 支付——因此,当剩余津贴不明时,SLOW是正确的 价格选择。 如果探测器持续故障,请检查IRIS的可达性.
    
-   **目的地的前方摊位.** 如果目的地腿没有到达 终端状态 - `CONFIRMED` 或者说 `COMPLETE` 携带 `forwardTxHash` - 那个 传输正在等待 Circle 的中继器执行 CCTPx 消息; 民调 持续到它。 一个终端 `FAILED` 向呼叫者显示 `forwardErrorCode` 编号 : `forwardErrorDetails`。完整的前向状态词汇 实值 `PENDING | SENT | CONFIRMED | COMPLETE | FAILED`;终端状态是 `CONFIRMED` 财务报告和审定财务报表 `COMPLETE` (当年a) `forwardTxHash` 报告),以及 `FAILED`。 。 。 . `bridge()` 以任何先到者为准,而不是 `COMPLETE` - 交货交易在链上 `CONFIRMED`,以及 `COMPLETE` 只添加最终目的, IRIS 可以报告分钟 等会 回来的 `forwardState` 说在两次民意调查中哪一次.
    
-   **在CCTPx路线上要求收取自定义费.** 自定义费仅为USDC 特性: 收费在转账数额上方收取,并通过 CCTPv2的USDC流量,因此不能适用于CCTPx(非USDC)的代币. 请求 一——通过全包政策或按电话计价 `config.customFee` 已经.. 以 `INPUT_VALIDATION_FAILED` 在提交任何文件之前 `estimate` 以及 `bridge`或降低航道收费.
    
-   **`feePayment: 'destination'` 被通过.** CCTPx 预缴费用 源腿,作为 同一签名引号的一部分 转移承诺,所以 没有可选择的目的端收藏 . `'source'` 和一个省略 价值被接受; 任何其他价值——包括近似缺失,例如: `'Destination'` ——被拒绝 `INPUT_VALIDATION_FAILED` 在事情发生之前 已提交,于 `estimate` 以及 `bridge`。 。 。 .
    
-   **`useForwarder: false` 被通过.** 每一次CCTPx转账都会支付转发费 在引文中,付款是发送 中继器,所以转发是 在转帐到达链条之前购买,不能每通电话关闭. 被录取和 `true` 被接受; 其它任何被拒绝 `INPUT_VALIDATION_FAILED` 在提交任何文件之前 `estimate` 以及 `bridge`。 。 。 .
    

## 发展

这个包是App Kits monorepo的一部分.

```bash
# Build
nx build @circle-fin/provider-cctpx

# Test
nx test @circle-fin/provider-cctpx
```

## 许可证

这个项目根据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-cctpx 是什么？

Circle 的 CCTPx 供应商,用于通过 CrossChainToken Service 进行非USDC 跨链令牌传输

### 如何安装 @circle-fin/provider-cctpx？

在项目目录运行 npm install @circle-fin/provider-cctpx，或使用 pnpm add / yarn add / bun add。

### @circle-fin/provider-cctpx 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @circle-fin/provider-cctpx 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @circle-fin/provider-cctpx 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @circle-fin/provider-cctpx 可以商用吗？

@circle-fin/provider-cctpx 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @circle-fin/provider-cctpx 的下载量有多少？

根据 npm 官方下载统计，@circle-fin/provider-cctpx 在 2026/10/10 – 2026/11/08 这 30 天内被下载 38,448 次，日均约 1,282 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @circle-fin/provider-cctpx 还在维护吗？

最新版本 1\.0\.7 发布于 2026/11/06（3 天前）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/09/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。