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.