@scure/btc-signer 2.2.0 → 2.4.0

package/payment.js

@@ -6,10 +6,16 @@ import { TaprootControlBlock } from "./psbt.js";
 import { MAX_SCRIPT_BYTE_LENGTH, OpToNum, Script, VarBytes } from "./script.js";
 import * as u from "./utils.js";
 import { NETWORK } from "./utils.js";
+// Pay to Anchor (P2A)
+// BIP433 Pay-to-Anchor witness program bytes; the scriptPubKey is `OP_1 <0x4e73>`.
+const P2A_PROGRAM = /* @__PURE__ */ Uint8Array.from([0x4e, 0x73]);
 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')
+        if (from.length !== 2 ||
+            from[0] !== 1 ||
+            !u.isBytes(from[1]) ||
+            !u.equalBytes(from[1], P2A_PROGRAM))
             return;
         return { type: 'p2a', script: Script.encode(from) };
     },
@@ -18,7 +24,7 @@ const OutP2A = {
             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')];
+        return [1, Uint8Array.from(P2A_PROGRAM)];
     },
 };
 function isValidPubkey(pub, type) {
@@ -54,8 +60,10 @@ 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.
+        // Require the exact 20-byte HASH160 here so near-miss scripts fall through
+        // to OutUnknown instead of throwing in the OutScript validator on decode.
+        if (from[2].length !== 20)
+            return;
         if (from[3] !== 'EQUALVERIFY' || from[4] !== 'CHECKSIG')
             return;
         return { type: 'pkh', hash: from[2] };
@@ -70,8 +78,10 @@ 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.
+        // Require the exact 20-byte HASH160 here so near-miss scripts fall through
+        // to OutUnknown instead of throwing in the OutScript validator on decode.
+        if (from[1].length !== 20)
+            return;
         return { type: 'sh', hash: from[1] };
     },
     // OutScript validates `sh.hash` before this branch emits the canonical
@@ -119,11 +129,15 @@ const OutMS = {
         const pubkeys = from.slice(1, -2);
         if (n !== pubkeys.length)
             return;
+        // Require valid ECDSA pubkeys and `0 < m <= n` here so near-miss
+        // CHECKMULTISIG scripts (garbage keys, degenerate 0-of-0) fall through to
+        // OutUnknown instead of throwing in the OutScript validator on decode.
+        // Script.decode only yields 0..16 for opcode numbers, so n <= 16 holds.
         for (const pub of pubkeys)
-            if (!u.isBytes(pub))
+            if (!u.isBytes(pub) || !isValidPubkey(pub, u.PubT.ecdsa))
                 return;
-        // OutScript validates pubkey encodings and `0 < m <= n <= 16`.
-        // This child matcher only recognizes the canonical CHECKMULTISIG skeleton.
+        if (!Number.isSafeInteger(m) || m < 1 || m > n)
+            return;
         // We don't need n here because it is the same as pubkeys.length.
         return { type: 'ms', m, pubkeys: pubkeys };
     },
@@ -143,6 +157,11 @@ const OutTR = {
         // 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;
+        // A 32-byte v1 program with an off-curve x coordinate is a fundable but
+        // taproot-unspendable output; classify it as unknown instead of throwing
+        // in the OutScript validator on decode.
+        if (!isValidPubkey(from[1], u.PubT.schnorr))
+            return;
         return { type: 'tr', pubkey: from[1] };
     },
     // OutScript validates `tr.pubkey` before this branch emits the canonical
@@ -172,7 +191,7 @@ const OutTRNS = {
         // 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)
+        if (!pubkeys.length || pubkeys.length > 999)
             return;
         return { type: 'tr_ns', pubkeys };
     },
@@ -206,10 +225,15 @@ const OutTRMS = {
                     return;
                 continue;
             }
-            if (!u.isBytes(elm))
+            // Require actual Schnorr pubkeys here (same as tr_ns) so near-miss
+            // CHECKSIGADD scripts fall through to OutUnknown instead of throwing
+            // in the OutScript validator on decode.
+            if (!u.isBytes(elm) || !isValidPubkey(elm, u.PubT.schnorr))
                 return;
             pubkeys.push(elm);
         }
