@bitcoinerlab/descriptors-core 3.1.0

package/dist/descriptors.d.ts

@@ -0,0 +1,481 @@
+import type { Payment, BitcoinLib, ECPairAPI, BIP32API, PsbtLike, ScureTransactionLike } from './bitcoinLib';
+import type { PartialSig } from './bip174';
+import type { TinySecp256k1Interface, Preimage, Expansion, ExpansionMap, KeyExpressionParser } from './types';
+import { type Network } from './networks';
+import type { TapTreeInfoNode, TapTreeNode } from './tapTree';
+import type { TaprootLeafSatisfaction } from './tapMiniscript';
+/**
+ * Constructs the necessary functions and classes for working with descriptors,
+ * using either an external elliptic curve (`ecc`) library or a core Bitcoin
+ * library (e.g.
+ * [bitcoinjs-lib](https://github.com/bitcoinjs/bitcoinjs-lib) or
+ * [@scure/btc-signer](https://github.com/paulmillr/scure-btc-signer)).
+ *
+ * Note:
+ * Most users do not need to call `DescriptorsFactory(...)` directly.
+ * - `@bitcoinerlab/descriptors` already provides the bitcoinjs-ready defaults.
+ * - `@bitcoinerlab/descriptors-scure` already provides the scure-ready defaults.
+ *
+ * This factory is mainly useful for:
+ * - backwards compatibility with pre-`3.1.x` bitcoinjs usage, and
+ * - advanced `@bitcoinerlab/descriptors-core` use cases where you want to bind
+ *   a specific `TinySecp256k1Interface` or a custom `BitcoinLib`.
+ *
+ * In the default bitcoinjs package, the implicit `TinySecp256k1Interface` is
+ * `@bitcoinerlab/secp256k1`.
+ *
+ * Notably, it returns the {@link _Internal_.Output | `Output`} class, which
+ * provides methods to create, sign, and finalize transactions from descriptor
+ * expressions.
+ *
+ * The factory also returns utility methods like `expand` (detailed below)
+ * and `parseKeyExpression` (see {@link KeyExpressionParser}).
+ *
+ * Additionally, for convenience, the factory returns
+ * {@link https://github.com/bitcoinjs/bip32 | `BIP32`} and
+ * {@link https://github.com/bitcoinjs/ecpair | `ECPair`}.
+ * In bitcoinjs mode, these are the already initialized bitcoinjs factories,
+ * equivalent to `BIP32 = BIP32Factory(ecc)` and `ECPair = ECPairFactory(ecc)`.
+ * When using scure, prefer scure-native key types
+ * ({@link https://github.com/paulmillr/scure-bip32 | `HDKey`} and
+ * `Uint8Array` for private keys), which do not require key-factory initialization.
+ *
+ * @param {TinySecp256k1Interface | BitcoinLib} eccOrBitcoinLib - The core
+ * Bitcoin library input used by the factory.
+ *
+ * You can pass this parameter in three common ways:
+ *
+ * ```ts
+ * import { DescriptorsFactory } from '@bitcoinerlab/descriptors-core';
+ * import { createScureLib } from '@bitcoinerlab/descriptors-core/scure';
+ *
+ * const { Output } = DescriptorsFactory(createScureLib());
+ * ```
+ *
+ * ```ts
+ * import * as ecc from '@bitcoinerlab/secp256k1';
+ * import { DescriptorsFactory } from '@bitcoinerlab/descriptors-core';
+ * import { createBitcoinjsLib } from '@bitcoinerlab/descriptors-core/bitcoinjs';
+ *
+ * const { Output } = DescriptorsFactory(createBitcoinjsLib(ecc));
+ * ```
+ *
+ * ```ts
+ * import * as ecc from '@bitcoinerlab/secp256k1';
+ * import { DescriptorsFactory } from '@bitcoinerlab/descriptors';
+ *
+ * // Equivalent to `DescriptorsFactory(createBitcoinjsLib(ecc))`, but implicit.
+ * const { Output } = DescriptorsFactory(ecc);
+ * ```
+ */
+export declare function DescriptorsFactory(eccOrBitcoinLib: TinySecp256k1Interface | BitcoinLib): {
+    Output: {
+        new ({ descriptor, index, change, checksumRequired, allowMiniscriptInP2SH, network, preimages, signersPubKeys, taprootSpendPath, tapLeaf }: {
+            /**
+             * The descriptor string in ASCII format. It may include a "*" to denote an arbitrary index (aka ranged descriptors).
+             */
+            descriptor: string;
+            /**
+             * The descriptor's index in the case of a range descriptor (must be an integer >=0).
+             *
+             * This `Output` class always models a concrete spendable output.
+             * If the descriptor contains any wildcard (`*`), an `index` is required.
+             */
+            index?: number;
+            /**
+             * Multipath branch selector for key-path tuples like `/<0;1>/*`.
+             *
+             * The value passed in `change` must be one of the numbers present in the
+             * tuple.
+             *
+             * Examples:
+             * - `/<0;1>/*` accepts `change: 0` (typically receive) or `change: 1`
+             *   (typically change).
+             * - `/<0;1;2>/*` accepts `change: 0`, `1` or `2`.
+             *
+             * This parameter is independent from `index`: `change` resolves
+             * multipath tuples, while `index` resolves the final wildcard `*`.
+             */
+            change?: number;
+            /**
+             * An optional flag indicating whether the descriptor is required to include a checksum.
+             * @defaultValue false
+             */
+            checksumRequired?: boolean;
+            /**
+             * A flag indicating whether this instance can parse and generate script satisfactions for sh(miniscript) top-level expressions of miniscripts. This is not recommended.
+             * @defaultValue false
+             */
+            allowMiniscriptInP2SH?: boolean;
+            /**
+             * One of bitcoinjs-lib [`networks`](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/src/networks.js) (or another one following the same interface).
+             * @defaultValue networks.bitcoin
+             */
+            network?: Network;
+            /**
+             * An array of preimages if the miniscript-based descriptor uses them.
+             *
+             * This info is necessary to finalize Psbts. Leave it `undefined` if your
+             * miniscript-based descriptor does not use preimages or you don't know
+             * or don't wanto use them.
+             *
+             * You can also leave it `undefined` if only need to generate the
+             * `scriptPubKey` or `address` for a descriptor.
+             *
+             * @defaultValue `[]`
+             */
+            preimages?: Preimage[];
+            /**
+             * An array of the public keys used for signing the transaction when
+             * spending the previous output associated with this descriptor.
+             *
+             * This parameter is only used if the descriptor object is being used to
+             * finalize a transaction. It is necessary to specify the spending path
+             * when working with miniscript-based expressions that have multiple
+             * spending paths.
+             *
+             * Set this parameter to an array containing the public
+             * keys involved in the desired spending path. Leave it `undefined` if you
+             * only need to generate the `scriptPubKey` or `address` for a descriptor,
+             * or if all the public keys involved in the descriptor will sign the
+             * transaction. In the latter case, the satisfier will automatically
+             * choose the most optimal spending path (if more than one is available).
+             * If omitted, this library assumes that all keys in the miniscript can
+             * sign. For taproot script-path spends, keys are inferred per leaf.
+             *
+             * For more details on using this parameter, refer to [this Stack Exchange
+             * answer](https://bitcoin.stackexchange.com/a/118036/89665).
+             */
+            signersPubKeys?: Uint8Array[];
+            /**
+             * Taproot spend path policy. Use `key` to force key-path estimation,
+             * or `script` to estimate script-path spends.
+             *
+             * This setting only applies to `tr(KEY,TREE)` descriptors.
+             * For `tr(KEY)` descriptors, only key-path is available.
+             *
+             * When `script` is selected:
+             * - if `tapLeaf` is provided, that leaf is used.
+             * - if `tapLeaf` is omitted, the satisfier auto-selects the leaf with the
+             *   smallest witness among satisfiable candidates.
+             *
+             * Default policy is `script` for `tr(KEY,TREE)` and `key` for key-only
+             * taproot descriptors (`tr(KEY)` and `addr(TR_ADDRESS)`).
+             */
+            taprootSpendPath?: "key" | "script";
+            /**
+             * Optional taproot leaf selector (tapleaf hash or miniscript string).
+             * Only used when taprootSpendPath is `script` and descriptor is
+             * `tr(KEY,TREE)`. If omitted, the smallest satisfiable leaf is selected.
+             */
+            tapLeaf?: Uint8Array | string;
+        }): {
+            readonly "__#private@#payment": Payment;
+            readonly "__#private@#preimages": Preimage[];
+            readonly "__#private@#signersPubKeys"?: Uint8Array[];
+            readonly "__#private@#miniscript"?: string;
+            readonly "__#private@#witnessScript"?: Uint8Array;
+            readonly "__#private@#redeemScript"?: Uint8Array;
+            readonly "__#private@#isSegwit"?: boolean;
+            readonly "__#private@#isTaproot"?: boolean;
+            readonly "__#private@#expandedExpression"?: string;
+            readonly "__#private@#expandedMiniscript"?: string;
+            readonly "__#private@#tapTreeExpression"?: string;
+            readonly "__#private@#tapTree"?: TapTreeNode;
+            readonly "__#private@#tapTreeInfo"?: TapTreeInfoNode;
+            readonly "__#private@#taprootSpendPath": "key" | "script";
+            readonly "__#private@#tapLeaf"?: Uint8Array | string;
+            readonly "__#private@#expansionMap"?: ExpansionMap;
+            readonly "__#private@#network": Network;
+            "__#private@#resolveMiniscriptSignersPubKeys"(): Uint8Array[];
+            "__#private@#assertMiniscriptSatisfactionResourceLimits"(scriptSatisfaction: Uint8Array): void;
+            /**
+             * Returns the compiled Script Satisfaction for a miniscript-based Output.
+             * The satisfaction is the unlocking script, derived by the Satisfier
+             * algorithm (https://bitcoin.sipa.be/miniscript/).
+             *
+             * This method uses a two-pass flow:
+             * 1) Planning: constraints (nLockTime/nSequence) are computed using fake
+             *    signatures. This is done since the final solution may not need all the
+             *    signatures in signersPubKeys. And we may avoid the user do extra
+             *    signing (tedious op with HWW).
+             * 2) Signing: the provided signatures are used to build the final
+             *    satisfaction, while enforcing the planned constraints so the same
+             *    solution is selected. Not all the signatures of signersPubKeys may
+             *    be required.
+             *
+             * The return value includes the satisfaction script and the constraints.
+             */
+            getScriptSatisfaction(signatures: PartialSig[]): {
+                scriptSatisfaction: Uint8Array;
+                nLockTime: number | undefined;
+                nSequence: number | undefined;
+            };
+            "__#private@#resolveTapTreeSignersPubKeys"(): Uint8Array[];
+            /**
+             * Returns the taproot script‑path satisfaction for a tap miniscript
+             * descriptor. This mirrors {@link getScriptSatisfaction} and uses the same
+             * two‑pass plan/sign flow.
+             *
+             * In addition to nLockTime/nSequence, it returns the selected tapLeafHash
+             * (the leaf chosen during planning) and the leaf’s tapscript.
+             */
+            getTapScriptSatisfaction(signatures: PartialSig[]): TaprootLeafSatisfaction;
+            /**
+             * Gets the planning constraints (nSequence and nLockTime) derived from the
+             * descriptor, just using the expression, signersPubKeys and preimages
+             * (using fake signatures).
+             * For taproot script-path spends, it also returns the selected tapLeafHash.
+             *
+             * We just need to know which will be the signatures that will be
+             * used (signersPubKeys) but final signatures are not necessary for
+             * obtaning nLockTime and nSequence.
+             *
+             * Remember: nSequence and nLockTime are part of the hash that is signed.
+             * Thus, they must not change after computing the signatures.
+             * When running miniscript satisfactions with final signatures,
+             * satisfyMiniscript verifies that the time constraints did not change.
+             */
+            "__#private@#getConstraints"(): {
+                nLockTime: number | undefined;
+                nSequence: number | undefined;
+                tapLeafHash: Uint8Array | undefined;
+            } | undefined;
+            /**
+             * Creates and returns an instance of bitcoinjs-lib
+             * [`Payment`](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/ts_src/payments/index.ts)'s interface with the `scriptPubKey` of this `Output`.
+             */
+            getPayment(): Payment;
+            /**
+             * Returns the Bitcoin Address of this `Output`.
+             */
+            getAddress(): string;
+            /**
+             * Returns this `Output`'s scriptPubKey.
+             */
+            getScriptPubKey(): Uint8Array;
+            /**
+             * Gets the nSequence required to fulfill this `Output`.
+             */
+            getSequence(): number | undefined;
+            /**
+             * Gets the nLockTime required to fulfill this `Output`.
+             */
+            getLockTime(): number | undefined;
+            /**
+             * Returns the tapleaf hash selected during planning for taproot script-path
+             * spends. If signersPubKeys are provided, selection is optimized for those
+             * pubkeys. If a specific tapLeaf selector is used in spending calls, this
+             * reflects that selection.
+             */
+            getTapLeafHash(): Uint8Array | undefined;
+            /**
+             * Gets the witnessScript required to fulfill this `Output`. Only applies to
+             * Segwit outputs.
+             */
+            getWitnessScript(): Uint8Array | undefined;
+            /**
+             * Gets the redeemScript required to fullfill this `Output`. Only applies to
+             * SH outputs: sh(wpkh), sh(wsh), sh(lockingScript).
+             */
+            getRedeemScript(): Uint8Array | undefined;
+            /**
+             * Gets the bitcoinjs-lib [`network`](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/ts_src/networks.ts) used to create this `Output`.
+             */
+            getNetwork(): Network;
+            /**
+             * Whether this `Output` is Segwit.
+             *
+             * *NOTE:* When the descriptor in an input is `addr(address)`, it is assumed
+             * that any `addr(SH_TYPE_ADDRESS)` is in fact a Segwit `SH_WPKH`
+             * (Script Hash-Witness Public Key Hash).
+             * For inputs using arbitrary scripts (not standard addresses),
+             * use a descriptor in the format `sh(MINISCRIPT)`.
+             *
+             */
+            isSegwit(): boolean | undefined;
+            /**
+             * Whether this `Output` is Taproot.
+             */
+            isTaproot(): boolean | undefined;
+            /**
+             * Attempts to determine the type of output script by testing it against
+             * various payment types.
+             *
+             * This method tries to identify if the output is one of the following types:
+             * - P2SH (Pay to Script Hash)
+             * - P2WSH (Pay to Witness Script Hash)
+             * - P2WPKH (Pay to Witness Public Key Hash)
+             * - P2PKH (Pay to Public Key Hash)
+             * - P2TR (Pay to Taproot)
+             *
+             * @returns An object { isPKH: boolean; isWPKH: boolean; isSH: boolean; isWSH: boolean; isTR: boolean;}
+             * with boolean properties indicating the detected output type
+             */
+            guessOutput(): {
+                isPKH: boolean;
+                isWPKH: boolean;
+                isSH: boolean;
+                isWSH: boolean;
+                isTR: boolean;
+            };
+            /**
+             * Computes the Weight Unit contributions of this Output as if it were the
+             * input in a tx.
+             *
+             * *NOTE:* When the descriptor in an input is `addr(address)`, it is assumed
+             * that any `addr(SH_TYPE_ADDRESS)` is in fact a Segwit `SH_WPKH`
+             * (Script Hash-Witness Public Key Hash).
+             *, Also any `addr(SINGLE_KEY_ADDRESS)` * is assumed to be a single key Taproot
+             * address (like those defined in BIP86).
+             * For inputs using arbitrary scripts (not standard addresses),
+             * use a descriptor in the format `sh(MINISCRIPT)`, `wsh(MINISCRIPT)` or
+             * `tr(KEY,TREE)` for taproot script-path expressions.
+             */
+            inputWeight(isSegwitTx: boolean, signatures: PartialSig[] | "DANGEROUSLY_USE_FAKE_SIGNATURES", options?: {
+                taprootSighash?: "SIGHASH_DEFAULT" | "non-SIGHASH_DEFAULT";
+            }): number;
+            /**
+             * Computes the Weight Unit contributions of this Output as if it were the
+             * output in a tx.
+             */
+            outputWeight(): number;
+            /**
+             * Sets this output as an input of the provided `psbt` and updates the
+             * `psbt` locktime if required by the descriptor.
+             *
+             * `psbt` and `vout` are mandatory. Include `txHex` as well. The pair
+             * `vout` and `txHex` define the transaction and output number this instance
+             * pertains to.
+             *
+             * Though not advised, for Segwit inputs you can pass `txId` and `value`
+             * in lieu of `txHex`. If doing so, ensure `value` accuracy to avoid
+             * potential fee attacks -
+             * [See this issue](https://github.com/bitcoinjs/bitcoinjs-lib/issues/1625).
+             *
+             * Note: Hardware wallets need the [full `txHex` for Segwit](https://blog.trezor.io/details-of-firmware-updates-for-trezor-one-version-1-9-1-and-trezor-model-t-version-2-3-1-1eba8f60f2dd).
+             *
+             * When unsure, always use `txHex`, and skip `txId` and `value` for safety.
+             *
+             * Use `rbf` to mark whether this tx can be replaced with another with
+             * higher fee while being in the mempool. Note that a tx will automatically
+             * be marked as replacable if a single input requests it.
+             * Note that any transaction using a relative timelock (nSequence < 0x80000000)
+             * also falls within the RBF range (nSequence < 0xFFFFFFFE), making it
+             * inherently replaceable. So don't set `rbf` to false if this is tx uses
+             * relative time locks.
+             *
+             * @returns A finalizer function to be used after signing the `psbt`.
+             * This function ensures that this input is properly finalized.
+             * The finalizer completes the PSBT input by adding the unlocking script
+             * (`scriptWitness` or `scriptSig`) that satisfies this `Output`'s spending
+             * conditions. Because these scripts include signatures, you should finish
+             * all signing operations before calling the finalizer.
+             * The finalizer has this signature:
+             *
+             * `( { psbt, validate = true } : { psbt: PsbtLike | ScureTransactionLike; validate: boolean | undefined } ) => void`
+             *
+             * where `psbt` can be either a
+             * {@link https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/ts_src/psbt.ts | bitcoinjs-lib `Psbt`}
+             * or a {@link https://github.com/paulmillr/scure-btc-signer | `@scure/btc-signer` `Transaction`}.
+             *
+             */
+            updatePsbtAsInput({ psbt, txHex, txId, value, vout, rbf }: {
+                psbt: PsbtLike | ScureTransactionLike;
+                txHex?: string;
+                txId?: string;
+                value?: bigint;
+                vout: number;
+                rbf?: boolean;
+            }): ({ psbt, validate }: {
+                psbt: PsbtLike | ScureTransactionLike;
+                /** Runs further test on the validity of the signatures.
+                 * It speeds down the finalization process but makes sure the psbt will
+                 * be valid.
+                 * @default true */
+                validate?: boolean | undefined;
+            }) => void;
+            /**
+             * Adds this output as an output of the provided `psbt` with the given
+             * value.
+             * @param params - The parameters for the method.
+             * @param params.psbt - Either a
+             * {@link https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/ts_src/psbt.ts | bitcoinjs-lib `Psbt`}
+             * or a {@link https://github.com/paulmillr/scure-btc-signer | `@scure/btc-signer` `Transaction`}.
+             * @param params.value - The value for the output in satoshis.
+             */
+            updatePsbtAsOutput({ psbt, value }: {
+                psbt: PsbtLike | ScureTransactionLike;
+                value: bigint;
+            }): void;
+            "__#private@#assertPsbtInput"({ psbt, index }: {
+                psbt: PsbtLike | ScureTransactionLike;
+                index: number;
+            }): void;
+            /**
+             * Decomposes the descriptor used to form this `Output` into its elemental
+             * parts. See {@link ExpansionMap ExpansionMap} for a detailed explanation.
+             */
+            expand(): {
+                expansionMap?: ExpansionMap;
+                tapTreeInfo?: TapTreeInfoNode;
+                tapTree?: TapTreeNode;
+                tapTreeExpression?: string;
+                expandedMiniscript?: string;
+                miniscript?: string;
+                expandedExpression?: string;
+            };
+        };
+    };
+    parseKeyExpression: KeyExpressionParser;
+    expand: (params: {
+        /**
+         * The descriptor expression to be expanded.
+         */
+        descriptor: string;
+        /**
+         * The descriptor index, if ranged.
+         */
+        index?: number;
+        /**
+         * Multipath branch selector used for descriptor key-path tuples like
+         * `/<0;1>/*` (and shorthand `/**`).
+         *
+         * The value passed in `change` must be one of the numbers present in the
+         * tuple. For example:
+         * - `/<0;1>/*` accepts `change: 0` or `change: 1`
+         * - `/<0;1;2>/*` accepts `change: 0`, `1` or `2`
+         */
+        change?: number;
+        /**
+         * A flag indicating whether the descriptor is required to include a checksum.
+         * @defaultValue false
+         */
+        checksumRequired?: boolean;
+        /**
+         * The Bitcoin network to use.
+         * @defaultValue `networks.bitcoin`
+         */
+        network?: Network;
+        /**
+         * Flag to allow miniscript in P2SH.
+         * @defaultValue false
+         */
+        allowMiniscriptInP2SH?: boolean;
+    }) => Expansion;
+    ECPair: ECPairAPI;
+    BIP32: BIP32API;
+};
+type OutputConstructor = ReturnType<typeof DescriptorsFactory>['Output'];
+/**
+ * The {@link DescriptorsFactory | `DescriptorsFactory`} function internally
+ * creates and returns the {@link _Internal_.Output | `Output`} class.
+ * This class is specialized for the provided `TinySecp256k1Interface`.
+ * Use `OutputInstance` to declare instances for this class:
+ * `const output: OutputInstance = new Output();`
+ *
+ * See the {@link _Internal_.Output | documentation for the internal `Output`
+ * class} for a complete list of available methods.
+ */
+type OutputInstance = InstanceType<OutputConstructor>;
+export { OutputInstance, OutputConstructor };