or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdcore-operations.mdindex.mdmessage-signing.mdservices-utilities.mdstarkex.mdtransaction-signing.md
tile.json

tessl/npm-ledgerhq--hw-app-eth

Ledger Hardware Wallet Ethereum Application API that enables developers to integrate Ledger wallet support into Ethereum applications for address generation, transaction signing, message signing, and various Ethereum operations.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@ledgerhq/hw-app-eth@6.45.x

To install, run

npx @tessl/cli install tessl/npm-ledgerhq--hw-app-eth@6.45.0

index.mddocs/

Ledger Hardware Wallet Ethereum Application API

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.

Package Information

  • Package Name: @ledgerhq/hw-app-eth
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @ledgerhq/hw-app-eth

Core Imports

import Eth from "@ledgerhq/hw-app-eth";

For CommonJS:

const Eth = require("@ledgerhq/hw-app-eth").default;

Named imports for utilities and services:

import Eth, { ledgerService, hexBuffer, splitPath, StarkQuantizationType } from "@ledgerhq/hw-app-eth";

Basic Usage

import Transport from "@ledgerhq/hw-transport-node-hid";
import Eth from "@ledgerhq/hw-app-eth";

// Initialize transport and Eth instance
const transport = await Transport.create();
const eth = new Eth(transport);

// Get Ethereum address
const result = await eth.getAddress("44'/60'/0'/0/0");
console.log(result.address); // 0x...

// Sign a transaction
const signature = await eth.signTransaction(
  "44'/60'/0'/0/0",
  "f86b808504a817c800825208943535353535353535353535353535353535353535880de0b6b3a7640000801ca0a95f3c7a0e8c5b7d2a3e3a7a6d2c2b2c2b2c2b2c2b2c2b2c2b2c2b2c2ba0"
);
console.log(signature); // { r: "...", s: "...", v: "..." }

// Sign a personal message
const messageSignature = await eth.signPersonalMessage(
  "44'/60'/0'/0/0",
  Buffer.from("Hello Ledger").toString("hex")
);
console.log(messageSignature); // { r: "...", s: "...", v: 27 }

Architecture

The library is built around several key components:

  • Eth Class: Main API class providing all hardware wallet operations
  • Transaction Resolution: Automatic resolution of transaction metadata for clear signing
  • Service Layer: ERC20, NFT, and contract plugin services for enhanced transaction display
  • Module System: Specialized modules for EIP712, Uniswap, and domain resolution
  • Utility Functions: Helper functions for transaction processing and data conversion
  • StarkEx Support: Complete support for StarkEx layer 2 protocol operations

Capabilities

Core Operations

Essential hardware wallet operations including address generation, app configuration, and basic device interaction.

class Eth {
  constructor(transport: Transport, scrambleKey?: string, loadConfig?: LoadConfig);
  
  getAddress(
    path: string,
    boolDisplay?: boolean,
    boolChaincode?: boolean,
    chainId?: string
  ): Promise<{publicKey: string; address: string; chainCode?: string}>;
  
  getAppConfiguration(): Promise<{
    arbitraryDataEnabled: number;
    erc20ProvisioningNecessary: number;
    starkEnabled: number;
    starkv2Supported: number;
    version: string;
  }>;
  
  setLoadConfig(loadConfig: LoadConfig): void;
}

Core Operations

Transaction Signing

Comprehensive transaction signing capabilities with automatic metadata resolution for clear signing on hardware devices.

signTransaction(
  path: string,
  rawTxHex: string,
  resolution?: LedgerEthTransactionResolution | null
): Promise<{s: string; v: string; r: string}>;

clearSignTransaction(
  path: string,
  rawTxHex: string,
  resolutionConfig: ResolutionConfig,
  throwOnError?: boolean
): Promise<{r: string; s: string; v: string}>;

Transaction Signing

Message Signing

Support for personal message signing and EIP-712 structured data signing with full type safety.

signPersonalMessage(
  path: string,
  messageHex: string
): Promise<{v: number; s: string; r: string}>;

