@ledgerhq/hw-transport v6.31.4
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
- Device
- DescriptorEvent
- Observer
- Transport
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
Bufferoptions
Object Contains optional options for the exchange function* abortTimeoutMs: stop the exchange after a given timeout. Another timeout exists to detect unresponsive device (seeunresponsiveTimeout
). This timeout aborts the exchange. (optional, default{}
)options.abortTimeoutMs
apdu
Buffer The data to send.
Returns Promise[Buffer](https://nodejs.org/api/buffer.html) 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](https://nodejs.org/api/buffer.html) array of apdus to send.observer
Observer[Buffer](https://nodejs.org/api/buffer.html) 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
stringkey
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\ 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
Returns void
off
Stop listening to an event on an instance of transport.
Parameters
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, defaultBuffer.alloc(0)
)statusList
Array[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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 (seeunresponsiveTimeout
). This timeout aborts the exchange. (optional, default{}
)options.abortTimeoutMs
Returns Promise[Buffer](https://nodejs.org/api/buffer.html) 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\ The exchange job, using the transport to run
Returns Promise\ 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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)
Returns Promise[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)\<any>
Examples
TransportFoo.list().then(descriptors => ...)
Returns Promise[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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\>): Subscription
Parameters
observer
Observer<DescriptorEvent\> 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, default3000
)listenTimeout
number?
Examples
TransportFoo.create().then(transport => ...)
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
4 months ago
4 months ago
6 months ago
5 months ago
6 months ago
5 months ago
6 months ago
5 months ago
7 months ago
4 months ago
7 months ago
7 months ago
7 months ago
6 months ago
6 months ago
6 months ago
7 months ago
8 months ago
9 months ago
9 months ago
9 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago