0
# Hardware Wallets
1

2
Hardware wallet adapters for secure, air-gapped transaction signing with custom derivation path support.
3

4
## Capabilities
5

6
### Ledger Wallet
7

8
Hardware wallet integration using WebHID transport with custom derivation path support.
9

10
```typescript { .api }
11
/**
12
 * Ledger hardware wallet adapter with WebHID transport
13
 */
14
class LedgerWalletAdapter extends BaseSignerWalletAdapter {
15
  name: WalletName<'Ledger'>;
16
  url: string;
17
  icon: string;
18
  supportedTransactionVersions: ReadonlySet<TransactionVersion>;
19
  
20
  constructor(config?: LedgerWalletAdapterConfig);
21
  
22
  /** Connect to Ledger device via WebHID */
23
  connect(): Promise<void>;
24
  
25
  /** Disconnect from Ledger device */
26
  disconnect(): Promise<void>;
27
  
28
  /** Sign transaction on hardware device */
29
  signTransaction<T extends Transaction | VersionedTransaction>(transaction: T): Promise<T>;
30
  
31
  /** Sign multiple transactions on hardware device */
32
  signAllTransactions<T extends Transaction | VersionedTransaction>(transactions: T[]): Promise<T[]>;
33
}
34

35
const LedgerWalletName: WalletName<'Ledger'>;
36

37
interface LedgerWalletAdapterConfig {
38
  /** Custom BIP44 derivation path as Buffer */
39
  derivationPath?: Buffer;
40
}
41

42
/**
43
 * Generate BIP44 derivation path for Ledger wallet
44
 * @param account - Account index (default: 0)
45
 * @param change - Change index (default: 0)  
46
 * @returns Buffer containing the derivation path
47
 */
48
function getDerivationPath(account?: number, change?: number): Buffer;
49
```
50

51
**Usage Example:**
52

53
```typescript
54
import { 
55
  LedgerWalletAdapter, 
56
  LedgerWalletName,
57
  getDerivationPath 
58
} from "@solana/wallet-adapter-wallets";
59

60
// Use default derivation path
61
const defaultAdapter = new LedgerWalletAdapter();
62

63
// Use custom derivation path
64
const customAdapter = new LedgerWalletAdapter({
65
  derivationPath: getDerivationPath(1, 0) // Account 1, Change 0
66
});
67

68
await customAdapter.connect();
69

70
// Sign transaction (requires user confirmation on device)
71
const signedTx = await customAdapter.signTransaction(transaction);
72
```
73

74
### Trezor Wallet
75

76
Hardware wallet integration using Trezor Connect with extensive configuration options.
77

78
```typescript { .api }
79
/**
80
 * Trezor hardware wallet adapter with Trezor Connect integration
81
 */
82
class TrezorWalletAdapter extends BaseSignerWalletAdapter {
83
  name: WalletName<'Trezor'>;
84
  url: string;
85
  icon: string;
86
  supportedTransactionVersions: ReadonlySet<TransactionVersion>;
87
  
88
  constructor(config?: TrezorWalletAdapterConfig);
89
  
90
  /** Connect to Trezor device via Trezor Connect */
91
  connect(): Promise<void>;
92
  
93
  /** Disconnect from Trezor device */
94
  disconnect(): Promise<void>;
95
  
96
  /** Sign transaction on Trezor device */
97
  signTransaction<T extends Transaction | VersionedTransaction>(transaction: T): Promise<T>;
98
  
99
  /** Sign multiple transactions on Trezor device */
100
  signAllTransactions<T extends Transaction | VersionedTransaction>(transactions: T[]): Promise<T[]>;
101
}
102

103
const TrezorWalletName: WalletName<'Trezor'>;
104

105
interface TrezorWalletAdapterConfig {
106
  /** Custom derivation path as string (e.g., "m/44'/501'/0'/0'") */
107
  derivationPath?: string;
108
  
109
  /** Custom Trezor Connect URL (for self-hosted instances) */
110
  connectUrl?: string;
111
  
112
  /** Application name shown on Trezor device */
113
  appName?: string;
114
  
115
  /** Developer email for Trezor Connect registration */
116
  email?: string;
117
}
118
```
119

120
**Usage Example:**
121

122
```typescript
123
import { TrezorWalletAdapter, TrezorWalletName } from "@solana/wallet-adapter-wallets";
124

125
const adapter = new TrezorWalletAdapter({
126
  derivationPath: "m/44'/501'/1'/0'", // Account 1
127
  appName: "My Solana App",
128
  email: "developer@example.com"
129
});
130

131
await adapter.connect();
132

133
// Sign transaction (requires user confirmation on device)
134
const signedTx = await adapter.signTransaction(transaction);
135
```
136

137
## Hardware Wallet Patterns
138