signEIP712Message(
  path: string,
  jsonMessage: EIP712Message,
  fullImplem?: boolean
): Promise<{v: number; s: string; r: string}>;

signEIP712HashedMessage(
  path: string,
  domainSeparatorHex: string,
  hashStructMessageHex: string
): Promise<{v: number; s: string; r: string}>;

Message Signing

StarkEx Protocol

Complete support for StarkEx layer 2 protocol operations including orders, transfers, and quantum provisioning.

starkGetPublicKey(path: string, boolDisplay?: boolean): Promise<Buffer>;

starkSignOrder_v2(
  path: string,
  sourceTokenAddress: string | undefined,
  sourceQuantizationType: StarkQuantizationType,
  sourceQuantization: BigNumber | undefined,
  sourceMintableBlobOrTokenId: BigNumber | undefined,
  destinationTokenAddress: string | undefined,
  destinationQuantizationType: StarkQuantizationType,
  destinationQuantization: BigNumber | undefined,
  destinationMintableBlobOrTokenId: BigNumber | undefined,
  sourceVault: number,
  destinationVault: number,
  amountSell: BigNumber,
  amountBuy: BigNumber,
  nonce: number,
  timestamp: number
): Promise<Buffer | {r: string; s: string}>;

type StarkQuantizationType = "eth" | "erc20" | "erc721" | "erc20mintable" | "erc721mintable";

StarkEx Protocol

Services and Utilities

Service layer for transaction resolution and utility functions for data processing.

const ledgerService: LedgerEthTransactionService;

function hexBuffer(str: string): Buffer;
function splitPath(path: string): number[];
function getV(vFromDevice: number, chainId: BigNumber, transactionType: Transaction["type"]): string;
function mergeResolutions(resolutionsArray: Partial<LedgerEthTransactionResolution>[]): LedgerEthTransactionResolution;

Services and Utilities

Advanced Features

Advanced capabilities including Ethereum 2.0 support, EIP-1024 encryption, and device information providers.

eth2GetPublicKey(path: string, boolDisplay?: boolean): Promise<{publicKey: string}>;
eth2SetWithdrawalIndex(withdrawalIndex: number): Promise<boolean>;

getEIP1024PublicEncryptionKey(path: string, boolDisplay?: boolean): Promise<{publicKey: string}>;
getEIP1024SharedSecret(
  path: string,
  remotePublicKeyHex: string,
  boolDisplay?: boolean
): Promise<{sharedSecret: string}>;

provideERC20TokenInformation(data: string): Promise<boolean>;
setExternalPlugin(payload: string, signature?: string): Promise<boolean>;
provideNFTInformation(data: string): Promise<boolean>;

Advanced Features

Core Types

interface LoadConfig {
  nftExplorerBaseURL?: string | null;
  pluginBaseURL?: string | null;
  extraPlugins?: any | null;
  cryptoassetsBaseURL?: string | null;
  calServiceURL?: string | null;
}

interface LedgerEthTransactionResolution {
  erc20Tokens: Array<string>;
  nfts: Array<string>;
  externalPlugin: Array<{payload: string; signature: string}>;
  plugin: Array<string>;
  domains: DomainDescriptor[];
}

interface ResolutionConfig {
  nft?: boolean;
  externalPlugins?: boolean;
  erc20?: boolean;
  domains?: DomainDescriptor[];
  uniswapV3?: boolean;
}

interface LedgerEthTransactionService {
  resolveTransaction(
    rawTxHex: string,
    loadConfig: LoadConfig,
    resolutionConfig: ResolutionConfig
  ): Promise<LedgerEthTransactionResolution>;
}

Error Handling

The library includes custom error classes for common failure scenarios:

class EthAppPleaseEnableContractData extends Error {
  constructor(message: string);
}

class EthAppNftNotSupported extends Error {
  constructor(message: string);
}

When transaction signing fails due to contract data being disabled, the library throws EthAppPleaseEnableContractData. For unsupported NFT operations, EthAppNftNotSupported is thrown.