@ledgerhq/hw-app-btc 6.10.0 → 6.12.0

package/lib/Btc.js

@@ -58,6 +58,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 exports.__esModule = true;
+var bip32_1 = require("./bip32");
 var BtcNew_1 = __importStar(require("./BtcNew"));
 var BtcOld_1 = __importDefault(require("./BtcOld"));
 var getAppAndVersion_1 = require("./getAppAndVersion");
@@ -113,7 +114,7 @@ var Btc = /** @class */ (function () {
      *
      * - p2sh format with 49' paths
      *
-     * - bech32 format with 173' paths
+     * - bech32 format with 84' paths
      *
      * - cashaddr in case of Bitcoin Cash
      *
@@ -122,6 +123,7 @@ var Btc = /** @class */ (function () {
      * btc.getWalletPublicKey("49'/0'/0'/0/0", { format: "p2sh" }).then(o => o.bitcoinAddress)
      */
     Btc.prototype.getWalletPublicKey = function (path, opts) {
+        var _this = this;
         var options;
         if (arguments.length > 2 || typeof opts === "boolean") {
             console.warn("btc.getWalletPublicKey deprecated signature used. Please switch to getWalletPublicKey(path, { format, verify })");
@@ -135,7 +137,39 @@ var Btc = /** @class */ (function () {
             options = opts || {};
         }
         return this.getCorrectImpl().then(function (impl) {
-            return impl.getWalletPublicKey(path, options);
+            /**
+             * Definition: A "normal path" is a prefix of a standard path where all
+             * the hardened steps of the standard path are included. For example, the
+             * paths m/44'/1'/17' and m/44'/1'/17'/1 are normal paths, but m/44'/1'
+             * is not. m/'199/1'/17'/0/1 is not a normal path either.
+             *
+             * There's a compatiblity issue between old and new app: When exporting
+             * the key of a non-normal path with verify=false, the new app would
+             * return an error, whereas the old app would return the key.
+             *
+             * See
+             * https://github.com/LedgerHQ/app-bitcoin-new/blob/master/doc/bitcoin.md#get_extended_pubkey
+             *
+             * If format bech32m is used, we'll not use old, because it doesn't
+             * support it.
+             *
+             * When to use new (given the app supports it)
+             *   * format is bech32m or
+             *   * path is normal or
+             *   * verify is true
+             *
+             * Otherwise use old.
+             */
+            if (impl instanceof BtcNew_1["default"] &&
+                options.format != "bech32m" &&
+                (!options.verify || options.verify == false) &&
+                !isPathNormal(path)) {
+                console.warn("WARNING: Using deprecated device protocol to get the public key because\n        \n        * a non-standard path is requested, and\n        * verify flag is false\n        \n        The new protocol only allows export of non-standard paths if the \n        verify flag is true. Standard paths are (currently):\n\n        M/44'/(1|0)'/X'\n        M/49'/(1|0)'/X'\n        M/84'/(1|0)'/X'\n        M/86'/(1|0)'/X'\n        M/48'/(1|0)'/X'/Y'\n\n        followed by \"\", \"(0|1)\", or \"(0|1)/b\", where a and b are \n        non-hardened. For example, the following paths are standard\n        \n        M/48'/1'/99'/7'\n        M/86'/1'/99'/0\n        M/48'/0'/99'/7'/1/17\n\n        The following paths are non-standard\n\n        M/48'/0'/99'           // Not deepest hardened path\n        M/48'/0'/99'/7'/1/17/2 // Too many non-hardened derivation steps\n        M/199'/0'/1'/0/88      // Not a known purpose 199\n        M/86'/1'/99'/2         // Change path item must be 0 or 1\n\n        This compatibility safeguard will be removed in the future.\n        Please consider calling Btc.getWalletXpub() instead.");
+                return _this.old().getWalletPublicKey(path, options);
+            }
+            else {
+                return impl.getWalletPublicKey(path, options);
+            }
         });
     };
     /**
@@ -160,21 +194,21 @@ var Btc = /** @class */ (function () {
      * * sequence is the sequence number to use for this input (when using RBF), or non present
      * @param associatedKeysets is an array of BIP 32 paths pointing to the path to the private key used for each UTXO
      * @param changePath is an optional BIP 32 path pointing to the path to the public key used to compute the change address
-     * @param outputScriptHex is the hexadecimal serialized outputs of the transaction to sign
+     * @param outputScriptHex is the hexadecimal serialized outputs of the transaction to sign, including leading vararg voutCount
      * @param lockTime is the optional lockTime of the transaction to sign, or default (0)
      * @param sigHashType is the hash type of the transaction to sign, or default (all)
-     * @param segwit is an optional boolean indicating wether to use segwit or not
+     * @param segwit is an optional boolean indicating wether to use segwit or not. This includes wrapped segwit.
      * @param initialTimestamp is an optional timestamp of the function call to use for coins that necessitate timestamps only, (not the one that the tx will include)
      * @param additionals list of additionnal options
      *
      * - "bech32" for spending native segwit outputs
-     * - "bech32m" for spending native segwit outputs
+     * - "bech32m" for spending segwit v1+ outputs
      * - "abc" for bch
      * - "gold" for btg
      * - "bipxxx" for using BIPxxx
      * - "sapling" to indicate a zec transaction is supporting sapling (to be set over block 419200)
      * @param expiryHeight is an optional Buffer for zec overwinter / sapling Txs
-     * @param useTrustedInputForSegwit trust inputs for segwit transactions
+     * @param useTrustedInputForSegwit trust inputs for segwit transactions. If app version >= 1.4.0 this should be true.
      * @return the signed transaction ready to be broadcast
      * @example
     btc.createTransaction({
@@ -269,10 +303,10 @@ var Btc = /** @class */ (function () {
                         appAndVersion = _a.sent();
                         canUseNewImplementation = (0, BtcNew_1.canSupportApp)(appAndVersion);
                         if (!canUseNewImplementation) {
-                            return [2 /*return*/, new BtcOld_1["default"](this.transport)];
+                            return [2 /*return*/, this.old()];
                         }
                         else {
-                            return [2 /*return*/, new BtcNew_1["default"](new appClient_1.AppClient(this.transport))];
+                            return [2 /*return*/, this["new"]()];
                         }
                         return [2 /*return*/];
                 }
@@ -282,7 +316,38 @@ var Btc = /** @class */ (function () {
     Btc.prototype.old = function () {
         return new BtcOld_1["default"](this.transport);
     };
+    Btc.prototype["new"] = function () {
+        return new BtcNew_1["default"](new appClient_1.AppClient(this.transport));
+    };
     return Btc;
 }());
 exports["default"] = Btc;
+function isPathNormal(path) {
+    //path is not deepest hardened node of a standard path or deeper, use BtcOld
+    var h = 0x80000000;
+    var pathElems = (0, bip32_1.pathStringToArray)(path);
+    var hard = function (n) { return n >= h; };
+    var soft = function (n) { return !n || n < h; };
+    var change = function (n) { return !n || n == 0 || n == 1; };
+    if (pathElems.length >= 3 &&
+        pathElems.length <= 5 &&
+        [44 + h, 49 + h, 84 + h, 86 + h].some(function (v) { return v == pathElems[0]; }) &&
+        [0 + h, 1 + h].some(function (v) { return v == pathElems[1]; }) &&
+        hard(pathElems[2]) &&
+        change(pathElems[3]) &&
+        soft(pathElems[4])) {
+        return true;
+    }
+    if (pathElems.length >= 4 &&
+        pathElems.length <= 6 &&
+        48 + h == pathElems[0] &&
+        [0 + h, 1 + h].some(function (v) { return v == pathElems[1]; }) &&
+        hard(pathElems[2]) &&
+        hard(pathElems[3]) &&
+        change(pathElems[4]) &&
+        soft(pathElems[5])) {
+        return true;
+    }
+    return false;
+}
 //# sourceMappingURL=Btc.js.map

package/lib/Btc.js.map

@@ -1 +1 @@
-{"version":3,"file":"Btc.js","sourceRoot":"","sources":["../src/Btc.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Btc.js","sourceRoot":"","sources":["../src/Btc.ts"],"names":[],"mappings":"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"}

package/lib/BtcNew.d.ts

@@ -1,15 +1,65 @@
 import type { CreateTransactionArg } from "./createTransaction";
+import { AppAndVersion } from "./getAppAndVersion";
 import type { AddressFormat } from "./getWalletPublicKey";
 import { AppClient as Client } from "./newops/appClient";
-import { AppAndVersion } from "./getAppAndVersion";
 export declare function canSupportApp(appAndVersion: AppAndVersion): boolean;
+/**
+ * This class implements the same interface as BtcOld (formerly
+ * named Btc), but interacts with Bitcoin hardware app version 2+
+ * which uses a totally new APDU protocol. This new
+ * protocol is documented at
+ * https://github.com/LedgerHQ/app-bitcoin-new/blob/master/doc/bitcoin.md
+ *
+ * Since the interface must remain compatible with BtcOld, the methods
+ * of this class are quite clunky, because it needs to adapt legacy
+ * input data into the PSBT process. In the future, a new interface should
+ * be developed that exposes PSBT to the outer world, which would render
+ * a much cleaner implementation.
+ */
 export default class BtcNew {
     private client;
     constructor(client: Client);
+    /**
+     * This is a new method that allow users to get an xpub at a standard path.
+     * Standard paths are described at
+     * https://github.com/LedgerHQ/app-bitcoin-new/blob/master/doc/bitcoin.md#description
+     *
+     * This boils down to paths (N=0 for Bitcoin, N=1 for Testnet):
+     * M/44'/N'/x'/**
+     * M/48'/N'/x'/y'/**
+     * M/49'/N'/x'/**
+     * M/84'/N'/x'/**
+     * M/86'/N'/x'/**
+     *
+     * The method was added because of added security in the hardware app v2+. The
+     * new hardware app will allow export of any xpub up to and including the
+     * deepest hardened key of standard derivation paths, whereas the old app
+     * would allow export of any key.
+     *
+     * This caused an issue for callers of this class, who only had
+     * getWalletPublicKey() to call which means they have to constuct xpub
+     * themselves:
+     *
+     * Suppose a user of this class wants to create an account xpub on a standard
+     * path, M/44'/0'/Z'. The user must get the parent key fingerprint (see BIP32)
+     * by requesting the parent key M/44'/0'. The new app won't allow that, because
+     * it only allows exporting deepest level hardened path. So the options are to
+     * allow requesting M/44'/0' from the app, or to add a new function
+     * "getWalletXpub".
+     *
+     * We opted for adding a new function, which can greatly simplify client code.
+     */
     getWalletXpub({ path, xpubVersion, }: {
         path: string;
         xpubVersion: number;
     }): Promise<string>;
+    /**
+     * This method returns a public key, a bitcoin address, and and a chaincode
+     * for a specific derivation path.
+     *
+     * Limitation: If the path is not a leaf node of a standard path, the address
+     * will be the empty string "", see this.getWalletAddress() for details.
+     */
     getWalletPublicKey(path: string, opts?: {
         verify?: boolean;
         format?: AddressFormat;
@@ -27,7 +77,7 @@ export default class BtcNew {
      *
      * If display is false we *could* generate the address ourselves, but chose to
      * get it from the device to save development time. However, it shouldn't take
-     * more than a few hours to implement local address generation.
+     * too much time to implement local address generation.
      *
      * Moreover, if the path is not for a leaf, ie accountPath+/X/Y, there is no
      * way to get the address from the device. In this case we have to create it
@@ -35,41 +85,38 @@ export default class BtcNew {
      */
     private getWalletAddress;
     /**
-     * To sign a transaction involving standard (P2PKH) inputs, call createTransaction with the following parameters
-     * @param inputs is an array of [ transaction, output_index, optional redeem script, optional sequence ] where
-     *
-     * * transaction is the previously computed transaction object for this UTXO
-     * * output_index is the output in the transaction used as input for this UTXO (counting from 0)
-     * * redeem script is the optional redeem script to use when consuming a Segregated Witness input
-     * * sequence is the sequence number to use for this input (when using RBF), or non present
-     * @param associatedKeysets is an array of BIP 32 paths pointing to the path to the private key used for each UTXO
-     * @param changePath is an optional BIP 32 path pointing to the path to the public key used to compute the change address
-     * @param outputScriptHex is the hexadecimal serialized outputs of the transaction to sign, including leading vararg voutCount
-     * @param lockTime is the optional lockTime of the transaction to sign, or default (0)
-     * @param sigHashType is the hash type of the transaction to sign, or default (all)
-     * @param segwit is an optional boolean indicating wether to use segwit or not. This includes wrapped segwit.
-     * @param initialTimestamp is an optional timestamp of the function call to use for coins that necessitate timestamps only, (not the one that the tx will include)
-     * @param additionals list of additionnal options
+     * Build and sign a transaction. See Btc.createPaymentTransactionNew for
+     * details on how to use this method.
      *
-     * - "bech32" for spending native segwit outputs
-     * - "bech32m" for spending segwit v1+ outptus
-     * - "abc" for bch
-     * - "gold" for btg
-     * - "bipxxx" for using BIPxxx
-     * - "sapling" to indicate a zec transaction is supporting sapling (to be set over block 419200)
-     * @param expiryHeight is an optional Buffer for zec overwinter / sapling Txs
-     * @param useTrustedInputForSegwit trust inputs for segwit transactions. If app version >= 1.4.0 this should be true.
-     * @return the signed transaction ready to be broadcast
-     * @example
-    btc.createTransaction({
-     inputs: [ [tx1, 1] ],
-     associatedKeysets: ["0'/0/0"],
-     outputScriptHex: "01905f0100000000001976a91472a5d75c8d2d0565b656a5232703b167d50d5a2b88ac"
-    }).then(res => ...);
+     * This method will convert the legacy arguments, CreateTransactionArg, into
+     * a psbt which is finally signed and finalized, and the extracted fully signed
+     * transaction is returned.
      */
     createPaymentTransactionNew(arg: CreateTransactionArg): Promise<string>;
+    /**
+     * Calculates an output script along with public key and possible redeemScript
+     * from a path and accountType. The accountPath must be a prefix of path.
+     *
+     * @returns an object with output script (property "script"), redeemScript (if
+     * wrapped p2wpkh), and pubkey at provided path. The values of these three
+     * properties depend on the accountType used.
+     */
     private outputScriptAt;
+    /**
+     * Adds relevant data about an input to the psbt. This includes sequence,
+     * previous txid, output index, spent UTXO, redeem script for wrapped p2wpkh,
+     * public key and its derivation path.
+     */
     private setInput;
+    /**
+     * This implements the "Signer" role of the BIP370 transaction signing
+     * process.
+     *
+     * It ssks the hardware device to sign the a psbt using the specified wallet
+     * policy. This method assumes BIP32 derived keys are used for all inputs, see
+     * comment in-line. The signatures returned from the hardware device is added
+     * to the appropriate input fields of the PSBT.
+     */
     private signPsbt;
 }
 //# sourceMappingURL=BtcNew.d.ts.map

package/lib/BtcNew.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BtcNew.d.ts","sourceRoot":"","sources":["../src/BtcNew.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EAAE,SAAS,IAAI,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAezD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAInD,wBAAgB,aAAa,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO,CAKnE;AAED,MAAM,CAAC,OAAO,OAAO,MAAM;IACb,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAE5B,aAAa,CAAC,EAClB,IAAI,EACJ,WAAW,GACZ,EAAE;QACD,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,MAAM,CAAC;IAYb,kBAAkB,CACtB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,MAAM,CAAC,EAAE,aAAa,CAAC;KACxB,GACA,OAAO,CAAC;QACT,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IAsBF;;;;;;;;;;;;;;OAcG;YACW,gBAAgB;IAyB9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,2BAA2B,CAC/B,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,MAAM,CAAC;YA0FJ,cAAc;YA2Bd,QAAQ;YA0DR,QAAQ;CA8BvB"}
+{"version":3,"file":"BtcNew.d.ts","sourceRoot":"","sources":["../src/BtcNew.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAS1D,OAAO,EAAE,SAAS,IAAI,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAczD,wBAAgB,aAAa,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO,CAKnE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,OAAO,MAAM;IACb,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,aAAa,CAAC,EAClB,IAAI,EACJ,WAAW,GACZ,EAAE;QACD,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,MAAM,CAAC;IAYnB;;;;;;OAMG;IACG,kBAAkB,CACtB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,MAAM,CAAC,EAAE,aAAa,CAAC;KACxB,GACA,OAAO,CAAC;QACT,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IAsBF;;;;;;;;;;;;;;OAcG;YACW,gBAAgB;IAyB9B;;;;;;;OAOG;IACG,2BAA2B,CAC/B,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,MAAM,CAAC;IAiHlB;;;;;;;OAOG;YACW,cAAc;IAsB5B;;;;OAIG;YACW,QAAQ;IAmDtB;;;;;;;;OAQG;YACW,QAAQ;CA6BvB"}