@bitcoinerlab/descriptors 3.0.6 → 3.1.1

package/dist/descriptors.d.ts

@@ -1,433 +0,0 @@
-import { Network, Payment, Psbt } from 'bitcoinjs-lib';
-import type { PartialSig } from 'bip174';
-import { BIP32API } from 'bip32';
-import { ECPairAPI } from 'ecpair';
-import type { TinySecp256k1Interface, Preimage, Expansion, ExpansionMap, KeyExpressionParser } from './types';
-import type { TapTreeInfoNode, TapTreeNode } from './tapTree';
-import type { TaprootLeafSatisfaction } from './tapMiniscript';
-/**
- * Constructs the necessary functions and classes for working with descriptors
- * using an external elliptic curve (ecc) library.
- *
- * Notably, it returns the {@link _Internal_.Output | `Output`} class, which
- * provides methods to create, sign, and finalize PSBTs based on descriptor
- * expressions.
- *
- * The Factory also returns utility methods like `expand` (detailed below)
- * and `parseKeyExpression` (see {@link KeyExpressionParser}).
- *
- * Additionally, for convenience, the function returns `BIP32` and `ECPair`.
- * These are {@link https://github.com/bitcoinjs bitcoinjs-lib} classes designed
- * for managing {@link https://github.com/bitcoinjs/bip32 | `BIP32`} keys and
- * public/private key pairs:
- * {@link https://github.com/bitcoinjs/ecpair | `ECPair`}, respectively.
- *
- * @param {Object} ecc - An object with elliptic curve operations, such as
- * [tiny-secp256k1](https://github.com/bitcoinjs/tiny-secp256k1) or
- * [@bitcoinerlab/secp256k1](https://github.com/bitcoinerlab/secp256k1).
- */
-export declare function DescriptorsFactory(ecc: TinySecp256k1Interface): {
-    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: Psbt; validate: boolean | undefined } ) => void`
-             *
-             */
-            updatePsbtAsInput({ psbt, txHex, txId, value, vout, rbf }: {
-                psbt: Psbt;
-                txHex?: string;
-                txId?: string;
-                value?: bigint;
-                vout: number;
-                rbf?: boolean;
-            }): ({ psbt, validate }: {
-                psbt: Psbt;
-                /** 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 - The Partially Signed Bitcoin Transaction.
-             * @param params.value - The value for the output in satoshis.
-             */
-            updatePsbtAsOutput({ psbt, value }: {
-                psbt: Psbt;
-                value: bigint;
-            }): void;
-            "__#private@#assertPsbtInput"({ psbt, index }: {
-                psbt: Psbt;
-                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: 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 };