README.md

HDWallet

A library for interacting with hardware wallets from JS/TS. Supports KeepKey, Trezor, and Ledger. Intended for use in web apps, chrome apps/extensions, and electon/node apps.

Documentation

• hdwallet
  • Documentation
  • Installation
  • Importing Library
  • Usage
  • Building
  • Developing
  • Tests
  • Contributing

Installation

yarn add @shapeshiftoss/hdwallet

Importing Library

You can import the generated bundle to use each of the component libraries:

import { HDWallet, isKeepKey, isTrezor, ... } from '@shapeshiftoss/hdwallet-core'
import { KeepKeyHDWallet } from '@shapeshiftoss/hdwallet-keepkey'
import { WebUSBKeepKeyAdapter } from '@shapeshiftoss/hdwallet-keepkey-webusb'

Usage

The recommended way to use the library is through a Keyring singleton, which manages connected devices:

import { Keyring } from '@shapeshiftoss/hdwallet-core'
const keyring = new Keyring()

To add in support for a given wallet type, add in the relevant Transport adapter by calling useKeyring() on it:

import { WebUSBKeepKeyAdapter } from '@shapeshiftoss/hdwallet-keepkey-webusb'
import { TrezorAdapter } from '@shapeshiftoss/hdwallet-trezor-connect'

const keepkeyAdapter = WebUSBKeepKeyAdapter.useKeyring(keyring)

const trezorAdapter = TrezorAdapter.useKeyring(keyring, {
  debug: false,
  manifest: {
    email: '[email protected]',     // TrezorConnect info
    appUrl: 'https://example.com' // URL of hosted domain
  }
})

const ledgerAdapter = LedgerAdapter.useKeyring(keyring)

After setting up a Keyring, and plugging various transport adapters into it, the next step is to pair a device:

let wallet = await keepkeyAdapter.pairDevice()

wallet.getLabel().then(result => { console.log(result) })

Building

It is expected that this take quite some time (around 15 minutes), due to the large size of the compiled KeepKey protobuf encoder/decoder.

yarn clean
yarn
yarn build

Developing

To compile and watch the browser bundle, run:

yarn dev:sandbox

This will launch an ssl webserver that runs at https://localhost:1234, with a small demo app that shows how to use various HDWallet functionality.

Tests

yarn
yarn build
yarn test

The integration tests have been set up to run either against a pyhsical KeepKey with debug firmware on it, or in CI pointed at a dockerized version of the emulator. Trezor and Ledger tests run against mocks of their respective transport layers.

Contributing

See our developer guidelines here.