0
# Services and Utilities
1

2
Service layer for transaction resolution and utility functions for data processing. The library includes comprehensive services for resolving ERC20 tokens, NFTs, contract plugins, and various utility functions for transaction and data manipulation.
3

4
## Capabilities
5

6
### Ledger Service
7

8
Main transaction resolution service that automatically resolves transaction metadata for clear signing.
9

10
```typescript { .api }
11
/**
12
 * Main ledger service for transaction resolution
13
 */
14
const ledgerService: LedgerEthTransactionService;
15

16
interface LedgerEthTransactionService {
17
  /**
18
   * Resolve transaction metadata for clear signing display
19
   * @param rawTxHex - Raw transaction data as hex string  
20
   * @param loadConfig - Service configuration for external APIs
21
   * @param resolutionConfig - Configuration for resolution features
22
   * @returns Resolved transaction metadata
23
   */
24
  resolveTransaction(
25
    rawTxHex: string,
26
    loadConfig: LoadConfig,
27
    resolutionConfig: ResolutionConfig
28
  ): Promise<LedgerEthTransactionResolution>;
29
}
30
```
31

32
**Usage Example:**
33

34
```typescript
35
import { ledgerService } from "@ledgerhq/hw-app-eth";
36

37
// Resolve transaction with all features enabled
38
const resolution = await ledgerService.resolveTransaction(
39
  rawTxHex,
40
  {
41
    nftExplorerBaseURL: "https://nft-api.com",
42
    pluginBaseURL: "https://plugin-api.com",
43
    cryptoassetsBaseURL: "https://crypto-api.com"
44
  },
45
  {
46
    erc20: true,
47
    nft: true,
48
    externalPlugins: true,
49
    uniswapV3: true
50
  }
51
);
52

53
console.log(resolution.erc20Tokens); // Resolved ERC20 addresses
54
console.log(resolution.nfts); // Resolved NFT contract addresses
55
console.log(resolution.externalPlugin); // Plugin configurations
56
```
57

58
### ERC20 Services
59

60
Services for resolving ERC20 token information and metadata.
61

62
```typescript { .api }
63
/**
64
 * Find ERC20 signature information for a given chain
65
 * @param loadConfig - Service configuration
66
 * @param chainId - Blockchain chain ID
67
 * @returns ERC20 signatures blob or null
68
 */
69
function findERC20SignaturesInfo(
70
  loadConfig: LoadConfig,
71
  chainId: number
72
): Promise<string | null | undefined>;
73

74
/**
75
 * Get token information by contract address and chain ID
76
 * @param contractAddress - ERC20 contract address
77
 * @param chainId - Blockchain chain ID  
78
 * @param erc20SignaturesBlob - ERC20 signatures data blob
79
 * @returns Token information or null
80
 */
81
function byContractAddressAndChainId(
82
  contractAddress: string,
83
  chainId: number,
84
  erc20SignaturesBlob: string | null | undefined
85
): TokenInfo | null | undefined;
86

87
interface TokenInfo {
88
  /** Token contract address */
89
  contractAddress: string;
90
  /** Token decimal places */
91
  decimals: number;
92
  /** Token symbol (e.g., "USDC") */
93
  symbol: string;
94
  /** Token full name */
95
  name: string;
96
  /** Chain ID where token exists */
97
  chainId: number;
98
}
99
```
100

101
**Usage Examples:**
102

103
```typescript
104
// Get ERC20 signatures for Ethereum mainnet
105
const signatures = await findERC20SignaturesInfo(loadConfig, 1);
106

107
// Look up USDC token information
108
const usdcInfo = byContractAddressAndChainId(
109
  "0xA0b86a33E6776a9fEddac4F0c0bfB3F4a9d7d3e7",
110
  1, // Ethereum mainnet
111
  signatures
112
);
113

114
if (usdcInfo) {
115
  console.log(usdcInfo.symbol); // "USDC"
116
  console.log(usdcInfo.decimals); // 6
117
  console.log(usdcInfo.name); // "USD Coin"
118
}
119
```
120

121
### NFT Services
122

123
Services for resolving NFT collection information and loading NFT-specific plugins.
124

125
```typescript { .api }
126
/**
127
 * Get NFT collection information
128
 * @param contractAddress - NFT contract address
129
 * @param chainId - Blockchain chain ID
130
 * @param loadConfig - Service configuration
131
 * @returns NFT collection metadata
132
 */
133
function getNFTInfo(
134
  contractAddress: string,
135
  chainId: number,
136
  loadConfig: LoadConfig
137
): Promise<any>;
138

139
/**
140
 * Load NFT-specific plugin data
141
 * @param contractAddress - NFT contract address
142
 * @param selector - Method selector (4-byte function signature)
143
 * @param chainId - Blockchain chain ID
144
 * @param loadConfig - Service configuration
145
 * @returns Plugin data or null
146
 */
147
function loadNftPlugin(
148
  contractAddress: string,
149
  selector: string,
150
  chainId: number,
151
  loadConfig: LoadConfig
152
): Promise<string | null>;
153
```
154

155
**Usage Examples:**
156

