⛔️ DEPRECATED

This repository is now deprecated. We moved to a new mono repository architecture containing all of Ledger Live JavaScript Ecosystem that you can find here. You can follow the migration guide to help you make the transition.

We are hiring, join us! 👨‍💻👩‍💻

Welcome to Ledger's JavaScript libraries.

See also:

Changelog
LedgerJS examples
Ledger Live Desktop
Ledger Live Mobile
live-common
Deprecated libraries are archived in https://github.com/LedgerHQ/ledgerjs-legacy

`@ledgerhq/hw-transport-*`

To communicate with a Ledger device, you first need to identify which transport(s) to use.

The hw-transport libraries implement communication protocol for our hardware wallet devices (Ledger Nano / Ledger Nano S / Ledger Nano X / Ledger Blue) in many platforms: Web, Node, Electron, React Native,... and using many different communication channels: U2F, HID, WebUSB, Bluetooth,...

Channels	U2F/WebAuthn	HID	WebUSB	Bluetooth
Blue	DEPRECATED¹	YES	NO	NO
Nano S	DEPRECATED¹	YES	YES	NO
Nano X	DEPRECATED¹	YES	YES	YES

U2F is deprecated. See https://github.com/LedgerHQ/ledgerjs/blob/master/docs/migrate_webusb.md

Summary of implementations available per platform

Platforms	U2F/WebAuthn	HID	WebUSB	Bluetooth
Web	`@ledgerhq/hw-transport-u2f`	`@ledgerhq/hw-transport-webhid`	`@ledgerhq/hw-transport-webusb`	`@ledgerhq/hw-transport-web-ble`
Electron/Node.js	NO	`@ledgerhq/hw-transport-node-hid`¹	NO	`@ledgerhq/hw-transport-node-ble`
iOS	NO	NO	NO	`@ledgerhq/react-native-hw-transport-ble`
Android	`@ledgerhq/hw-transport-u2f`²	`@ledgerhq/react-native-hid`	`@ledgerhq/hw-transport-webusb`²	`@ledgerhq/react-native-hw-transport-ble`

3 implementations available
via Android Chrome

Beware the current web support:

Channels	U2F	WebHID.	WebUSB	WebBluetooth
Windows	DEPRECATED¹	YES	OK BUT²	YES
Mac	DEPRECATED¹	YES	YES	YES
Linux	DEPRECATED¹	YES	YES	YES
Chrome	DEPRECATED¹	YES³	YES	YES
Safari	DEPRECATED¹	NO	NO	NO
Firefox	DEPRECATED¹	NO	NO	NO
IE.	DEPRECATED¹	NO	NO	NO

U2F is deprecated. See https://github.com/LedgerHQ/ledgerjs/blob/master/docs/migrate_webusb.md
instabilities has been reported
WebHID supported under Chrome experimental flags

Please find respective documentation for each transport:

@ledgerhq/hw-transport-u2f [Web] (U2F) (legacy but reliable) – FIDO U2F api. check browser support.
@ledgerhq/hw-transport-webauthn [Web] (WebAuthn) (experimental) – WebAuthn api. check browser support.
@ledgerhq/hw-transport-webusb [Web] (WebUSB) – WebUSB check browser support.
@ledgerhq/hw-transport-webhid [Web] (WebHID) – WebHID check browser support.
@ledgerhq/hw-transport-web-ble [Web] (Bluetooth) – check browser support.
@ledgerhq/hw-transport-node-hid [Node]/Electron (HID) – historical implementation – uses node-hid and usb.
@ledgerhq/hw-transport-node-hid-noevents [Node]/Electron (HID) – uses only node-hid. Does not provide USB events.
@ledgerhq/hw-transport-node-hid-singleton [Node]/Electron (HID) – uses node-hid and usb-detection. Focus on supporting one device at a time (potentially will have more robust events and less blocking cases)
@ledgerhq/hw-transport-node-ble [Node]/Electron (BLE) (experimental) – uses @abandonware/noble.
@ledgerhq/react-native-hw-transport-ble [React Native] (Bluetooth) – uses react-native-ble-plx
@ledgerhq/react-native-hid [React Native] (HID) Android – Ledger's native implementation
@ledgerhq/hw-transport-http [DEV only] universal HTTP channel. NOT for PROD.

An unified Transport interface

All these transports implement a generic interface exposed by @ledgerhq/hw-transport. There are specifics for each transport which are explained in each package.

A Transport is essentially:

Transport.listen: (observer)=>Subscription
Transport.open: (descriptor)=>Promise<Transport>
transport.exchange(apdu: Buffer): Promise<Buffer>
transport.close()

and some derivates:

transport.create(): Promise<Transport>: make use of listen and open for the most simple scenario.
transport.send(cla, ins, p1, p2, data): Promise<Buffer>: a small abstraction of exchange

NB: APDU is the encoding primitive for all binary exchange with the devices. (it comes from smart card industry)

`@ledgerhq/hw-app-*`

As soon as your Transport is created, you can already communicate by implementing the apps protocol (refer to application documentations, for instance BTC app and ETH app ones).

We also provide libraries that help implementing the low level exchanges. These higher level APIs are split per app:

@ledgerhq/hw-app-eth: Ethereum Application API
@ledgerhq/hw-app-btc: Bitcoin Application API
@ledgerhq/hw-app-xrp: Ripple Application API
@ledgerhq/hw-app-str: Stellar Application API

