@bitcoinerlab/descriptors 2.3.6 → 3.0.1

package/dist/tapMiniscript.d.ts

@@ -0,0 +1,215 @@
+import { Network } from 'bitcoinjs-lib';
+import type { BIP32API } from 'bip32';
+import type { ECPairAPI } from 'ecpair';
+import type { PartialSig, TapBip32Derivation } from 'bip174';
+import type { Taptree } from 'bitcoinjs-lib/src/cjs/types';
+import type { ExpansionMap, KeyInfo, Preimage, TimeConstraints } from './types';
+import type { TapLeafInfo, TapTreeInfoNode, TapTreeNode } from './tapTree';
+export type TapLeafExpansionOverride = {
+    expandedExpression: string;
+    expansionMap: ExpansionMap;
+    tapScript: Uint8Array;
+};
+export type TaprootLeafSatisfaction = {
+    leaf: TapLeafInfo;
+    depth: number;
+    tapLeafHash: Uint8Array;
+    scriptSatisfaction: Uint8Array;
+    stackItems: Uint8Array[];
+    nLockTime: number | undefined;
+    nSequence: number | undefined;
+    totalWitnessSize: number;
+};
+export type TaprootPsbtLeafMetadata = {
+    leaf: TapLeafInfo;
+    depth: number;
+    tapLeafHash: Uint8Array;
+    controlBlock: Uint8Array;
+};
+/**
+ * Compiles a taproot miniscript tree into per-leaf metadata.
+ * Each leaf contains expanded expression metadata, key expansion map,
+ * compiled tapscript and leaf version. This keeps the taproot script-path data
+ * ready for satisfactions and witness building.
+ *
+ * `leafExpansionOverride` allows descriptor-level script expressions to provide:
+ * - user-facing expanded expression metadata (for selector/template use), and
+ * - custom expansion map and tapscript bytes for compilation.
+ *
+ * Example: sortedmulti_a can expose `expandedExpression=sortedmulti_a(...)`
+ * while providing a tapscript already compiled.
+ */
+export declare function buildTapTreeInfo({ tapTree, network, BIP32, ECPair, leafExpansionOverride }: {
+    tapTree: TapTreeNode;
+    network?: Network;
+    BIP32: BIP32API;
+    ECPair: ECPairAPI;
+    leafExpansionOverride: (expression: string) => TapLeafExpansionOverride | undefined;
+}): TapTreeInfoNode;
+export declare function tapTreeInfoToScriptTree(tapTreeInfo: TapTreeInfoNode): Taptree;
+/**
+ * Builds taproot PSBT leaf metadata for every leaf in a `tapTreeInfo`.
+ *
+ * For each leaf, this function computes:
+ * - `tapLeafHash`: BIP341 leaf hash of tapscript + leaf version
+ * - `depth`: leaf depth in the tree (root children have depth 1)
+ * - `controlBlock`: script-path proof used in PSBT `tapLeafScript`
+ *
+ * The control block layout is:
+ *
+ * ```text
+ * [1-byte (leafVersion | parity)] [32-byte internal key]
+ * [32-byte sibling hash #1] ... [32-byte sibling hash #N]
+ * ```
+ *
+ * where:
+ * - `parity` is derived from tweaking the internal key with the tree root
+ * - sibling hashes are the merkle path from that leaf to the root
+ *
+ * Example tree:
+ *
+ * ```text
+ *         root
+ *        /    \
+ *      L1      L2
+ *             /  \
+ *           L3    L4
+ * ```
+ *
+ * Depths:
+ * - L1 depth = 1
+ * - L3 depth = 2
+ * - L4 depth = 2
+ *
+ * Conceptual output:
+ *
+ * ```text
+ * [
+ *   L1 -> { depth: 1, tapLeafHash: h1, controlBlock: [v|p, ik, hash(L2)] }
+ *   L3 -> { depth: 2, tapLeafHash: h3, controlBlock: [v|p, ik, hash(L4), hash(L1)] }
+ *   L4 -> { depth: 2, tapLeafHash: h4, controlBlock: [v|p, ik, hash(L3), hash(L1)] }
+ * ]
+ * ```
+ *
+ * Legend:
+ * - `ik`: the 32-byte internal key placed in the control block.
+ * - `hash(X)`: the merkle sibling hash at each level when proving leaf `X`.
+ *
+ * Note: in this diagram, `L2` is a branch node (right subtree), not a leaf,
+ * so `hash(L2) = TapBranch(hash(L3), hash(L4))`.
+ *
+ * Notes:
+ * - Leaves are returned in deterministic left-first order.
+ * - One metadata entry is returned per leaf.
+ * - `controlBlock.length === 33 + 32 * depth`.
+ * - Throws if internal key is invalid or merkle path cannot be found.
+ *
+ * Typical usage:
+ * - Convert this metadata into PSBT `tapLeafScript[]` entries
+ *   for all leaves.
+ */
+export declare function buildTaprootLeafPsbtMetadata({ tapTreeInfo, internalPubkey }: {
+    tapTreeInfo: TapTreeInfoNode;
+    internalPubkey: Uint8Array;
+}): TaprootPsbtLeafMetadata[];
+/**
+ * Builds PSBT `tapBip32Derivation` entries for taproot script-path spends.
+ *
+ * Leaf keys include the list of tapleaf hashes where they appear.
+ * If `internalKeyInfo` has derivation data, it is included with empty
+ * `leafHashes`.
+ *
+ * Example tree:
+ *
+ * ```text
+ *         root
+ *        /    \
+ *      L1      L2
+ *
+ * L1 uses key A
+ * L2 uses key A and key B
+ *
+ * h1 = tapleafHash(L1)
+ * h2 = tapleafHash(L2)
+ * ```
+ *
+ * Then output is conceptually:
+ *
+ * ```text
+ * [
+ *   key A -> leafHashes [h1, h2]
+ *   key B -> leafHashes [h2]
+ *   internal key -> leafHashes []
+ * ]
+ * ```
+ *
+ * Notes:
+ * - Keys missing `masterFingerprint` or `path` are skipped.
+ * - Duplicate pubkeys are merged.
+ * - If the same pubkey appears with conflicting derivation metadata,
+ *   this function throws.
+ * - Output and `leafHashes` are sorted deterministically.
+ */
+export declare function buildTaprootBip32Derivations({ tapTreeInfo, internalKeyInfo }: {
+    tapTreeInfo: TapTreeInfoNode;
+    internalKeyInfo?: KeyInfo;
+}): TapBip32Derivation[];
+export declare function normalizeTaprootPubkey(pubkey: Uint8Array): Uint8Array;
+/**
+ * Compiles an expanded `sortedmulti_a(...)` leaf expression to its internal
+ * `multi_a(...)` form by sorting placeholders using the resolved pubkeys from
+ * `expansionMap`.
+ */
+export declare function compileSortedMultiAExpandedExpression({ expandedExpression, expansionMap }: {
+    expandedExpression: string;
+    expansionMap: ExpansionMap;
+}): string;
+/**
+ * Computes satisfactions for taproot script-path leaves.
+ *
+ * If `tapLeaf` is undefined, all satisfiable leaves are returned. If `tapLeaf`
+ * is provided, only that leaf is considered.
+ *
+ * Callers are expected to pass real signatures, or fake signatures generated
+ * during planning. See satisfyMiniscript() for how timeConstraints keep the
+ * chosen leaf consistent between planning and signing.
+ */
+export declare function collectTaprootLeafSatisfactions({ tapTreeInfo, preimages, signatures, timeConstraints, tapLeaf }: {
+    tapTreeInfo: TapTreeInfoNode;
+    preimages: Preimage[];
+    signatures: PartialSig[];
+    timeConstraints?: TimeConstraints;
+    tapLeaf?: Uint8Array | string;
+}): TaprootLeafSatisfaction[];
+/**
+ * Selects the taproot leaf satisfaction with the smallest total witness size.
+ * Assumes the input list is in left-first tree order for deterministic ties.
+ */
+export declare function selectBestTaprootLeafSatisfaction(satisfactions: TaprootLeafSatisfaction[]): TaprootLeafSatisfaction;
+/**
+ * Collects a unique set of taproot leaf pubkeys (x-only) across the tree.
+ * This is useful for building fake signatures when no signer subset is given.
+ */
+export declare function collectTapTreePubkeys(tapTreeInfo: TapTreeInfoNode): Uint8Array[];
+/**
+ * Returns the best satisfaction for a taproot tree, by witness size.
+ *
+ * If `tapLeaf` is provided, only that leaf is considered. If `tapLeaf` is a
+ * bytes, it is treated as a tapLeafHash and must match exactly one leaf. If
+ * `tapLeaf` is a string, it is treated as a raw leaf expression and must
+ * match exactly one leaf (whitespace-insensitive).
+ *
+ * This function is typically called twice:
+ * 1) Planning pass: call it with fake signatures (built by the caller) to
+ *    choose the best leaf without requiring user signatures.
+ * 2) Signing pass: call it again with real signatures and the timeConstraints
+ *    returned from the first pass (see satisfyMiniscript() for why this keeps
+ *    the chosen leaf consistent between planning and signing).
+ */
+export declare function satisfyTapTree({ tapTreeInfo, signatures, preimages, tapLeaf, timeConstraints }: {
+    tapTreeInfo: TapTreeInfoNode;
+    signatures: PartialSig[];
+    preimages: Preimage[];
+    tapLeaf?: Uint8Array | string;
+    timeConstraints?: TimeConstraints;
+}): TaprootLeafSatisfaction;