+        if (!Number.isSafeInteger(m) || m < 1 || m > pubkeys.length || pubkeys.length > 999)
+            return;
         return { type: 'tr_ms', pubkeys, m };
     },
     decode: (to) => {
@@ -298,20 +322,40 @@ export const OutScript = /* @__PURE__ */ (() => Object.freeze(P.validate(_OutScr
             throw new Error('OutScript/multisig: invalid params');
     }
     if (i.type === 'tr_ns' || i.type === 'tr_ms') {
+        const n = i.pubkeys.length;
+        // BIP342 keeps the 1,000-element stack limit. Both supported tapscript multisig forms
+        // start with n signatures and then push a pubkey, so n must stay at or below 999.
+        if (n > 999)
+            throw new Error(`OutScript/${i.type}: invalid params`);
         for (const p of i.pubkeys)
             if (!isValidPubkey(p, u.PubT.schnorr))
                 throw new Error(`OutScript/${i.type}: wrong pubkey`);
     }
     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)
+        if (i.m <= 0 || i.m > n)
             throw new Error('OutScript/tr_ms: invalid params');
     }
     return i;
 })))();
+// Internal raw-aware boundary for actual scriptPubKeys and P2SH-nested witness programs. Generic
+// OutScript remains semantic because witnessScript and tapscript children may use the same opcodes
+// without claiming BIP141 witness-program framing.
+export const _WitnessOutScript = /* @__PURE__ */ (() => Object.freeze(P.wrap({
+    encodeStream: (w, value) => OutScript.encodeStream(w, value),
+    decodeStream: (r) => {
+        const raw = r.bytes(r.leftBytes);
+        const out = OutScript.decode(raw);
+        // Script.decode normalizes push opcodes, but BIP141 recognition requires the exact direct
+        // push. Reject only when this explicit outer-program boundary is selected by the caller.
+        if (out &&
+            (out.type === 'p2a' || out.type === 'wpkh' || out.type === 'wsh' || out.type === 'tr') &&
+            !u.equalBytes(raw, OutScript.encode(out)))
+            throw new Error('OutScript: non-canonical witness program');
+        return out;
+    },
+})))();
 // Basic sanity check for scripts
 function checkWSH(s, witnessScript) {
     if (!u.equalBytes(s.hash, u.sha256(witnessScript)))
@@ -346,7 +390,7 @@ export function checkScript(script, redeemScript, witnessScript) {
     let hasWsh = false;
     let r = undefined;
     if (script) {
-        const s = OutScript.decode(script);
+        const s = _WitnessOutScript.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.
@@ -358,7 +402,7 @@ export function checkScript(script, redeemScript, witnessScript) {
                 throw new Error('checkScript: redeemScript without P2SH');
             if (!u.equalBytes(s.hash, u.hash160(redeemScript)))
                 throw new Error('checkScript: sh wrong redeemScript hash');
-            r = OutScript.decode(redeemScript);
+            r = _WitnessOutScript.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
@@ -373,7 +417,7 @@ export function checkScript(script, redeemScript, witnessScript) {
     }
     if (redeemScript) {
         if (r === undefined)
-            r = OutScript.decode(redeemScript);
+            r = _WitnessOutScript.decode(redeemScript);
         if (r?.type === 'wsh') {
             hasWsh = true;
             if (witnessScript)
@@ -383,12 +427,21 @@ export function checkScript(script, redeemScript, witnessScript) {
     if (witnessScript && !hasWsh)
         throw new Error('checkScript: witnessScript without P2WSH');
 }
-function uniqPubkey(pubkeys) {
+function uniqPubkey(pubkeys, type) {
     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);
+        u.validatePubkey(pub, type);
+        let normalized = pub;
+        if (type === u.PubT.ecdsa && pub.length === 65) {
+            // Compressed and uncompressed SEC1 encodings can represent the same curve point. Normalize
+            // valid uncompressed keys before comparing so one signer cannot occupy multiple threshold
+            // slots merely by changing the serialization. `allowSamePubkeys` remains the explicit
+            // compatibility escape hatch for callers that intentionally construct duplicate-key scripts.
+            normalized = new Uint8Array(33);
+            normalized[0] = 2 | (pub[64] & 1);
+            normalized.set(pub.subarray(1, 33), 1);
+        }
+        const key = hex.encode(normalized);
         if (map[key])
             throw new Error(`Multisig: non-uniq pubkey: ${pubkeys.map(hex.encode)}`);
         map[key] = true;
@@ -442,10 +495,23 @@ export const p2pkh = (publicKey, network = NETWORK) => {
         hash,
     };
 };
+const checkCanonicalScript = (script, name, allowNonCanonicalScript) => {
+    if (allowNonCanonicalScript)
+        return;
+    const decoded = Script.decode(script);
+    const nonMinimalNumber = decoded.some((op) => u.isBytes(op) && op.length === 1 && ((1 <= op[0] && op[0] <= 16) || op[0] === 0x81));
+    // Core's default MINIMALDATA policy rejects these spends from its mempool, so address-producing
+    // helpers require an explicit opt-in even though the original bytes remain consensus-valid.
+    if (nonMinimalNumber || !u.equalBytes(script, Script.encode(decoded))) {
+        const wrapper = name === 'redeemScript' ? 'P2SH' : 'P2WSH';
+        throw new Error(`${wrapper}: non-canonical ${name}`);
+    }
+};
 /**
  * Wraps a child script inside P2SH.
  * @param child - child payment descriptor to wrap
  * @param network - address network parameters
+ * @param allowNonCanonicalScript - whether to create an address for a non-minimal child script
  * @returns P2SH descriptor preserving witness metadata when present.
  * @throws If the wrapped script combination is invalid or unsupported. {@link Error}
  * @example
@@ -456,7 +522,8 @@ export const p2pkh = (publicKey, network = NETWORK) => {
  * p2sh(p2wsh(p2pk(hex.decode('0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'))));
  * ```
  */
-export const p2sh = (child, network = NETWORK) => {
+export const p2sh = (child, network = NETWORK, allowNonCanonicalScript = false) => {
+    u.validateObject(child, {}, {}, 'child');
     // It is already tested inside noble-hashes and checkScript
     // 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.
@@ -466,6 +533,7 @@ export const p2sh = (child, network = NETWORK) => {
         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}`);
+    checkCanonicalScript(cs, 'redeemScript', allowNonCanonicalScript);
     const hash = u.hash160(cs);
     const out = { type: 'sh', hash };
     const script = OutScript.encode(out);
@@ -495,6 +563,7 @@ export const p2sh = (child, network = NETWORK) => {
  * Wraps a child script inside native SegWit P2WSH.
  * @param child - child payment descriptor to wrap
  * @param network - address network parameters
+ * @param allowNonCanonicalScript - whether to create an address for a non-minimal child script
  * @returns P2WSH descriptor.
  * @throws If the wrapped script combination is invalid or unsupported. {@link Error}
  * @example
@@ -505,7 +574,8 @@ export const p2sh = (child, network = NETWORK) => {
  * p2wsh(p2pk(hex.decode('0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798')));
  * ```
  */
-export const p2wsh = (child, network = NETWORK) => {
+export const p2wsh = (child, network = NETWORK, allowNonCanonicalScript = false) => {
+    u.validateObject(child, {}, {}, 'child');
     const cs = child.script;
     if (!u.isBytes(cs))
         throw new Error(`Wrong script: ${typeof cs}, expected Uint8Array`);
@@ -513,6 +583,7 @@ export const p2wsh = (child, network = NETWORK) => {
     // 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');
+    checkCanonicalScript(cs, 'witnessScript', allowNonCanonicalScript);
     const hash = u.sha256(cs);
     const script = OutScript.encode({ type: 'wsh', hash });
     checkScript(script, undefined, cs);
@@ -571,7 +642,7 @@ 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);
+        uniqPubkey(pubkeys, u.PubT.ecdsa);
     return {
         type: 'ms',
         script: OutScript.encode({ type: 'ms', pubkeys, m }),
@@ -584,9 +655,17 @@ function checkTaprootScript(script, internalPubKey, allowUnknownOutputs = false,
         // disable custom. All custom scripts for taproot should have prefix 'tr_'
         if (customScripts) {
             const cs = P.apply(Script, P.coders.match(customScripts));
-            const c = cs.decode(script);
+            let c;
+            // match() throws when no custom coder matches; treat that as "not a custom
+            // script" so the allowUnknownOutputs escape below stays reachable.
+            try {
+                c = cs.decode(script);
+            }
+            catch (e) {
+                c = undefined;
+            }
             if (c !== undefined) {
-                if (typeof c.type !== 'string' || !c.type.startsWith('tr_'))
+                if (!u.astring(c.type, 'c.type').startsWith('tr_'))
                     throw new Error(`P2TR: invalid custom type=${c.type}`);
                 return;
             }
@@ -599,7 +678,7 @@ function checkTaprootScript(script, internalPubKey, allowUnknownOutputs = false,
     const outms = out;
     if (!allowUnknownOutputs && outms.pubkeys) {
         for (const p of outms.pubkeys) {
-            if (u.equalBytes(p, u.TAPROOT_UNSPENDABLE_KEY))
+            if (u.equalBytes(p, u.taprootNumsKey()))
                 throw new Error('Unspendable taproot key in leaf script');
             // It's likely a mistake at this point:
             // 1. p2tr(A, p2tr_ns(2, [A, B])) == p2tr(A, p2tr_pk(B)) (A or B key)
@@ -632,6 +711,15 @@ function checkTaprootScript(script, internalPubKey, allowUnknownOutputs = false,
  * ```
  */
 export function taprootListToTree(taprootList) {
+    u.aarray(taprootList, 'taprootList', (leaf, title) => {
+        // p2tr reduces non-binary trees through this helper, so nested branch arrays are valid here.
+        if (Array.isArray(leaf))
+            return;
+        u.validateObject(leaf, {}, {}, title);
+        // This helper only arranges weighted tree nodes; p2tr validates leaf scripts while hashing.
+        if (leaf.weight !== undefined)
+            anumber(leaf.weight, title + '.weight');
+    });
     // 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.
@@ -683,21 +771,30 @@ function taprootWalkTree(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) {
-    if (!tree)
+// BIP 341 control blocks can encode at most 128 sibling hashes.
+const TAPROOT_MAX_DEPTH = 128;
+function taprootHashTree(tree, internalPubKey, allowUnknownOutputs = false, customScripts, depth = 0) {
+    // Reject before inspecting or descending into the next node, which also bounds the
+    // recursion used by the path annotation and tree-flattening passes below.
+    if (depth > TAPROOT_MAX_DEPTH)
+        throw new RangeError(`P2TR: tree depth exceeds ${TAPROOT_MAX_DEPTH}`);
+    if (tree === undefined)
         throw new Error('taprootHashTree: empty tree');
+    if (!Array.isArray(tree) && !P.utils.isPlainObject(tree))
+        throw new TypeError('"tree" expected object or array, got type=' + typeof tree);
     if (Array.isArray(tree) && tree.length === 1)
         tree = tree[0];
     // Terminal node (leaf)
     if (!Array.isArray(tree)) {
+        u.validateObject(tree, {}, {}, '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');
-        const script = typeof leafScript === 'string' ? hex.decode(leafScript) : leafScript;
-        if (!u.isBytes(script))
-            throw new Error(`checkScript: wrong script type=${script}`);
+        const script = typeof leafScript === 'string'
+            ? hex.decode(leafScript)
+            : abytes(leafScript, undefined, 'tree.script');
         checkTaprootScript(script, internalPubKey, allowUnknownOutputs, customScripts);
         return {
             type: 'leaf',
@@ -713,8 +810,8 @@ function taprootHashTree(tree, internalPubKey, allowUnknownOutputs = false, cust
         throw new Error('hashTree: non binary tree!');
     // branch
     // Both nodes should exist
-    const left = taprootHashTree(tree[0], internalPubKey, allowUnknownOutputs, customScripts);
-    const right = taprootHashTree(tree[1], internalPubKey, allowUnknownOutputs, customScripts);
+    const left = taprootHashTree(tree[0], internalPubKey, allowUnknownOutputs, customScripts, depth + 1);
+    const right = taprootHashTree(tree[1], internalPubKey, allowUnknownOutputs, customScripts, depth + 1);
     // 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];
@@ -759,25 +856,27 @@ export function p2tr(internalPubKey, tree, network = NETWORK, allowUnknownOutput
         throw new Error('p2tr: should have pubKey or scriptTree (or both)');
     const pubKey = typeof internalPubKey === 'string'
         ? hex.decode(internalPubKey)
-        : internalPubKey || u.TAPROOT_UNSPENDABLE_KEY;
+        : (internalPubKey ?? u.taprootNumsKey());
     if (!isValidPubkey(pubKey, u.PubT.schnorr))
         throw new Error('p2tr: non-schnorr pubkey');
     if (tree) {
         let hashedTree = taprootAddPath(taprootHashTree(tree, pubKey, allowUnknownOutputs, customScripts));
         const tapMerkleRoot = hashedTree.hash;
         const [tweakedPubkey, parity] = u.taprootTweakPubkey(pubKey, tapMerkleRoot);
+        const tapLeafScript = [];
         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,
-                }),
+            // 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.
+            const controlBlock = {
+                version: version + parity,
+                internalKey: pubKey,
+                merklePath: l.path,
             };
+            // Skip an encode/decode copy for performance; callers must treat returned metadata as
+            // immutable.
+            tapLeafScript.push([controlBlock, u.concatBytes(l.script, new Uint8Array([version]))]);
+            return { ...l, controlBlock: TaprootControlBlock.encode(controlBlock) };
         });
         return {
             type: 'tr',
@@ -788,10 +887,7 @@ export function p2tr(internalPubKey, tree, network = NETWORK, allowUnknownOutput
             // PSBT stuff
             tapInternalKey: pubKey,
             leaves,
-            tapLeafScript: leaves.map((l) => [
-                TaprootControlBlock.decode(l.controlBlock),
-                u.concatBytes(l.script, new Uint8Array([tapLeafVersion(l.version)])),
-            ]),
+            tapLeafScript,
             tapMerkleRoot,
         };
     }
@@ -810,27 +906,47 @@ export function p2tr(internalPubKey, tree, network = NETWORK, allowUnknownOutput
         };
     }
 }
+/** Maximum number of combinations materialized by one default helper call. */
+export const MAX_COMBINATIONS = 4096;
+const combinationCount = (n, m) => {
+    const k = Math.min(m, n - m);
+    let count = 1;
+    for (let i = 1; i <= k; i++) {
+        count = (count * (n - k + i)) / i;
+        if (!Number.isSafeInteger(count))
+            return Number.POSITIVE_INFINITY;
+    }
+    return count;
+};
 // 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
+ * @param maxCombinations - maximum result rows to materialize
  * @returns Array of combinations.
  * @throws If the combination size or input list is invalid. {@link Error}
+ * @throws If the requested result exceeds the materialization limit. {@link RangeError}
  * @example
  * Enumerate all size-two subsets of a short list.
  * ```ts
  * combinations(2, [1, 2, 3]);
  * ```
  */
-export function combinations(m, list) {
+export function combinations(m, list, maxCombinations = MAX_COMBINATIONS) {
     const res = [];
     if (!Array.isArray(list))
         throw new Error('combinations: lst arg should be array');
     const n = list.length;
     anumber(m, 'm');
+    anumber(maxCombinations, 'maxCombinations');
     if (m < 1 || m > n)
         throw new Error('combinations: m must satisfy 1 <= m <= lst.length');
+    if (maxCombinations < 1)
+        throw new Error('combinations: maxCombinations must be >= 1');
+    const count = combinationCount(n, m);
+    if (count > maxCombinations)
+        throw new RangeError(`combinations: C(${n}, ${m}) exceeds materialization limit=${maxCombinations}`);
     /*
     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]++)
@@ -866,6 +982,7 @@ export function combinations(m, list) {
  * @param allowSamePubkeys - whether duplicate keys are allowed
  * @returns Array of taproot leaf descriptors.
  * @throws If the taproot multisig parameters are invalid. {@link Error}
+ * @throws If the requested leaf set exceeds the materialization limit. {@link RangeError}
  * @example
  * Build the leaf set for an M-of-N taproot `CHECKSIGVERIFY` policy.
  * ```ts
@@ -875,12 +992,29 @@ export function combinations(m, list) {
  * ```
  */
 export const p2tr_ns = (m, pubkeys, allowSamePubkeys = false) => {
-    if (!allowSamePubkeys)
-        uniqPubkey(pubkeys);
-    return combinations(m, pubkeys).map((i) => ({
-        type: 'tr_ns',
-        script: OutScript.encode({ type: 'tr_ns', pubkeys: i }),
-    }));
+    anumber(m, 'm');
+    if (m > 999)
+        throw new Error('OutScript/tr_ns: invalid params');
+    // Enforce the allocation bound before doing curve work on an attacker-controlled key list.
+    const keySets = combinations(m, pubkeys);
+    if (allowSamePubkeys) {
+        for (const pubkey of pubkeys)
+            u.validatePubkey(pubkey, u.PubT.schnorr);
+    }
+    else
+        uniqPubkey(pubkeys, u.PubT.schnorr);
+    return keySets.map((keys) => {
+        // Keys were validated once above. Encoding through OutScript here would repeat lift_x for
+        // every key in every combination, turning a bounded leaf set into avoidable curve-level work.
+        const ops = [];
+        for (let i = 0; i < keys.length - 1; i++)
+            ops.push(keys[i], 'CHECKSIGVERIFY');
+        ops.push(keys[keys.length - 1], 'CHECKSIG');
+        return {
+            type: 'tr_ns',
+            script: Script.encode(ops),
+        };
+    });
 };
 /**
  * Builds a single-key taproot leaf script.
@@ -889,6 +1023,7 @@ export const p2tr_ns = (m, pubkeys, allowSamePubkeys = false) => {
  * @param pubkey - Schnorr public key
  * @returns Taproot single-key leaf descriptor.
  * @throws If the taproot single-key leaf cannot be encoded. {@link Error}
+ * @throws If the delegated leaf policy exceeds its supported range. {@link RangeError}
  * @example
  * Build a single-key tapscript leaf.
  * ```ts
@@ -915,7 +1050,7 @@ export const p2tr_pk = (pubkey) => p2tr_ns(1, [pubkey], undefined)[0];
  */
 export function p2tr_ms(m, pubkeys, allowSamePubkeys = false) {
     if (!allowSamePubkeys)
-        uniqPubkey(pubkeys);
+        uniqPubkey(pubkeys, u.PubT.schnorr);
     return {
         type: 'tr_ms',
         script: OutScript.encode({ type: 'tr_ms', pubkeys, m }),
@@ -929,6 +1064,7 @@ export function p2tr_ms(m, pubkeys, allowSamePubkeys = false) {
  * @param network - address network parameters
  * @returns Encoded Bitcoin address.
  * @throws If the requested address type is unknown. {@link Error}
+ * @throws If a key-derived script value is outside its supported range. {@link RangeError}
  * @example
  * Pick the output type first, then derive the matching address from the private key.
  * ```ts
@@ -938,6 +1074,7 @@ export function p2tr_ms(m, pubkeys, allowSamePubkeys = false) {
  * ```
  */
 export function getAddress(type, privKey, network = NETWORK) {
+    u.astring(type, 'type');
     if (type === 'tr') {
         return p2tr(u.pubSchnorr(privKey), undefined, network).address;
     }
@@ -1076,15 +1213,21 @@ export function WIF(network = NETWORK) {
  * ```
  */
 export function Address(network = NETWORK) {
+    u.validateObject(network, {}, {}, 'network');
     return {
         encode(from) {
+            u.validateObject(from, {}, {}, 'from');
             const { type } = from;
+            u.astring(type, 'from.type');
             if (type === 'wpkh')
                 return programToWitness(0, from.hash, network);
             else if (type === 'wsh')
                 return programToWitness(0, from.hash, network);
             else if (type === 'tr')
                 return programToWitness(1, from.pubkey, network);
+            // BIP433 P2A is the fixed v1 witness program 0x4e73 ('bc1pfeessrawgf').
+            else if (type === 'p2a')
+                return programToWitness(1, P2A_PROGRAM, network);
             else if (type === 'pkh')
                 return formatKey(from.hash, [network.pubKeyHash]);
             else if (type === 'sh')
@@ -1092,6 +1235,7 @@ export function Address(network = NETWORK) {
             throw new Error(`Unknown address type=${type}`);
         },
         decode(address) {
+            u.astring(address, 'address');
             if (address.length < 14 || address.length > 74)
                 throw new Error('Invalid address length');
             // Bech32
@@ -1119,8 +1263,10 @@ export function Address(network = NETWORK) {
                     return { type: 'wpkh', hash: data };
                 else if (version === 1 && data.length === 32)
                     return { type: 'tr', pubkey: data };
+                else if (version === 1 && u.equalBytes(data, P2A_PROGRAM))
+                    return { type: 'p2a', script: Script.encode([1, data]) };
                 // Future witness versions can still be valid addresses, but this helper
-                // only returns typed descriptors for recognized v0 and taproot templates.
+                // only returns typed descriptors for recognized v0, taproot and P2A templates.
                 else
                     throw new Error('Unknown witness program');
             }
@@ -1141,4 +1287,3 @@ export function Address(network = NETWORK) {
         },
     };
 }
-//# sourceMappingURL=payment.js.map