# @cardano-sdk/hardware-trezor 中文文档

规范地址：https://npmcn.com/package/%40cardano-sdk/hardware-trezor/

版本：0\.7\.39
npm 元数据更新时间：2026-09-25T13:52:01.779Z
中文译文更新时间：2026-11-09T04:15:27.973Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cardano-sdk/hardware-trezor
原文对照：https://npmcn.com/package/%40cardano-sdk/hardware-trezor/?lang=original
项目主页：https://github.com/input-output-hk/cardano-js-sdk#readme
源码仓库：https://github.com/input-output-hk/cardano-js-sdk

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

- 包体积（解压后）：668 kB，120 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：11 个
- 首次发布：2023-10-12T10:42:34.069Z
- 最新版本发布：2026-09-25T13:52:01.190Z
- 近 30 天下载量：37615（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：106（近 12 个月 7 个）

## 中文简介

绘图和与Trezor硬件的整合

## 安装

```sh
npm install @cardano-sdk/hardware-trezor
```

也可以使用：`pnpm add @cardano-sdk/hardware-trezor`、`yarn add @cardano-sdk/hardware-trezor`、`bun add @cardano-sdk/hardware-trezor`

## README

# 卡多诺 JS SDK 硬件 Trezor

卡德诺生态系统中Trezor设备的硬件钱包集成. 这个软件包为Trezor硬件钱包提供了安全的密钥管理和交易签名能力.

## 特征

-   🔐 **安全密钥管理** - 私人钥匙从不离开Trezor设备
-   🔄 **多主密钥生成方案** - 支持ICARUS、ICARUS TREZOR和LEDGER主键生成算法
-   📝 **交易签名** - 在硬件上安全地签署卡达诺交易
-   🏗️ **类型脚本支持** - 全面安全和情报支持
-   🔌 **Trezor 连接集成** - 在正式的Trezor连接图书馆上建造

## 安装

```bash
npm install @cardano-sdk/hardware-trezor
# or
yarn add @cardano-sdk/hardware-trezor
```

## 先决条件

-   **Trezor 设备** - T型、一型或更新型
-   **特雷佐尔桥** - USB通讯所需
-   **节点.js** - 第16.20.1或以上版本

### 快速设置

对于Trezor测试环境的自动设置:

```bash
# Set up Trezor testing environment (from wallet package)
./packages/wallet/scripts/setup-hw-testing.sh

# Or install Trezor Bridge only
./packages/wallet/scripts/install-trezor-bridge.sh
```

## 快速启动

### 基本用途

```typescript
import { TrezorKeyAgent } from '@cardano-sdk/hardware-trezor';
import { Cardano, CommunicationType } from '@cardano-sdk/core';

// Create a key agent with default settings
const keyAgent = await TrezorKeyAgent.createWithDevice({
  chainId: Cardano.ChainIds.Mainnet,
  trezorConfig: {
    communicationType: CommunicationType.Node,
    manifest: {
      appUrl: 'https://your-app.com',
      email: 'contact@your-app.com'
    }
  }
}, dependencies);
```

### 带有自定义衍生类型

```typescript
import { TrezorKeyAgent } from '@cardano-sdk/hardware-trezor';
import { Cardano, CommunicationType } from '@cardano-sdk/core';

// Create a key agent with specific derivation type
const keyAgent = await TrezorKeyAgent.createWithDevice({
  chainId: Cardano.ChainIds.Mainnet,
  trezorConfig: {
    communicationType: CommunicationType.Node,
    derivationType: 'ICARUS', // or 'ICARUS_TREZOR', 'LEDGER'
    manifest: {
      appUrl: 'https://your-app.com',
      email: 'contact@your-app.com'
    }
  }
}, dependencies);
```

## 主密钥生成方案

软件包支持三种主密钥生成算法与不同的钱包类型相兼容:

### ICARUS( 碱- 软件钱包)

-   **数值**数字 : `'ICARUS'`
-   **使用大小写**: 软件钱包
-   **算法**: 标准CIP-3(BIP-39 → Ed25519-BIP32)
-   **技术流动**数字 : `Mnemonic → entropy → BIP-39 seed (using PBKDF2-HMAC-SHA512, with optional passphrase) → ed25519-bip32 master key (CIP-3 spec)`

### ICARUS TREZOR( 外观硬件兼容性)

