Skip to content

Latest commit

 

History

History

ledgerjs

README.md

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

Ledger Devs Slack License

Welcome to Ledger's JavaScript libraries.

See also:

@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 DEPRECATED1 YES NO NO
Nano S DEPRECATED1 YES YES NO
Nano S Plus DEPRECATED1 YES YES NO
Nano X DEPRECATED1 YES YES YES
  1. U2F is deprecated. See https://github.com/LedgerHQ/ledger-live/wiki/LJS:MigrateWebUSB

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-hid1 NO NO
iOS NO NO NO @ledgerhq/react-native-hw-transport-ble
Android @ledgerhq/hw-transport-u2f2 @ledgerhq/react-native-hid @ledgerhq/hw-transport-webusb2 @ledgerhq/react-native-hw-transport-ble
  1. 3 implementations available
  2. via Android Chrome

Beware the current web support:

Channels U2F WebHID. WebUSB WebBluetooth
Windows DEPRECATED1 YES OK BUT2 YES
Mac DEPRECATED1 YES YES YES
Linux DEPRECATED1 YES YES YES
Chrome DEPRECATED1 YES3 YES YES
Safari DEPRECATED1 NO NO NO
Firefox DEPRECATED1 NO NO NO
IE. DEPRECATED1 NO NO NO
  1. U2F is deprecated. See https://github.com/LedgerHQ/ledger-live/wiki/LJS:MigrateWebUSB
  2. instabilities has been reported
  3. WebHID supported under Chrome experimental flags

Please find respective documentation for each transport:

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:

Community packages:

Other packages

Published Packages

Package Version Description
create-dapp npm Ledger DApp Ethereum starter kit
@ledgerhq/web3-subprovider npm web3 subprovider implementation for web3-provider-engine
Development Tools
@ledgerhq/hw-transport-mocker npm 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

Reminder: all commands should be run at the root of the monorepository

pnpm i

Build

Build all packages

pnpm build:ljs

Watch

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

pnpm watch:ljs

Lint

Lint all packages

pnpm lint --filter="./libs/ledgerjs/**"

Typecheck

Typecheck all packages

pnpm typecheck --filter="./libs/ledgerjs/**"

Run Tests

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

pnpm test --filter="./libs/ledgerjs/**"

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 pnpm login once (check pnpm 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 pnpm i once, there is still no changes in git status

deploy a new release

pnpm clean:ljs && pnpm build:ljs && pnpm doc:ljs && pnpm publish --filter="./libs/ledgerjs/**"

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

Are you adding the support of a blockchain to Ledger Live?

This part of the repository is where you will add your blockchain to the cryptoasset library.

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.

Are you adding Ledger device support to your web/mobile/desktop application?

This part of the repository contains the transport libraries that will be used to establish the communication between your app and Ledger devices.

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.