@scure/btc-signer 2.2.0 → 2.4.0

package/src/payment.ts

@@ -29,11 +29,18 @@ export type P2Ret = {
 };
 
 // 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]);
 type OutP2AType = { type: 'p2a'; script: Bytes };
 const OutP2A: Coder<OptScript, OutP2AType | undefined> = {
   encode(from: TArg<ScriptType>): TRet<OutP2AType | undefined> {
     // 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) } as TRet<OutP2AType | undefined>;
   },
@@ -41,7 +48,7 @@ const OutP2A: Coder<OptScript, OutP2AType | undefined> = {
     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')] as TRet<OptScript>;
+    return [1, Uint8Array.from(P2A_PROGRAM)] as TRet<OptScript>;
   },
 };
 
@@ -87,8 +94,9 @@ const OutPKH: Coder<OptScript, OutPKHType | undefined> = {
   encode(from: TArg<ScriptType>): TRet<OutPKHType | undefined> {
     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] } as TRet<OutPKHType | undefined>;
   },
@@ -105,8 +113,9 @@ const OutSH: Coder<OptScript, OutSHType | undefined> = {
   encode(from: TArg<ScriptType>): TRet<OutSHType | undefined> {
     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] } as TRet<OutSHType | undefined>;
   },
   // OutScript validates `sh.hash` before this branch emits the canonical
@@ -159,9 +168,12 @@ const OutMS: Coder<OptScript, OutMSType | undefined> = {
     if (typeof m !== 'number' || typeof n !== 'number') return;
     const pubkeys = from.slice(1, -2);
     if (n !== pubkeys.length) return;
-    for (const pub of pubkeys) if (!u.isBytes(pub)) return;
-    // OutScript validates pubkey encodings and `0 < m <= n <= 16`.
-    // This child matcher only recognizes the canonical CHECKMULTISIG skeleton.
+    // 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) || !isValidPubkey(pub, u.PubT.ecdsa)) return;
+    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 as Bytes[] } as TRet<OutMSType | undefined>;
   },
@@ -182,6 +194,10 @@ const OutTR: Coder<OptScript, OutTRType | undefined> = {
     // 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;
+    // 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] } as TRet<OutTRType | undefined>;
   },
   // OutScript validates `tr.pubkey` before this branch emits the canonical
@@ -212,7 +228,7 @@ const OutTRNS: Coder<OptScript, OutTRNSType | undefined> = {
     // 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;
+    if (!pubkeys.length || pubkeys.length > 999) return;
     return { type: 'tr_ns', pubkeys } as TRet<OutTRNSType | undefined>;
   },
   decode: (to: TArg<OutTRNSType>): TRet<OptScript> => {
@@ -243,9 +259,13 @@ const OutTRMS: Coder<OptScript, OutTRMSType | undefined> = {
         if (elm !== (i === 1 ? 'CHECKSIG' : 'CHECKSIGADD')) return;
         continue;
       }
-      if (!u.isBytes(elm)) return;
+      // 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 } as TRet<OutTRMSType | undefined>;
   },
   decode: (to: TArg<OutTRMSType>): TRet<OptScript> => {
@@ -373,16 +393,18 @@ export const OutScript: TRet<
         if (i.m <= 0 || n > 16 || i.m > n) 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) throw new Error('OutScript/tr_ms: invalid params');
+        if (i.m <= 0 || i.m > n) throw new Error('OutScript/tr_ms: invalid params');
       }
       return i;
     })
@@ -406,9 +428,32 @@ export const OutScript: TRet<
 >;
 /** Type of the output-script coder. */
 export type OutScriptType = typeof OutScript;
+// 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: OutScriptType = /* @__PURE__ */ (() =>
+  Object.freeze(
+    P.wrap<P.UnwrapCoder<typeof _OutScript>>({
+      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;
+      },
+    })
+  ))() as OutScriptType;
 // TRet-wrapping OutScript changes decode() to the normalized descriptor surface, but the local
 // checkScript/Address caches still need an explicit alias that can carry the decode-side `undefined`.