-   **数值**数字 : `'ICARUS_TREZOR'`
-   **使用大小写**: Trezor 硬件钱包
-   **算法**:Trezor为CIP-3的变种,有不同的PRF为24个字的映射
-   **技术细节**:Trezor在历史上在处理24个字的默默论时如何将BIP-39种子变成根主键上存在分歧. 坚固软件没有做一直接的Icarus(CIP-3)根生成,而是在将种子扩展为Ed25519-BIP32主键时使用了略有不同的PRF步骤.

### LEDGER( 打印硬件钱包)

-   **数值**数字 : `'LEDGER'`
-   **使用大小写**: 编目硬件钱包
-   **算法**: 编者CIP-3的执行

## 密钥差异: ICARUS vs ICARUS TREZOR

**行为:**

-   **12/18个字**数字 : `ICARUS` 财务报告和审定财务报表 `ICARUS_TREZOR` 生成相同的密钥
-   **24 个字**数字 : `ICARUS` 财务报告和审定财务报表 `ICARUS_TREZOR` 生成不同的密钥

> **重要吗**: 当恢复Trezor钱包时,使用 `ICARUS_TREZOR` 24个字的Mnemonics 源于Trezor设备, 否则你会得到错误的地址.

**为什么这很重要:** 如果您正在写入代码以恢复一个Trezor钱包, 您必须选择正确的导出方案(`ICARUS_TREZOR`),如果元音出自一出特雷佐克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克.

### 用法实例

```typescript
// Software wallet compatibility
const softwareWallet = await TrezorKeyAgent.createWithDevice({
  chainId: Cardano.ChainIds.Mainnet,
  trezorConfig: { derivationType: 'ICARUS' }
});

// Trezor wallet (uses internal default)
const trezorWallet = await TrezorKeyAgent.createWithDevice({
  chainId: Cardano.ChainIds.Mainnet,
  trezorConfig: { /* no derivationType */ }
});

// Ledger wallet migration
const ledgerWallet = await TrezorKeyAgent.createWithDevice({
  chainId: Cardano.ChainIds.Mainnet,
  trezorConfig: { derivationType: 'LEDGER' }
});
```

## 配置

### Trezor 连接接口

```typescript
interface TrezorConfig {
  communicationType: CommunicationType;
  derivationType?: 'ICARUS' | 'ICARUS_TREZOR' | 'LEDGER'; // Master key generation scheme
  manifest: {
    appUrl: string;
    email: string;
  };
  shouldHandlePassphrase?: boolean;
}
```

### 通信类型

-   **`CommunicationType.Node`** - 通过Trezor桥的USB通信(为Node.js推荐)
-   **`CommunicationType.Web`** - 网络通信(用于浏览器环境)

## API 参考

### 特雷佐凯特代理公司

#### `createWithDevice(options, dependencies)`

创建新的 TrezorKeyAgent 实例,并附带连接的 Trezor 设备.

**参数:**

-   `options.chainId` - 卡德诺链式ID(主网、Preprod等)
-   `options.trezorConfig` - Trezor 配置对象
-   `dependencies` - 必要的依赖关系(crypto、logger等)

**回返情况:** `Promise<TrezorKeyAgent>`

#### `getXpub(props)`

从Trezor设备中获取扩展公钥.

**参数:**

-   `props.purpose` - 关键目的(付款、购买等)
-   `props.accountIndex` - 账户指数
-   `props.derivationType` - 可选主键生成方案

**回返情况:** `Promise<Bip32PublicKeyHex>`

#### `signTransaction(txBody, context)`

使用 Trezor 设备签署 Cardano 交易 .

**参数:**

-   `txBody` - 要签名的交易机构
-   `context` - 签名上下文(地址、关键路径等)

**回返情况:** `Promise<CardanoTxWitnesses>`

## 处理错误

该套件为常见情景提供全面的错误处理:

```typescript
import { TrezorKeyAgent } from '@cardano-sdk/hardware-trezor';

try {
  const keyAgent = await TrezorKeyAgent.createWithDevice(config, deps);
} catch (error) {
  if (error.message.includes('Trezor transport failed')) {
    // Handle device connection issues
    console.error('Please ensure your Trezor device is connected and unlocked');
  } else if (error.message.includes('Authentication failure')) {
    // Handle authentication issues
    console.error('Please check your Trezor device and try again');
  }
}
```

## 解决问题

### 共同问题

1.  **"雷佐运输失败"**
    
    -   确保Trezor桥安装和运行
    -   检查 USB 连接
    -   校验设备已解锁
2.  **"校正失败"**
    
    -   解锁您的 Trezor 设备
    -   使用此设备关闭其他应用程序
    -   尝试重新连接设备
3.  **错误的主密钥生成方案**
    
    -   校验主密钥生成方案符合钱包的来源
    -   请检查access-date=中的日期值 (帮助) M

