@cardano-sdk/hardware-trezor
Advanced tools
Hardware wallet integration for Trezor devices in the Cardano ecosystem. This package provides secure key management and transaction signing capabilities for Trezor hardware wallets.
npm install @cardano-sdk/hardware-trezor
# or
yarn add @cardano-sdk/hardware-trezor
For automated setup of the Trezor testing environment:
# 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: 'contact@your-app.com'
}
}
}, 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: 'contact@your-app.com'
}
}
}, dependencies);
The package supports three master key generation algorithms for compatibility with different wallet types:
'ICARUS'Mnemonic → entropy → BIP-39 seed (using PBKDF2-HMAC-SHA512, with optional passphrase) → ed25519-bip32 master key (CIP-3 spec)'ICARUS_TREZOR''LEDGER'Behavior:
ICARUS and ICARUS_TREZOR produce identical keysICARUS and ICARUS_TREZOR produce different keys⚠️ Important: When restoring a Trezor wallet, use
ICARUS_TREZORfor 24-word mnemonics that originated from Trezor devices, otherwise you'll get wrong addresses.
Why it matters:
If you're writing code to restore a Trezor wallet, you must select the correct derivation scheme (ICARUS_TREZOR) if the mnemonic came from a Trezor, otherwise you'll get a completely different xpub tree and addresses won't match.
// 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' }
});
interface TrezorConfig {
communicationType: CommunicationType;
derivationType?: 'ICARUS' | 'ICARUS_TREZOR' | 'LEDGER'; // Master key generation scheme
manifest: {
appUrl: string;
email: string;
};
shouldHandlePassphrase?: boolean;
}
CommunicationType.Node - USB communication via Trezor Bridge (recommended for Node.js)CommunicationType.Web - Web-based communication (for browser environments)createWithDevice(options, dependencies)Creates a new TrezorKeyAgent instance with a connected Trezor device.
Parameters:
options.chainId - Cardano chain ID (Mainnet, Preprod, etc.)options.trezorConfig - Trezor configuration objectdependencies - Required dependencies (crypto, logger, etc.)Returns: Promise<TrezorKeyAgent>
getXpub(props)Retrieves the extended public key from the Trezor device.
Parameters:
props.purpose - Key purpose (Payment, Stake, etc.)props.accountIndex - Account indexprops.derivationType - Optional master key generation scheme overrideReturns: Promise<Bip32PublicKeyHex>
signTransaction(txBody, context)Signs a Cardano transaction using the Trezor device.
Parameters:
txBody - Transaction body to signcontext - Signing context (addresses, key paths, etc.)Returns: Promise<CardanoTxWitnesses>
The package provides comprehensive error handling for common scenarios:
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');
}
}
"Trezor transport failed"
"Authentication failure"
Wrong master key generation scheme
Install Trezor Bridge
# Download from https://suite.trezor.io/trezor-bridge
# Or install via package manager
Connect and Unlock Device
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;
}
# 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
When no derivationType is specified in the TrezorConfig, the SDK passes no derivation type to Trezor, allowing Trezor to use its own internal default:
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');
}
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
For issues and questions:
FAQs
Mappings and integration with Trezor hardware
The npm package @cardano-sdk/hardware-trezor receives a total of 1,485 weekly downloads. As such, @cardano-sdk/hardware-trezor popularity was classified as popular.
We found that @cardano-sdk/hardware-trezor demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Socket found a Rust typosquat (finch-rust) that loads sha-rust to steal credentials, using impersonation and an unpinned dependency to auto-deliver updates.
Research
/Security Fundamentals
A pair of typosquatted Go packages posing as Google’s UUID library quietly turn helper functions into encrypted exfiltration channels to a paste site, putting developer and CI data at risk.
Security News
November CVE publications fell 25% YoY even as 2025 totals rose, showing how a few major CNAs can swing “global” counts and skew perceived risk.