0
# Ledger Hardware Wallet Ethereum Application API
1
2
The @ledgerhq/hw-app-eth library provides a comprehensive TypeScript API for communicating with Ledger Hardware Wallets to perform Ethereum-related operations. It enables developers to integrate Ledger wallet support into Ethereum applications with features for address generation, transaction signing, message signing (including EIP-712), StarkEx protocol support, and various Ethereum 2.0 operations.
3
4
## Package Information
5
6
- **Package Name**: @ledgerhq/hw-app-eth
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @ledgerhq/hw-app-eth`
10
11
## Core Imports
12
13
```typescript
14
import Eth from "@ledgerhq/hw-app-eth";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const Eth = require("@ledgerhq/hw-app-eth").default;
21
```
22
23
Named imports for utilities and services:
24
25
```typescript
26
import Eth, { ledgerService, hexBuffer, splitPath, StarkQuantizationType } from "@ledgerhq/hw-app-eth";
27
```
28
29
## Basic Usage
30
31
```typescript
32
import Transport from "@ledgerhq/hw-transport-node-hid";
33
import Eth from "@ledgerhq/hw-app-eth";
34
35
// Initialize transport and Eth instance
36
const transport = await Transport.create();
37
const eth = new Eth(transport);
38
39
// Get Ethereum address
40
const result = await eth.getAddress("44'/60'/0'/0/0");
41
console.log(result.address); // 0x...
42
43
// Sign a transaction
44
const signature = await eth.signTransaction(
45
"44'/60'/0'/0/0",
46
"f86b808504a817c800825208943535353535353535353535353535353535353535880de0b6b3a7640000801ca0a95f3c7a0e8c5b7d2a3e3a7a6d2c2b2c2b2c2b2c2b2c2b2c2b2c2b2c2ba0"
47
);
48
console.log(signature); // { r: "...", s: "...", v: "..." }
49
50
// Sign a personal message
51
const messageSignature = await eth.signPersonalMessage(
52
"44'/60'/0'/0/0",
53
Buffer.from("Hello Ledger").toString("hex")
54
);
55
console.log(messageSignature); // { r: "...", s: "...", v: 27 }
56
```
57
58
## Architecture
59
60
The library is built around several key components:
61
62
- **Eth Class**: Main API class providing all hardware wallet operations
63
- **Transaction Resolution**: Automatic resolution of transaction metadata for clear signing
64
- **Service Layer**: ERC20, NFT, and contract plugin services for enhanced transaction display
65
- **Module System**: Specialized modules for EIP712, Uniswap, and domain resolution
66
- **Utility Functions**: Helper functions for transaction processing and data conversion
67
- **StarkEx Support**: Complete support for StarkEx layer 2 protocol operations
68
69
## Capabilities
70
71
### Core Operations
72
73
Essential hardware wallet operations including address generation, app configuration, and basic device interaction.
74
75
```typescript { .api }
76
class Eth {
77
constructor(transport: Transport, scrambleKey?: string, loadConfig?: LoadConfig);
78
79
getAddress(
80
path: string,
81
boolDisplay?: boolean,
82
boolChaincode?: boolean,
83
chainId?: string
84
): Promise<{publicKey: string; address: string; chainCode?: string}>;
85
86
getAppConfiguration(): Promise<{
87
arbitraryDataEnabled: number;
88
erc20ProvisioningNecessary: number;
89
starkEnabled: number;
90
starkv2Supported: number;
91
version: string;
92
}>;
93
94
setLoadConfig(loadConfig: LoadConfig): void;
95
}
96
```
97
98
[Core Operations](./core-operations.md)
99
100
### Transaction Signing
101
102
Comprehensive transaction signing capabilities with automatic metadata resolution for clear signing on hardware devices.
103
104
```typescript { .api }
105
signTransaction(
106
path: string,
107
rawTxHex: string,
108
resolution?: LedgerEthTransactionResolution | null
109
): Promise<{s: string; v: string; r: string}>;
110
111
clearSignTransaction(
112
path: string,
113
rawTxHex: string,
114
resolutionConfig: ResolutionConfig,
115
throwOnError?: boolean
116
): Promise<{r: string; s: string; v: string}>;
117
```
118
119
[Transaction Signing](./transaction-signing.md)
120
121
### Message Signing
122
123
Support for personal message signing and EIP-712 structured data signing with full type safety.
124
125
```typescript { .api }
126
signPersonalMessage(
127
path: string,
128
messageHex: string
129
): Promise<{v: number; s: string; r: string}>;
130
131
signEIP712Message(
132
path: string,
133
jsonMessage: EIP712Message,
134
fullImplem?: boolean
135
): Promise<{v: number; s: string; r: string}>;
136
137
signEIP712HashedMessage(
138
path: string,
139
domainSeparatorHex: string,
140
hashStructMessageHex: string
141
): Promise<{v: number; s: string; r: string}>;
142
```
143
144
[Message Signing](./message-signing.md)
145
146
### StarkEx Protocol
147
148
Complete support for StarkEx layer 2 protocol operations including orders, transfers, and quantum provisioning.
149
150
```typescript { .api }
151
starkGetPublicKey(path: string, boolDisplay?: boolean): Promise<Buffer>;
152
153
starkSignOrder_v2(
154
path: string,
155
sourceTokenAddress: string | undefined,
156
sourceQuantizationType: StarkQuantizationType,
157
sourceQuantization: BigNumber | undefined,
158
sourceMintableBlobOrTokenId: BigNumber | undefined,
159
destinationTokenAddress: string | undefined,
160
destinationQuantizationType: StarkQuantizationType,
161
destinationQuantization: BigNumber | undefined,
162
destinationMintableBlobOrTokenId: BigNumber | undefined,
163
sourceVault: number,
164
destinationVault: number,
165
amountSell: BigNumber,
166
amountBuy: BigNumber,
167
nonce: number,
168
timestamp: number
169
): Promise<Buffer | {r: string; s: string}>;
170
171
type StarkQuantizationType = "eth" | "erc20" | "erc721" | "erc20mintable" | "erc721mintable";
172
```
173
174
[StarkEx Protocol](./starkex.md)
175
176
### Services and Utilities
177
178
Service layer for transaction resolution and utility functions for data processing.
179
180
```typescript { .api }
181
const ledgerService: LedgerEthTransactionService;
182
183
function hexBuffer(str: string): Buffer;
184
function splitPath(path: string): number[];
185
function getV(vFromDevice: number, chainId: BigNumber, transactionType: Transaction["type"]): string;
186
function mergeResolutions(resolutionsArray: Partial<LedgerEthTransactionResolution>[]): LedgerEthTransactionResolution;
187
```
188
189
[Services and Utilities](./services-utilities.md)
190
191
### Advanced Features
192
193
Advanced capabilities including Ethereum 2.0 support, EIP-1024 encryption, and device information providers.
194
195
```typescript { .api }
196
eth2GetPublicKey(path: string, boolDisplay?: boolean): Promise<{publicKey: string}>;
197
eth2SetWithdrawalIndex(withdrawalIndex: number): Promise<boolean>;
198
199
getEIP1024PublicEncryptionKey(path: string, boolDisplay?: boolean): Promise<{publicKey: string}>;
200
getEIP1024SharedSecret(
201
path: string,
202
remotePublicKeyHex: string,
203
boolDisplay?: boolean
204
): Promise<{sharedSecret: string}>;
205
206
provideERC20TokenInformation(data: string): Promise<boolean>;
207
setExternalPlugin(payload: string, signature?: string): Promise<boolean>;
208
provideNFTInformation(data: string): Promise<boolean>;
209
```
210
211
[Advanced Features](./advanced-features.md)
212
213
## Core Types
214
215
```typescript { .api }
216
interface LoadConfig {
217
nftExplorerBaseURL?: string | null;
218
pluginBaseURL?: string | null;
219
extraPlugins?: any | null;
220
cryptoassetsBaseURL?: string | null;
221
calServiceURL?: string | null;
222
}
223
224
interface LedgerEthTransactionResolution {
225
erc20Tokens: Array<string>;
226
nfts: Array<string>;
227
externalPlugin: Array<{payload: string; signature: string}>;
228
plugin: Array<string>;
229
domains: DomainDescriptor[];
230
}
231
232
interface ResolutionConfig {
233
nft?: boolean;
234
externalPlugins?: boolean;
235
erc20?: boolean;
236
domains?: DomainDescriptor[];
237
uniswapV3?: boolean;
238
}
239
240
interface LedgerEthTransactionService {
241
resolveTransaction(
242
rawTxHex: string,
243
loadConfig: LoadConfig,
244
resolutionConfig: ResolutionConfig
245
): Promise<LedgerEthTransactionResolution>;
246
}
247
```
248
249
## Error Handling
250
251
The library includes custom error classes for common failure scenarios:
252
253
```typescript { .api }
254
class EthAppPleaseEnableContractData extends Error {
255
constructor(message: string);
256
}
257
258
class EthAppNftNotSupported extends Error {
259
constructor(message: string);
260
}
261
```
262
263
When transaction signing fails due to contract data being disabled, the library throws `EthAppPleaseEnableContractData`. For unsupported NFT operations, `EthAppNftNotSupported` is thrown.