@bitcoinerlab/descriptors 0.2.0

package/dist/scriptExpressions.d.ts

@@ -0,0 +1,58 @@
+import type { AppClient } from '@bitcoinerlab/ledger';
+import { Network } from 'bitcoinjs-lib';
+import type { LedgerState } from './ledger';
+import type { BIP32Interface } from 'bip32';
+export declare const pkhBIP32: ({ masterNode, network, keyPath, account, change, index, isPublic }: {
+    masterNode: BIP32Interface;
+    network?: Network;
+    account: number;
+    change?: number | undefined;
+    index?: number | undefined | '*';
+    keyPath?: string;
+    isPublic?: boolean;
+}) => string;
+export declare const shWpkhBIP32: ({ masterNode, network, keyPath, account, change, index, isPublic }: {
+    masterNode: BIP32Interface;
+    network?: Network;
+    account: number;
+    change?: number | undefined;
+    index?: number | undefined | '*';
+    keyPath?: string;
+    isPublic?: boolean;
+}) => string;
+export declare const wpkhBIP32: ({ masterNode, network, keyPath, account, change, index, isPublic }: {
+    masterNode: BIP32Interface;
+    network?: Network;
+    account: number;
+    change?: number | undefined;
+    index?: number | undefined | '*';
+    keyPath?: string;
+    isPublic?: boolean;
+}) => string;
+export declare const pkhLedger: ({ ledgerClient, ledgerState, network, account, keyPath, change, index }: {
+    ledgerClient: AppClient;
+    ledgerState: LedgerState;
+    network?: Network;
+    account: number;
+    keyPath?: string;
+    change?: number | undefined;
+    index?: number | undefined | '*';
+}) => Promise<string>;
+export declare const shWpkhLedger: ({ ledgerClient, ledgerState, network, account, keyPath, change, index }: {
+    ledgerClient: AppClient;
+    ledgerState: LedgerState;
+    network?: Network;
+    account: number;
+    keyPath?: string;
+    change?: number | undefined;
+    index?: number | undefined | '*';
+}) => Promise<string>;
+export declare const wpkhLedger: ({ ledgerClient, ledgerState, network, account, keyPath, change, index }: {
+    ledgerClient: AppClient;
+    ledgerState: LedgerState;
+    network?: Network;
+    account: number;
+    keyPath?: string;
+    change?: number | undefined;
+    index?: number | undefined | '*';
+}) => Promise<string>;

package/dist/scriptExpressions.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wpkhLedger = exports.shWpkhLedger = exports.pkhLedger = exports.wpkhBIP32 = exports.shWpkhBIP32 = exports.pkhBIP32 = void 0;
+const bitcoinjs_lib_1 = require("bitcoinjs-lib");
+const keyExpressions_1 = require("./keyExpressions");
+function assertStandardKeyPath(keyPath) {
+    // Regular expression to match "/change/index" or "/change/*" format
+    const regex = /^\/[01]\/(\d+|\*)$/;
+    if (!regex.test(keyPath)) {
+        throw new Error("Error: Key path must be in the format '/change/index', where change is either 0 or 1 and index is a non-negative integer.");
+    }
+}
+function standardExpressionsBIP32Maker(purpose, scriptTemplate) {
+    function standardKeyExpressionBIP32({ masterNode, network = bitcoinjs_lib_1.networks.bitcoin, keyPath, account, change, index, isPublic = true }) {
+        const originPath = `/${purpose}'/${network === bitcoinjs_lib_1.networks.bitcoin ? 0 : 1}'/${account}'`;
+        if (keyPath !== undefined)
+            assertStandardKeyPath(keyPath);
+        const keyExpression = (0, keyExpressions_1.keyExpressionBIP32)({
+            masterNode,
+            originPath,
+            keyPath,
+            change,
+            index,
+            isPublic
+        });
+        return scriptTemplate.replace('KEYEXPRESSION', keyExpression);
+    }
+    return standardKeyExpressionBIP32;
+}
+exports.pkhBIP32 = standardExpressionsBIP32Maker(44, 'pkh(KEYEXPRESSION)');
+exports.shWpkhBIP32 = standardExpressionsBIP32Maker(49, 'sh(wpkh(KEYEXPRESSION))');
+exports.wpkhBIP32 = standardExpressionsBIP32Maker(84, 'wpkh(KEYEXPRESSION)');
+function standardExpressionsLedgerMaker(purpose, scriptTemplate) {
+    async function standardKeyExpressionLedger({ ledgerClient, ledgerState, network = bitcoinjs_lib_1.networks.bitcoin, account, keyPath, change, index }) {
+        const originPath = `/${purpose}'/${network === bitcoinjs_lib_1.networks.bitcoin ? 0 : 1}'/${account}'`;
+        if (keyPath !== undefined)
+            assertStandardKeyPath(keyPath);
+        const keyExpression = await (0, keyExpressions_1.keyExpressionLedger)({
+            ledgerClient,
+            ledgerState,
+            originPath,
+            keyPath,
+            change,
+            index
+        });
+        return scriptTemplate.replace('KEYEXPRESSION', keyExpression);
+    }
+    return standardKeyExpressionLedger;
+}
+exports.pkhLedger = standardExpressionsLedgerMaker(44, 'pkh(KEYEXPRESSION)');
+exports.shWpkhLedger = standardExpressionsLedgerMaker(49, 'sh(wpkh(KEYEXPRESSION))');
+exports.wpkhLedger = standardExpressionsLedgerMaker(84, 'wpkh(KEYEXPRESSION)');

