Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
bitbox02-api
Advanced tools
bitbox02-api - npm Package Compare versions
Comparing version 0.4.0 to 0.4.1
@@ -0,1 +1,6 @@ | ||
| # 0.4.1 | ||
| - Updated BitBoxSandbox demo | ||
| - Add methods documentation in docs/methods.md | ||
| - Sandbox UI improvements | ||
| # 0.4.0 | ||
@@ -2,0 +7,0 @@ - Changed api.firmware.* to constants.* (all constants) |
| { | ||
| "name": "bitbox02-api", | ||
| "version": "0.4.0", | ||
| "version": "0.4.1", | ||
| "description": "BitBox02 JavaScript library", | ||
@@ -5,0 +5,0 @@ "main": "src/index.js", |
113
README.md
@@ -6,7 +6,8 @@ # BitBox02 JavaScript library | ||
| 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. | ||
| 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 | ||
| ## Local development | ||
| To compile: | ||
| To compile the library using GopherJS, run the following commands: | ||
@@ -18,10 +19,20 @@ ```sh | ||
| To run a demo: `$ make servedemo` and visit `localhost:8000` | ||
| To simply run the demo sandbox implementation, run the following command and visit <http://localhost:8000>. | ||
| ```sh | ||
| $ make servedemo | ||
| ``` | ||
| ## 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](https://github.com/digitalbitbox/bitbox-bridge) repo. | ||
| To enable communication from the browser to the BitBox02, the [BitBoxBridge](https://github.com/digitalbitbox/bitbox-bridge) needs to be installed and running. | ||
| ### Install: | ||
| 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](https://github.com/digitalbitbox/bitbox-bridge) repository. | ||
| Localhost is already whitelisted, so you can develop locally. | ||
| The BitBox02 Javascript library is available as NPM package [bitbox02-api](https://www.npmjs.com/package/bitbox02-api). | ||
| ### Install | ||
| ```sh | ||
@@ -32,2 +43,3 @@ $ npm install bitbox02-api | ||
| ### Import | ||
| ```javascript | ||
@@ -38,4 +50,5 @@ import { BitBox02API, getDevicePath} from 'bitbox02-api'; | ||
| ### Initialize | ||
| To get the device path, the BitBoxBridge needs to be running | ||
| To get the device path, the BitBoxBridge needs to be running. | ||
| ```javascript | ||
@@ -46,4 +59,6 @@ const devicePath = await getDevicePath(); | ||
| ### Connect | ||
| ### Connect to device | ||
| The `BitBox02API.connect()` method takes 5 arguments: | ||
| ```javascript | ||
@@ -61,75 +76,8 @@ /** | ||
| For more detailed example see the [Sample integration](https://github.com/digitalbitbox/bitbox02-api-js/blob/master/README.md#sample-integration) below. | ||
| ### Check BitBox02 edition | ||
| ### Methods and functions | ||
| 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. | ||
| #### ethGetRootPubKey: Get Ethereum Root Pub Key | ||
| Get eth xpub for a given coin and derivation path | ||
| ```javascript | ||
| /** | ||
| * @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: | ||
| ```javascript | ||
| /** | ||
| * 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 | ||
| ```javascript | ||
| /** @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 | ||
| ```javascript | ||
| /** | ||
| * @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: | ||
| ```javascript | ||
| import { constants } from 'bitbox02-api'; | ||
@@ -141,5 +89,10 @@ | ||
| ### Methods | ||
| All available methods are documented in [`docs/methods.md`](docs/methods.md). | ||
| ## 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 | ||
| See [`demo/demo.js`](demo/demo.js) for a fully functional sandbox implementation. | ||
@@ -146,0 +99,0 @@ ```javascript |
@@ -0,1 +1,17 @@ | ||
| // Copyright 2019 Shift Cryptosecurity AG | ||
| // | ||
| // Licensed under the Apache License, Version 2.0 (the "License"); | ||
| // you may not use this file except in compliance with the License. | ||
| // You may obtain a copy of the License at | ||
| // | ||
| // http://www.apache.org/licenses/LICENSE-2.0 | ||
| // | ||
| // Unless required by applicable law or agreed to in writing, software | ||
| // distributed under the License is distributed on an "AS IS" BASIS, | ||
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| // See the License for the specific language governing permissions and | ||
| // limitations under the License. | ||
| // For full method documentation see: https://github.com/digitalbitbox/bitbox02-api-js/blob/master/docs/methods.md | ||
| import './bitbox02-api-go.js'; | ||
@@ -27,3 +43,3 @@ | ||
| errorMessage = 'Origin not whitelisted'; | ||
| throw new Error(); | ||
| throw new Error(); | ||
| } else if (!response.ok) { | ||
@@ -170,3 +186,8 @@ errorMessage = 'Unexpected'; | ||
| // --- Bitcoin methods --- | ||
| /** | ||
| * # Get a Bitcoin xPub key for a given coin and derivation path. | ||
| * | ||
| * @param coin Coin to target - `constants.messages.BTCCoin.*`, for example `constants.messages.BTCCoin.BTC`. | ||
@@ -183,6 +204,7 @@ * @param keypath account-level keypath, for example `getKeypathFromString("m/49'/0'/0'")`. | ||
| /** | ||
| * Display a single-sig address on the device. The address to be shown in the wallet is usually derived from the xpub (see `btcXPub` and account type. | ||
| * # Display a single-sig address on the device. The address to be shown in the wallet is usually derived | ||
| * # from the xpub (see `btcXPub` and account type. | ||
| * | ||
| * @param coin Coin to target - `constants.messages.BTCCoin.*`, for example `constants.messages.BTCCoin.BTC`. | ||
| * @param keypath address-level keypath, for example `getKeypathFromString("m/49'/0'/0'/1/10")`. | ||
| * Note: the keypaths are strictly enforced according to bip44, and must match the provided script/address types. | ||
| * @param simpleType is the address type - `constants.messages.BTCScriptConfig_SimpleType.*`, for example `constants.messages.BTCScriptConfig_SimpleType.P2WPKH_P2SH` for `3...` segwit addresses. | ||
@@ -201,30 +223,30 @@ */ | ||
| /** | ||
| * Sign a single-sig transaction. | ||
| * # Sign a single-sig transaction. | ||
| * | ||
| * @param coin Coin to target - `constants.messages.BTCCoin.*`, for example `constants.messages.BTCCoin.BTC`. | ||
| * @param simpleType same as in `btcDisplayAddresssimple`. | ||
| * @param keypathAccount account-level keypath, for example `getKeypathFromString("m/84'/0'/0'")`. | ||
| * All inputs and changes must be from this account. | ||
| * @param inputs array of input objects, with each input: | ||
| * { | ||
| * "prevOutHash": Uint8Array(32), | ||
| * "prevOutIndex": number, | ||
| * "prevOutValue": string, // satoshis as a decimal string, | ||
| * "sequence": number, // usually 0xFFFFFFFF | ||
| * "keypath": [number], // usually keypathAccount.concat([change, address]), | ||
| * } | ||
| * @param outputs array of output objects, with each output being either regular output or a change output: | ||
| * Change outputs: | ||
| * { | ||
| * "ours": true, | ||
| * "keypath": [number], // usually keypathAccount.concat([1, <address>]), | ||
| * "value": string, // satoshis as a decimal string, | ||
| * } | ||
| * Regular outputs: | ||
| * { | ||
| * "ours": false, | ||
| * "type": constants.messages.BTCOutputType.P2WSH // e.g. constants.messages.BTCOutputType.P2PKH, | ||
| * // pubkey or script hash. 20 bytes for P2PKH, P2SH, P2WPKH. 32 bytes for P2WSH. | ||
| * "hash": new Uint8Array(20) | new Uint8Array(32) | ||
| * "value": string, // satoshis as a decimal string, | ||
| * } | ||
| * @param inputs array of input objects | ||
| * { | ||
| * "prevOutHash": Uint8Array(32), | ||
| * "prevOutIndex": number, | ||
| * "prevOutValue": string, // satoshis as a decimal string, | ||
| * "sequence": number, // usually 0xFFFFFFFF | ||
| * "keypath": [number], // usually keypathAccount.concat([change, address]), | ||
| * } | ||
| * @param outputs array of output objects, with each output being either regular output or a change output | ||
| * Change outputs: | ||
| * { | ||
| * "ours": true, | ||
| * "keypath": [number], // usually keypathAccount.concat([1, <address>]), | ||
| * "value": string, // satoshis as a decimal string, | ||
| * } | ||
| * Regular outputs: | ||
| * { | ||
| * "ours": false, | ||
| * "type": constants.messages.BTCOutputType.P2WSH // e.g. constants.messages.BTCOutputType.P2PKH, | ||
| * // pubkey or script hash. 20 bytes for P2PKH, P2SH, P2WPKH. 32 bytes for P2WSH. | ||
| * "hash": new Uint8Array(20) | new Uint8Array(32) | ||
| * "value": string, // satoshis as a decimal string, | ||
| * } | ||
| * @param version Transaction version, usually 1 or 2. | ||
@@ -255,14 +277,15 @@ * @param locktime Transaction locktime, usually 0. | ||
| /** | ||
| * Register a multisig account on the device with a user chosen name. If it is already registered, this does nothing. | ||
| * A multisig account must be registered before it can be used to show multisig addresses or sign multisig transactions. | ||
| * Note: | ||
| * Currently, only P2WSH (bech32) multisig accounts on the keypath `m/48'/<coin>'/<account>'/2'` are supported. | ||
| * # Register a multisig account on the device with a user chosen name. If it is already registered, this does nothing. | ||
| * # A multisig account must be registered before it can be used to show multisig addresses or sign multisig transactions. | ||
| * # Note: | ||
| * # Currently, only P2WSH (bech32) multisig accounts on the keypath `m/48'/<coin>'/<account>'/2'` are supported. | ||
| * | ||
| * @param account account object details: | ||
| * { | ||
| * "coin": constants.messages.BTCCoin, // for example constants.messages.BTCCoin.BTC | ||
| * "keypathAccount": [number], // account-level keypath, for example `getKeypathFromString("m/48'/0'/0'/2'")`. | ||
| * "threshold": number, // signing threshold, e.g. 2. | ||
| * "xpubs": [string], // list of account-level xpubs given in any format. One of them must belong to the connected BitBox02. | ||
| * "ourXPubIndex": nmber, // index of the currently connected BitBox02's multisig xpub in the xpubs array, e.g. 0. | ||
| * } | ||
| * { | ||
| * "coin": constants.messages.BTCCoin, // for example constants.messages.BTCCoin.BTC | ||
| * "keypathAccount": [number], // account-level keypath, for example `getKeypathFromString("m/48'/0'/0'/2'")`. | ||
| * "threshold": number, // signing threshold, e.g. 2. | ||
| * "xpubs": [string], // list of account-level xpubs given in any format. One of them must belong to the connected BitBox02. | ||
| * "ourXPubIndex": nmber, // index of the currently connected BitBox02's multisig xpub in the xpubs array, e.g. 0. | ||
| * } | ||
| * @param getName: async () => string - If the account is unknown to the device, this function will be called to get an | ||
@@ -278,4 +301,5 @@ * account name from the user. The resulting name must be between 1 and 30 ascii chars. | ||
| /* | ||
| * Display a multisig address on the device. `btcMaybeRegisterScriptConfig` should be called beforehand. | ||
| /** | ||
| * # Display a multisig address on the device. `btcMaybeRegisterScriptConfig` should be called beforehand. | ||
| * | ||
| * @param account same as in `btcMaybeRegisterScriptConfig`. | ||
@@ -293,4 +317,5 @@ * @param keypath address-level keypath from the account, usually `account.keypathAccount.concat([0, address])`. | ||
| /* | ||
| * Sign a multisig transaction. `btcMaybeRegisterScriptConfig` should be called beforehand. | ||
| /** | ||
| * # Sign a multisig transaction. `btcMaybeRegisterScriptConfig` should be called beforehand. | ||
| * | ||
| * @param account same as in `btcMaybeRegisterScriptConfig`. | ||
@@ -315,7 +340,14 @@ * Other params and return are the same as in `btcSignSimple`. | ||
| // --- End Bitcoin methods --- | ||
| // --- Ethereum methods --- | ||
| /** | ||
| * # Get Ethereum xPub key 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 | ||
| * - `m/44'/60'/0'/0` for mainnet and | ||
| * - `m/44'/1'/0'/0` for Rinkeby and Ropsten testnets | ||
| * @returns string; ethereum extended public key | ||
@@ -337,5 +369,5 @@ */ | ||
| /** | ||
| * # Display an Ethereum address on the device screen for verification. | ||
| * | ||
| * @param keypath string, e.g. m/44'/60'/0'/0/0 for the first mainnet account | ||
| * Displays the address of the provided ethereum account on device screen | ||
| * Only displays address on device, does not return. For verification, derive address from xpub | ||
| */ | ||
@@ -357,16 +389,19 @@ async ethDisplayAddress(keypath) { | ||
| /** | ||
| * 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 | ||
| * } | ||
| * # Signs an Ethereum transaction on the device. | ||
| * | ||
| * We recommend using the [`Transaction` type](https://github.com/ethereumjs/ethereumjs-tx/blob/master/src/transaction.ts) provided by the `ethereumjs` library.\ | ||
| * | ||
| * @param signingData Object | ||
| * { | ||
| * 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) | ||
| * } | ||
| * { | ||
| * r: Uint8Array(32) | ||
| * s: Uint8Array(32) | ||
| * v: Uint8Array(1) | ||
| * } | ||
| */ | ||
@@ -401,15 +436,16 @@ async ethSignTransaction(signingData) { | ||
| /** @param msgData is an object including the keypath and the message as bytes: | ||
| /** | ||
| * # Sign an Ethereum message on the device. | ||
| * | ||
| * const msgData = { | ||
| * keypath // string, e.g. m/44'/60'/0'/0/0 for the first mainnet account | ||
| * message // Buffer/Uint8Array | ||
| * } | ||
| * | ||
| * @param msgData is an object including the keypath and the message as bytes | ||
| * { | ||
| * 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) | ||
| * } | ||
| * { | ||
| * r: Uint8Array(32) | ||
| * s: Uint8Array(32) | ||
| * v: Uint8Array(1) | ||
| * } | ||
| */ | ||
@@ -440,2 +476,4 @@ async ethSignMessage(msgData) { | ||
| // --- End Ethereum methods --- | ||
| /** | ||
@@ -442,0 +480,0 @@ * @returns True if the connection has been opened and successfully established. |
@@ -0,1 +1,15 @@ | ||
| // Copyright 2019 Shift Cryptosecurity AG | ||
| // | ||
| // Licensed under the Apache License, Version 2.0 (the "License"); | ||
| // you may not use this file except in compliance with the License. | ||
| // You may obtain a copy of the License at | ||
| // | ||
| // http://www.apache.org/licenses/LICENSE-2.0 | ||
| // | ||
| // Unless required by applicable law or agreed to in writing, software | ||
| // distributed under the License is distributed on an "AS IS" BASIS, | ||
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| // See the License for the specific language governing permissions and | ||
| // limitations under the License. | ||
| export { getKeypathFromString } from './utils.js'; | ||
@@ -2,0 +16,0 @@ |
@@ -0,1 +1,15 @@ | ||
| // Copyright 2019 Shift Cryptosecurity AG | ||
| // | ||
| // Licensed under the Apache License, Version 2.0 (the "License"); | ||
| // you may not use this file except in compliance with the License. | ||
| // You may obtain a copy of the License at | ||
| // | ||
| // http://www.apache.org/licenses/LICENSE-2.0 | ||
| // | ||
| // Unless required by applicable law or agreed to in writing, software | ||
| // distributed under the License is distributed on an "AS IS" BASIS, | ||
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| // See the License for the specific language governing permissions and | ||
| // limitations under the License. | ||
| import { constants, HARDENED } from './bitbox02.js'; | ||
@@ -2,0 +16,0 @@ |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by0.01%
4557947
- Lines of code
- increased by3.76%
1547
Worsened metrics
- Number of lines in readme file
- decreased by-20.09%
187
No dependency changes