Merge pull request #210 from GridPlus/prerelease-0.9.3

0.9.3

README.md

@@ -39,41 +39,38 @@ Once you have paired with a device in a re-usable way (i.e. using the commands a
 
 **ETH**
 
-Ethereum tests include both boundary checks on transaction params and randomized test vectors (20 by default). You can run the suite with:
+Ethereum tests include both boundary checks on transaction params and randomized test vectors (20 by default). 
+
+*`env` options:*
+
+* `N=<int>` (default=`3`) - number of random vectors to test
+* `SEED=<string>` (default=`myrandomseed`) - randomness for the pseudorandom number generator that builds deterministic test vectors
+
+Run the suite with:
 
 ```sh
 env DEVICE_ID='my_device_id' npm run test-eth
 ```
 
 If you wish to do more or fewer than 20 random transaction tests, you can specify the `N` param:
 
-```sh
-env DEVICE_ID='my_device_id' N=25 npm run test-eth
-```
-
 
 **BTC**
 
-Bitcoin tests cover legacy and segwit spends on both mainnet and testnet. They are completely randomized and when you run them, the following happens:
+Bitcoin tests cover legacy, wrapped segwit, and segwit spending to all address types. Vectors are built deterministically using the seed and all permutations are tested.
 
-1. Build a wallet using a mnemonic. There is a default mnemonic matching other GridPlus tests, but you can pass your own in with the `env` param `MNEMONIC`. This mnemonic **must** match the wallet on your Lattice or none of these tests will work.
-2. Build a bunch of randomized inputs. The number defaults to 10, but you can define a number with the `env` param `N`.
-3. Use `bitcoinjs-lib` to generate a series of sighashes corresponding to the inputs. These first need to be signed with the respective keys, which can be derived using the wallet from step 1.
-4. Build the Lattice request with the same inputs. You will get `N` signatures back from the Lattice (in addition to a fully broadcastable transaction payload, which we do not use in these tests). Note that `N` must be <11, as the Lattice will only sign up to 10 inputs together.
-5. With the `bitcoinjs-lib` sighashes, the derived keys from the wallet, and now signatures from the Lattice, we validate the signatures against the sighashes. If the validation passes, it means we built the correct sighash in the Lattice and signed it with the correct derived key.
+*`env` options:*
+
+* `N=<int>` (default=`3`) - number of inputs per test. Note that if you choose e.g. `N=2` each test will first test one input, then will test two. Must be >0 and <11.
+* `SEED=<string>` (default=`myrandomseed`) - randomness for the pseudorandom number generator that builds deterministic test vectors
+* `TESTNET=<any>` (default=`false`) - if set to any value you will test all combinations for both mainnet and testnet transactions (doubles number of tests run)
 
 Run the tests with:
 
 ```sh
 env DEVICE_ID='my_device_id' npm run test-btc
 ```
 
-If you want to specify the above params:
-
-```sh
-env DEVICE_ID='my_device_id' N=5 MNEMONIC='negative spare peasant raw feature camera glide notice fee gown heavy depart' npm run test-btc
-```
-
 ### Ethereum ABI Tests
 
 You may test functionality around loading Ethereum ABI definitions and displaying calldata in a markdwon screen with the following script:

docs/index.md

@@ -66,6 +66,14 @@ If you get a non-error response, it means you can talk to the device. Note that
 
 > The `deviceId` is listed on your Lattice under `Settings->Device Info`
 
+### Canceling a Pairing Request
+
+If you get `isPaired = false` in the callback, this request will have started the pairing request with the specified device, which will now be showing a random 8 character pairing code for 60 seconds. 
+
+If you wish to cancel this request, you may call `pair()` with an empty string `''` as the first argument. This will 
+gracefully cancel the request. You may also call `pair()` with any random string which will also cancel the request, but 
+the Lattice will show an error screen.
+
 # Pairing with a Lattice
 
 > This function requires the user to interact with the Lattice. It therefore uses your client's timeout to sever the request if needed.
@@ -117,7 +125,6 @@ client.addresses(req, (err, res) => {
 |:-----------|:----------|:-----------------|:----------------|:----------------------|
 | `startPath` | Array    | none             | n/a             | First address path in BIP44 tree to return. You must provide 5 indices to form the path. |
 | `n`        | number    | 1                | n/a             | Number of subsequent addresses after `start` to derive. These will increment over the final index in the path |
-| `skipCache` | bool     | true            | n/a             | If set to true, skip the restriction that only cached addresses may be requested. This allows the user to request any address for a supported currency (BTC and ETH). Ignored for Lattice firmware versions <0.10.0 |
 
 **Response:**
 
@@ -132,16 +139,6 @@ res = [
 ]
 ```
 
-## The Address Cache
-
-If `skipCache=false`, the requester may only fetch addresses that have been saved to the Lattice's cache. This is used mainly for BTC to keep track
-of which addresses have been generated in an effort to sync an HD wallet. **Since the gap limit of ETH is 0, caching isn't relevant for it, so you should generally use `skipCache=true` when requesting ETH addresses.**
-
-The following restrictions apply when using `skipCache=false`:
-
-* `ETH`: The Lattice only returns the 0-th index address (`m/44'/60'/0'/0/0`) of the current wallet (either on-board Lattice or external SafeCard). This means `n` must be equal to `1` and the only acceptable path is that of the 0-th index address.
-* `BTC`: Currently we only support `p2sh-p2wpkh` BTC addresses which use [BIP49](https://en.bitcoin.it/wiki/BIP_0049): `m/49'/0'/0'/0/x`. If testnet is enabled (`testnet3`), we also allow `m/49'/1'/0'/0/x`. Here, `x` may be any address that has been "cached" by the Lattice. We cache addresses relative to the requested address based on the [gap limit](https://blog.blockonomics.co/bitcoin-what-is-this-gap-limit-4f098e52d7e1?gi=616654046ec4). For the regular wallet, the gap limit is 20. In addition to these addresses, the user may request change addresses (`m/49'/0'/0/1/x` and `m/49'/1'/0'/1/x`). The gap limit for change addresses is 1. Because the Lattice itself is stateless, it creates new addresses whenever previous addresses are requested. For example, if regular addresses 0-19 have been cached (i.e. on an initial cache) and the user requests addresses 9-19, the wallet would then cache 20-29 and the user could then request any of those addresses (which would, in turn, lead to more becoming available). The same logic applies for change addresses, but only the subsequent one would get cached. Note that if you request addresses outside of the gap limit, you will get an error and no new addresses will be cached.
-
 # Requesting Signatures
 
 > This function requires the user to interact with the Lattice. It therefore uses your client's timeout to sever the request if needed.