@scure/btc-signer 2.0.0 → 2.2.0

package/payment.js

@@ -1,11 +1,14 @@
 import { bech32, bech32m, createBase58check, hex } from '@scure/base';
+import { anumber } from '@noble/hashes/utils.js';
+import { abytes } from '@noble/curves/utils.js';
 import * as P from 'micro-packed';
 import { TaprootControlBlock } from "./psbt.js";
-import { OpToNum, Script, VarBytes } from "./script.js";
+import { MAX_SCRIPT_BYTE_LENGTH, OpToNum, Script, VarBytes } from "./script.js";
 import * as u from "./utils.js";
 import { NETWORK } from "./utils.js";
 const OutP2A = {
     encode(from) {
+        // BIP433 defines P2A as the exact OP_1 <0x4e73> scriptPubKey.
         if (from.length !== 2 || from[0] !== 1 || !u.isBytes(from[1]) || hex.encode(from[1]) !== '4e73')
             return;
         return { type: 'p2a', script: Script.encode(from) };
@@ -13,10 +16,13 @@ const OutP2A = {
     decode: (to) => {
         if (to.type !== 'p2a')
             return;
+        // The decoded object keeps `script` for caller convenience, but the `p2a`
+        // tag always canonicalizes back to the fixed BIP433 script.
         return [1, hex.decode('4e73')];
     },
 };
 function isValidPubkey(pub, type) {
+    // Payment coders use a boolean guard here and normalize validatePubkey failures to false.
     try {
         u.validatePubkey(pub, type);
         return true;
@@ -27,6 +33,8 @@ function isValidPubkey(pub, type) {
 }
 const OutPK = {
     encode(from) {
+        // BIP380/BIP381 `pk(KEY)` only admits SEC1 ECDSA pubkeys here; x-only
+        // 32-byte CHECKSIG scripts are left for the later tapscript coders.
         if (from.length !== 2 ||
             !u.isBytes(from[0]) ||
             !isValidPubkey(from[0], u.PubT.ecdsa) ||
@@ -34,44 +42,69 @@ const OutPK = {
             return;
         return { type: 'pk', pubkey: from[0] };
     },
-    decode: (to) => (to.type === 'pk' ? [to.pubkey, 'CHECKSIG'] : undefined),
+    decode: (to) => {
+        if (to.type !== 'pk')
+            return;
+        // OutScript validates `pk.pubkey` before this branch emits the canonical
+        // `<pubkey> CHECKSIG` script.
+        return [to.pubkey, 'CHECKSIG'];
+    },
 };
 const OutPKH = {
     encode(from) {
         if (from.length !== 5 || from[0] !== 'DUP' || from[1] !== 'HASH160' || !u.isBytes(from[2]))
             return;
+        // OutScript validates that the pushed HASH160 is exactly 20 bytes.
+        // This child matcher only recognizes the canonical P2PKH opcode skeleton.
         if (from[3] !== 'EQUALVERIFY' || from[4] !== 'CHECKSIG')
             return;
         return { type: 'pkh', hash: from[2] };
     },
-    decode: (to) => to.type === 'pkh' ? ['DUP', 'HASH160', to.hash, 'EQUALVERIFY', 'CHECKSIG'] : undefined,
+    // OutScript validates `pkh.hash` before this branch emits the canonical
+    // `DUP HASH160 <hash> EQUALVERIFY CHECKSIG` script.
+    decode: (to) => (to.type === 'pkh'
+        ? ['DUP', 'HASH160', to.hash, 'EQUALVERIFY', 'CHECKSIG']
+        : undefined),
 };
 const OutSH = {
     encode(from) {
         if (from.length !== 3 || from[0] !== 'HASH160' || !u.isBytes(from[1]) || from[2] !== 'EQUAL')
             return;
+        // OutScript validates that the pushed HASH160 is exactly 20 bytes.
+        // This child matcher only recognizes the canonical P2SH opcode skeleton.
         return { type: 'sh', hash: from[1] };
     },
-    decode: (to) => to.type === 'sh' ? ['HASH160', to.hash, 'EQUAL'] : undefined,
+    // OutScript validates `sh.hash` before this branch emits the canonical
+    // `HASH160 <hash> EQUAL` script.
+    decode: (to) => (to.type === 'sh' ? ['HASH160', to.hash, 'EQUAL'] : undefined),
 };
 const OutWSH = {
     encode(from) {
         if (from.length !== 2 || from[0] !== 0 || !u.isBytes(from[1]))
             return;
+        // BIP382 `wsh()` is specifically the version-0 32-byte witness program.
+        // Other witness versions stay with the later coders.
         if (from[1].length !== 32)
             return;
         return { type: 'wsh', hash: from[1] };
     },
+    // OutScript validates `wsh.hash` before this branch emits the canonical
+    // version-0 32-byte witness program.
     decode: (to) => (to.type === 'wsh' ? [0, to.hash] : undefined),
 };
 const OutWPKH = {
     encode(from) {
         if (from.length !== 2 || from[0] !== 0 || !u.isBytes(from[1]))
             return;
+        // BIP382 `wpkh()` is specifically the version-0 20-byte witness program.
+        // Compressed-key restrictions are enforced upstream, and other witness
+        // versions stay with the later coders.
         if (from[1].length !== 20)
             return;
         return { type: 'wpkh', hash: from[1] };
     },
+    // OutScript validates `wpkh.hash` before this branch emits the canonical
+    // version-0 20-byte witness program.
     decode: (to) => (to.type === 'wpkh' ? [0, to.hash] : undefined),
 };
 const OutMS = {
@@ -89,17 +122,31 @@ const OutMS = {
         for (const pub of pubkeys)
             if (!u.isBytes(pub))
                 return;
-        return { type: 'ms', m, pubkeys: pubkeys }; // we don't need n, since it is the same as pubkeys
+        // OutScript validates pubkey encodings and `0 < m <= n <= 16`.
+        // This child matcher only recognizes the canonical CHECKMULTISIG skeleton.
+        // We don't need n here because it is the same as pubkeys.length.
+        return { type: 'ms', m, pubkeys: pubkeys };
     },
     // checkmultisig(n, ..pubkeys, m)
-    decode: (to) => to.type === 'ms' ? [to.m, ...to.pubkeys, to.pubkeys.length, 'CHECKMULTISIG'] : undefined,
+    decode: (to) => 
+    // OutScript validates multisig pubkeys and `0 < m <= n <= 16`.
+    // This branch only emits the canonical `m <pubkeys...> n CHECKMULTISIG`
+    // script.
+    (to.type === 'ms'
+        ? [to.m, ...to.pubkeys, to.pubkeys.length, 'CHECKMULTISIG']
+        : undefined),
 };
 const OutTR = {
     encode(from) {
-        if (from.length !== 2 || from[0] !== 1 || !u.isBytes(from[1]))
+        // BIP141 witness programs are `OP_0..OP_16` followed by a direct 2..40-byte push.
+        // BIP341 assigns native taproot meaning only to version 1 with a 32-byte x-only program;
+        // other OP_1 program lengths remain reserved future witness programs and should fall through.
+        if (from.length !== 2 || from[0] !== 1 || !u.isBytes(from[1]) || from[1].length !== 32)
             return;
         return { type: 'tr', pubkey: from[1] };
     },
+    // OutScript validates `tr.pubkey` before this branch emits the canonical
+    // version-1 32-byte witness program.
     decode: (to) => (to.type === 'tr' ? [1, to.pubkey] : undefined),
 };
 const OutTRNS = {
@@ -116,10 +163,17 @@ const OutTRNS = {
                     return;
                 continue;
             }
-            if (!u.isBytes(elm))
+            // Require actual Schnorr pubkeys here so near-miss `<bytes> CHECKSIG`
+            // scripts fall through to OutUnknown instead of failing later.
+            if (!u.isBytes(elm) || !isValidPubkey(elm, u.PubT.schnorr))
                 return;
             pubkeys.push(elm);
         }
+        // BIP342 "Using a k-of-k script for every combination" documents the shape
+        // `<pubkey_1> CHECKSIGVERIFY ... <pubkey_n> CHECKSIG`; this matcher only
+        // classifies that embedded-pubkey form, so bare CHECKSIG stays unknown.
+        if (!pubkeys.length)
+            return;
         return { type: 'tr_ns', pubkeys };
     },
     decode: (to) => {
@@ -128,6 +182,8 @@ const OutTRNS = {
         const out = [];
         for (let i = 0; i < to.pubkeys.length - 1; i++)
             out.push(to.pubkeys[i], 'CHECKSIGVERIFY');
+        // This branch assumes at least one Schnorr pubkey; [] would otherwise emit
+        // `[undefined, CHECKSIG]` and only fail later in Script.encode.
         out.push(to.pubkeys[to.pubkeys.length - 1], 'CHECKSIG');
         return out;
     },
@@ -143,13 +199,15 @@ const OutTRMS = {
             return;
         for (let i = 0; i < last - 1; i++) {
             const elm = from[i];
+            // Structural mismatches should fall through to OutUnknown instead of
+            // throwing from the tr_ms matcher.
             if (i & 1) {
                 if (elm !== (i === 1 ? 'CHECKSIG' : 'CHECKSIGADD'))
-                    throw new Error('OutScript.encode/tr_ms: wrong element');
+                    return;
                 continue;
             }
             if (!u.isBytes(elm))
-                throw new Error('OutScript.encode/tr_ms: wrong key element');
+                return;
             pubkeys.push(elm);
         }
         return { type: 'tr_ms', pubkeys, m };
@@ -160,18 +218,29 @@ const OutTRMS = {
         const out = [to.pubkeys[0], 'CHECKSIG'];
         for (let i = 1; i < to.pubkeys.length; i++)
             out.push(to.pubkeys[i], 'CHECKSIGADD');
+        // This branch assumes `m` was already validated as an integer ScriptNum;
+        // fractional JS numbers would otherwise serialize as a different threshold.
         out.push(to.m, 'NUMEQUAL');
         return out;
     },
 };
 const OutUnknown = {
     encode(from) {
+        // This is the catch-all fallback for scripts no structured coder recognized,
+        // so earlier matchers must return `undefined` instead of throwing on mismatch.
+        // Because this reserializes the parsed Script AST, unknown scripts preserve
+        // semantics but not original non-minimal push spellings.
         return { type: 'unknown', script: Script.encode(from) };
     },
-    decode: (to) => to.type === 'unknown' ? Script.decode(to.script) : undefined,
+    decode: (to) => 
+    // This reparses `unknown.script` through the semantic Script codec, so raw
+    // bytes must still be syntactically parseable and may canonicalize on re-encode.
+    (to.type === 'unknown' ? Script.decode(to.script) : undefined),
 };
 // /Payments
-const OutScripts = [
+const OutScripts = /* @__PURE__ */ (() => [
+    // Order is semantic: specific structured coders run first and the catch-all
+    // unknown fallback must stay last.
     OutP2A,
     OutPK,
     OutPKH,
@@ -183,15 +252,28 @@ const OutScripts = [
     OutTRNS,
     OutTRMS,
     OutUnknown,
-];
+])();
 // TODO: we can support user supplied output scripts now
 // - addOutScript
 // - removeOutScript
 // - We can do that as log we modify array in-place
 // - Actually is very hard, since there is sign/finalize logic
-const _OutScript = P.apply(Script, P.coders.match(OutScripts));
+// Raw composition of semantic Script parsing with the ordered output-script
+// matcher; OutScript adds the higher-level validation layer on top.
+const _OutScript = /* @__PURE__ */ (() => P.apply(Script, P.coders.match(OutScripts)))();
 // We can validate this once, because of packed & coders
-export const OutScript = P.validate(_OutScript, (i) => {
+/**
+ * Coder for recognized Bitcoin output scripts.
+ * @example
+ * Decode a serialized output script back into the tagged payment descriptor.
+ * ```ts
+ * import { OutScript, p2wpkh } from '@scure/btc-signer/payment.js';
+ * import { pubECDSA, randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * const pay = p2wpkh(pubECDSA(randomPrivateKeyBytes()));
+ * OutScript.decode(pay.script);
+ * ```
+ */
+export const OutScript = /* @__PURE__ */ (() => Object.freeze(P.validate(_OutScript, (i) => {
     if (i.type === 'pk' && !isValidPubkey(i.pubkey, u.PubT.ecdsa))
         throw new Error('OutScript/pk: wrong key');
     if ((i.type === 'pkh' || i.type === 'sh' || i.type === 'wpkh') &&
@@ -209,6 +291,9 @@ export const OutScript = P.validate(_OutScript, (i) => {
         for (const p of i.pubkeys)
             if (!isValidPubkey(p, u.PubT.ecdsa))
                 throw new Error('OutScript/multisig: wrong pubkey');
+        // Range checks are not enough here: non-integer JS numbers like 1.5 would
+        // otherwise slip through and serialize as a different ScriptNum threshold.
+        anumber(i.m, 'm');
         if (i.m <= 0 || n > 16 || i.m > n)
             throw new Error('OutScript/multisig: invalid params');
     }
@@ -219,61 +304,133 @@ export const OutScript = P.validate(_OutScript, (i) => {
     }
     if (i.type === 'tr_ms') {
         const n = i.pubkeys.length;
+        // BIP 342 keeps the 1000-element stack limit. This CHECKSIG/CHECKSIGADD form
+        // momentarily has n witness items plus one pushed pubkey on the stack, so n must stay <= 999.
+        anumber(i.m, 'm');
         if (i.m <= 0 || n > 999 || i.m > n)
             throw new Error('OutScript/tr_ms: invalid params');
     }
     return i;
-});
+})))();
 // Basic sanity check for scripts
 function checkWSH(s, witnessScript) {
     if (!u.equalBytes(s.hash, u.sha256(witnessScript)))
         throw new Error('checkScript: wsh wrong witnessScript hash');
+    // BIP141 only requires the witnessScript hash match; the type-based rejects
+    // below are an extra descriptor sanity layer for BIP382 invalid-descriptor
+    // bullets `wpkh() nested in wsh()` and `wsh() nested in wsh()`.
     const w = OutScript.decode(witnessScript);
     if (w.type === 'tr' || w.type === 'tr_ns' || w.type === 'tr_ms')
         throw new Error(`checkScript: P2${w.type} cannot be wrapped in P2SH`);
-    if (w.type === 'wpkh' || w.type === 'sh')
+    if (w.type === 'wpkh' || w.type === 'wsh' || w.type === 'sh')
         throw new Error(`checkScript: P2${w.type} cannot be wrapped in P2WSH`);
 }
+/**
+ * Validates that nested redeem and witness scripts match their wrappers.
+ * @param script - top-level output script
+ * @param redeemScript - optional redeem script for P2SH wrappers
+ * @param witnessScript - optional witness script for P2WSH wrappers
+ * @throws If the script nesting is invalid or unsupported. {@link Error}
+ * @example
+ * Verify that wrapped scripts and hashes still match after custom edits.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { checkScript, p2pkh, p2sh } from '@scure/btc-signer/payment.js';
+ * const wrapped = p2sh(
+ *   p2pkh(hex.decode('0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'))
+ * );
+ * checkScript(wrapped.script, wrapped.redeemScript);
+ * ```
+ */
 export function checkScript(script, redeemScript, witnessScript) {
+    let hasWsh = false;
+    let r = undefined;
     if (script) {
         const s = OutScript.decode(script);
+        // BIP174 Data Signers Check For bullets: provided redeemScript must match
+        // the scriptPubKey, and provided witnessScript must match the scriptPubKey
+        // or redeemScript instead of being silently ignored as stray metadata.
         // ms||pk maybe work, but there will be no address, hard to spend
         if (s.type === 'tr_ns' || s.type === 'tr_ms' || s.type === 'ms' || s.type == 'pk')
             throw new Error(`checkScript: non-wrapped ${s.type}`);
-        if (s.type === 'sh' && redeemScript) {
+        if (redeemScript) {
+            if (s.type !== 'sh')
+                throw new Error('checkScript: redeemScript without P2SH');
             if (!u.equalBytes(s.hash, u.hash160(redeemScript)))
                 throw new Error('checkScript: sh wrong redeemScript hash');
-            const r = OutScript.decode(redeemScript);
-            if (r.type === 'tr' || r.type === 'tr_ns' || r.type === 'tr_ms')
+            r = OutScript.decode(redeemScript);
+            if (r?.type === 'tr' || r?.type === 'tr_ns' || r?.type === 'tr_ms')
                 throw new Error(`checkScript: P2${r.type} cannot be wrapped in P2SH`);
             // Not sure if this unspendable, but we cannot represent this via PSBT
-            if (r.type === 'sh')
+            if (r?.type === 'sh')
                 throw new Error('checkScript: P2SH cannot be wrapped in P2SH');
         }
-        if (s.type === 'wsh' && witnessScript)
-            checkWSH(s, witnessScript);
+        if (s.type === 'wsh') {
+            hasWsh = true;
+            if (witnessScript)
+                checkWSH(s, witnessScript);
+        }
     }
     if (redeemScript) {
-        const r = OutScript.decode(redeemScript);
-        if (r.type === 'wsh' && witnessScript)
-            checkWSH(r, witnessScript);
+        if (r === undefined)
+            r = OutScript.decode(redeemScript);
+        if (r?.type === 'wsh') {
+            hasWsh = true;
+            if (witnessScript)
+                checkWSH(r, witnessScript);
+        }
     }
+    if (witnessScript && !hasWsh)
+        throw new Error('checkScript: witnessScript without P2WSH');
 }
 function uniqPubkey(pubkeys) {
     const map = {};
     for (const pub of pubkeys) {
+        // Exact-byte duplicate filter only: BIP383 valid vectors still permit the
+        // same point to appear in compressed and uncompressed SEC1 form in multi().
         const key = hex.encode(pub);
         if (map[key])
             throw new Error(`Multisig: non-uniq pubkey: ${pubkeys.map(hex.encode)}`);
         map[key] = true;
     }
 }
+/**
+ * Builds a pay-to-public-key script.
+ * @param pubkey - compressed or uncompressed ECDSA public key
+ * @param _network - unused network placeholder for API consistency
+ * @returns P2PK descriptor.
+ * @throws If the public key cannot be encoded as a P2PK output. {@link Error}
+ * @example
+ * Build a bare pay-to-public-key output.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { p2pk } from '@scure/btc-signer/payment.js';
+ * p2pk(hex.decode('0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'));
+ * ```
+ */
 export const p2pk = (pubkey, _network = NETWORK) => {
     // network is unused
     if (!isValidPubkey(pubkey, u.PubT.ecdsa))
         throw new Error('P2PK: invalid publicKey');
-    return { type: 'pk', script: OutScript.encode({ type: 'pk', pubkey }) };
+    return {
+        type: 'pk',
+        script: OutScript.encode({ type: 'pk', pubkey }),
+    };
 };
+/**
+ * Builds a P2PKH output from a public key.
+ * @param publicKey - compressed or uncompressed ECDSA public key bytes; HASH160 commits to the exact encoding
+ * @param network - address network parameters
+ * @returns P2PKH descriptor.
+ * @throws If the public key cannot be encoded as a P2PKH output. {@link Error}
+ * @example
+ * Build a classic pay-to-public-key-hash output.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { p2pkh } from '@scure/btc-signer/payment.js';
+ * p2pkh(hex.decode('0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'));
+ * ```
+ */
 export const p2pkh = (publicKey, network = NETWORK) => {
     if (!isValidPubkey(publicKey, u.PubT.ecdsa))
         throw new Error('P2PKH: invalid publicKey');
@@ -285,52 +442,106 @@ export const p2pkh = (publicKey, network = NETWORK) => {
         hash,
     };
 };
+/**
+ * Wraps a child script inside P2SH.
+ * @param child - child payment descriptor to wrap
+ * @param network - address network parameters
+ * @returns P2SH descriptor preserving witness metadata when present.
+ * @throws If the wrapped script combination is invalid or unsupported. {@link Error}
+ * @example
+ * Wrap a child script in P2SH so it gets a base58 address form.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { p2pk, p2sh, p2wsh } from '@scure/btc-signer/payment.js';
+ * p2sh(p2wsh(p2pk(hex.decode('0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'))));
+ * ```
+ */
 export const p2sh = (child, network = NETWORK) => {
     // It is already tested inside noble-hashes and checkScript
-    const cs = child.script;
+    // BIP16 redeemScripts are pushed by scriptSig, so anything over the 520-byte pushed-element
+    // limit would be fundable by HASH160 but unspendable once wrapped in P2SH.
+    const c = child;
+    const cs = c.script;
     if (!u.isBytes(cs))
-        throw new Error(`Wrong script: ${typeof child.script}, expected Uint8Array`);
+        throw new Error(`Wrong script: ${typeof c.script}, expected Uint8Array`);
+    if (cs.length > MAX_SCRIPT_BYTE_LENGTH)
+        throw new Error(`P2SH: redeemScript exceeds ${MAX_SCRIPT_BYTE_LENGTH}-byte push limit: len=${cs.length}`);
     const hash = u.hash160(cs);
-    const script = OutScript.encode({ type: 'sh', hash });
-    checkScript(script, cs, child.witnessScript);
-    if (child.witnessScript) {
+    const out = { type: 'sh', hash };
+    const script = OutScript.encode(out);
+    const address = Address(network).encode(out);
+    checkScript(script, cs, c.witnessScript);
+    if (c.witnessScript) {
         return {
             type: 'sh',
             redeemScript: cs,
-            script: OutScript.encode({ type: 'sh', hash }),
-            address: Address(network).encode({ type: 'sh', hash }),
+            script,
+            address,
             hash,
-            witnessScript: child.witnessScript,
+            witnessScript: c.witnessScript,
         };
     }
     else {
         return {
             type: 'sh',
             redeemScript: cs,
-            script: OutScript.encode({ type: 'sh', hash }),
-            address: Address(network).encode({ type: 'sh', hash }),
+            script,
+            address,
             hash,
         };
     }
 };
+/**
+ * Wraps a child script inside native SegWit P2WSH.
+ * @param child - child payment descriptor to wrap
+ * @param network - address network parameters
+ * @returns P2WSH descriptor.
+ * @throws If the wrapped script combination is invalid or unsupported. {@link Error}
+ * @example
+ * Wrap a child script in native SegWit P2WSH.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { p2pk, p2wsh } from '@scure/btc-signer/payment.js';
+ * p2wsh(p2pk(hex.decode('0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798')));
+ * ```
+ */
 export const p2wsh = (child, network = NETWORK) => {
     const cs = child.script;
     if (!u.isBytes(cs))
         throw new Error(`Wrong script: ${typeof cs}, expected Uint8Array`);
+    // BIP141 P2WSH says the witness "must consist of ... a serialized script (witnessScript)"
+    // and that witnessScript is limited to 10,000 bytes, so larger wrapped scripts must reject.
+    if (cs.length > 10000)
+        throw new Error('P2WSH: witnessScript exceeds 10,000 bytes');
     const hash = u.sha256(cs);
     const script = OutScript.encode({ type: 'wsh', hash });
     checkScript(script, undefined, cs);
     return {
         type: 'wsh',
         witnessScript: cs,
-        script: OutScript.encode({ type: 'wsh', hash }),
+        script,
         address: Address(network).encode({ type: 'wsh', hash }),
         hash,
     };
 };
+/**
+ * Builds a native SegWit P2WPKH output from a public key.
+ * @param publicKey - compressed ECDSA public key
+ * @param network - address network parameters
+ * @returns P2WPKH descriptor.
+ * @throws If the public key cannot be encoded as a P2WPKH output. {@link Error}
+ * @example
+ * Build a native SegWit pay-to-public-key-hash output.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { p2wpkh } from '@scure/btc-signer/payment.js';
+ * p2wpkh(hex.decode('0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'));
+ * ```
+ */
 export const p2wpkh = (publicKey, network = NETWORK) => {
     if (!isValidPubkey(publicKey, u.PubT.ecdsa))
         throw new Error('P2WPKH: invalid publicKey');
+    // BIP 143 default policy: version-0 witness programs MUST use 33-byte compressed ECDSA keys.
     if (publicKey.length === 65)
         throw new Error('P2WPKH: uncompressed public key');
     const hash = u.hash160(publicKey);
@@ -341,7 +552,24 @@ export const p2wpkh = (publicKey, network = NETWORK) => {
         hash,
     };
 };
+/**
+ * Builds a bare multisig script.
+ * @param m - number of required signatures
+ * @param pubkeys - participating public keys
+ * @param allowSamePubkeys - whether duplicate keys are allowed
+ * @returns P2MS descriptor.
+ * @throws If the multisig parameters are invalid. {@link Error}
+ * @example
+ * Build a bare multisig output script.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { p2ms } from '@scure/btc-signer/payment.js';
+ * p2ms(1, [hex.decode('0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798')], true);
+ * ```
+ */
 export const p2ms = (m, pubkeys, allowSamePubkeys = false) => {
+    // BIP 11 only standardized bare multisig up to 3 keys; this helper still permits up to 16
+    // because the same script shape is commonly wrapped by p2sh()/p2wsh() instead of used bare.
     if (!allowSamePubkeys)
         uniqPubkey(pubkeys);
     return {
@@ -387,7 +615,28 @@ function checkTaprootScript(script, internalPubKey, allowUnknownOutputs = false,
     }
 }
 // Helper for generating binary tree from list, with weights
+/**
+ * Converts a flat list of weighted leaves into a binary taproot tree.
+ * @param taprootList - weighted leaves to arrange
+ * @returns Binary taproot script tree.
+ * @throws If the list is empty and cannot describe any tree. {@link Error}
+ * @example
+ * Start from a flat weighted list, then let the helper build the binary tree shape.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { p2tr_pk, taprootListToTree } from '@scure/btc-signer/payment.js';
+ * taprootListToTree([
+ *   p2tr_pk(hex.decode('f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9')),
+ *   p2tr_pk(hex.decode('dff1d77f2a671c5f36183726db2341be58feae1da2deced843240f7b502ba659')),
+ * ]);
+ * ```
+ */
 export function taprootListToTree(taprootList) {
+    // Empty flat lists cannot represent a taproot script tree; omit the tree entirely for
+    // key-path-only outputs instead of passing [] here, otherwise this helper would return
+    // undefined and downstream taproot tree walkers would fail much later on a non-tree value.
+    if (!taprootList.length)
+        throw new Error('taprootListToTree: empty tree');
     // Clone input in order to not corrupt it
     const lst = Array.from(taprootList);
     // We have at least 2 elements => can create branch
@@ -418,7 +667,8 @@ function taprootAddPath(tree, path = []) {
     return {
         ...tree,
         path,
-        // Left element has right hash in path and otherwise
+        // BIP 341 control blocks serialize sibling hashes from leaf to root, so prepend the
+        // current sibling before descending into the child subtree.
         left: taprootAddPath(tree.left, [tree.right.hash, ...path]),
         right: taprootAddPath(tree.right, [tree.left.hash, ...path]),
     };
@@ -430,6 +680,7 @@ function taprootWalkTree(tree) {
         return [tree];
     if (tree.type !== 'branch')
         throw new Error(`taprootWalkTree: wrong type=${tree}`);
+    // Keep a stable left-to-right DFS leaf order when flattening the annotated tree.
     return [...taprootWalkTree(tree.left), ...taprootWalkTree(tree.right)];
 }
 function taprootHashTree(tree, internalPubKey, allowUnknownOutputs = false, customScripts) {
@@ -439,7 +690,8 @@ function taprootHashTree(tree, internalPubKey, allowUnknownOutputs = false, cust
         tree = tree[0];
     // Terminal node (leaf)
     if (!Array.isArray(tree)) {
-        const { leafVersion: version, script: leafScript } = tree;
+        const version = tree.leafVersion;
+        const { script: leafScript } = tree;
         // Earliest tree walk where we can validate tapScripts
         if (tree.tapLeafScript || (tree.tapMerkleRoot && !u.equalBytes(tree.tapMerkleRoot, P.EMPTY)))
             throw new Error('P2TR: tapRoot leafScript cannot have tree');
@@ -451,7 +703,7 @@ function taprootHashTree(tree, internalPubKey, allowUnknownOutputs = false, cust
             type: 'leaf',
             version,
             script,
-            hash: tapLeafHash(script, version),
+            hash: tapLeafHash(script, tapLeafVersion(version)),
         };
     }
     // If tree / branch is not binary tree, convert it
@@ -463,14 +715,44 @@ function taprootHashTree(tree, internalPubKey, allowUnknownOutputs = false, cust
     // Both nodes should exist
     const left = taprootHashTree(tree[0], internalPubKey, allowUnknownOutputs, customScripts);
     const right = taprootHashTree(tree[1], internalPubKey, allowUnknownOutputs, customScripts);
-    // We cannot swap left/right here, since it will change structure of tree
+    // BIP 341 sorts TapBranch child hashes lexicographically for hashing, but the original
+    // left/right structure still determines the control-block sibling paths for each leaf.
     let [lH, rH] = [left.hash, right.hash];
     if (u.compareBytes(rH, lH) === -1)
         [lH, rH] = [rH, lH];
-    return { type: 'branch', left, right, hash: u.tagSchnorr('TapBranch', lH, rH) };
+    return {
+        type: 'branch',
+        left,
+        right,
+        hash: u.tagSchnorr('TapBranch', lH, rH),
+    };
 }
+/** Default tapleaf version used by taproot script-path outputs before adding the parity bit. */
 export const TAP_LEAF_VERSION = 0xc0;
-export const tapLeafHash = (script, version = TAP_LEAF_VERSION) => u.tagSchnorr('TapLeaf', new Uint8Array([version]), VarBytes.encode(script));
+const tapLeafVersion = (version) => {
+    if (version === undefined)
+        return TAP_LEAF_VERSION;
+    anumber(version, 'leafVersion');
+    // BIP341 script-path validation defines the effective leaf version as `v = c[0] & 0xfe`
+    // and says it cannot be odd or `0x50`; tapleaf hashes also serialize this as one byte.
+    if (version > 0xfe || version === 0x50 || !!(version & 1))
+        throw new Error(`P2TR: invalid leafVersion=${version}`);
+    return version;
+};
+/**
+ * Computes the tagged hash of a tapleaf script.
+ * @param script - tapleaf script bytes
+ * @param version - base even tapleaf version byte (for tapscript, `0xc0`)
+ * @returns Tapleaf hash.
+ * @throws If the tapleaf version is not a valid even one-byte version.
+ * {@link Error}
+ * @example
+ * Hash a finalized tapscript leaf before placing it into a Merkle tree.
+ * ```ts
+ * tapLeafHash(new Uint8Array([0x51]));
+ * ```
+ */
+export const tapLeafHash = (script, version = TAP_LEAF_VERSION) => u.tagSchnorr('TapLeaf', new Uint8Array([tapLeafVersion(version)]), VarBytes.encode(script));
 export function p2tr(internalPubKey, tree, network = NETWORK, allowUnknownOutputs = false, customScripts) {
     // Unspendable
     if (!internalPubKey && !tree)
@@ -484,14 +766,19 @@ export function p2tr(internalPubKey, tree, network = NETWORK, allowUnknownOutput
         let hashedTree = taprootAddPath(taprootHashTree(tree, pubKey, allowUnknownOutputs, customScripts));
         const tapMerkleRoot = hashedTree.hash;
         const [tweakedPubkey, parity] = u.taprootTweakPubkey(pubKey, tapMerkleRoot);
-        const leaves = taprootWalkTree(hashedTree).map((l) => ({
-            ...l,
-            controlBlock: TaprootControlBlock.encode({
-                version: (l.version || TAP_LEAF_VERSION) + parity,
-                internalKey: pubKey,
-                merklePath: l.path,
-            }),
-        }));
+        const leaves = taprootWalkTree(hashedTree).map((l) => {
+            const version = tapLeafVersion(l.version);
+            return {
+                ...l,
+                // Leaf versions are stored as the base even byte; only the control block adds the
+                // output-key parity bit required by BIP 341 script-path spending.
+                controlBlock: TaprootControlBlock.encode({
+                    version: version + parity,
+                    internalKey: pubKey,
+                    merklePath: l.path,
+                }),
+            };
+        });
         return {
             type: 'tr',
             script: OutScript.encode({ type: 'tr', pubkey: tweakedPubkey }),
@@ -503,12 +790,14 @@ export function p2tr(internalPubKey, tree, network = NETWORK, allowUnknownOutput
             leaves,
             tapLeafScript: leaves.map((l) => [
                 TaprootControlBlock.decode(l.controlBlock),
-                u.concatBytes(l.script, new Uint8Array([l.version || TAP_LEAF_VERSION])),
+                u.concatBytes(l.script, new Uint8Array([tapLeafVersion(l.version)])),
             ]),
             tapMerkleRoot,
         };
     }
     else {
+        // BIP 341 / BIP 86: key-only Taproot still tweaks with the empty Merkle root so the
+        // output commits to an unspendable script path instead of leaving the key untweaked.
         const tweakedPubkey = u.taprootTweakPubkey(pubKey, P.EMPTY)[0];
         return {
             type: 'tr',
@@ -522,18 +811,33 @@ export function p2tr(internalPubKey, tree, network = NETWORK, allowUnknownOutput
     }
 }
 // Returns all combinations of size M from lst
+/**
+ * Returns all size-`m` combinations from a list.
+ * @param m - size of each combination
+ * @param list - input items to combine
+ * @returns Array of combinations.
+ * @throws If the combination size or input list is invalid. {@link Error}
+ * @example
+ * Enumerate all size-two subsets of a short list.
+ * ```ts
+ * combinations(2, [1, 2, 3]);
+ * ```
+ */
 export function combinations(m, list) {
     const res = [];
     if (!Array.isArray(list))
         throw new Error('combinations: lst arg should be array');
     const n = list.length;
-    if (m > n)
-        throw new Error('combinations: m > lst.length, no combinations possible');
+    anumber(m, 'm');
+    if (m < 1 || m > n)
+        throw new Error('combinations: m must satisfy 1 <= m <= lst.length');
     /*
     Basically works as M nested loops like:
     for (;idx[0]<lst.length;idx[0]++) for (idx[1]=idx[0]+1;idx[1]<lst.length;idx[1]++)
     but since we cannot create nested loops dynamically, we unroll it to a single loop
     */
+    // This unrolled-loop implementation assumes an integer 1 <= m <= n; zero, negative, and
+    // fractional m values need an explicit guard before entering the loop.
     const idx = Array.from({ length: m }, (_, i) => i);
     const last = idx.length - 1;
     main: for (;;) {
@@ -555,6 +859,21 @@ export function combinations(m, list) {
     }
     return res;
 }
+/**
+ * Builds the leaf set for an M-of-N `CHECKSIGVERIFY` taproot policy.
+ * @param m - number of required signatures
+ * @param pubkeys - participating Schnorr public keys
+ * @param allowSamePubkeys - whether duplicate keys are allowed
+ * @returns Array of taproot leaf descriptors.
+ * @throws If the taproot multisig parameters are invalid. {@link Error}
+ * @example
+ * Build the leaf set for an M-of-N taproot `CHECKSIGVERIFY` policy.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { p2tr_ns } from '@scure/btc-signer/payment.js';
+ * p2tr_ns(1, [hex.decode('f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9')], true);
+ * ```
+ */
 export const p2tr_ns = (m, pubkeys, allowSamePubkeys = false) => {
     if (!allowSamePubkeys)
         uniqPubkey(pubkeys);
@@ -563,7 +882,37 @@ export const p2tr_ns = (m, pubkeys, allowSamePubkeys = false) => {
         script: OutScript.encode({ type: 'tr_ns', pubkeys: i }),
     }));
 };
+/**
+ * Builds a single-key taproot leaf script.
+ * BIP 341 design guidance: if this is the most likely single-key spend path, prefer
+ * using that key as the `p2tr()` internal key instead of forcing it into a script leaf.
+ * @param pubkey - Schnorr public key
+ * @returns Taproot single-key leaf descriptor.
+ * @throws If the taproot single-key leaf cannot be encoded. {@link Error}
+ * @example
+ * Build a single-key tapscript leaf.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { p2tr_pk } from '@scure/btc-signer/payment.js';
+ * p2tr_pk(hex.decode('f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9'));
+ * ```
+ */
 export const p2tr_pk = (pubkey) => p2tr_ns(1, [pubkey], undefined)[0];
+/**
+ * Builds a `CHECKSIGADD` taproot multisig leaf.
+ * @param m - number of required signatures
+ * @param pubkeys - participating Schnorr public keys
+ * @param allowSamePubkeys - whether duplicate keys are allowed
+ * @returns Taproot multisig leaf descriptor.
+ * @throws If the taproot multisig parameters are invalid. {@link Error}
+ * @example
+ * Build a `CHECKSIGADD` taproot multisig leaf.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { p2tr_ms } from '@scure/btc-signer/payment.js';
+ * p2tr_ms(1, [hex.decode('f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9')], true);
+ * ```
+ */
 export function p2tr_ms(m, pubkeys, allowSamePubkeys = false) {
     if (!allowSamePubkeys)
         uniqPubkey(pubkeys);
@@ -573,10 +922,27 @@ export function p2tr_ms(m, pubkeys, allowSamePubkeys = false) {
     };
 }
 // Simple pubkey address, without complex scripts
+/**
+ * Derives a simple address from a private key.
+ * @param type - address type to derive
+ * @param privKey - private key bytes
+ * @param network - address network parameters
+ * @returns Encoded Bitcoin address.
+ * @throws If the requested address type is unknown. {@link Error}
+ * @example
+ * Pick the output type first, then derive the matching address from the private key.
+ * ```ts
+ * import { getAddress } from '@scure/btc-signer/payment.js';
+ * import { randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * getAddress('wpkh', randomPrivateKeyBytes());
+ * ```
+ */
 export function getAddress(type, privKey, network = NETWORK) {
     if (type === 'tr') {
         return p2tr(u.pubSchnorr(privKey), undefined, network).address;
     }
+    // This convenience wrapper always uses the compressed ECDSA public key; derive
+    // `pubECDSA(privKey, false)` and call `p2pkh(...)` directly for legacy uncompressed P2PKH.
     const pubKey = u.pubECDSA(privKey);
     if (type === 'pkh')
         return p2pkh(pubKey, network).address;
@@ -584,15 +950,65 @@ export function getAddress(type, privKey, network = NETWORK) {
         return p2wpkh(pubKey, network).address;
     throw new Error(`getAddress: unknown type=${type}`);
 }
+// BIP67 defines canonical multisig ordering only for compressed pubkeys; this helper still sorts
+// raw bytes generically, and higher-level callers may accept uncompressed participants for compat.
 export const _sortPubkeys = (pubkeys) => Array.from(pubkeys).sort(u.compareBytes);
+/**
+ * Builds a classic M-of-N multisig output, wrapped in P2SH or P2WSH.
+ * @param m - number of required signatures
+ * @param pubkeys - participating public keys
+ * @param sorted - whether to sort the public keys first
+ * @param witness - whether to wrap the result as native SegWit
+ * @param network - address network parameters
+ * @returns Multisig payment descriptor.
+ * @throws If the multisig parameters or wrapped script are invalid. {@link Error}
+ * @example
+ * Wrap a classic 2-of-2 script into an addressable multisig output.
+ * ```ts
+ * import { multisig } from '@scure/btc-signer/payment.js';
+ * import { pubECDSA, randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * multisig(
+ *   2,
+ *   [pubECDSA(randomPrivateKeyBytes()), pubECDSA(randomPrivateKeyBytes())],
+ *   true,
+ *   true
+ * );
+ * ```
+ */
 export function multisig(m, pubkeys, sorted = false, witness = false, network = NETWORK) {
+    // BIP 143 default policy: version-0 witness programs should use compressed ECDSA pubkeys only;
+    // witness multisig callers must avoid uncompressed keys because p2ms accepts generic ECDSA encodings.
+    // BIP 16 caps spendable compressed-key P2SH multisig at 15 pubkeys because larger redeem scripts
+    // exceed the 520-byte push limit; use witness=true for larger classic multisig sets.
     const ms = p2ms(m, sorted ? _sortPubkeys(pubkeys) : pubkeys);
-    return witness ? p2wsh(ms, network) : p2sh(ms, network);
+    return (witness ? p2wsh(ms, network) : p2sh(ms, network));
 }
+/**
+ * Builds a multisig output after lexicographically sorting the keys.
+ * @param m - number of required signatures
+ * @param pubkeys - participating public keys
+ * @param witness - whether to wrap the result as native SegWit
+ * @param network - address network parameters
+ * @returns Sorted multisig payment descriptor.
+ * @throws If the multisig parameters or wrapped script are invalid. {@link Error}
+ * @example
+ * Sort public keys deterministically before constructing the multisig address.
+ * ```ts
+ * import { sortedMultisig } from '@scure/btc-signer/payment.js';
+ * import { pubECDSA, randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * sortedMultisig(
+ *   2,
+ *   [pubECDSA(randomPrivateKeyBytes()), pubECDSA(randomPrivateKeyBytes())],
+ *   true
+ * );
+ * ```
+ */
 export function sortedMultisig(m, pubkeys, witness = false, network = NETWORK) {
+    // BIP67 canonical multisig is compressed-only, but this wrapper intentionally keeps the generic
+    // sorted-multisig behavior and still allows uncompressed participant keys for compatibility.
     return multisig(m, pubkeys, true, witness, network);
 }
-const base58check = createBase58check(u.sha256);
+const base58check = /* @__PURE__ */ createBase58check(u.sha256);
 function validateWitness(version, data) {
     if (data.length < 2 || data.length > 40)
         throw new Error('Witness: invalid length');
@@ -603,15 +1019,31 @@ function validateWitness(version, data) {
 }
 function programToWitness(version, data, network = NETWORK) {
     validateWitness(version, data);
+    // BIP 350 keeps segwit v0 on Bech32, while witness versions 1+ switch to Bech32m.
     const coder = version === 0 ? bech32 : bech32m;
     return coder.encode(network.bech32, [version].concat(coder.toWords(data)));
 }
 function formatKey(hashed, prefix) {
+    // Legacy Base58Check paths all serialize [version-byte || payload] before checksumming.
     return base58check.encode(u.concatBytes(Uint8Array.from(prefix), hashed));
 }
+/**
+ * Wallet-import-format coder for private keys.
+ * @param network - address network parameters
+ * @returns WIF coder.
+ * @example
+ * Encode or decode wallet-import-format private keys.
+ * ```ts
+ * const coder = WIF();
+ * coder.encode(new Uint8Array(32).fill(1));
+ * ```
+ */
 export function WIF(network = NETWORK) {
     return {
         encode(privKey) {
+            // Compressed WIF is exactly 32 private-key bytes plus the 0x01 suffix; shorter or longer
+            // inputs must be rejected instead of being silently padded or truncated by subarray().
+            abytes(privKey, 32, 'privKey');
             const compressed = u.concatBytes(privKey, new Uint8Array([0x01]));
             return formatKey(compressed.subarray(0, 33), [network.wif]);
         },
@@ -630,6 +1062,19 @@ export function WIF(network = NETWORK) {
     };
 }
 // Returns OutType, which can be used to create outscript
+/**
+ * Address encoder/decoder for a specific Bitcoin network.
+ * @param network - address network parameters
+ * @returns Address coder backed by the provided network.
+ * @example
+ * Create a network-specific address coder and encode a payment descriptor.
+ * ```ts
+ * import { Address, p2wpkh } from '@scure/btc-signer/payment.js';
+ * import { pubECDSA, randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * const coder = Address();
+ * coder.encode(p2wpkh(pubECDSA(randomPrivateKeyBytes())));
+ * ```
+ */
 export function Address(network = NETWORK) {
     return {
         encode(from) {
@@ -674,6 +1119,8 @@ export function Address(network = NETWORK) {
                     return { type: 'wpkh', hash: data };
                 else if (version === 1 && data.length === 32)
                     return { type: 'tr', pubkey: data };
+                // Future witness versions can still be valid addresses, but this helper
+                // only returns typed descriptors for recognized v0 and taproot templates.
                 else
                     throw new Error('Unknown witness program');
             }