139
### Derivation Path Management
140

141
```typescript
142
import { getDerivationPath, LedgerWalletAdapter } from "@solana/wallet-adapter-wallets";
143

144
// Generate paths for multiple accounts
145
const accounts = [0, 1, 2].map(account => ({
146
  account,
147
  derivationPath: getDerivationPath(account, 0),
148
  adapter: new LedgerWalletAdapter({
149
    derivationPath: getDerivationPath(account, 0)
150
  })
151
}));
152

153
// Connect to specific account
154
const selectedAccount = accounts[1];
155
await selectedAccount.adapter.connect();
156
```
157

158
### Error Handling
159

160
```typescript
161
import { 
162
  LedgerWalletAdapter,
163
  WalletNotReadyError,
164
  WalletConnectionError 
165
} from "@solana/wallet-adapter-wallets";
166

167
const adapter = new LedgerWalletAdapter();
168

169
try {
170
  await adapter.connect();
171
} catch (error) {
172
  if (error instanceof WalletNotReadyError) {
173
    console.log("WebHID not supported or device not available");
174
  } else if (error instanceof WalletConnectionError) {
175
    console.log("Failed to connect to Ledger device");
176
  }
177
}
178
```
179

180
### Multi-Device Support
181

182
```typescript
183
// Support both hardware wallets
184
const hardwareWallets = [
185
  new LedgerWalletAdapter(),
186
  new TrezorWalletAdapter({
187
    appName: "My App",
188
    email: "dev@example.com"
189
  })
190
];
191

192
// Check which devices are available
193
const availableWallets = hardwareWallets.filter(
194
  wallet => wallet.readyState === WalletReadyState.Loadable
195
);
196
```
197

198
## Security Considerations
199

200
### Transaction Review
201

202
Hardware wallets require user confirmation for every transaction:
203

204
```typescript
205
// User must physically confirm on device
206
const signedTransaction = await hardwareAdapter.signTransaction(transaction);
207

208
// For multiple transactions, each requires confirmation
209
const signedTransactions = await hardwareAdapter.signAllTransactions([tx1, tx2, tx3]);
210
```
211

212
### Derivation Path Validation
213

214
```typescript
215
import { getDerivationPath } from "@solana/wallet-adapter-wallets";
216

217
// Validate account bounds (typically 0-2147483647)
218
function createLedgerAdapter(accountIndex: number) {
219
  if (accountIndex < 0 || accountIndex > 2147483647) {
220
    throw new Error("Invalid account index");
221
  }
222
  
223
  return new LedgerWalletAdapter({
224
    derivationPath: getDerivationPath(accountIndex, 0)
225
  });
226
}
227
```
228

229
### Additional Transaction-Only Wallets
230

231
These wallets also extend `BaseSignerWalletAdapter` (transaction signing only, no message signing):
232

233
```typescript { .api }
234
// Bitpie Wallet
235
class BitpieWalletAdapter extends BaseSignerWalletAdapter {
236
  name: WalletName<'Bitpie'>;
237
}
238
const BitpieWalletName: WalletName<'Bitpie'>;
239
interface BitpieWalletAdapterConfig {}
240

241
// Coinhub Wallet
242
class CoinhubWalletAdapter extends BaseSignerWalletAdapter {
243
  name: WalletName<'Coinhub'>;
244
}
245
const CoinhubWalletName: WalletName<'Coinhub'>;
246
interface CoinhubWalletAdapterConfig {}
247

248
// MathWallet
249
class MathWalletAdapter extends BaseSignerWalletAdapter {
250
  name: WalletName<'MathWallet'>;
251
}
252
const MathWalletName: WalletName<'MathWallet'>;
253
interface MathWalletAdapterConfig {}
254

255
// SafePal Wallet
256
class SafePalWalletAdapter extends BaseSignerWalletAdapter {
257
  name: WalletName<'SafePal'>;
258
}
259
const SafePalWalletName: WalletName<'SafePal'>;
260
interface SafePalWalletAdapterConfig {}
261

262
// Solong Wallet
263
class SolongWalletAdapter extends BaseSignerWalletAdapter {
264
  name: WalletName<'Solong'>;
265
}
266
const SolongWalletName: WalletName<'Solong'>;
267
interface SolongWalletAdapterConfig {}
268
```
269

270
### WebHID Requirements
271

272
Ledger wallet requires WebHID support:
273

274
```typescript
275
// Check WebHID availability
276
if (!navigator.hid) {
277
  console.log("WebHID not supported - Ledger wallet unavailable");
278
}
279

280
// Check wallet ready state
281
if (ledgerAdapter.readyState === WalletReadyState.Unsupported) {
282
  console.log("Hardware wallet not supported in this environment");
283
}
284
```