Community packages:

@cardano-foundation/ledgerjs-hw-app-cardano: Cardano ADA Application API
ledger-cosmos-js: Cosmos/Tendermint Application API

Other packages

Published Packages

Package	Version	Description
`create-dapp`		Ledger DApp Ethereum starter kit
`@ledgerhq/web3-subprovider`		web3 subprovider implementation for web3-provider-engine
Development Tools
`@ledgerhq/hw-transport-mocker`		Tool used for test to record and replay APDU calls.

Basic gist

import Transport from "@ledgerhq/hw-transport-node-hid";
// import Transport from "@ledgerhq/hw-transport-webusb";
// import Transport from "@ledgerhq/react-native-hw-transport-ble";
import AppBtc from "@ledgerhq/hw-app-btc";
const getBtcAddress = async () => {
  const transport = await Transport.create();
  const btc = new AppBtc(transport);
  const result = await btc.getWalletPublicKey("44'/0'/0'/0/0");
  return result.bitcoinAddress;
};
getBtcAddress().then(a => console.log(a));

Contributing

Please read our contribution guidelines before getting started.

You need to have a recent Node.js and Yarn installed.

Install dependencies

yarn

Build

Build all packages

yarn build

Watch

Watch all packages change. Very useful during development to build only file that changes.

yarn watch

Lint

Lint all packages

yarn lint

Run Tests

First of all, this ensure the libraries are correctly building, and passing lint and flow:

yarn test

then to test on a real device...

Plug a device like the Nano S and open Bitcoin app.

Then run the test and accept the commands on the devices for the tests to continue.

yarn test-node

You can also test on the web:

yarn test-browser

make sure to configure your device app with "Browser support" set to "YES".

Deploy

Checklist before deploying a new release:

you have the right in the LedgerHQ org on NPM
you have run npm login once (check npm whoami)
Go to master branch
- your master point on LedgerHQ repository (check with git config remote.$(git config branch.master.remote).url and fix it with git branch --set-upstream master origin/master)
- you are in sync (git pull) and there is no changes in git status
Run yarn once, there is still no changes in git status

deploy a new release

 yarn run publish

then, go to /releases and create a release with change logs.

alternatively:

deploy a canary release (beta, etc)

 yarn run publish -c

NB: if there is a new package, AFAIK you need to manually npm publish it once on NPM.

VSCode settings

Here is a example config for a workspace file to handle the monorepo setup.
Just add project.code-workspace to your .vscode folder

{
  "folders": [
    {
      "name": "root",
      "path": "../"
    },
    {
      "name": "cryptoassets",
      "path": "../packages/cryptoassets"
    },
    {
      "name": "devices",
      "path": "../packages/devices"
    },
    {
      "name": "errors",
      "path": "../packages/errors"
    },
    {
      "name": "hw-app-algorand",
      "path": "../packages/hw-app-algorand"
    },
    {
      "name": "hw-app-btc",
      "path": "../packages/hw-app-btc"
    },
    {
      "name": "hw-app-cosmos",
      "path": "../packages/hw-app-cosmos"
    },
    {
      "name": "hw-app-eth",
      "path": "../packages/hw-app-eth"
    },
    {
      "name": "hw-app-polkadot",
      "path": "../packages/hw-app-polkadot"
    },
    {
      "name": "hw-app-str",
      "path": "../packages/hw-app-str"
    },
    {
      "name": "hw-app-tezos",
      "path": "../packages/hw-app-tezos"
    },
    {
      "name": "hw-app-trx",
      "path": "../packages/hw-app-trx"
    },
    {
      "name": "hw-app-xrp",
      "path": "../packages/hw-app-xrp"
    },
    {
      "name": "hw-transport",
      "path": "../packages/hw-transport"
    },
    {
      "name": "hw-transport-http",
      "path": "../packages/hw-transport-http"
    },
    {
      "name": "hw-transport-mocker",
      "path": "../packages/hw-transport-mocker"
    },
    {
      "name": "hw-transport-node-ble",
      "path": "../packages/hw-transport-node-ble"
    },
    {
      "name": "hw-transport-node-hid",
      "path": "../packages/hw-transport-node-hid"
    },
    {
      "name": "hw-transport-node-hid-noevents",
      "path": "../packages/hw-transport-node-hid-noevents"
    },
    {
      "name": "hw-transport-node-hid-singleton",
      "path": "../packages/hw-transport-node-hid-singleton"
    },
    {
      "name": "hw-transport-node-speculos",
      "path": "../packages/hw-transport-node-speculos"
    },
    {
      "name": "hw-transport-web-ble",
      "path": "../packages/hw-transport-web-ble"
    },
    {
      "name": "hw-transport-webhid",
      "path": "../packages/hw-transport-webhid"
    },
    {
      "name": "hw-transport-webusb",
      "path": "../packages/hw-transport-webusb"
    },
    {
      "name": "logs",
      "path": "../packages/logs"
    },
    {
      "name": "react-native-hid",
      "path": "../packages/react-native-hid"
    },
    {
      "name": "react-native-hw-transport-ble",
      "path": "../packages/react-native-hw-transport-ble"
    }
  ],
}

LedgerHQ / ledgerjs

readme