@ledgerhq/hw-transport-webhid

GitHub, Ledger Devs Discord, Developer Portal

@ledgerhq/hw-transport-webhid

Allows to communicate with Ledger Hardware Wallets.

[Web] (WebHID) – WebHID check browser support.

---

Are you adding Ledger support to your software wallet?

You may be using this package to open a USB connection between your web application and the device.

For a smooth and quick integration:

• See the developers’ documentation on the Developer Portal and
• Go on Discord to chat with developer support and the developer community.

---

FAQ: "DOM Exception" is triggered when creating the transport

The transport functions create() and listen() must be called in the context of a user interaction (like a "click" event), otherwise it fails with DOM Exception. This is by WebUSB design. You also must run on HTTPS.

How to use this transport?

Please check @ledgerhq/hw-transport-webusb documentation because it is very similar paradigm.

Support status

WebUSB is currently only supported on Google Chrome / Chromium DEV version and by explicitly enabling chrome://flags/#enable-experimental-web-platform-features

API

Table of Contents

• createHIDframing
  • Parameters
• makeBlocks
  • Parameters
• reduceResponse
  • Parameters
• getReducedResult
  • Parameters
• TransportWebHID
  • Parameters
  • Examples
  • close
  • exchange
    • Parameters
  • isSupported
  • list
  • listen
    • Parameters
  • request
  • openConnected
  • open
    • Parameters

createHIDframing

Object to handle HID frames (encoding and decoding)

Parameters

• channel number
• packetSize number The HID protocol packet size in bytes (usually 64)

makeBlocks

Frames/encodes an APDU message into HID USB packets/frames

Parameters

• apdu Buffer The APDU message to send, in a Buffer containing [cla, ins, p1, p2, data length, data(if not empty)]

Returns Array<Uint8Array<ArrayBuffer>> an array of HID USB frames ready to be sent

reduceResponse

Reduces HID USB packets/frames to one response.

Parameters

• acc ResponseAcc The value resulting from (accumulating) the previous call of reduceResponse. On first call initialized to initialAcc. The accumulator enables handling multi-frames messages.
• chunk Buffer Current chunk to reduce into accumulator

Returns ResponseAcc An accumulator value updated with the current chunk

getReducedResult

Returns the response message that has been reduced from the HID USB frames

Parameters

• acc ResponseAcc The accumulator

Returns (Buffer | null | undefined) A Buffer containing the cleaned response message, or null if no response message, or undefined if the accumulator is incorrect (message length is not valid)

TransportWebHID

Extends Transport

WebHID Transport implementation

Parameters

• device HIDDevice

Examples

import TransportWebHID from "@ledgerhq/hw-transport-webhid";
...
TransportWebHID.create().then(transport => ...)

close

Release the transport device

Returns Promise<void>

exchange

Exchange with the device using APDU protocol.

Parameters

• apdu Buffer

Returns Promise<Buffer> a promise of apdu response

isSupported

Check if WebUSB transport is supported.

list

List the WebUSB devices that was previously authorized by the user.

listen

Actively listen to WebUSB devices and emit ONE device that was either accepted before, if not it will trigger the native permission UI.

Important: it must be called in the context of a UI click!

Parameters

• observer Observer<DescriptorEvent<HIDDevice>>

Returns Subscription

request

Similar to create() except it will always display the device permission (even if some devices are already accepted).

openConnected

Similar to create() except it will never display the device permission (it returns a Promise<?Transport>, null if it fails to find a device).

open

Create a Ledger transport with a HIDDevice

Parameters

• device HIDDevice