bip388 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1020 @@
+import { BIP32Interface } from 'bip32';
+import { Network } from 'bitcoinjs-lib';
+
+/**
+ * BIP-379 Miniscript Fragment Builders
+ *
+ * Provides typesafe construction of miniscript fragments for use in
+ * Bitcoin Script descriptors (wsh, tr).
+ *
+ * @see https://github.com/bitcoin/bips/blob/master/bip-0379.mediawiki
+ */
+/**
+ * Base interface for all miniscript fragments.
+ * Each fragment knows how to serialize itself to a string.
+ */
+interface MiniscriptFragment {
+    readonly type: string;
+    toString(): string;
+}
+/**
+ * pk(@N/**) - Public key check
+ */
+interface PkFragment extends MiniscriptFragment {
+    readonly type: "pk";
+    readonly key: string;
+}
+/**
+ * pkh(@N/**) - Public key hash check
+ */
+interface PkhFragment extends MiniscriptFragment {
+    readonly type: "pkh";
+    readonly key: string;
+}
+/**
+ * sha256(H) - SHA256 preimage check
+ */
+interface Sha256Fragment extends MiniscriptFragment {
+    readonly type: "sha256";
+    readonly hash: string;
+}
+/**
+ * hash256(H) - Double SHA256 preimage check
+ */
+interface Hash256Fragment extends MiniscriptFragment {
+    readonly type: "hash256";
+    readonly hash: string;
+}
+/**
+ * hash160(H) - HASH160 preimage check
+ */
+interface Hash160Fragment extends MiniscriptFragment {
+    readonly type: "hash160";
+    readonly hash: string;
+}
+/**
+ * ripemd160(H) - RIPEMD160 preimage check
+ */
+interface Ripemd160Fragment extends MiniscriptFragment {
+    readonly type: "ripemd160";
+    readonly hash: string;
+}
+/**
+ * older(N) - Relative timelock (CSV)
+ */
+interface OlderFragment extends MiniscriptFragment {
+    readonly type: "older";
+    readonly blocks: number;
+}
+/**
+ * after(N) - Absolute timelock (CLTV)
+ */
+interface AfterFragment extends MiniscriptFragment {
+    readonly type: "after";
+    readonly time: number;
+}
+/**
+ * and_v(X, Y) - Verify AND
+ */
+interface AndVFragment extends MiniscriptFragment {
+    readonly type: "and_v";
+    readonly left: Fragment;
+    readonly right: Fragment;
+}
+/**
+ * or_d(X, Y) - Dissatisfiable OR
+ */
+interface OrDFragment extends MiniscriptFragment {
+    readonly type: "or_d";
+    readonly left: Fragment;
+    readonly right: Fragment;
+}
+/**
+ * or_i(X, Z) - IF/ELSE OR
+ */
+interface OrIFragment extends MiniscriptFragment {
+    readonly type: "or_i";
+    readonly left: Fragment;
+    readonly right: Fragment;
+}
+/**
+ * v:X - Verify wrapper
+ */
+interface VerifyWrapper extends MiniscriptFragment {
+    readonly type: "v";
+    readonly inner: Fragment;
+}
+/**
+ * multi(k, key1, key2, ...) - k-of-n multisig (SegWit)
+ */
+interface MultiFragment extends MiniscriptFragment {
+    readonly type: "multi";
+    readonly threshold: number;
+    readonly keys: string[];
+}
+/**
+ * sortedmulti(k, key1, key2, ...) - k-of-n multisig with sorted keys (SegWit)
+ */
+interface SortedMultiFragment extends MiniscriptFragment {
+    readonly type: "sortedmulti";
+    readonly threshold: number;
+    readonly keys: string[];
+}
+/**
+ * multi_a(k, key1, key2, ...) - k-of-n multisig (Taproot)
+ */
+interface MultiAFragment extends MiniscriptFragment {
+    readonly type: "multi_a";
+    readonly threshold: number;
+    readonly keys: string[];
+}
+/**
+ * sortedmulti_a(k, key1, key2, ...) - k-of-n multisig with sorted keys (Taproot)
+ */
+interface SortedMultiAFragment extends MiniscriptFragment {
+    readonly type: "sortedmulti_a";
+    readonly threshold: number;
+    readonly keys: string[];
+}
+/**
+ * Union of all fragment types
+ */
+type Fragment = PkFragment | PkhFragment | Sha256Fragment | Hash256Fragment | Hash160Fragment | Ripemd160Fragment | OlderFragment | AfterFragment | AndVFragment | OrDFragment | OrIFragment | VerifyWrapper | MultiFragment | SortedMultiFragment | MultiAFragment | SortedMultiAFragment;
+/**
+ * Create a pk() fragment for a key placeholder.
+ * @param key Key placeholder string (e.g., "@0/**")
+ */
+declare function pk(key: string): PkFragment;
+/**
+ * Create a pkh() fragment for a key placeholder.
+ * @param key Key placeholder string (e.g., "@0/**")
+ */
+declare function pkh(key: string): PkhFragment;
+/**
+ * Create a sha256() fragment with a preimage hash.
+ * @param hash 32-byte hash as 64 hex characters
+ */
+declare function sha256(hash: string): Sha256Fragment;
+/**
+ * Create a hash256() fragment (double SHA256).
+ * @param hash 32-byte hash as 64 hex characters
+ */
+declare function hash256(hash: string): Hash256Fragment;
+/**
+ * Create a hash160() fragment (SHA256 + RIPEMD160).
+ * @param hash 20-byte hash as 40 hex characters
+ */
+declare function hash160(hash: string): Hash160Fragment;
+/**
+ * Create a ripemd160() fragment.
+ * @param hash 20-byte hash as 40 hex characters
+ */
+declare function ripemd160(hash: string): Ripemd160Fragment;
+/**
+ * Create an older() fragment for relative timelocks.
+ * @param blocks Number of blocks (must be positive, max 2^31-1)
+ */
+declare function older(blocks: number): OlderFragment;
+/**
+ * Create an after() fragment for absolute timelocks.
+ * @param time Block height or timestamp
+ */
+declare function after(time: number): AfterFragment;
+/**
+ * Create an and_v() fragment combining two conditions.
+ */
+declare function and_v(left: Fragment, right: Fragment): AndVFragment;
+/**
+ * Create an or_d() fragment for alternative conditions.
+ * Requires X to be Bdu (dissatisfiable).
+ */
+declare function or_d(left: Fragment, right: Fragment): OrDFragment;
+/**
+ * Create an or_i() fragment for IF/ELSE alternatives.
+ * Compiles to: IF [X] ELSE [Z] ENDIF
+ * Satisfaction: sat(X) 1; sat(Z) 0
+ */
+declare function or_i(left: Fragment, right: Fragment): OrIFragment;
+/**
+ * Wrap a fragment with v: (verify).
+ */
+declare function v(inner: Fragment): VerifyWrapper;
+/**
+ * Create a multi() fragment for k-of-n multisig (SegWit).
+ * @param threshold Number of required signatures
+ * @param keys Key placeholder strings
+ */
+declare function multi(threshold: number, keys: string[]): MultiFragment;
+/**
+ * Create a sortedmulti() fragment for k-of-n multisig with sorted keys (SegWit).
+ * Keys are sorted lexicographically in the resulting script.
+ * @param threshold Number of required signatures
+ * @param keys Key placeholder strings
+ */
+declare function sortedmulti(threshold: number, keys: string[]): SortedMultiFragment;
+/**
+ * Create a multi_a() fragment for k-of-n multisig (Taproot).
+ * Uses OP_CHECKSIGADD for efficient Taproot multisig.
+ * @param threshold Number of required signatures
+ * @param keys Key placeholder strings
+ */
+declare function multi_a(threshold: number, keys: string[]): MultiAFragment;
+/**
+ * Create a sortedmulti_a() fragment for k-of-n multisig with sorted keys (Taproot).
+ * Keys are sorted lexicographically in the resulting script.
+ * @param threshold Number of required signatures
+ * @param keys Key placeholder strings
+ */
+declare function sortedmulti_a(threshold: number, keys: string[]): SortedMultiAFragment;
+
+type NetworkName = "mainnet" | "testnet" | "regtest";
+/** Key with xpub - enables BIP-388 policy generation and child derivation */
+interface XpubKey {
+    /** Master fingerprint (8 hex chars) */
+    fingerprint?: string;
+    /** Origin path e.g. "48'/1'/0'/2'" */
+    originPath?: string;
+    /** Extended public key (xpub/tpub) */
+    xpub: string;
+    /** Child index for derivation (default: 0) */
+    index?: number;
+    /** Change path: 0 = receive, 1 = change (default: 0) */
+    change?: 0 | 1;
+}
+/** Raw public key - no policy generation, just script building */
+interface RawKey {
+    /** Compressed (33 bytes / 66 hex) or x-only (32 bytes / 64 hex) */
+    pubkey: string;
+}
+/** Either xpub-based or raw pubkey */
+type Key = XpubKey | RawKey;
+/** Type guard for XpubKey */
+declare function isXpubKey(key: Key): key is XpubKey;
+/** Type guard for RawKey */
+declare function isRawKey(key: Key): key is RawKey;
+interface KeyInfo {
+    fingerprint?: string;
+    originPath?: string;
+    xpub: string;
+}
+interface TapLeaf {
+    script: Buffer;
+    hash: Buffer;
+}
+interface TaprootOutput {
+    /** The P2TR address */
+    address: string;
+    /** The scriptPubkey for this output */
+    scriptPubkey: Buffer;
+    /** Internal public key (x-only, 32 bytes) */
+    internalPubkey: Buffer;
+    /** Merkle root of the tap tree (32 bytes) */
+    merkleRoot: Buffer;
+    /** Tweak applied to internal key */
+    tweak: Buffer;
+    /** Tweaked output key (x-only, 32 bytes) */
+    outputKey: Buffer;
+}
+interface SegwitOutput {
+    /** The P2WSH address */
+    address: string;
+    /** The scriptPubkey for this output */
+    scriptPubkey: Buffer;
+    /** The witness script (redeemScript) */
+    witnessScript: Buffer;
+    /** SHA256 hash of witness script */
+    scriptHash: Buffer;
+}
+
+/**
+ * BIP-388 Wallet Policy Builder
+ *
+ * Provides typesafe construction of wallet policy templates for Ledger devices.
+ * Wallet policies are a compact representation of descriptor templates with
+ * a separate key information vector.
+ *
+ * @see https://github.com/bitcoin/bips/blob/master/bip-0388.mediawiki
+ */
+
+/**
+ * A key placeholder in a policy template.
+ * Format: @N/** where N is the index into the keys array.
+ */
+type KeyPlaceholder = `@${number}/**`;
+/**
+ * Create a key placeholder for a given index.
+ */
+declare function keyPlaceholder(index: number): KeyPlaceholder;
+/**
+ * A tap tree node - either a leaf or a branch with two children.
+ */
+type TapTree = Fragment | [TapTree, TapTree];
+/**
+ * Build a tr() descriptor template string.
+ * @param internalKeyIndex Index of the internal key in the keys array
+ * @param tree Optional tap tree of script leaves
+ */
+declare function trDescriptor(internalKeyIndex: number, tree?: TapTree): string;
+/**
+ * Build a wsh() descriptor template string.
+ * @param script The miniscript fragment inside wsh()
+ */
+declare function wshDescriptor(script: Fragment): string;
+/**
+ * Build a wpkh() descriptor template string.
+ * @param keyIndex Index of the key in the keys array
+ */
+declare function wpkhDescriptor(keyIndex: number): string;
+/**
+ * BIP-388 Wallet Policy
+ */
+interface WalletPolicy {
+    /** Human-readable name for the policy */
+    name: string;
+    /** Descriptor template with @N/** placeholders */
+    template: string;
+    /** Ordered list of key origins */
+    keys: KeyInfo[];
+}
+/**
+ * Options for building a wallet policy.
+ */
+interface PolicyOptions {
+    /** Human-readable name (max 64 chars recommended) */
+    name: string;
+    /** Keys in the order they're referenced (@0, @1, ...) */
+    keys: KeyInfo[];
+}
+/**
+ * Build a complete wallet policy for a Taproot output.
+ */
+declare function buildTaprootPolicy(internalKeyIndex: number, tree: TapTree | undefined, options: PolicyOptions): WalletPolicy;
+/**
+ * Build a complete wallet policy for a SegWit (P2WSH) output.
+ */
+declare function buildSegwitPolicy(script: Fragment, options: PolicyOptions): WalletPolicy;
+/**
+ * Format KeyInfo as a string for BIP-388 key vector.
+ * e.g., "[d34db33f/48'/0'/0'/2']xpub6ERApfZ..."
+ */
+declare function formatKeyInfo(info: KeyInfo): string;
+/**
+ * Create a KeyInfo for a bare xpub (no origin info).
+ * Used for external keys like NUMS.
+ */
+declare function bareKey(xpub: string): KeyInfo;
+
+/**
+ * HTLC (Hash Time-Locked Contract) Policy Builders
+ *
+ * Constructs BIP-388 wallet policies for HTLC patterns in both
+ * Taproot and SegWit variants.
+ */
+
+/**
+ * Parameters for building a Taproot HTLC policy.
+ */
+interface TaprootHtlcPolicyParams {
+    /** Name for the policy */
+    name: string;
+    /** SHA256 hash of the secret (64 hex chars) */
+    secretHash: string;
+    /** Timelock value for the refund path */
+    timelock: number;
+    /** Key info for NUMS (internal key) */
+    numsKey: KeyInfo;
+    /** Key info for the payee */
+    payeeKey: KeyInfo;
+    /** Key info for the payer */
+    payerKey: KeyInfo;
+}
+/**
+ * Build a Taproot HTLC wallet policy.
+ *
+ * Creates a policy with:
+ * - Internal key: NUMS (index 0) - no key path spend
+ * - Secret leaf: and_v(v:sha256(H), pk(@1))
+ * - Timeout leaf: and_v(v:older(N), pk(@2))
+ */
+declare function buildTaprootHtlcPolicy(params: TaprootHtlcPolicyParams): WalletPolicy;
+/**
+ * Parameters for building a SegWit HTLC policy.
+ */
+interface SegwitHtlcPolicyParams {
+    /** Name for the policy */
+    name: string;
+    /** SHA256 hash of the secret (64 hex chars) */
+    secretHash: string;
+    /** Timelock value for the refund path */
+    timelock: number;
+    /** Key info for the payee */
+    payeeKey: KeyInfo;
+    /** Key info for the payer */
+    payerKey: KeyInfo;
+}
+/**
+ * Build a SegWit HTLC wallet policy.
+ *
+ * Creates a policy with:
+ * - Secret path (IF): and_v(v:sha256(H), pk(@0))
+ * - Timeout path (ELSE): and_v(v:pk(@1), after(N))
+ *
+ * Uses or_i which compiles to IF [X] ELSE [Z] ENDIF
+ */
+declare function buildSegwitHtlcPolicy(params: SegwitHtlcPolicyParams): WalletPolicy;
+
+/**
+ * Multisig Policy Builders
+ *
+ * Constructs BIP-388 wallet policies for multisig patterns in both
+ * Taproot (multi_a/sortedmulti_a) and SegWit (multi/sortedmulti) variants.
+ */
+
+/**
+ * Parameters for building a SegWit multisig policy.
+ */
+interface SegwitMultisigPolicyParams {
+    /** Name for the policy */
+    name: string;
+    /** Number of required signatures */
+    threshold: number;
+    /** Keys (order matters for non-sorted multisig) */
+    keys: KeyInfo[];
+    /** Sort keys lexicographically (default: true) */
+    sorted?: boolean;
+}
+/**
+ * Build a SegWit multisig wallet policy.
+ *
+ * Creates a policy with:
+ * - wsh(sortedmulti(k, @0/**, @1/**, ...)) for sorted (default)
+ * - wsh(multi(k, @0/**, @1/**, ...)) for non-sorted
+ */
+declare function buildSegwitMultisigPolicy(params: SegwitMultisigPolicyParams): WalletPolicy;
+/**
+ * Parameters for building a Taproot multisig policy.
+ */
+interface TaprootMultisigPolicyParams {
+    /** Name for the policy */
+    name: string;
+    /** Number of required signatures */
+    threshold: number;
+    /** Keys (order matters for non-sorted multisig) */
+    keys: KeyInfo[];
+    /** Sort keys lexicographically (default: true) */
+    sorted?: boolean;
+}
+/**
+ * Build a Taproot multisig wallet policy (script path spend).
+ *
+ * Creates a policy with:
+ * - tr(@0/**, sortedmulti_a(k, @1/**, @2/**, ...)) for sorted (default)
+ * - tr(@0/**, multi_a(k, @1/**, @2/**, ...)) for non-sorted
+ *
+ * Note: First key is used as internal key. For script-only spend,
+ * use a NUMS key as the first key.
+ */
+declare function buildTaprootMultisigPolicy(params: TaprootMultisigPolicyParams): WalletPolicy;
+
+/**
+ * pk() Script Builder
+ *
+ * Compiles to: <pubkey> OP_CHECKSIG
+ *
+ * Used in:
+ * - wsh(pk(...)) for P2WSH single-key outputs
+ * - Taproot script leaves
+ */
+/**
+ * Build a pk() script.
+ *
+ * @param pubkey - Compressed public key (33 bytes) or x-only pubkey (32 bytes for Taproot)
+ * @returns Compiled script buffer
+ *
+ * @example
+ * ```ts
+ * const script = pkScript(pubkey);
+ * // <pubkey> OP_CHECKSIG
+ * ```
+ */
+declare function pkScript(pubkey: Buffer): Buffer;
+
+/**
+ * pkh() Script Builder
+ *
+ * Compiles to: OP_DUP OP_HASH160 <pubkeyhash> OP_EQUALVERIFY OP_CHECKSIG
+ *
+ * Used in:
+ * - wsh(pkh(...)) for P2WSH with pubkey hash
+ * - Legacy P2PKH (though typically handled by bitcoinjs-lib payments)
+ */
+/**
+ * Build a pkh() script from a public key.
+ *
+ * @param pubkey - Compressed public key (33 bytes)
+ * @returns Compiled script buffer
+ *
+ * @example
+ * ```ts
+ * const script = pkhScript(pubkey);
+ * // OP_DUP OP_HASH160 <hash160(pubkey)> OP_EQUALVERIFY OP_CHECKSIG
+ * ```
+ */
+declare function pkhScript(pubkey: Buffer): Buffer;
+/**
+ * Build a pkh() script from a pubkey hash directly.
+ *
+ * @param pubkeyHash - 20-byte HASH160 of the public key
+ * @returns Compiled script buffer
+ */
+declare function pkhScriptFromHash(pubkeyHash: Buffer): Buffer;
+
+/**
+ * multi() / sortedmulti() Script Builder
+ *
+ * Compiles to: OP_M <pubkey1> <pubkey2> ... <pubkeyN> OP_N OP_CHECKMULTISIG
+ *
+ * Used in:
+ * - wsh(multi(...)) for P2WSH multisig
+ * - wsh(sortedmulti(...)) with lexicographically sorted keys
+ * - Bare multisig (top-level, limited to 3 keys)
+ * - sh(multi(...)) for P2SH multisig (limited to 15 keys)
+ */
+/**
+ * Encode a number for use in Bitcoin Script.
+ * For values 0, uses OP_0.
+ * For values 1-16, uses OP_1 through OP_16.
+ * For values > 16, uses minimal push encoding per BIP-383.
+ *
+ * @param n - Number to encode
+ * @returns Opcode number or Buffer for values > 16
+ */
+declare function encodeScriptInt(n: number): number | Buffer;
+/**
+ * Build a multi() script (k-of-n multisig) for SegWit.
+ *
+ * @param threshold - Number of required signatures (k), max 20
+ * @param pubkeys - Array of compressed public keys (33 bytes each)
+ * @param sorted - If true, sort keys lexicographically (sortedmulti behavior)
+ * @returns Compiled script buffer
+ *
+ * @example
+ * ```ts
+ * const script = multiScript(2, [pubkey1, pubkey2, pubkey3]);
+ * // OP_2 <pk1> <pk2> <pk3> OP_3 OP_CHECKMULTISIG
+ * ```
+ */
+declare function multiScript(threshold: number, pubkeys: Buffer[], sorted?: boolean): Buffer;
+/**
+ * Build a sortedmulti() script (k-of-n multisig with sorted keys).
+ *
+ * Keys are sorted lexicographically for deterministic script generation.
+ *
+ * @param threshold - Number of required signatures (k)
+ * @param pubkeys - Array of compressed public keys (33 bytes each)
+ * @returns Compiled script buffer
+ */
+declare function sortedMultiScript(threshold: number, pubkeys: Buffer[]): Buffer;
+/**
+ * Build a bare multi() script that supports both compressed and uncompressed keys.
+ *
+ * This is used for:
+ * - Top-level bare multisig (limited to 3 keys per BIP-383)
+ * - Legacy P2SH multisig (limited to 15 keys)
+ *
+ * Unlike multiScript(), this function accepts uncompressed pubkeys (65 bytes).
+ *
+ * @param threshold - Number of required signatures (k)
+ * @param pubkeys - Array of public keys (33 or 65 bytes each)
+ * @param sorted - If true, sort keys lexicographically (sortedmulti behavior)
+ * @returns Compiled script buffer
+ *
+ * @example
+ * ```ts
+ * const script = bareMultiScript(1, [compressedKey, uncompressedKey]);
+ * // OP_1 <pk1> <pk2> OP_2 OP_CHECKMULTISIG
+ * ```
+ */
+declare function bareMultiScript(threshold: number, pubkeys: Buffer[], sorted?: boolean): Buffer;
+/**
+ * Build a sortedmulti() script for bare/legacy multisig with sorted keys.
+ *
+ * Supports both compressed and uncompressed keys.
+ *
+ * @param threshold - Number of required signatures (k)
+ * @param pubkeys - Array of public keys (33 or 65 bytes each)
+ * @returns Compiled script buffer
+ */
+declare function sortedBareMultiScript(threshold: number, pubkeys: Buffer[]): Buffer;
+
+/**
+ * Hashlock Script Builders
+ *
+ * Scripts that require revealing a preimage to spend.
+ *
+ * Used in HTLCs and other hash-locked contracts.
+ */
+/**
+ * Hash types supported for hashlock scripts.
+ */
+type HashType$1 = "sha256" | "hash256" | "hash160" | "ripemd160";
+/**
+ * Build a hashlock script with pubkey check.
+ *
+ * Miniscript: and_v(v:sha256(H), pk(K))
+ * Compiles to: SIZE <32> EQUALVERIFY <HASHOP> <hash> EQUALVERIFY <pubkey> CHECKSIG
+ *
+ * The SIZE check ensures the preimage is exactly the expected length.
+ *
+ * @param hash - The hash that the preimage must match
+ * @param pubkey - Public key that must sign (32 or 33 bytes)
+ * @param hashType - Hash function to use (default: sha256)
+ * @returns Compiled script buffer
+ *
+ * @example
+ * ```ts
+ * const script = hashlockScript(secretHash, payeePubkey);
+ * // SIZE 32 EQUALVERIFY SHA256 <hash> EQUALVERIFY <pubkey> CHECKSIG
+ * ```
+ */
+declare function hashlockScript(hash: Buffer, pubkey: Buffer, hashType?: HashType$1): Buffer;
+/**
+ * Build a simple hashlock script without pubkey (just hash verification).
+ *
+ * Compiles to: SIZE <len> EQUALVERIFY <HASHOP> <hash> EQUAL
+ *
+ * @param hash - The hash that the preimage must match
+ * @param hashType - Hash function to use (default: sha256)
+ * @returns Compiled script buffer
+ */
+declare function simpleHashlockScript(hash: Buffer, hashType?: HashType$1): Buffer;
+
+/**
+ * Timelock Script Builders
+ *
+ * Scripts that can only be spent after a certain time/block.
+ *
+ * - CLTV (OP_CHECKLOCKTIMEVERIFY): Absolute timelock
+ * - CSV (OP_CHECKSEQUENCEVERIFY): Relative timelock
+ */
+/**
+ * Encode a number for use in Bitcoin Script.
+ *
+ * Numbers in Script use a minimal encoding:
+ * - 0 is OP_0
+ * - 1-16 are OP_1 through OP_16
+ * - Larger numbers use little-endian encoding with sign bit
+ */
+declare function encodeScriptNumber(n: number): Buffer | number;
+/**
+ * Build an absolute timelock script with pubkey check.
+ *
+ * Miniscript: and_v(v:after(N), pk(K))
+ * Compiles to: <N> CHECKLOCKTIMEVERIFY VERIFY <pubkey> CHECKSIG
+ *
+ * @param locktime - Block height or Unix timestamp
+ * @param pubkey - Public key that must sign (32 or 33 bytes)
+ * @param useDrop - Use OP_DROP instead of OP_VERIFY after CLTV
+ * @returns Compiled script buffer
+ *
+ * @example
+ * ```ts
+ * // Spend only after block 800000
+ * const script = cltvScript(800000, payerPubkey);
+ * ```
+ */
+declare function cltvScript(locktime: number, pubkey: Buffer, useDrop?: boolean): Buffer;
+/**
+ * Build a relative timelock script with pubkey check.
+ *
+ * Miniscript: and_v(v:older(N), pk(K))
+ * Compiles to: <N> CHECKSEQUENCEVERIFY VERIFY <pubkey> CHECKSIG
+ *
+ * @param sequence - Relative locktime in blocks or time units
+ * @param pubkey - Public key that must sign (32 or 33 bytes)
+ * @param useDrop - Use DROP instead of VERIFY (for Taproot compatibility)
+ * @returns Compiled script buffer
+ *
+ * @example
+ * ```ts
+ * // Spend only after 144 blocks (~1 day)
+ * const script = csvScript(144, recoveryPubkey);
+ * ```
+ */
+declare function csvScript(sequence: number, pubkey: Buffer, useDrop?: boolean): Buffer;
+/**
+ * Build a simple absolute timelock script (no pubkey).
+ *
+ * Compiles to: <N> CHECKLOCKTIMEVERIFY DROP OP_TRUE
+ *
+ * @param locktime - Block height or Unix timestamp
+ * @returns Compiled script buffer
+ */
+declare function simpleCltvScript(locktime: number): Buffer;
+
+declare function getNetwork(name: NetworkName): Network;
+/**
+ * Derive a child public key from an xpub at the given path.
+ * @param xpub Extended public key
+ * @param change 0 for receive, 1 for change
+ * @param index Child index
+ * @param network Network for xpub parsing
+ * @returns BIP32 node at the derived path
+ */
+declare function deriveFromXpub(xpub: string, change: number, index: number, network: Network): BIP32Interface;
+/**
+ * Resolve a Key to its compressed public key (33 bytes).
+ * For XpubKey, derives the child key. For RawKey, validates and returns the pubkey.
+ */
+declare function resolveCompressedPubkey(key: Key, network: NetworkName): Buffer;
+/**
+ * Resolve a Key to its x-only public key (32 bytes) for Taproot.
+ */
+declare function resolveXOnlyPubkey(key: Key, network: NetworkName): Buffer;
+/**
+ * Convert compressed (33 byte) or uncompressed (65 byte) pubkey to x-only (32 byte).
+ */
+declare function toXOnly(pubkey: Buffer): Buffer;
+/**
+ * Parse a hex public key string to Buffer, validating format.
+ * Accepts compressed (66 hex), x-only (64 hex), or uncompressed (130 hex).
+ */
+declare function parsePublicKey(pubkeyHex: string): Buffer;
+/**
+ * Check if a compressed public key is a valid secp256k1 point.
+ */
+declare function isValidPoint(pubkey: Buffer): boolean;
+/**
+ * Convert an XpubKey to KeyInfo for BIP-388 policy.
+ */
+declare function toKeyInfo(key: XpubKey): KeyInfo;
+/**
+ * Try to extract KeyInfo from an array of Keys.
+ * Returns null if any key is a RawKey (no xpub info available).
+ */
+declare function extractKeyInfos(keys: Key[]): KeyInfo[] | null;
+
+type HashType = "sha256" | "hash256" | "ripemd160" | "hash160";
+type TimelockType = "blocks" | "timestamp";
+interface HtlcParams<K extends Key = Key> {
+    /** Recipient key - spends by revealing preimage */
+    payee: K;
+    /** Sender key - refund after timeout */
+    payer: K;
+    /** Hash of the secret (hex string) */
+    secretHash: string;
+    /** Timelock value (block height or timestamp) */
+    timelock: number;
+    /** Network */
+    network: NetworkName;
+}
+interface TaprootHtlcParams<K extends Key = Key> extends HtlcParams<K> {
+    /** Optional name for BIP-388 policy */
+    name?: string;
+}
+interface SegwitHtlcParams<K extends Key = Key> extends HtlcParams<K> {
+    /** Hash function used (default: sha256) */
+    hashType?: HashType;
+    /** Timelock type (default: blocks) */
+    timelockType?: TimelockType;
+    /** Optional name for BIP-388 policy */
+    name?: string;
+}
+/** Witness builders for HTLC spending */
+interface HtlcWitness {
+    /** Build witness stack for secret reveal spend (payee) */
+    secret: (signature: Buffer, preimage: Buffer) => Buffer[];
+    /** Build witness stack for timeout refund spend (payer) */
+    timeout: (signature: Buffer) => Buffer[];
+}
+interface TaprootHtlc extends TaprootOutput {
+    /** Secret reveal leaf (payee spends with preimage) */
+    secretLeaf: TapLeaf;
+    /** Timeout leaf (payer spends after timelock) */
+    timeoutLeaf: TapLeaf;
+    /** Get control block for spending a specific leaf */
+    controlBlock: (leaf: "secret" | "timeout") => Buffer;
+    /** Witness builders */
+    witness: HtlcWitness;
+    /** BIP-388 policy (only if xpub keys provided) */
+    policy: WalletPolicy | null;
+    /** The timelock value */
+    timelock: number;
+}
+interface SegwitHtlc extends SegwitOutput {
+    /** Witness builders */
+    witness: HtlcWitness;
+    /** BIP-388 policy (only if xpub keys provided) */
+    policy: WalletPolicy | null;
+    /** The timelock value */
+    timelock: number;
+}
+interface MultisigParams<K extends Key = Key> {
+    /** Number of required signatures */
+    threshold: number;
+    /** Public keys */
+    keys: K[];
+    /** Sort keys lexicographically (default: true) */
+    sorted?: boolean;
+    /** Network */
+    network: NetworkName;
+    /** Optional name for BIP-388 policy */
+    name?: string;
+}
+interface TaprootMultisigParams<K extends Key = Key> extends MultisigParams<K> {
+    /** Use key path spend with MuSig2 (default: false = script-only) */
+    keyPathSpend?: boolean;
+}
+/** Witness builder for multisig spending */
+interface MultisigWitness {
+    /** Build witness stack for spending */
+    (signatures: Buffer[]): Buffer[];
+}
+interface TaprootMultisig extends TaprootOutput {
+    /** BIP-388 policy (only if xpub keys provided) */
+    policy: WalletPolicy | null;
+    /** Build witness stack for script path spend */
+    witness: MultisigWitness;
+    /** The tap leaf containing the multisig script */
+    scriptLeaf: TapLeaf;
+    /** Get control block for script path spend */
+    controlBlock: Buffer;
+}
+interface SegwitMultisig extends SegwitOutput {
+    /** BIP-388 policy (only if xpub keys provided) */
+    policy: WalletPolicy | null;
+    /** Build witness stack for spending */
+    witness: MultisigWitness;
+}
+
+/**
+ * Create a Taproot HTLC with two script paths:
+ * - Secret path: payee can spend by revealing the preimage
+ * - Timeout path: payer can refund after the timelock expires
+ *
+ * Secret leaf script:
+ * ```
+ * OP_SHA256 <secretHash> OP_EQUALVERIFY <payeePubkey> OP_CHECKSIG
+ * ```
+ *
+ * Timeout leaf script:
+ * ```
+ * <timelock> OP_CHECKLOCKTIMEVERIFY OP_DROP <payerPubkey> OP_CHECKSIG
+ * ```
+ *
+ * Uses NUMS as internal key (script-only spend, no key path).
+ *
+ * @example
+ * ```ts
+ * const htlc = taprootHtlc({
+ *   payee: { pubkey: '02abc...' },
+ *   payer: { xpub: 'tpub...', fingerprint: 'aabbccdd', originPath: "86'/1'/0'" },
+ *   secretHash: 'deadbeef...',
+ *   timelock: 800000,
+ *   network: 'testnet'
+ * });
+ *
+ * // Fund it
+ * console.log(htlc.address);
+ *
+ * // Spend with preimage
+ * const witness = htlc.witnessSecret(signature, preimage);
+ * ```
+ */
+declare function taprootHtlc<K extends Key>(params: TaprootHtlcParams<K>): TaprootHtlc;
+/**
+ * Extract the preimage from a spent HTLC witness.
+ * @param witness The witness stack from a transaction input
+ * @param secretHash Optional hash to validate the preimage against
+ * @returns The preimage hex string, or null if not found/invalid
+ */
+declare function extractSecret$1(witness: Buffer[], secretHash?: string): string | null;
+
+/**
+ * Create a Taproot multisig output using script path spend.
+ *
+ * Uses multi_a / sortedmulti_a which leverages OP_CHECKSIGADD for
+ * efficient k-of-n multisig in Tapscript.
+ *
+ * Script structure (for 2-of-3):
+ * ```
+ * <pubkey1> OP_CHECKSIG
+ * <pubkey2> OP_CHECKSIGADD
+ * <pubkey3> OP_CHECKSIGADD
+ * OP_2 OP_NUMEQUAL
+ * ```
+ *
+ * Uses NUMS as internal key (script-only spend, no key path).
+ *
+ * @example
+ * ```ts
+ * const multisig = taprootMultisig({
+ *   threshold: 2,
+ *   keys: [
+ *     { xpub: 'tpub...', fingerprint: 'aabbccdd', originPath: "86'/1'/0'" },
+ *     { xpub: 'tpub...', fingerprint: 'eeff0011', originPath: "86'/1'/0'" },
+ *     { xpub: 'tpub...', fingerprint: '22334455', originPath: "86'/1'/0'" },
+ *   ],
+ *   network: 'testnet'
+ * });
+ *
+ * console.log(multisig.address);  // tb1p...
+ * ```
+ */
+declare function taprootMultisig<K extends Key>(params: TaprootMultisigParams<K>): TaprootMultisig;
+
+/**
+ * NUMS (Nothing Up My Sleeve) point for script-only Taproot.
+ *
+ * This is the BIP-341 recommended NUMS point. It has no known discrete log,
+ * meaning no one can spend via the key path - only script paths are valid.
+ *
+ * Public key: lift_x(0x0250929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0)
+ * This is SHA256("TapTweak")[:32] interpreted as an x-coordinate.
+ */
+declare const NUMS: {
+    /** Compressed public key (33 bytes as hex) */
+    readonly pubkey: "0250929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0";
+    /** X-only public key (32 bytes as hex) - for taproot internal key */
+    readonly xonly: "50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0";
+    /** X-only as Buffer */
+    readonly xonlyBuffer: Buffer;
+    /** Compressed as Buffer */
+    readonly pubkeyBuffer: Buffer;
+    /**
+     * Get NUMS xpub for a specific network.
+     * Constructed with:
+     * - Public key: NUMS point
+     * - Chain code: 32 zero bytes
+     * - Depth/parent/index: all zeros (acts like master key)
+     */
+    readonly xpub: (network: NetworkName) => string;
+};
+
+/**
+ * Create a SegWit (P2WSH) HTLC with SHA256 hashlock.
+ *
+ * Miniscript policy: or_d(and_v(v:sha256(H), pk(@0)), and_v(v:pk(@1), after(N)))
+ *
+ * Compiles to:
+ * ```
+ * SIZE <32> EQUALVERIFY SHA256 <H> EQUALVERIFY <payeePubkey> CHECKSIG
+ * IFDUP NOTIF
+ *     <payerPubkey> CHECKSIGVERIFY <timelock> CHECKLOCKTIMEVERIFY
+ * ENDIF
+ * ```
+ *
+ * - Payee: reveals preimage, signature satisfies first branch (returns true, skips NOTIF)
+ * - Payer: provides signature + timelock satisfied (first branch fails, enters NOTIF)
+ *
+ * @example
+ * ```ts
+ * const htlc = segwitHtlc({
+ *   payee: { pubkey: '02abc...' },
+ *   payer: { pubkey: '03def...' },
+ *   secretHash: 'deadbeef...',  // sha256(preimage)
+ *   timelock: 800000,
+ *   network: 'testnet'
+ * });
+ *
+ * console.log(htlc.address);  // bc1q...
+ * ```
+ */
+declare function segwitHtlc<K extends Key>(params: SegwitHtlcParams<K>): SegwitHtlc;
+/**
+ * Extract the preimage from a spent SegWit HTLC witness.
+ * @param witness The witness stack from a transaction input
+ * @param secretHash Optional sha256 hash to validate the preimage against
+ * @returns The preimage hex string, or null if not found/invalid
+ */
+declare function extractSecret(witness: Buffer[], secretHash?: string): string | null;
+
+/**
+ * Create a SegWit (P2WSH) multisig output.
+ *
+ * Script structure (for sorted=true, which is default):
+ * ```
+ * OP_2 <pubkey1> <pubkey2> <pubkey3> OP_3 OP_CHECKMULTISIG
+ * ```
+ *
+ * Keys are sorted lexicographically when sorted=true (recommended for
+ * deterministic addresses regardless of key order in params).
+ *
+ * @example
+ * ```ts
+ * const multisig = segwitMultisig({
+ *   threshold: 2,
+ *   keys: [
+ *     { xpub: 'tpub...', fingerprint: 'aabbccdd', originPath: "48'/1'/0'/2'" },
+ *     { xpub: 'tpub...', fingerprint: 'eeff0011', originPath: "48'/1'/0'/2'" },
+ *     { xpub: 'tpub...', fingerprint: '22334455', originPath: "48'/1'/0'/2'" },
+ *   ],
+ *   network: 'testnet'
+ * });
+ *
+ * console.log(multisig.address);  // tb1q...
+ * ```
+ */
+declare function segwitMultisig<K extends Key>(params: MultisigParams<K>): SegwitMultisig;
+
+export { type AfterFragment, type AndVFragment, type Fragment, type Hash160Fragment, type Hash256Fragment, type HashType$1 as HashType, type HtlcWitness, type Key, type KeyInfo, type MultiAFragment, type MultiFragment, type MultisigParams, type MultisigWitness, NUMS, type NetworkName, type OlderFragment, type OrDFragment, type OrIFragment, type PkFragment, type PkhFragment, type PolicyOptions, type RawKey, type Ripemd160Fragment, type SegwitHtlc, type SegwitHtlcParams, type SegwitHtlcPolicyParams, type SegwitMultisig, type SegwitMultisigPolicyParams, type SegwitOutput, type Sha256Fragment, type SortedMultiAFragment, type SortedMultiFragment, type TapLeaf, type TapTree, type TaprootHtlc, type TaprootHtlcParams, type TaprootHtlcPolicyParams, type TaprootMultisig, type TaprootMultisigParams, type TaprootMultisigPolicyParams, type TaprootOutput, type VerifyWrapper, type WalletPolicy, type XpubKey, after, and_v, bareKey, bareMultiScript, buildSegwitHtlcPolicy, buildSegwitMultisigPolicy, buildSegwitPolicy, buildTaprootHtlcPolicy, buildTaprootMultisigPolicy, buildTaprootPolicy, cltvScript, csvScript, deriveFromXpub, encodeScriptInt, encodeScriptNumber, extractKeyInfos, extractSecret as extractSegwitSecret, extractSecret$1 as extractTaprootSecret, formatKeyInfo, getNetwork, hash160, hash256, hashlockScript, isRawKey, isValidPoint, isXpubKey, keyPlaceholder, multi, multiScript, multi_a, older, or_d, or_i, parsePublicKey, pk, pkScript, pkh, pkhScript, pkhScriptFromHash, resolveCompressedPubkey, resolveXOnlyPubkey, ripemd160, segwitHtlc, segwitMultisig, sha256, simpleCltvScript, simpleHashlockScript, sortedBareMultiScript, sortedMultiScript, sortedmulti, sortedmulti_a, taprootHtlc, taprootMultisig, toKeyInfo, toXOnly, trDescriptor, v, wpkhDescriptor, wshDescriptor };