@ledgerhq/hw-transport

What is @ledgerhq/hw-transport?

@ledgerhq/hw-transport is a JavaScript library that provides a set of transport methods to communicate with Ledger hardware wallets. It supports various transport protocols such as USB, WebUSB, and Bluetooth, allowing developers to interact with Ledger devices in a secure and efficient manner.

What are @ledgerhq/hw-transport's main functionalities?

USB Transport

This feature allows you to connect to a Ledger device using USB. The code sample demonstrates how to establish a connection and then close it.

const Transport = require('@ledgerhq/hw-transport-node-hid').default;

async function connectLedger() {
  const transport = await Transport.create();
  console.log('Connected to Ledger via USB');
  await transport.close();
}

connectLedger();

WebUSB Transport

This feature allows you to connect to a Ledger device using WebUSB. The code sample demonstrates how to establish a connection and then close it.

const TransportWebUSB = require('@ledgerhq/hw-transport-webusb').default;

async function connectLedgerWebUSB() {
  const transport = await TransportWebUSB.create();
  console.log('Connected to Ledger via WebUSB');
  await transport.close();
}

connectLedgerWebUSB();

Bluetooth Transport

This feature allows you to connect to a Ledger device using Bluetooth. The code sample demonstrates how to establish a connection and then close it.

const TransportBLE = require('@ledgerhq/hw-transport-ble').default;

async function connectLedgerBLE() {
  const transport = await TransportBLE.create();
  console.log('Connected to Ledger via Bluetooth');
  await transport.close();
}

connectLedgerBLE();

Other packages similar to @ledgerhq/hw-transport

trezor-connect

trezor-connect is a JavaScript library for communicating with Trezor hardware wallets. It provides similar functionalities to @ledgerhq/hw-transport, such as USB and WebUSB support, but is specifically designed for Trezor devices.

bitbox02-api

bitbox02-api is a JavaScript library for interacting with BitBox02 hardware wallets. It offers functionalities similar to @ledgerhq/hw-transport, including USB communication, but is tailored for BitBox02 devices.

README

GitHub, Ledger Devs Discord, Developer Portal

@ledgerhq/hw-transport

@ledgerhq/hw-transport implements the generic interface of a Ledger Hardware Wallet transport.

API

Table of Contents

• Subscription
  • Properties
• Device
• DescriptorEvent
• Observer
• Transport
  • Parameters
  • exchange
    • Parameters
  • exchangeBulk
    • Parameters
  • setScrambleKey
    • Parameters
  • close
  • on
    • Parameters
  • off
    • Parameters
  • setDebugMode
  • setExchangeTimeout
    • Parameters
  • setExchangeUnresponsiveTimeout
    • Parameters
  • send
    • Parameters
  • exchangeAtomicImpl
    • Parameters
  • setTraceContext
    • Parameters
  • updateTraceContext
    • Parameters
  • getTraceContext
  • isSupported
  • list
    • Examples
  • listen
    • Parameters
    • Examples
  • open
    • Parameters
    • Examples
  • create
    • Parameters
    • Examples

Subscription

Type: {unsubscribe: function (): void}

Properties

• unsubscribe function (): void

Device

Type: any

DescriptorEvent

A "descriptor" is a parameter that is specific to the implementation, and can be an ID, file path, or URL. type: add or remove event descriptor: a parameter that can be passed to open(descriptor) deviceModel: device info on the model (is it a nano s, nano x, ...) device: transport specific device info

Observer

Observer generic type, following the Observer pattern

Type: Readonly<{next: function (event: EventType): any, error: function (e: EventError): any, complete: function (): any}>

Transport

The Transport class defines a generic interface for communicating with a Ledger hardware wallet. There are different kind of transports based on the technology (channels like U2F, HID, Bluetooth, Webusb) and environment (Node, Web,...). It is an abstract class that needs to be implemented.

Parameters

• $0 {context: TraceContext?, logType: LogType?} (optional, default {})

  • $0.context
  • $0.logType

exchange

Send data to the device using a low level API. It's recommended to use the "send" method for a higher level API.

Parameters

• _apdu Buffer

• options Object Contains optional options for the exchange function* abortTimeoutMs: stop the exchange after a given timeout. Another timeout exists to detect unresponsive device (see unresponsiveTimeout). This timeout aborts the exchange. (optional, default {})

  • options.abortTimeoutMs

• apdu Buffer The data to send.

Returns Promise<Buffer> A promise that resolves with the response data from the device.

exchangeBulk

Send apdus in batch to the device using a low level API. The default implementation is to call exchange for each apdu.

Parameters

• apdus Array<Buffer> array of apdus to send.
• observer Observer<Buffer> an observer that will receive the response of each apdu.

Returns Subscription A Subscription object on which you can call ".unsubscribe()" to stop sending apdus.

setScrambleKey

Set the "scramble key" for the next data exchanges with the device. Each app can have a different scramble key and it is set internally during instantiation.

Parameters

