The JavaScript library is compiled from bitbox02-api-go using GopherJS.
Given that it contains the full client implementation compiled from Go, the library is quite large (~3MB). We recommend lazy-loading it only when necessary.
The BitBox02 is a hardware wallet made by Shift Crypto that simplifies secure handling of crypto coins through storing private keys and signing transactions.
To enable communication from the browser to the BitBox02, either:
- WebHID needs to be supported by the browser, e.g. Chrome
- or the BitBoxBridge needs to be installed and running
When integrating the BitBox02 into your application, your domain needs to be whitelisted in the BitBoxBridge. To do so, please submit a Pull Request or an Issue in the bitbox-bridge repository. Localhost is already whitelisted, so you can develop locally.
The BitBox02 Javascript library is available as NPM package bitbox02-api.
$ npm install bitbox02-api
import { BitBox02API, getDevicePath} from 'bitbox02-api';
To get the device path, the BitBoxBridge needs to be running.
If WebHID (navigator.hid
) is available, getDevicePath()
returns "WEBHID"
, which instructs BitBox02API
to prefer WebHID over the BitBoxBridge.
const devicePath = await getDevicePath();
const BitBox02 = new BitBox02API(devicePath);
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)
The BitBox02 is available in two editions: "Multi" and "Bitcoin-only". To check what edition is used, e.g. to make sure that Ethereum functionality is supported, use the following function.
import { constants } from 'bitbox02-api';
BitBox02.firmware().Product() === constants.Product.BitBox02Multi
BitBox02.firmware().Product() === constants.Product.BitBox02BTCOnly
All available methods are documented in docs/methods.md
.
This is a sample BitBox02Wallet class integration for connecting to the BitBox02 device using the BitBoxBridge and this JS API.
See sandbox/src/index.js
for a fully functional sandbox implementation.
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");
To compile the library using GopherJS, run the following commands:
$ make dockerinit
$ make dockercompile
To simply run the demo sandbox implementation, run the following command and visit http://localhost:8000.
$ make builddemo
$ make servedemo