CCTPx 连接提供者

目录

• CCTPx 连接提供者
  • 目录
  • 概览
  • 安装
  • 使用量
    • 与 Bridge Kit( 建议)
    • 估计转移
    • 直接提供者的使用
  • 公共 API
  • 支持的链条( T)
  • IRIS API (英语)
  • 观察性
    • 连接运行时间后端
    • 排放地点
  • 解决问题
  • 发展
  • 许可证

概览

CCTPx 搭桥提供商是 Circle 的 CCCTPx 的强型执行 协议。 这里 CCTPv2 供应商 移动本地 USDC, CCTPx 移动 非USDC 代号 跨链条 通过CrossChainToken服务。 哪些符号和路线可用 由 CCTPx 令牌登记册驱动; KNOWN_TOKEN_SYMBOLS 列出 提供者代表呼叫者解决.

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

虽然主要设计为电力 桥套, (中文(简体) ), 提供者可以直接用于需要精细控制的程序.

安装

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

说明: 默认情况下包含此提供者 桥套安装它 仅当您需要自定义的 CCTPx 集成时.

使用量

与 Bridge Kit( 建议)

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

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) 给卢布链.

估计转移

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

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 (捆绑这个供应商),所以 直接整合者从那里进口:

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 表面最需要的:

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 数量或探测器本身失败时;见 观察性 对于信号的火.
• 证明和前进状态 —— 说 GET /v2/messages/{sourceDomain} 返回时 来源传输的签名证明。 这个 目的地腿投票 同一端点 第二次中继器 forwardState; 见 解决问题 给那些词汇.
• 重新测试 —— 说 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数字 :

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) },
})

// 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 路由意外返回"不支持" . 路线检查需要 两条链条都搭载 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的一部分.

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

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

许可证

这个项目根据Apache 2.0许可证获得许可. 联系人 支助 详细情况.