bitbox02-api

BitBox02 JavaScript library

The JavaScript library is compiled from bitbox02-api-go using GopherJS.

Given that it contains the full client implentation compiled from Go, the library is quite large (~3MB), we recommend lazy-loading it only when necessary.

Develop locally

To compile:

$ make dockerinit
$ make dockercompile

To run a demo: $ make servedemo and visit localhost:8000

Integration

To talk to the device from a browser using this API, you will need the BitBoxBridge: https://github.com/digitalbitbox/bitbox-bridge To integrate the BitBox02 into your application, your domain will need to be whitelisted in the Bridge. To do so, please submit a Pull Request or an Issue in the bitbox-bridge repo.

Install:

$ npm install bitbox02-api

Import

import { BitBox02API, getDevicePath} from 'bitbox02-api';

Initialize

To get the device path, the BitBoxBridge needs to be running

const devicePath = await getDevicePath();
const BitBox02 = new BitBox02API(devicePath);

Connect

The BitBox02API.connect() method takes 5 arguments:

/**
 * @param showPairingCb Callback that is used to show pairing code. Must not block.
 * @param userVerify Promise that should resolve once the user wants to continue.
 * @param handleAttastionCb Callback that should handle the bool attestation result. Must not block.
 * @param onCloseCb Callback that's called when the websocket connection is closed.
 * @param setStatusCb Callback that lets the API set the status received from the device.
 * @return Promise that will resolve once the pairing is complete.
 */
connect (showPairingCb, userVerify, handleAttestationCb, onCloseCb, setStatusCb)

For more detailed example see the Sample integration below.

Methods and functions

ethGetRootPubKey: Get Ethereum Root Pub Key

Get eth xpub for a given coin and derivation path

/**
 * @param keypath account keypath in string format
 * Currently only two keypaths are supported:
 * - `m/44'/60'/0'/0` for mainnet and
 * - `m/44'/1'/0'/0`  for Rinkeby and Ropsten testnets
 * @returns string; ethereum extended public key
 */
const rootPub = await BitBox02.ethGetRootPubKey(keypath: string);

ethSignTransaction: Sign Ethereum transaction

To sign Ethereum transactions, we recommend using the Transaction type provided by the ethereumjs library https://github.com/ethereumjs/ethereumjs-tx/blob/master/src/transaction.ts.

Then to send the data to the device and get the signature bytes:

/**
 * Signs an ethereum transaction on device
 * @param signingData Object;
 * signingData = {
 *     keypath, // string, e.g. m/44'/60'/0'/0/0
 *     chainId, // number, currently 1, 3 or 4 for Mainnet, Ropsten and Rinkeby respectively
 *     tx       // Object, either as provided by the `Transaction` type from `ethereumjs` library
 *              // or including `nonce`, `gasPrice`, `gasLimit`, `to`, `value`, and `data` as byte arrays
 * }
 * @returns Object; result with the signature bytes r, s, v
 * result = {
 *     r: Uint8Array(32)
 *     s: Uint8Array(32)
 *     v: Uint8Array(1)
 * }
 */
const result = await BitBox02.ethSignTransaction(signingData);

ethSignMessage: Sign Ethereum messages

/** @param msgData is an object including the keypath and the message as bytes/Buffer:
  *
  * const msgData = {
  *     keypath    // string, e.g. m/44'/60'/0'/0/0 for the first mainnet account
  *     message    // Buffer/Uint8Array
  *   }
  *
  * @returns Object; result with the signature bytes r, s, v
  * result = {
  *   r: Uint8Array(32)
  *   s: Uint8Array(32)
  *   v: Uint8Array(1)
  * }
  */
const result = await BitBox02.ethSignMessage(msgData);

ethDisplayAddress: Display Ethereum address on BitBox02 screen for verification

/**
 * @param keypath string, e.g. m/44'/60'/0'/0/0 for the first mainnet account
 */
await BitBox02.ethDisplayAddress(keypath)

Check if product is supported

To use with Ethereum, the user needs a BB02 Multi and not the Bitcoin Only edition. You can use for the following check:

import { constants } from 'bitbox02-api';

BitBox02.firmware().Product() === constants.Product.BitBox02Multi
BitBox02.firmware().Product() === constants.Product.BitBox02BTCOnly

Sample integration

This is a sample BitBox02Wallet class integration for connecting to the BitBox02 device using the BitBoxBridge and this JS API. For a functioning sandbox implementation, you can see demo.js: https://github.com/digitalbitbox/bitbox02-api-js/blob/master/demo/demo.js

import {
  constants,
  BitBox02API,
  getDevicePath,
  sanitizeEthTransactionData
} from 'bitbox02-api';

class BitBox02 {
  constructor(logout) {  // You can provide the `logout` callback of your application in the constructor
    this.logout = logout;
    this.status = undefined;
    this.pairingConfirmed = false;
  }

  async init(keypath) {
    try {
      const devicePath = await getDevicePath();
      this.api = new BitBox02API(devicePath);

      await this.api.connect(

        /** @param showPairingCb
         *  Store the pairing code on the class instance. Show this to the user to compare with code
         *  on the device when `this.status === 'unpaired'`
         */
        pairingCode => {
          this.pairingCode = pairingCode;
        },

        /** @param userVerify
         *  Store the Promise's `resolve` on the class instance to call when the user clicks the corresponding button
         *  in your application after confirming the pairing on device
         */
        async () => {
          return new Promise(resolve => {
            this.pairingConfirmed = true;
            this.pairingConfirmationResolve = resolve;
          });
        },

        /** @param handleAttestationCb
        *  Store the attestation result on the class instance. If attestation fails, the user might have a fake device.
        *  Handle this condition below.
        */
        attestationResult => {
          this.attestation = attestationResult;
        },

        /** @param onCloseCb
        *  Log the user out of your application when device is unplugged/the websocket closes.
        *  Here we use the `logout` function provided in the constructor as the callback.
        */
        () => {
          this.logout();
        },

        /** @param setStatusCb
        *  Store the status on the class instance to take appropriate actions based on status.
        *  All possible status can be found here: https://github.com/digitalbitbox/bitbox02-api-go/blob/master/api/firmware/status.go
        */
        status => {
          this.status = status;
        }
      );
    } catch(e) {
      alert(e);
      this.logout();
      return;
    }

    switch (this.api.firmware().Product()) {
        case constants.Product.BitBox02Multi:
            console.log("This is a BitBox02 Multi");
            break;
        case constants.Product.BitBox02BTCOnly:
            console.log("This is a BitBox02 BTC-only");
            break;
    }

    // Handle attestattion failure
    if (!this.attestation) {
      alert('Attestation failed');
    }

  }
}

const device = new BitBox02(yourLogoutFunction)
await device.init()

// Now you can call any of the supported API methods documented above e.g.:
const ethPub = await device.api.ethGetRootPubKey("m/44'/60'/0'/0");

Changelog

0.4.0

• Changed api.firmware.* to constants.* (all constants)
• Changed api.firmware.isErrorAbort to isErrorAbort (direct export)
• api no longer exported (treated as internal).
• add btcXPub, btcMaybeRegisterScriptConfig, btcDisplayAddressMultisig, btcSignMultisig api calls.
• bitbox02-api-go: updated to 49d314b148cccb193e26b5c154044ed7eb819384 (v7.0.0 compatibility)
• Add Jest framework and Travis CI for testing and add unit tests for util functions
• Improve error handling with regards to CORS headers when connecting to the device. We can now correctly identify when the origin is not whitelisted based on the response from the bridge