package/dist/signers.d.ts

@@ -0,0 +1,37 @@
+import type { Psbt } from 'bitcoinjs-lib';
+import type { ECPairInterface } from 'ecpair';
+import type { BIP32Interface } from 'bip32';
+import { AppClient } from '@bitcoinerlab/ledger';
+import type { DescriptorInterface } from './types';
+import { LedgerState } from './ledger';
+export declare function signInputECPair({ psbt, index, ecpair }: {
+    psbt: Psbt;
+    index: number;
+    ecpair: ECPairInterface;
+}): void;
+export declare function signECPair({ psbt, ecpair }: {
+    psbt: Psbt;
+    ecpair: ECPairInterface;
+}): void;
+export declare function signInputBIP32({ psbt, index, node }: {
+    psbt: Psbt;
+    index: number;
+    node: BIP32Interface;
+}): void;
+export declare function signBIP32({ psbt, masterNode }: {
+    psbt: Psbt;
+    masterNode: BIP32Interface;
+}): void;
+export declare function signInputLedger({ psbt, index, descriptor, ledgerClient, ledgerState }: {
+    psbt: Psbt;
+    index: number;
+    descriptor: DescriptorInterface;
+    ledgerClient: AppClient;
+    ledgerState: LedgerState;
+}): Promise<void>;
+export declare function signLedger({ psbt, descriptors, ledgerClient, ledgerState }: {
+    psbt: Psbt;
+    descriptors: DescriptorInterface[];
+    ledgerClient: AppClient;
+    ledgerState: LedgerState;
+}): Promise<void>;

package/dist/signers.js

