or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

account-balance-errors.mdapplication-manager-errors.mdcurrency-transaction-errors.mddatabase-errors.mddevice-management-errors.mderror-utilities.mdindex.mdnetwork-api-errors.mdtransport-errors.mduser-interaction-errors.md
tile.json

tessl/npm-ledgerhq--errors

Comprehensive error handling system for Ledger hardware wallet applications and libraries

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@ledgerhq/errors@6.10.x

To install, run

npx @tessl/cli install tessl/npm-ledgerhq--errors@6.10.0

index.mddocs/

@ledgerhq/errors

@ledgerhq/errors provides a comprehensive error handling system for Ledger hardware wallet applications and libraries. It includes a collection of custom error classes specifically designed for Ledger device communication, transport protocols, and blockchain interactions with utilities for creating custom error classes, serializing and deserializing errors for cross-context communication, and maintaining a unified error taxonomy across the Ledger ecosystem.

Package Information

  • Package Name: @ledgerhq/errors
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @ledgerhq/errors

Core Imports

import { TransportError, TransportStatusError, StatusCodes } from "@ledgerhq/errors";
import { serializeError, deserializeError, createCustomErrorClass } from "@ledgerhq/errors";
import { 
  NoDBPathGiven, DBWrongPassword, DBNotReset,
  EthAppPleaseEnableContractData,
  UpdateFetchFileFail, UpdateIncorrectHash, UpdateIncorrectSig
} from "@ledgerhq/errors";

For CommonJS:

const { TransportError, TransportStatusError, StatusCodes } = require("@ledgerhq/errors");
const { serializeError, deserializeError, createCustomErrorClass } = require("@ledgerhq/errors");
const { 
  NoDBPathGiven, DBWrongPassword, DBNotReset,
  EthAppPleaseEnableContractData,
  UpdateFetchFileFail, UpdateIncorrectHash, UpdateIncorrectSig
} = require("@ledgerhq/errors");

Basic Usage

import { 
  TransportError, 
  TransportStatusError, 
  StatusCodes,
  DeviceNotGenuineError,
  serializeError,
  deserializeError
} from "@ledgerhq/errors";

// Using specific error classes
try {
  // Device operation
} catch (error) {
  if (error instanceof DeviceNotGenuineError) {
    console.log("Device authenticity check failed");
  }
}

// Using transport errors
const transportError = new TransportError("Communication failed", "USB_DISCONNECT");

// Using transport status errors
const statusError = new TransportStatusError(StatusCodes.DEVICE_LOCKED);

// Error serialization for cross-context communication
const serialized = serializeError(error);
const restored = deserializeError(serialized);

Architecture

@ledgerhq/errors is built around several key patterns:

  • Custom Error Factory: createCustomErrorClass generates custom error types with consistent behavior
  • Transport Layer: Specialized errors for device communication (TransportError, TransportStatusError)
  • Status Code Integration: Direct mapping to Ledger device status codes for hardware-level error handling
  • Serialization System: Cross-context error communication with serializeError/deserializeError
  • Error Taxonomy: Organized categories covering device management, user interactions, blockchain operations, database operations, and application-specific scenarios

Capabilities

Error Utilities

Core utilities for creating custom error classes and handling error serialization across different contexts.

function createCustomErrorClass(name: string): CustomErrorFunc;
function serializeError(value: any): undefined | To | string;
function deserializeError(object: any): Error;
function addCustomErrorDeserializer(
  name: string,
  deserializer: (obj: any) => any
): void;

type CustomErrorFunc = (
  message?: string,
  fields?: { [key: string]: any }
) => void;

interface To {
  name?: string;
  message?: string;
  stack?: string;
}

Error Utilities

Transport Errors

Specialized error classes for Ledger device communication, including transport-level failures and device status code errors.

function TransportError(message: string, id: string): void;
function TransportStatusError(statusCode: number): void;

const StatusCodes: {
  PIN_REMAINING_ATTEMPTS: number;
  INCORRECT_LENGTH: number;
  SECURITY_STATUS_NOT_SATISFIED: number;
  CONDITIONS_OF_USE_NOT_SATISFIED: number;
  OK: number;
  // ... 25+ additional status codes
};

function getAltStatusMessage(code: number): string | undefined | null;

Transport Errors

Device Management Errors

Error classes for Ledger device management operations including device state validation, connection issues, and hardware-specific errors.

