@ledgerhq/hw-transport

  • Version 6.30.4
  • Published
  • 126 kB
  • 4 dependencies
  • Apache-2.0 license

Install

npm i @ledgerhq/hw-transport
yarn add @ledgerhq/hw-transport
pnpm add @ledgerhq/hw-transport

Overview

Ledger Hardware Wallet common interface of the communication layer

Index

Classes

class Transport

class 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.

constructor

constructor({
context,
logType,
}?: {
context?: TraceContext;
logType?: LogType;
});

    property deviceModel

    deviceModel: any;

      property ErrorMessage_ListenTimeout

      static ErrorMessage_ListenTimeout: string;

        property ErrorMessage_NoDeviceFound

        static ErrorMessage_NoDeviceFound: string;

          property exchangeBusyPromise

          exchangeBusyPromise: Promise<void>;

            property exchangeTimeout

            exchangeTimeout: number;

              property isSupported

              static readonly isSupported: () => Promise<boolean>;
              • Check if the transport is supported on the current platform/browser.

                Returns

                {Promise} A promise that resolves with a boolean indicating support.

              property list

              static readonly list: () => Promise<Array<any>>;
              • List all available descriptors for the transport. For a better granularity, checkout listen().

                Returns

                {Promise<Array>} A promise that resolves with an array of descriptors.

                Example 1

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

              property listen

              static readonly listen: (
              observer: Observer<DescriptorEvent<any>>
              ) => Subscription;
              • 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.

                Parameter observer

                An object with "next", "error", and "complete" functions, following the observer pattern.

                Returns

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

                Example 1

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

              property open

              static readonly open: (
              descriptor?: any,
              timeoutMs?: number,
              context?: TraceContext
              ) => Promise<Transport>;
              • Attempt to create a Transport instance with a specific descriptor.

                Parameter descriptor

                The descriptor to open the transport with.

                Parameter timeout

                An optional timeout for the transport connection.

                Parameter context

                Optional tracing/log context

                Returns

                {Promise} A promise that resolves with a Transport instance.

                Example 1

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

              property send

              send: (
              cla: number,
              ins: number,
              p1: number,
              p2: number,
              data?: Buffer,
              statusList?: Array<number>,
              { abortTimeoutMs }?: { abortTimeoutMs?: number | undefined }
              ) => Promise<Buffer>;
              • Send data to the device using the higher level API.

                Parameter cla

                The instruction class for the command.

                Parameter ins

                The instruction code for the command.

                Parameter p1

                The first parameter for the instruction.

                Parameter p2

                The second parameter for the instruction.

                Parameter data

                The data to be sent. Defaults to an empty buffer.

                Parameter statusList

                A list of acceptable status codes for the response. Defaults to [StatusCodes.OK].

                Parameter options

                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.

                Returns

                {Promise} A promise that resolves with the response data from the device.

              property tracer

              tracer: LocalTracer;

                property unresponsiveTimeout

                unresponsiveTimeout: number;

                  method close

                  close: () => Promise<void>;
                  • 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} A promise that resolves when the transport is closed.

                  method create

                  static create: (
                  openTimeout?: number,
                  listenTimeout?: number
                  ) => Promise<Transport>;
                  • 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)

                    Example 1

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

                  method decorateAppAPIMethod

                  decorateAppAPIMethod: <R, A extends any[]>(
                  methodName: string,
                  f: (...args: A) => Promise<R>,
                  ctx: any,
                  scrambleKey: string
                  ) => (...args: A) => Promise<R>;

                    method decorateAppAPIMethods

                    decorateAppAPIMethods: (
                    self: Record<string, any>,
                    methods: Array<string>,
                    scrambleKey: string
                    ) => void;

                      method emit

                      emit: (event: string, ...args: any) => void;

                        method exchange

                        exchange: (
                        _apdu: Buffer,
                        { abortTimeoutMs }?: { abortTimeoutMs?: number }
                        ) => Promise<Buffer>;
                        • Send data to the device using a low level API. It's recommended to use the "send" method for a higher level API.

                          Parameter apdu

                          The data to send.

                          Parameter options

                          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.

                          Returns

                          {Promise} A promise that resolves with the response data from the device.

                        method exchangeAtomicImpl

                        exchangeAtomicImpl: <Output>(f: () => Promise<Output>) => Promise<Output>;
                        • Wrapper to make an exchange "atomic" (blocking any other exchange)

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

                          Parameter f

                          The exchange job, using the transport to run

                          Returns

                          a Promise resolving with the output of the given job

                        method exchangeBulk

                        exchangeBulk: (apdus: Buffer[], observer: Observer<Buffer>) => Subscription;
                        • Send apdus in batch to the device using a low level API. The default implementation is to call exchange for each apdu.

                          Parameter apdus

                          array of apdus to send.

                          Parameter observer

                          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.

                        method getTraceContext

                        getTraceContext: () => TraceContext | undefined;
                        • Gets the tracing context of the transport instance

                        method off

                        off: (eventName: string, cb: (...args: Array<any>) => any) => void;
                        • Stop listening to an event on an instance of transport.

                        method on

                        on: (eventName: string, cb: (...args: Array<any>) => any) => void;
                        • Listen for an event on the transport instance. Transport implementations may have specific events. Common events include: "disconnect" : triggered when the transport is disconnected.

                          Parameter eventName

                          The name of the event to listen for.

                          Parameter cb

                          The callback function to be invoked when the event occurs.

                        method setDebugMode

                        setDebugMode: () => void;
                        • Enable or not logs of the binary exchange

                        method setExchangeTimeout

                        setExchangeTimeout: (exchangeTimeout: number) => void;
                        • Set a timeout (in milliseconds) for the exchange call. Only some transport might implement it. (e.g. U2F)

                        method setExchangeUnresponsiveTimeout

                        setExchangeUnresponsiveTimeout: (unresponsiveTimeout: number) => void;
                        • Define the delay before emitting "unresponsive" on an exchange that does not respond

                        method setScrambleKey

                        setScrambleKey: (_key: string) => void;
                        • 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.

                          Parameter key

                          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

                        method setTraceContext

                        setTraceContext: (context?: TraceContext) => void;
                        • Sets the context used by the logging/tracing mechanism

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

                          Parameter context

                          A TraceContext, that can undefined to reset the context

                        method updateTraceContext

                        updateTraceContext: (contextToAdd: TraceContext) => void;
                        • Updates the context used by the logging/tracing mechanism

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

                          Parameter contextToAdd

                          A TraceContext that will be added to the current context

                        Interfaces

                        interface DescriptorEvent

                        interface DescriptorEvent<Descriptor> {}
                        • 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

                        property descriptor

                        descriptor: Descriptor;

                          property device

                          device?: Device;

                            property deviceModel

                            deviceModel?: DeviceModel | null | undefined;

                              property type

                              type: DescriptorEventType;

                                Type Aliases

                                type DescriptorEventType

                                type DescriptorEventType = 'add' | 'remove';

                                  type Device

                                  type Device = any;

                                  type Observer

                                  type Observer<EventType, EventError = unknown> = Readonly<{
                                  next: (event: EventType) => unknown;
                                  error: (e: EventError) => unknown;
                                  complete: () => unknown;
                                  }>;
                                  • Observer generic type, following the Observer pattern

                                  type Subscription

                                  type Subscription = {
                                  unsubscribe: () => void;
                                  };

                                  Package Files (1)

                                  Dependencies (4)

                                  Dev Dependencies (8)

                                  Peer Dependencies (0)

                                  No peer dependencies.

                                  Badge

                                  To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                  You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@ledgerhq/hw-transport.

                                  • Markdown
                                    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@ledgerhq/hw-transport)
                                  • HTML
                                    <a href="https://www.jsdocs.io/package/@ledgerhq/hw-transport"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>