### 设备设置

1.  **安装 Trezor 桥**
    
    ```bash
    # Download from https://suite.trezor.io/trezor-bridge
    # Or install via package manager
    ```
    
2.  **连接和解锁设备**
    
    -   通过 USB 连接您的 Trezor 设备
    -   使用您的 PIN 解锁设备
    -   确保没有其它应用程序使用此设备

## 实例

### 完成钱包整合

```typescript
import { TrezorKeyAgent } from '@cardano-sdk/hardware-trezor';
import { createPersonalWallet } from '@cardano-sdk/wallet';
import { Cardano, CommunicationType } from '@cardano-sdk/core';

async function createTrezorWallet() {
  // Create key agent
  const keyAgent = await TrezorKeyAgent.createWithDevice({
    chainId: Cardano.ChainIds.Mainnet,
    trezorConfig: {
      communicationType: CommunicationType.Node,
      derivationType: 'ICARUS_TREZOR', // or omit to use Trezor's internal default
      manifest: {
        appUrl: 'https://my-cardano-app.com',
        email: 'support@my-cardano-app.com'
      }
    }
  }, dependencies);

  // Create wallet
  const wallet = createPersonalWallet(
    { name: 'My Trezor Wallet' },
    {
      keyAgent,
      // ... other providers
    }
  );

  return wallet;
}
```

## 发展

### 运行测试

```bash
# Run all tests
yarn test

# Run with coverage
yarn test --coverage

# Run specific test file
yarn test TrezorKeyAgent.test.ts
```

### 大楼

```bash
# Build the package
yarn build

# Build and watch for changes
yarn build --watch
```

## 执行细节

### 默认行为

否时 `derivationType` 指定于 `TrezorConfig`,SDK不通过衍生类型到Trezor,允许Trezor使用自己的内部默认:

````typescript
const trezorConfig: TrezorConfig = {
  communicationType: CommunicationType.Node,
  manifest: {
    appUrl: 'https://your.application.com',
    email: 'email@developer.com'
  }
  // No derivationType specified - Trezor uses its internal default
};

## Troubleshooting

### Common Issues

1. **Wrong addresses when restoring Trezor wallet**: Use `ICARUS_TREZOR` for 24-word mnemonics that originated from Trezor devices
2. **Same keys for different schemes**: This is expected for 12/18-word seeds with `ICARUS` and `ICARUS_TREZOR`
3. **Test failures**: Ensure tests account for both 12/18 and 24-word seed scenarios

### Debugging

To determine which scenario you're dealing with:

```typescript
const defaultXPub = defaultKeyAgent.extendedAccountPublicKey;
const icarusXPub = icarusKeyAgent.extendedAccountPublicKey;

if (defaultXPub === icarusXPub) {
  console.log('12/18 word seed detected - ICARUS and ICARUS_TREZOR master key generation schemes are identical');
} else {
  console.log('24 word seed detected - ICARUS and ICARUS_TREZOR master key generation schemes are different');
}
````

## 相关文档

-   [Cardano JS SDK 文档](https://github.com/input-output-hk/cardano-js-sdk)
-   [Trezor 连接文档](https://docs.trezor.io/trezor-connect/)
-   [CIP-1852: Cardano的HD钱包](https://cips.cardano.org/cips/cip1852/)
-   [CIP-3:钱包密钥生成](https://cips.cardano.org/cips/cip3/)

## 许可证

这个项目根据Apache许可证2.0获得许可——见 [自由主义](https://npmcn.com/package/%40cardano-sdk/hardware-trezor/LICENSE) 详细文件.

## 支助

关于议题和问题清单:

-   [GitHub 问题](https://github.com/input-output-hk/cardano-js-sdk/issues)
-   [卡多诺社区](https://cardano.org/community)

## 常见问题

### @cardano-sdk/hardware-trezor 是什么？

绘图和与Trezor硬件的整合

### 如何安装 @cardano-sdk/hardware-trezor？

在项目目录运行 npm install @cardano-sdk/hardware-trezor，或使用 pnpm add / yarn add / bun add。

### @cardano-sdk/hardware-trezor 支持 TypeScript 吗？

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

### @cardano-sdk/hardware-trezor 支持 ESM 还是 CommonJS？

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

### @cardano-sdk/hardware-trezor 需要什么版本的 Node\.js？

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

### @cardano-sdk/hardware-trezor 可以商用吗？

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

### @cardano-sdk/hardware-trezor 的下载量有多少？

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

### @cardano-sdk/hardware-trezor 还在维护吗？

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