# @aptos-labs/cross-chain-core 中文文档

规范地址：https://npmcn.com/package/%40aptos-labs/cross-chain-core/

版本：6\.1\.2
npm 元数据更新时间：2026-05-08T19:13:41.301Z
中文译文更新时间：2026-11-06T13:08:57.356Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aptos-labs/cross-chain-core
原文对照：https://npmcn.com/package/%40aptos-labs/cross-chain-core/?lang=original
项目主页：https://github.com/aptos-labs/aptos-wallet-adapter
源码仓库：https://github.com/aptos-labs/aptos-wallet-adapter

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

- 包体积（解压后）：600 kB，85 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：23 个
- peer 依赖：@aptos-labs/ts-sdk ^5\.1\.1
- 首次发布：2025-03-25T23:50:58.998Z
- 最新版本发布：2026-05-08T19:13:40.964Z
- 近 30 天下载量：6113（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：70（近 12 个月 38 个）

## 中文简介

Aptos 跨链核心

## 安装

```sh
npm install @aptos-labs/cross-chain-core
```

也可以使用：`pnpm add @aptos-labs/cross-chain-core`、`yarn add @aptos-labs/cross-chain-core`、`bun add @aptos-labs/cross-chain-core`

## README

# Aptos 跨钱核心

使用 Aptos 块链进行跨链 USDC 传输的 SDK 类型 [圆形的 CCTP](https://www.circle.com/en/cross-chain-transfer-protocol) (Cross-Chain转让协议) [虫洞](https://wormhole.com/) 桥.

## 概览

这个软件包可以在Aptos和其他支持的区块链之间实现无缝的USDC传输. 它总结了跨链交易的复杂性,为:

-   **转账**: 将USDC从外部链条(索拉纳、伊特鲁姆等)移动到Aptos
-   **退 款**: 将 USDC 从 Aptos 移动到外部链条
-   **余额查询**: 检查所有支持链的USDC余额
-   **引文估计**: 在执行前获取转账费用和手续费

## 建筑

```mermaid
flowchart TB
    subgraph core [CrossChainCore]
        CCCore[CrossChainCore Class]
        Config[Config - chains/tokens]
        Utils[Utils - logger, balance]
    end

    subgraph provider [WormholeProvider]
        WH[WormholeProvider]
        Quote[getQuote]
        Transfer[transfer]
        Withdraw[withdraw]
    end

    subgraph signers [Signers]
        MainSigner[Signer - Router]
        SolanaSig[SolanaSigner]
        EthSig[EthereumSigner]
        AptosSig[AptosSigner]
        SuiSig[SuiSigner]
        AptosLocal[AptosLocalSigner]
    end

    CCCore --> WH
    WH --> MainSigner
    MainSigner --> SolanaSig
    MainSigner --> EthSig
    MainSigner --> AptosSig
    MainSigner --> SuiSig
```

## 支持的链条

| 网络 | 主网链标识 | 测试网链 ID | A. 背景情况 |
| --- | --- | --- | --- |
| 自动 | 1个 | 2个 | 目标/来源 |
| 索拉纳 | 主网-β | 脱网 | 来源/来源 |
| 以利亚 | 1个 | 11155111(塞波利亚) | 来源/来源 |
| 基础 | 8453 (英语) | 84532 (塞波利亚) | 来源/来源 |
| 坐标 | 42161 (韩语) | 421614 (塞波利亚) | 来源/来源 |
| 雪崩 | 第43114号 | 43113 (富吉语) | 来源/来源 |
| 多边形 | 137国 | 80002 (阿莫伊语) | 来源/来源 |
| 苏 | 主网 | 测试网 | 来源/来源 |

## 支持的托肯斯语Name

目前,仅 **USDC 美洲金融共同体** 通过Circle's Cross-Chain 传输协议(CCTP)支持.

## 如何运作

1.  **初始化**创建一个 `CrossChainCore` 使用您的网络配置
2.  **获取提供者**: 获取 `WormholeProvider` 用于执行转账
3.  **获取引用**: 计算费用和转账参数
4.  **执行传输**: 签署并提交跨链交易
5.  **等待完成时**: SDK 处理验证和在目的地链上索赔

### 转移流量(外部链-平面)

```
Source Chain Wallet → CCTP Burn → Wormhole Attestation → Aptos Claim → Aptos Wallet
```

### 取出流量(阿普托斯-外部链)

```
Aptos Wallet → CCTP Burn → Wormhole Attestation → External Chain Claim → Destination Wallet
```

## 签名人

A 类 **签名** 是处理特定区块链交易签名和提交内容的组件。 SDK使用签名器与Wormhole桥协议交互,执行 `SignAndSendSigner` 来自 Wormhole SDK 的接口.

### 可用的签名符

| 签名 | 链条 | 说明 |
| --- | --- | --- |
| `Signer` | 全体 | 根据上下文向链式特定标志代表发送的路由器符号 |
| `SolanaSigner` | 索拉纳 | 通过 `SolanaDerivedWallet` |
| `EthereumSigner` | EVM链 | 通过 `EIP1193DerivedWallet` |
| `AptosSigner` | 自动 | 通过钱包适配器( 用户交互) 签名交易 |
| `AptosLocalSigner` | 自动 | 与本地交易签名 `Account` (方案) |
| `SuiSigner` | 苏 | 通过 `SuiDerivedWallet` |

### 为什么是两个Aptos的签名人?

跨链转移涉及两个不同的阶段,每个阶段都有不同的签署要求:

#### 两级移交进程

1.  **启动阶段** (源链):用户在源链上燃烧USDC并创建证明
2.  **索赔阶段** (调制链): 经认证的USDC在目的地链上被铸造

这些阶段需要不同类型的签字:

| 阶段 | 签名 | 用户交互 | 使用大小写 |
| --- | --- | --- | --- |
| 启动( 退出) | `AptosSigner` | 所需时间 | 用户从 Aptos 钱包中燃烧 USDC |
| 索赔(转让) | `AptosLocalSigner` | 自动 | 代表用户的USDC索赔 |

#### Aptos 符号

用于 **退 款** 用户从 Aptos 钱包启动交易时:

-   需要钱包适配器连接和用户批准
-   用户必须明确签名才能烧掉 USDC
-   标准钱包交互流量

#### 本地标志

用于 **转让** uSDC从另一条链上到达的Aptos:

-   与本地 `Account` 对象
-   不需要用户交互
-   启用无需用户动作的自动要求

#### 衍生的钱包优势

当从外部链(索拉纳、伊特鲁姆等)转移到Aptos时,SDK使用 **衍生钱包**。一个衍生的钱包创建了与用户外部链条公钥在数学上链接的Aptos账户地址.

**这意味着用户不需要现有的Aptos钱包来接收资金!**

流动是这样的:

1.  用户连接他们的 Solana 钱包( 例如)
2.  SDK从索拉纳的公用钥匙得到相应的Aptos地址
3.  用户在 Solana 上签名燃烧交易
4.  Aptos 自动索赔USDC 使用 `AptosLocalSigner`
5.  资金出现在衍生的Aptos地址中,由同一索拉纳钥匙控制

这种设计可以实现无缝上载:用户只能使用现有的外链钱包将USDC转移到Aptos上.

## 安装

```bash
pnpm add @aptos-labs/cross-chain-core
```

或者说

```bash
npm install @aptos-labs/cross-chain-core
```

## 快速启动

```typescript
import { CrossChainCore, Network } from "@aptos-labs/cross-chain-core";

// Initialize the core with network configuration
const crossChainCore = new CrossChainCore({
  dappConfig: {
    aptosNetwork: Network.TESTNET,
    // Optional: Custom Solana RPC
    solanaConfig: {
      rpc: "https://api.devnet.solana.com",
    },
  },
});

// Get the Wormhole provider
const provider = crossChainCore.getProvider("Wormhole");
```

## API 参考

### 十字铸币局

跨链业务的主要切入点.

```typescript
const core = new CrossChainCore({
  dappConfig: {
    aptosNetwork: Network.TESTNET | Network.MAINNET,
    disableTelemetry?: boolean,
    solanaConfig?: {
      rpc?: string,
      priorityFeeConfig?: {
        percentile?: number,
        percentileMultiple?: number,
        min?: number,
        max?: number,
      }
    }
  }
});
```

#### `getProvider(providerType: "Wormhole")`

返回执行跨链传输的提供者实例.

```typescript
const provider = core.getProvider("Wormhole");
```

#### `getWalletUSDCBalance(walletAddress: string, chain: Chain)`

在任何支持的链上获取 USDC 的钱包余额 .

```typescript
const balance = await core.getWalletUSDCBalance(
  "0x1234...", // wallet address
  "Solana", // chain name
);
console.log(`Balance: ${balance} USDC`);
```

### 虫洞提供器

#### `getQuote(params)`

计算转账费用并在执行前获得报价.

```typescript
const quote = await provider.getQuote({
  // Amount to transfer (as string, e.g., "100.50")
  amount: "100",
  // The external chain involved
  originChain: "Solana",
  // Transaction type:
  // - "transfer": External chain → Aptos
  // - "withdraw": Aptos → External chain
  type: "transfer",
});
```

**回返**: 有收费、估计时间和转账细节的引文对象.

#### `transfer(params)`

将 USDC 从一个外部链钱包转移到一个 Aptos 钱包 .

```typescript
const { originChainTxnId, destinationChainTxnId } = await provider.transfer({
  // Source blockchain
  sourceChain: "Solana",
  // Source chain wallet adapter (must support signing)
  wallet: solanaWalletAdapter,
  // Destination Aptos address
  destinationAddress: "0x1234...",
  // Aptos account to sign the claim transaction
  mainSigner: aptosAccount,
  // Optional: Amount (if not using a previous quote)
  amount: "100",
  // Optional: Sponsor account for gas fees
  sponsorAccount: feePayerAccount,
});

console.log(`Source TX: ${originChainTxnId}`);
console.log(`Destination TX: ${destinationChainTxnId}`);
```

**回返**数字 :

-   `originChainTxnId`: 源链上交易散列
-   `destinationChainTxnId`: Aptos 目的地链上的散列交易

#### `withdraw(params)`

将 USDC 从 Aptos 钱包撤回到外部链钱包 .

```typescript
const { originChainTxnId, destinationChainTxnId } = await provider.withdraw({
  // Destination blockchain
  sourceChain: "Ethereum",
  // Aptos wallet adapter
  wallet: aptosWalletAdapter,
  // Destination address on the external chain
  destinationAddress: "0xabcd...",
  // Optional: Sponsor account for gas fees
  sponsorAccount: feePayerAccount,
});

console.log(`Aptos TX: ${originChainTxnId}`);
console.log(`Destination TX: ${destinationChainTxnId}`);
```

**回返**数字 :

-   `originChainTxnId`平面散列交易
-   `destinationChainTxnId`: 目的地链上的散列交易

### 服务器-Side Solana索赔(备选)

在将USDC从Aptos撤回索拉纳时,索拉纳公司的索赔交易需要签名. 默认情况下,用户的钱包会在此交易上签名. 然而,对于更平滑的用户体验,您可以配置一个 **服务器端索赔** 你的后端签下了索拉纳的债权交易.

**福利:**

-   用户只签名一次( Aptos 刻录交易)
-   ~60 第二级证明后没有第二个钱包跳出
-   无缝一击取出流量

要启用服务器端的主张, 配置 `serverClaimUrl` 在你身边 `solanaConfig`数字 :

```typescript
const crossChainCore = new CrossChainCore({
  dappConfig: {
    aptosNetwork: Network.MAINNET,
    solanaConfig: {
      serverClaimUrl: "/api/claim-withdraw", // Your API endpoint
    },
  },
});
```

在配置时, SDK 在确认和验证 Aptos 刻录交易后, 将会自动 POST 给您的服务器端点的验证收据 。 您的服务器然后使用一个有资金的 keypair 签名并提交 Solana 索赔交易 .

📖 **见 [(原始内容存档于2012-10-12). ServerSide Solana SIGNER.md](https://npmcn.com/package/%40aptos-labs/cross-chain-core/SERVERSIDE_SOLANA_SIGNER.md) 完整实施指南.**

## 链式ID映射

SDK提供从Ethereum链式ID到链式配置的映射:

```typescript
import {
  EthereumChainIdToTestnetChain,
  EthereumChainIdToMainnetChain,
} from "@aptos-labs/cross-chain-core";

// Get chain config from chain ID
const sepoliaConfig = EthereumChainIdToTestnetChain["11155111"];
const ethereumConfig = EthereumChainIdToMainnetChain["1"];
```

## 处理错误

SDK 为常见问题投出描述性错误:

```typescript
try {
  await provider.transfer({ ... });
} catch (error) {
  if (error.message.includes("Unsupported chain")) {
    // Handle unsupported chain
  } else if (error.message.includes("User rejected")) {
    // Handle user rejection
  }
}
```

## 所需资源

-   节点.js 18+
-   `@aptos-labs/ts-sdk` ^ 5.1.1(对老年人的依赖)
-   `@aptos-labs/wallet-adapter-react` - 这个软件包旨在与Aptos钱包适配器生态系统合作,特别是使用衍生的钱包适配器(`@aptos-labs/derived-wallet-solana`, (中文(简体) ), `@aptos-labs/derived-wallet-ethereum`, (中文(简体) ), `@aptos-labs/derived-wallet-sui`属于该项目的一部分

## 常见问题

### @aptos-labs/cross-chain-core 是什么？

Aptos 跨链核心

### 如何安装 @aptos-labs/cross-chain-core？

在项目目录运行 npm install @aptos-labs/cross-chain-core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@aptos-labs/ts-sdk（^5\.1\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aptos-labs/cross-chain-core 支持 TypeScript 吗？

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

### @aptos-labs/cross-chain-core 支持 ESM 还是 CommonJS？

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

### @aptos-labs/cross-chain-core 可以商用吗？

@aptos-labs/cross-chain-core 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aptos-labs/cross-chain-core 的下载量有多少？

根据 npm 官方下载统计，@aptos-labs/cross-chain-core 在 2026/10/07 – 2026/11/05 这 30 天内被下载 6,113 次，日均约 204 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aptos-labs/cross-chain-core 还在维护吗？

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