@@ -0,0 +1,112 @@
+"use strict";
+// Copyright (c) 2023 Jose-Luis Landabaso - https://bitcoinerlab.com
+// Distributed under the MIT software license
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signLedger = exports.signInputLedger = exports.signBIP32 = exports.signInputBIP32 = exports.signECPair = exports.signInputECPair = void 0;
+const ledger_1 = require("@bitcoinerlab/ledger");
+const ledger_2 = require("./ledger");
+function signInputECPair({ psbt, index, ecpair }) {
+    psbt.signInput(index, ecpair);
+}
+exports.signInputECPair = signInputECPair;
+function signECPair({ psbt, ecpair }) {
+    psbt.signAllInputs(ecpair);
+}
+exports.signECPair = signECPair;
+function signInputBIP32({ psbt, index, node }) {
+    psbt.signInputHD(index, node);
+}
+exports.signInputBIP32 = signInputBIP32;
+function signBIP32({ psbt, masterNode }) {
+    psbt.signAllInputsHD(masterNode);
+}
+exports.signBIP32 = signBIP32;
+const ledgerSignaturesForInputIndex = (index, ledgerSignatures) => ledgerSignatures
+    .filter(([i]) => i === index)
+    .map(([_i, pubkey, signature]) => ({
+    pubkey,
+    signature
+}));
+async function signInputLedger({ psbt, index, descriptor, ledgerClient, ledgerState }) {
+    const result = await (0, ledger_2.descriptorToLedgerFormat)({
+        descriptor,
+        ledgerClient,
+        ledgerState
+    });
+    if (!result)
+        throw new Error(`Error: descriptor does not have a ledger input`);
+    const { ledgerTemplate, keyRoots } = result;
+    let ledgerSignatures;
+    const standardPolicy = await (0, ledger_2.ledgerPolicyFromStandard)({
+        descriptor,
+        ledgerClient,
+        ledgerState
+    });
+    if (standardPolicy) {
+        ledgerSignatures = await ledgerClient.signPsbt(new ledger_1.PsbtV2().fromBitcoinJS(psbt), new ledger_1.DefaultWalletPolicy(ledgerTemplate, keyRoots[0]), null);
+    }
+    else {
+        const policy = await (0, ledger_2.ledgerPolicyFromState)({
+            descriptor,
+            ledgerClient,
+            ledgerState
+        });
+        if (!policy || !policy.policyName || !policy.policyHmac)
+            throw new Error(`Error: the descriptor's policy is not registered`);
+        const walletPolicy = new ledger_1.WalletPolicy(policy.policyName, ledgerTemplate, keyRoots);
+        ledgerSignatures = await ledgerClient.signPsbt(new ledger_1.PsbtV2().fromBitcoinJS(psbt), walletPolicy, policy.policyHmac);
+    }
+    //Add the signatures to the Psbt object using PartialSig format:
+    psbt.updateInput(index, {
+        partialSig: ledgerSignaturesForInputIndex(index, ledgerSignatures)
+    });
+}
+exports.signInputLedger = signInputLedger;
+//signLedger is able to sign several inputs of the same wallet policy since it
+//it clusters together wallet policy types before signing
+//it throws if it cannot sign any input.
+async function signLedger({ psbt, descriptors, ledgerClient, ledgerState }) {
+    const ledgerPolicies = [];
+    for (const descriptor of descriptors) {
+        const policy = (await (0, ledger_2.ledgerPolicyFromState)({
+            descriptor,
+            ledgerClient,
+            ledgerState
+        })) ||
+            (await (0, ledger_2.ledgerPolicyFromStandard)({
+                descriptor,
+                ledgerClient,
+                ledgerState
+            }));
+        if (policy)
+            ledgerPolicies.push(policy);
+    }
+    if (ledgerPolicies.length === 0)
+        throw new Error(`Error: there are no inputs which could be signed`);
+    //cluster unique LedgerPolicies
+    const uniquePolicies = [];
+    for (const policy of ledgerPolicies) {
+        if (!uniquePolicies.find((uniquePolicy) => (0, ledger_2.comparePolicies)(uniquePolicy, policy)))
+            uniquePolicies.push(policy);
+    }
+    for (const uniquePolicy of uniquePolicies) {
+        let ledgerSignatures;
+        if (uniquePolicy.policyName &&
+            uniquePolicy.policyHmac &&
+            uniquePolicy.policyId) {
+            //non-standard policy
+            const walletPolicy = new ledger_1.WalletPolicy(uniquePolicy.policyName, uniquePolicy.ledgerTemplate, uniquePolicy.keyRoots);
+            ledgerSignatures = await ledgerClient.signPsbt(new ledger_1.PsbtV2().fromBitcoinJS(psbt), walletPolicy, uniquePolicy.policyHmac);
+        }
+        else {
+            //standard policy
+            ledgerSignatures = await ledgerClient.signPsbt(new ledger_1.PsbtV2().fromBitcoinJS(psbt), new ledger_1.DefaultWalletPolicy(uniquePolicy.ledgerTemplate, uniquePolicy.keyRoots[0]), null);
+        }
+        for (const [index, ,] of ledgerSignatures) {
+            psbt.updateInput(index, {
+                partialSig: ledgerSignaturesForInputIndex(index, ledgerSignatures)
+            });
+        }
+    }
+}
+exports.signLedger = signLedger;

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+/// <reference types="node" />
+import type { ECPairInterface } from 'ecpair';
+import type { BIP32Interface } from 'bip32';
+import type { Network, Payment, Psbt } from 'bitcoinjs-lib';
+import type { PartialSig } from 'bip174/src/lib/interfaces';
+export interface Preimage {
+    digest: string;
+    preimage: string;
+}
+export type TimeConstraints = {
+    nLockTime: number | undefined;
+    nSequence: number | undefined;
+};
+export type KeyInfo = {
+    keyExpression: string;
+    pubkey: Buffer;
+    ecpair?: ECPairInterface;
+    bip32?: BIP32Interface;
+    masterFingerprint?: Buffer;
+    originPath?: string;
+    keyPath?: string;
+    path?: string;
+};
+export type ExpansionMap = {
+    [key: string]: KeyInfo;
+};
+export interface ParseKeyExpression {
+    (params: {
+        keyExpression: string;
+        isSegwit?: boolean;
+        network?: Network;
+    }): KeyInfo;
+}
+interface XOnlyPointAddTweakResult {
+    parity: 1 | 0;
+    xOnlyPubkey: Uint8Array;
+}
+export interface TinySecp256k1Interface {
+    isPoint(p: Uint8Array): boolean;
+    pointCompress(p: Uint8Array, compressed?: boolean): Uint8Array;
+    isPrivate(d: Uint8Array): boolean;
+    pointFromScalar(d: Uint8Array, compressed?: boolean): Uint8Array | null;
+    pointAddScalar(p: Uint8Array, tweak: Uint8Array, compressed?: boolean): Uint8Array | null;
+    privateAdd(d: Uint8Array, tweak: Uint8Array): Uint8Array | null;
+    sign(h: Uint8Array, d: Uint8Array, e?: Uint8Array): Uint8Array;
+    signSchnorr?(h: Uint8Array, d: Uint8Array, e?: Uint8Array): Uint8Array;
+    verify(h: Uint8Array, Q: Uint8Array, signature: Uint8Array, strict?: boolean): boolean;
+    verifySchnorr?(h: Uint8Array, Q: Uint8Array, signature: Uint8Array): boolean;
+    xOnlyPointAddTweak(p: Uint8Array, tweak: Uint8Array): XOnlyPointAddTweakResult | null;
+    privateNegate(d: Uint8Array): Uint8Array;
+}
+export type DescriptorInfo = {
+    expression: string;
+    index?: number;
+    checksumRequired?: boolean;
+    allowMiniscriptInP2SH?: boolean;
+    network?: Network;
+    preimages?: Preimage[];
+    signersPubKeys?: Buffer[];
+};
+export interface DescriptorInterface {
+    getPayment(): Payment;
+    getAddress(): string;
+    getScriptPubKey(): Buffer;
+    getScriptSatisfaction(signatures: PartialSig[]): Buffer;
+    getSequence(): number | undefined;
+    getLockTime(): number | undefined;
+    getWitnessScript(): Buffer | undefined;
+    getRedeemScript(): Buffer | undefined;
+    getNetwork(): Network;
+    isSegwit(): boolean | undefined;
+    updatePsbt({ psbt, vout, txHex, txId, value }: {
+        psbt: Psbt;
+        vout: number;
+        txHex?: string;
+        txId?: string;
+        value?: number;
+    }): number;
+    finalizePsbtInput({ index, psbt, validate }: {
+        index: number;
+        psbt: Psbt;
+        validate?: boolean | undefined;
+    }): void;
+    expand(): {
+        expandedExpression?: string;
+        miniscript?: string;
+        expandedMiniscript?: string;
+        expansionMap?: ExpansionMap;
+    };
+}
+export interface DescriptorInterfaceConstructor {
+    new (args: DescriptorInfo): DescriptorInterface;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,4 @@
+"use strict";
+// Copyright (c) 2023 Jose-Luis Landabaso - https://bitcoinerlab.com
+// Distributed under the MIT software license
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@bitcoinerlab/descriptors",
+  "homepage": "https://github.com/bitcoinerlab/descriptors",
+  "version": "0.2.0",
+  "description": "This library parses and creates Bitcoin Miniscript Descriptors and generates Partially Signed Bitcoin Transactions (PSBTs). It provides PSBT finalizers and signers for single-signature, BIP32 and Hardware Wallets.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "npx tsc",
+    "prepublishOnly": "npm run build && npm test && echo \"\\n\\n\" && npm run test:integration:ledger",
+    "docs": "jsdoc -c jsdoc.json",
+    "regtest-docker": "docker ps | grep bitcoinjs-regtest-server > /dev/null || (docker pull junderw/bitcoinjs-regtest-server && docker run -d -p 8080:8080 junderw/bitcoinjs-regtest-server && sleep 5)",
+    "test:integration:soft": "npm run regtest-docker && npx ts-node test/integration/standardOutputs.ts && echo \"\\n\\n\" && npx ts-node test/integration/miniscript.ts",
+    "test:integration:ledger": "npm run regtest-docker && npx ts-node test/integration/ledger.ts",
+    "test:unit": "npm run build && node test/tools/generateBitcoinCoreFixtures.js && jest",
+    "test": "npm run lint && npm run lint:test && npm run test:unit && npm run test:integration:soft",
+    "lint": "eslint --ignore-path .gitignore --ext .js,.ts src/",
+    "lint:test": "eslint --ignore-path .gitignore --ext .js,.ts test/"
+  },
+  "COMMENT_babel": "Babel plugins are are only needed for the jest testing environment. Jest needs to use commonjs. Also, jest cannot handle ESM converted code, since it uses 'import.meta.url'. See src/bindings.js. babel-plugin-transform-import-meta fixes it.",
+  "babel": {
+    "env": {
+      "test": {
+        "plugins": [
+          "@babel/plugin-transform-modules-commonjs",
+          "babel-plugin-transform-import-meta"
+        ]
+      }
+    }
+  },
+  "jest": {
+    "testPathIgnorePatterns": [
+      "example/",
+      "dist/"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bitcoinerlab/descriptors.git"
+  },
+  "keywords": [
+    "bitcoin",
+    "descriptors",
+    "bitcoinjs",
+    "miniscript"
+  ],
+  "author": "Jose-Luis Landabaso",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/bitcoinerlab/descriptors/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@bitcoinerlab/ledger": "^0.1.6",
+    "@bitcoinerlab/miniscript": "^1.2.1",
+    "@bitcoinerlab/secp256k1": "^1.0.2",
+    "bip32": "^3.1.0",
+    "bitcoinjs-lib": "^6.1.0",
+    "ecpair": "^2.1.0"
+  },
+  "devDependencies": {
+    "@babel/plugin-transform-modules-commonjs": "^7.20.11",
+    "@ledgerhq/hw-transport-node-hid": "^6.27.12",
+    "@typescript-eslint/eslint-plugin": "^5.53.0",
+    "@typescript-eslint/parser": "^5.53.0",
+    "babel-plugin-transform-import-meta": "^2.2.0",
+    "bip39": "^3.0.4",
+    "bip65": "^1.0.3",
+    "bip68": "^1.0.4",
+    "eslint-config-prettier": "^8.6.0",
+    "eslint-plugin-jest": "^27.2.1",
+    "eslint-plugin-prettier": "^4.2.1",
+    "fs": "^0.0.1-security",
+    "jest": "^29.4.3",
+    "jsdoc": "^4.0.0",
+    "path": "^0.12.7",
+    "prettier": "^2.8.4",
+    "regtest-client": "^0.2.0",
+    "ts-node-dev": "^2.0.0"
+  }
+}