const CantOpenDevice: CustomErrorFunc;
const DeviceNotGenuineError: CustomErrorFunc;
const DeviceOnDashboardExpected: CustomErrorFunc;
const DeviceOnDashboardUnexpected: CustomErrorFunc;
const DeviceInOSUExpected: CustomErrorFunc;
const DeviceHalted: CustomErrorFunc;
const DisconnectedDevice: CustomErrorFunc;
const DisconnectedDeviceDuringOperation: CustomErrorFunc;
// ... 15+ additional device management errors

Device Management Errors

User Interaction Errors

Error classes for user interaction scenarios including user refusals, permission issues, and input validation failures.

const UserRefusedOnDevice: CustomErrorFunc;
const UserRefusedAddress: CustomErrorFunc;
const UserRefusedFirmwareUpdate: CustomErrorFunc;
const UserRefusedAllowManager: CustomErrorFunc;
const UserRefusedDeviceNameChange: CustomErrorFunc;
const NoAccessToCamera: CustomErrorFunc;
const CantScanQRCode: CustomErrorFunc;
const PairingFailed: CustomErrorFunc;
// ... 5+ additional user interaction errors

User Interaction Errors

Account and Balance Errors

Error classes for account management and balance validation including insufficient funds, account state issues, and transaction validation errors.

const AccountNameRequiredError: CustomErrorFunc;
const AccountNotSupported: CustomErrorFunc;
const NotEnoughBalance: CustomErrorFunc;
const NotEnoughBalanceToDelegate: CustomErrorFunc;
const NotEnoughBalanceInParentAccount: CustomErrorFunc;
const NotEnoughSpendableBalance: CustomErrorFunc;
const NotEnoughBalanceBecauseDestinationNotCreated: CustomErrorFunc;
const WrongDeviceForAccount: CustomErrorFunc;
const NoAddressesFound: CustomErrorFunc;
// ... 5+ additional account and balance errors

Account and Balance Errors

Application and Manager Errors

Error classes for Ledger application management including app installation, dependencies, firmware updates, and manager operations.

const ManagerAppAlreadyInstalledError: CustomErrorFunc;
const ManagerAppRelyOnBTCError: CustomErrorFunc;
const ManagerAppDepInstallRequired: CustomErrorFunc;
const ManagerAppDepUninstallRequired: CustomErrorFunc;
const ManagerDeviceLockedError: CustomErrorFunc;
const ManagerNotEnoughSpaceError: CustomErrorFunc;
const FirmwareNotRecognized: CustomErrorFunc;
const FirmwareOrAppUpdateRequired: CustomErrorFunc;
const UpdateYourApp: CustomErrorFunc;
// ... 10+ additional application and manager errors

Application and Manager Errors

Network and API Errors

Error classes for network connectivity, API communication, and external service integration issues.

const NetworkDown: CustomErrorFunc;
const LedgerAPIError: CustomErrorFunc;
const LedgerAPIErrorWithMessage: CustomErrorFunc;
const LedgerAPINotAvailable: CustomErrorFunc;
const LedgerAPI4xx: CustomErrorFunc;
const LedgerAPI5xx: CustomErrorFunc;
const WebsocketConnectionError: CustomErrorFunc;
const WebsocketConnectionFailed: CustomErrorFunc;
// ... 5+ additional network and API errors

Network and API Errors

Currency and Transaction Errors

Error classes for cryptocurrency operations including address validation, transaction processing, fee estimation, and currency-specific issues.

const CurrencyNotSupported: CustomErrorFunc;
const InvalidAddress: CustomErrorFunc;
const InvalidAddressBecauseDestinationIsAlsoSource: CustomErrorFunc;
const InvalidXRPTag: CustomErrorFunc;
const AmountRequired: CustomErrorFunc;
const RecipientRequired: CustomErrorFunc;
const FeeEstimationFailed: CustomErrorFunc;
const FeeRequired: CustomErrorFunc;
const FeeTooHigh: CustomErrorFunc;
const NotEnoughGas: CustomErrorFunc;
const GasLessThanEstimate: CustomErrorFunc;
// ... 10+ additional currency and transaction errors

Currency and Transaction Errors

Database Errors

Error classes for database operations and configuration issues in Ledger applications.

const NoDBPathGiven: CustomErrorFunc;
const DBWrongPassword: CustomErrorFunc;
const DBNotReset: CustomErrorFunc;

Database Errors