157
```typescript
158
// Get NFT collection information
159
const nftInfo = await getNFTInfo(
160
  "0x1234567890123456789012345678901234567890", // CryptoPunks
161
  1, // Ethereum mainnet
162
  loadConfig
163
);
164
console.log(nftInfo.name); // Collection name
165
console.log(nftInfo.symbol); // Collection symbol
166

167
// Load NFT plugin for specific method
168
const pluginData = await loadNftPlugin(
169
  "0x1234567890123456789012345678901234567890",
170
  "0xa22cb465", // setApprovalForAll selector
171
  1,
172
  loadConfig
173
);
174
```
175

176
### Contract Services
177

178
Services for loading contract method information and external plugins.
179

180
```typescript { .api }
181
/**
182
 * Load contract method information for clear signing
183
 * @param contractAddress - Contract address
184
 * @param selector - Method selector (4-byte function signature)
185
 * @param chainId - Blockchain chain ID
186
 * @param loadConfig - Service configuration
187
 * @returns Contract method metadata
188
 */
189
function loadInfosForContractMethod(
190
  contractAddress: string,
191
  selector: string,
192
  chainId: number,
193
  loadConfig: LoadConfig
194
): Promise<any>;
195
```
196

197
**Usage Example:**
198

199
```typescript
200
// Load contract method information
201
const methodInfo = await loadInfosForContractMethod(
202
  "0xContractAddress123...",
203
  "0x095ea7b3", // approve(address,uint256) selector
204
  1, // Ethereum mainnet
205
  loadConfig
206
);
207
console.log(methodInfo); // Method signature and parameter info
208
```
209

210
### Load Configuration Service
211

212
Service for merging and managing load configurations.
213

214
```typescript { .api }
215
/**
216
 * Get merged load configuration with defaults
217
 * @param userLoadConfig - User-provided configuration (optional)
218
 * @returns Complete load configuration with defaults
219
 */
220
function getLoadConfig(userLoadConfig?: LoadConfig): LoadConfig;
221
```
222

223
**Usage Example:**
224

225
```typescript
226
// Get default configuration
227
const defaultConfig = getLoadConfig();
228

229
// Merge with user configuration
230
const customConfig = getLoadConfig({
231
  nftExplorerBaseURL: "https://custom-nft-api.com",
232
  pluginBaseURL: null // Disable plugin loading
233
});
234
```
235

236
## Utility Functions
237

238
### String and Buffer Utilities
239

240
Utilities for hex string processing and buffer conversion.
241

242
```typescript { .api }
243
/**
244
 * Pad hex string to even length
245
 * @param str - Hex string to pad
246
 * @returns Padded hex string
247
 */
248
function padHexString(str: string): string;
249

250
/**
251
 * Convert hex string to buffer, handling 0x prefix
252
 * @param str - Hex string (with or without 0x prefix)
253
 * @returns Buffer representation
254
 */
255
function hexBuffer(str: string): Buffer;
256

257
/**
258
 * Safe hex buffer conversion with null handling
259
 * @param str - Hex string, null, or undefined
260
 * @returns Buffer, null, or undefined
261
 */
262
function maybeHexBuffer(str: string | null | undefined): Buffer | null | undefined;
263

264
/**
265
 * Convert integer to hex string with specified byte length
266
 * @param int - Integer value
267
 * @param bytes - Number of bytes for output
268
 * @returns Hex string with specified length
269
 */
270
function intAsHexBytes(int: number, bytes: number): string;
271
```
272

273
**Usage Examples:**
274

275
```typescript
276
// Pad hex string
277
const padded = padHexString("abc"); // "0abc"
278

279
// Convert hex to buffer
280
const buffer = hexBuffer("0x1234abcd"); // Buffer with hex data
281
const buffer2 = hexBuffer("1234abcd"); // Works without 0x prefix
282

283
// Safe conversion with null handling
284
const result = maybeHexBuffer(null); // null
285
const result2 = maybeHexBuffer("0x1234"); // Buffer
286

287
// Integer to hex bytes
288
const hex = intAsHexBytes(255, 2); // "00ff"
289
const hex2 = intAsHexBytes(65535, 4); // "0000ffff"
290
```
291

292
### Path Utilities
293

294
Utilities for BIP32 derivation path processing.
295

296
```typescript { .api }
297
/**
298
 * Parse BIP32 derivation path into numeric array
299
 * @param path - BIP32 path string (e.g., "44'/60'/0'/0/0")
300
 * @returns Array of path components as numbers
301
 */
302
function splitPath(path: string): number[];
303
```
304

305
**Usage Example:**
306

307
```typescript
308
// Parse BIP32 path
309
const pathComponents = splitPath("44'/60'/0'/0/0");
310
console.log(pathComponents); // [2147483692, 2147483708, 2147483648, 0, 0]
311

312
// Parse complex path
313
const components = splitPath("44'/60'/1'/5/10");
314
console.log(components); // [2147483692, 2147483708, 2147483649, 5, 10]
315
```
316

317
### Transaction Utilities
318

319
Utilities for transaction signature calculation and processing.
320