• _key string
• key string The scramble key to set. deprecated This method is no longer needed for modern transports and should be migrated away from. no @ before deprecated as it breaks documentationjs on version 14.0.2 https://github.com/documentationjs/documentation/issues/1596

close

Close the connection with the device.

Note: for certain transports (hw-transport-node-hid-singleton for ex), once the promise resolved, the transport instance is actually still cached, and the device is disconnected only after a defined timeout. But for the consumer of the Transport, this does not matter and it can consider the transport to be closed.

Returns Promise<void> A promise that resolves when the transport is closed.

on

Listen for an event on the transport instance. Transport implementations may have specific events. Common events include: "disconnect" : triggered when the transport is disconnected.

Parameters

• eventName string The name of the event to listen for.
• cb function (...args: Array<any>): any

Returns void

off

Stop listening to an event on an instance of transport.

Parameters

• eventName string
• cb function (...args: Array<any>): any

Returns void

setDebugMode

Enable or not logs of the binary exchange

setExchangeTimeout

Set a timeout (in milliseconds) for the exchange call. Only some transport might implement it. (e.g. U2F)

Parameters

• exchangeTimeout number

Returns void

setExchangeUnresponsiveTimeout

Define the delay before emitting "unresponsive" on an exchange that does not respond

Parameters

• unresponsiveTimeout number

Returns void

send

Send data to the device using the higher level API.

Parameters

• cla number The instruction class for the command.

• ins number The instruction code for the command.

• p1 number The first parameter for the instruction.

• p2 number The second parameter for the instruction.

• data Buffer The data to be sent. Defaults to an empty buffer. (optional, default Buffer.alloc(0))

• statusList Array<number> A list of acceptable status codes for the response. Defaults to [StatusCodes.OK]. (optional, default [StatusCodes.OK])

• options Object Contains optional options for the exchange function* abortTimeoutMs: stop the send after a given timeout. Another timeout exists to detect unresponsive device (see unresponsiveTimeout). This timeout aborts the exchange. (optional, default {})

  • options.abortTimeoutMs

Returns Promise<Buffer> A promise that resolves with the response data from the device.

exchangeAtomicImpl

Wrapper to make an exchange "atomic" (blocking any other exchange)

It also handles "unresponsiveness" by emitting "unresponsive" and "responsive" events.

Parameters

• f function (): Promise<Output> The exchange job, using the transport to run

Returns Promise<Output> a Promise resolving with the output of the given job

setTraceContext

Sets the context used by the logging/tracing mechanism

Useful when re-using (cached) the same Transport instance, but with a new tracing context.

Parameters

• context TraceContext? A TraceContext, that can undefined to reset the context

updateTraceContext

Updates the context used by the logging/tracing mechanism

The update only overrides the key-value that are already defined in the current context.

Parameters

• contextToAdd TraceContext A TraceContext that will be added to the current context

getTraceContext

Gets the tracing context of the transport instance

Returns (TraceContext | undefined)

isSupported

Check if the transport is supported on the current platform/browser.

Type: function (): Promise<boolean>

Returns Promise<boolean> A promise that resolves with a boolean indicating support.

list

List all available descriptors for the transport. For a better granularity, checkout listen().

Type: function (): Promise<Array<any>>

Examples

TransportFoo.list().then(descriptors => ...)

Returns Promise<Array<any>> A promise that resolves with an array of descriptors.

listen

Listen for device events for the transport. The method takes an observer of DescriptorEvent and returns a Subscription. A DescriptorEvent is an object containing a "descriptor" and a "type" field. The "type" field can be "add" or "remove", and the "descriptor" field can be passed to the "open" method. The "listen" method will first emit all currently connected devices and then will emit events as they occur, such as when a USB device is plugged in or a Bluetooth device becomes discoverable.

Type: function (observer: Observer<DescriptorEvent<any>>): Subscription

Parameters

• observer Observer<DescriptorEvent<any>> An object with "next", "error", and "complete" functions, following the observer pattern.

Examples

const sub = TransportFoo.listen({
next: e => {
if (e.type==="add") {
sub.unsubscribe();
const transport = await TransportFoo.open(e.descriptor);
...
}
},
error: error => {},
complete: () => {}
})

Returns Subscription A Subscription object on which you can call ".unsubscribe()" to stop listening to descriptors.

open

Attempt to create a Transport instance with a specific descriptor.

Type: function (descriptor: any, timeoutMs: number, context: TraceContext): Promise<Transport>

Parameters

• descriptor any The descriptor to open the transport with.
• timeout number An optional timeout for the transport connection.
• context TraceContext Optional tracing/log context

Examples

TransportFoo.open(descriptor).then(transport => ...)

Returns Promise<Transport> A promise that resolves with a Transport instance.

create

create() allows to open the first descriptor available or throw if there is none or if timeout is reached. This is a light helper, alternative to using listen() and open() (that you may need for any more advanced usecase)

Parameters

• openTimeout (optional, default 3000)
• listenTimeout number?

Examples

TransportFoo.create().then(transport => ...)

Returns Promise<Transport>