-type OutScriptValue = ReturnType<OutScriptType['decode']> | undefined;
+type AddressValue = NonNullable<ReturnType<OutScriptType['decode']>>;
+type OutScriptValue = AddressValue | undefined;
 
 // Basic sanity check for scripts
 function checkWSH(s: TArg<OutWSHType>, witnessScript: TArg<Bytes>) {
@@ -449,7 +494,7 @@ export function checkScript(
   let hasWsh = false;
   let r: OutScriptValue = 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.
@@ -460,7 +505,7 @@ export function checkScript(
       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');
-      r = OutScript.decode(redeemScript) as OutScriptValue;
+      r = _WitnessOutScript.decode(redeemScript) as OutScriptValue;
       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
@@ -472,7 +517,7 @@ export function checkScript(
     }
   }
   if (redeemScript) {
-    if (r === undefined) r = OutScript.decode(redeemScript) as OutScriptValue;
+    if (r === undefined) r = _WitnessOutScript.decode(redeemScript) as OutScriptValue;
     if (r?.type === 'wsh') {
       hasWsh = true;
       if (witnessScript) checkWSH(r as TArg<OutWSHType>, witnessScript);
@@ -481,12 +526,21 @@ export function checkScript(
   if (witnessScript && !hasWsh) throw new Error('checkScript: witnessScript without P2WSH');
 }
 
-function uniqPubkey(pubkeys: TArg<Bytes[]>) {
+function uniqPubkey(pubkeys: TArg<Bytes[]>, type: u.PubT) {
   const map: Record<string, boolean> = {};
   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;
   }
@@ -588,10 +642,30 @@ export type P2SHWithoutWitness = Omit<P2SHBase, 'witnessScript'>;
 export type P2SHReturn<T extends P2Ret> = T extends { witnessScript: Bytes }
   ? P2SHWithWitness
   : P2SHWithoutWitness;
+
+const checkCanonicalScript = (
+  script: TArg<Bytes>,
+  name: 'redeemScript' | 'witnessScript',
+  allowNonCanonicalScript: boolean
+): void => {
+  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
@@ -604,8 +678,10 @@ export type P2SHReturn<T extends P2Ret> = T extends { witnessScript: Bytes }
  */
 export const p2sh = <T extends P2Ret>(
   child: TArg<T>,
-  network: BTC_NETWORK = NETWORK
+  network: BTC_NETWORK = NETWORK,
+  allowNonCanonicalScript = false
 ): TRet<Extends<P2SHReturn<T>, P2Ret>> => {
+  u.validateObject(child as Record<string, any>, {}, {}, '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.
@@ -616,6 +692,7 @@ export const p2sh = <T extends P2Ret>(
     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 } as const;
   const script = OutScript.encode(out);
@@ -658,6 +735,7 @@ export type P2WSH = {
  * 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
@@ -670,13 +748,16 @@ export type P2WSH = {
  */
 export const p2wsh = (
   child: TArg<P2Ret>,
-  network: BTC_NETWORK = NETWORK
+  network: BTC_NETWORK = NETWORK,
+  allowNonCanonicalScript = false
 ): TRet<Extends<P2WSH, P2Ret>> => {
+  u.validateObject(child as Record<string, any>, {}, {}, 'child');
   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');
+  checkCanonicalScript(cs, 'witnessScript', allowNonCanonicalScript);
   const hash = u.sha256(cs);
   const script = OutScript.encode({ type: 'wsh', hash });
   checkScript(script, undefined, cs);
@@ -759,7 +840,7 @@ export const p2ms = (
 ): TRet<Extends<P2MS, P2Ret>> => {
   // 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);
+  if (!allowSamePubkeys) uniqPubkey(pubkeys, u.PubT.ecdsa);
   return {
     type: 'ms',
     script: OutScript.encode({ type: 'ms', pubkeys, m }),
@@ -782,9 +863,16 @@ function checkTaprootScript(
     // 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;
       }
@@ -796,7 +884,7 @@ function checkTaprootScript(
   const outms = out as OutTRNSType | OutTRMSType;
   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)
@@ -867,6 +955,13 @@ type _TaprootTreeInternal = {
  * ```
  */
 export function taprootListToTree(taprootList: TArg<TaprootScriptList>): TRet<TaprootScriptTree> {
+  u.aarray<TaprootScriptList[number]>(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 as Record<string, any>, {}, {}, 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.
@@ -941,23 +1036,35 @@ function taprootWalkTree(tree: TArg<HashedTreeWithPath>): TRet<TaprootLeaf[]> {
   return [...taprootWalkTree(tree.left), ...taprootWalkTree(tree.right)] as TRet<TaprootLeaf[]>;
 }
 
+// BIP 341 control blocks can encode at most 128 sibling hashes.
+const TAPROOT_MAX_DEPTH = 128;
 function taprootHashTree(
   tree: TArg<TaprootScriptTree>,
   internalPubKey: TArg<Bytes>,
   allowUnknownOutputs = false,
-  customScripts?: TArg<CustomScript[]>
+  customScripts?: TArg<CustomScript[]>,
+  depth = 0
 ): TRet<HashedTree> {
-  if (!tree) throw new Error('taprootHashTree: empty tree');
+  // 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 as Record<string, any>, {}, {}, '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',
@@ -971,8 +1078,20 @@ function taprootHashTree(
   if (tree.length !== 2) 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];
@@ -1014,7 +1133,7 @@ export const tapLeafHash = (script: TArg<Bytes>, version: number = TAP_LEAF_VERS
 
 // Works as key OR tree.
 // If we only have tree, need to add unspendable key, otherwise
-// complex multisig wallet can be spent by owner of key only. See TAPROOT_UNSPENDABLE_KEY
+// complex multisig wallet can be spent by owner of key only. See taprootNumsKey
 /** Conditional taproot return type for key-only or tree-backed outputs. */
 export type P2TRRet<T> = T extends TaprootScriptTree ? P2TR_TREE : P2TR;
 /**
@@ -1026,6 +1145,7 @@ export type P2TRRet<T> = T extends TaprootScriptTree ? P2TR_TREE : P2TR;
  * @param customScripts - optional custom script codecs for taproot leaves
  * @returns Taproot descriptor with optional script-path metadata.
  * @throws If the internal key or taproot script tree is invalid. {@link Error}
+ * @throws If a numeric script value is outside its supported range. {@link RangeError}
  * @example
  * Combine script leaves into a final taproot output descriptor and address.
  * ```ts
@@ -1063,7 +1183,7 @@ export function p2tr(
   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(
@@ -1071,18 +1191,20 @@ export function p2tr(
     );
     const tapMerkleRoot = hashedTree.hash;
     const [tweakedPubkey, parity] = u.taprootTweakPubkey(pubKey, tapMerkleRoot);
+    const tapLeafScript: NonNullable<TransactionInput['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',
@@ -1093,10 +1215,7 @@ export function p2tr(
       // PSBT stuff
       tapInternalKey: pubKey,
       leaves,
-      tapLeafScript: leaves.map((l) => [
-        TaprootControlBlock.decode(l.controlBlock),
-        u.concatBytes(l.script, new Uint8Array([tapLeafVersion(l.version)])),
-      ]),
+      tapLeafScript,
       tapMerkleRoot,
     } as const as TRet<Extends<P2TR_TREE, P2Ret>>;
   } else {
@@ -1115,25 +1234,47 @@ export function p2tr(
   }
 }
 
+/** Maximum number of combinations materialized by one default helper call. */
+export const MAX_COMBINATIONS = 4096;
+
+const combinationCount = (n: number, m: number): number => {
+  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<T>(m: number, list: T[]): T[][] {
+export function combinations<T>(m: number, list: T[], maxCombinations = MAX_COMBINATIONS): T[][] {
   const res: T[][] = [];
   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]++)
@@ -1163,8 +1304,8 @@ export function combinations<T>(m: number, list: T[]): T[][] {
 
 /**
  * M-of-N multi-leaf wallet via p2tr_ns. If m == n, single script is emitted.
- * Takes O(n^2) if m != n. 99-of-100 is ok, 5-of-100 is not.
- * It materializes C(n, m) leaves, so middle-of-the-range thresholds blow up combinatorially.
+ * It materializes C(n, m) leaves up to {@link MAX_COMBINATIONS}; middle-of-the-range thresholds
+ * above that bound are rejected before allocation.
  * `2-of-[A,B,C] => [A,B] | [A,C] | [B,C]`
  */
 export type P2TR_NS = {
@@ -1180,6 +1321,7 @@ export type P2TR_NS = {
  * @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
@@ -1193,14 +1335,24 @@ export const p2tr_ns = (
   pubkeys: TArg<Bytes[]>,
   allowSamePubkeys = false
 ): TRet<Extends<P2TR_NS, P2Ret>[]> => {
-  if (!allowSamePubkeys) uniqPubkey(pubkeys);
-  return combinations(m, pubkeys).map(
-    (i) =>
-      ({
-        type: 'tr_ns',
-        script: OutScript.encode({ type: 'tr_ns', pubkeys: i }),
-      }) as const as TRet<Extends<P2TR_NS, P2Ret>>
-  ) as TRet<Extends<P2TR_NS, P2Ret>[]>;
+  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: ScriptType = [];
+    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),
+    } as const as TRet<Extends<P2TR_NS, P2Ret>>;
+  }) as TRet<Extends<P2TR_NS, P2Ret>[]>;
 };
 // Taproot public key (case of p2tr_ns)
 /** Single-key taproot leaf descriptor. */
@@ -1212,6 +1364,7 @@ export type P2TR_PK = P2TR_NS;
  * @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
@@ -1250,7 +1403,7 @@ export function p2tr_ms(
   pubkeys: TArg<Bytes[]>,
   allowSamePubkeys = false
 ): TRet<Extends<P2TR_MS, P2Ret>> {
-  if (!allowSamePubkeys) uniqPubkey(pubkeys);
+  if (!allowSamePubkeys) uniqPubkey(pubkeys, u.PubT.schnorr);
   return {
     type: 'tr_ms',
     script: OutScript.encode({ type: 'tr_ms', pubkeys, m }),
@@ -1265,6 +1418,7 @@ export function p2tr_ms(
  * @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
@@ -1278,6 +1432,7 @@ export function getAddress(
   privKey: TArg<Bytes>,
   network: BTC_NETWORK = NETWORK
 ): string {
+  u.astring(type, 'type');
   if (type === 'tr') {
     return p2tr(u.pubSchnorr(privKey), undefined, network).address;
   }
@@ -1429,18 +1584,24 @@ export function WIF(network: BTC_NETWORK = NETWORK): TRet<Coder<Bytes, string>>
  * coder.encode(p2wpkh(pubECDSA(randomPrivateKeyBytes())));
  * ```
  */
-export function Address(network: BTC_NETWORK = NETWORK) {
+export function Address(network: BTC_NETWORK = NETWORK): TRet<P.Coder<AddressValue, string>> {
+  u.validateObject(network as Record<string, any>, {}, {}, 'network');
   return {
-    encode(from: Exclude<OutScriptValue, undefined>): string {
+    encode(from: TArg<AddressValue>): string {
+      u.validateObject(from as Record<string, any>, {}, {}, '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') return formatKey(from.hash, [network.scriptHash]);
       throw new Error(`Unknown address type=${type}`);
     },
-    decode(address: string): OutScriptValue {
+    decode(address: string): TRet<AddressValue> {
+      u.astring(address, 'address');
       if (address.length < 14 || address.length > 74) throw new Error('Invalid address length');
       // Bech32
       if (network.bech32 && address.toLowerCase().startsWith(`${network.bech32}1`)) {
@@ -1458,25 +1619,27 @@ export function Address(network: BTC_NETWORK = NETWORK) {
         const data = bech32.fromWords(program);
         validateWitness(version, data);
         if (version === 0 && data.length === 32)
-          return { type: 'wsh', hash: data } as OutScriptValue;
+          return { type: 'wsh', hash: data } as TRet<AddressValue>;
         else if (version === 0 && data.length === 20)
-          return { type: 'wpkh', hash: data } as OutScriptValue;
+          return { type: 'wpkh', hash: data } as TRet<AddressValue>;
         else if (version === 1 && data.length === 32)
-          return { type: 'tr', pubkey: data } as OutScriptValue;
+          return { type: 'tr', pubkey: data } as TRet<AddressValue>;
+        else if (version === 1 && u.equalBytes(data, P2A_PROGRAM))
+          return { type: 'p2a', script: Script.encode([1, data]) } as TRet<AddressValue>;
         // 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');
       }
       const data = base58check.decode(address);
       if (data.length !== 21) throw new Error('Invalid base58 address');
       // Pay To Public Key Hash
       if (data[0] === network.pubKeyHash) {
-        return { type: 'pkh', hash: data.slice(1) } as OutScriptValue;
+        return { type: 'pkh', hash: data.slice(1) } as TRet<AddressValue>;
       } else if (data[0] === network.scriptHash) {
         return {
           type: 'sh',
           hash: data.slice(1),
-        } as OutScriptValue;
+        } as TRet<AddressValue>;
       }
       throw new Error(`Invalid address prefix=${data[0]}`);
     },