321
```typescript { .api }
322
/**
323
 * Calculate transaction signature V value
324
 * @param vFromDevice - V value from hardware wallet
325
 * @param chainId - Blockchain chain ID
326
 * @param transactionType - Transaction type (legacy, EIP-1559, etc.)
327
 * @returns Calculated V value as string
328
 */
329
function getV(
330
  vFromDevice: number,
331
  chainId: BigNumber,
332
  transactionType: Transaction["type"]
333
): string;
334

335
/**
336
 * Extract signature parity from V value
337
 * @param vFromDevice - V value from hardware wallet
338
 * @param chainId - Blockchain chain ID
339
 * @param transactionType - Transaction type
340
 * @returns Signature parity (0 or 1)
341
 */
342
function getParity(
343
  vFromDevice: number,
344
  chainId: BigNumber,
345
  transactionType: Transaction["type"]
346
): 0 | 1;
347

348
/**
349
 * Convert chain ID to 4-byte integer
350
 * @param chainId - Chain ID as BigNumber or number
351
 * @returns Chain ID as 4-byte integer
352
 */
353
function getChainIdAsUint32(chainId: BigNumber | number): number;
354

355
/**
356
 * Split transaction for device transmission
357
 * @param transactionRlp - RLP-encoded transaction
358
 * @param derivationPath - BIP32 path as buffer
359
 * @param transactionType - Transaction type
360
 * @returns Array of transaction chunks
361
 */
362
function safeChunkTransaction(
363
  transactionRlp: Buffer,
364
  derivationPath: Buffer,
365
  transactionType: Transaction["type"]
366
): Buffer[];
367
```
368

369
**Usage Examples:**
370

371
```typescript
372
import { BigNumber } from "bignumber.js";
373

374
// Calculate V value for Ethereum mainnet
375
const vValue = getV(27, new BigNumber(1), "legacy");
376
console.log(vValue); // "0x1c"
377

378
// Get signature parity
379
const parity = getParity(28, new BigNumber(1), "legacy");
380
console.log(parity); // 1
381

382
// Convert chain ID to uint32
383
const chainIdUint32 = getChainIdAsUint32(new BigNumber(1));
384
console.log(chainIdUint32); // 1
385

386
// Split large transaction for device
387
const chunks = safeChunkTransaction(
388
  transactionRlpBuffer,
389
  pathBuffer,
390
  "eip1559"
391
);
392
console.log(chunks.length); // Number of chunks needed
393
```
394

395
### Resolution Utilities
396

397
Utilities for merging transaction resolution metadata.
398

399
```typescript { .api }
400
/**
401
 * Merge multiple transaction resolutions into one
402
 * @param resolutionsArray - Array of partial resolution objects
403
 * @returns Merged complete resolution object
404
 */
405
function mergeResolutions(
406
  resolutionsArray: Partial<LedgerEthTransactionResolution>[]
407
): LedgerEthTransactionResolution;
408
```
409

410
**Usage Example:**
411

412
```typescript
413
// Merge multiple resolution sources
414
const erc20Resolution = { erc20Tokens: ["0x123..."], nfts: [], externalPlugin: [], plugin: [], domains: [] };
415
const nftResolution = { erc20Tokens: [], nfts: ["0x456..."], externalPlugin: [], plugin: [], domains: [] };
416

417
const mergedResolution = mergeResolutions([erc20Resolution, nftResolution]);
418
console.log(mergedResolution.erc20Tokens); // ["0x123..."]
419
console.log(mergedResolution.nfts); // ["0x456..."]
420
```
421

422
## Method Selector Constants
423

424
Pre-defined method selectors for common operations.
425

426
```typescript { .api }
427
/** ERC20 clear-signed method selectors */
428
const tokenSelectors: string[];
429
const ERC20_CLEAR_SIGNED_SELECTORS: readonly string[];
430

431
/** ERC721 clear-signed method selectors */
432
const ERC721_CLEAR_SIGNED_SELECTORS: readonly string[];
433

434
/** ERC1155 clear-signed method selectors */  
435
const ERC1155_CLEAR_SIGNED_SELECTORS: readonly string[];
436

437
/** NFT method selectors (ERC721 + ERC1155) */
438
const nftSelectors: string[];
439

440
/** DApp-specific method selectors */
441
const DAPP_SELECTORS: readonly string[];
442
```
443

444
**Usage Examples:**
445

446
```typescript
447
// Check if method is ERC20 clear-signed
448
const isERC20Method = ERC20_CLEAR_SIGNED_SELECTORS.includes("0x095ea7b3"); // approve
449

450
// Check if method is NFT-related
451
const isNFTMethod = nftSelectors.includes("0xa22cb465"); // setApprovalForAll
452

453
// Get all supported clear-signed selectors
454
const allSelectors = [
455
  ...ERC20_CLEAR_SIGNED_SELECTORS,
456
  ...ERC721_CLEAR_SIGNED_SELECTORS,
457
  ...ERC1155_CLEAR_SIGNED_SELECTORS,
458
  ...DAPP_SELECTORS
459
];
460
```