卡多诺 JS SDK 硬件 Trezor

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

特征

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

安装

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

先决条件

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

快速设置

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

# 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

快速启动

基本用途

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: '[email protected]'
    }
  }
}, dependencies);

带有自定义衍生类型

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: '[email protected]'
    }
  }
}, 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),如果元音出自一出特雷佐克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克.

用法实例

// 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 连接接口

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>

处理错误

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

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 桥

   # Download from https://suite.trezor.io/trezor-bridge
   # Or install via package manager
   

2. 连接和解锁设备

   • 通过 USB 连接您的 Trezor 设备
   • 使用您的 PIN 解锁设备
   • 确保没有其它应用程序使用此设备

实例

完成钱包整合

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: '[email protected]'
      }
    }
  }, dependencies);

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

  return wallet;
}

发展

运行测试

# Run all tests
yarn test

# Run with coverage
yarn test --coverage

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

大楼

# Build the package
yarn build

# Build and watch for changes
yarn build --watch

执行细节

默认行为

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

const trezorConfig: TrezorConfig = {
  communicationType: CommunicationType.Node,
  manifest: {
    appUrl: 'https://your.application.com',
    email: '[email protected]'
  }
  // 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 文档
• Trezor 连接文档
• CIP-1852: Cardano的HD钱包
• CIP-3:钱包密钥生成

许可证

这个项目根据Apache许可证2.0获得许可——见 自由主义 详细文件.

支助

关于议题和问题清单:

• GitHub 问题
• 卡多诺社区