@scure/btc-signer 2.2.0 → 2.4.0

package/src/utils.ts

@@ -4,6 +4,7 @@ import { ripemd160 } from '@noble/hashes/legacy.js';
 import { sha256 as nobleSha256 } from '@noble/hashes/sha2.js';
 import { type TArg, type TRet } from '@noble/hashes/utils.js';
 import { utils as packedUtils, U32LE } from 'micro-packed';
+export { abytes, validateObject as vld } from '@noble/curves/utils.js';
 export { type TArg, type TRet } from '@noble/hashes/utils.js';
 
 /** Hex-like input accepted by helpers in this module. */
@@ -11,9 +12,71 @@ export type Hex = string | Uint8Array;
 /** Byte array alias used across the library. */
 export type Bytes = Uint8Array;
 
+/**
+ * Validates that a value is a non-negative bigint.
+ * @param n - Value to validate.
+ * @param title - Label included in thrown errors.
+ * @returns The same bigint.
+ * @throws On wrong argument types. {@link TypeError}
+ * @example
+ * Validate a satoshi amount before transaction encoding.
+ * ```ts
+ * abigint(1n, 'amount');
+ * ```
+ */
+export function abigint(n: unknown, title: string = 'value'): bigint {
+  if (typeof n !== 'bigint')
+    throw new TypeError(`"${title}" expected bigint, got type=${typeof n}`);
+  if (n < _0n) throw new RangeError(`"${title}" expected non-negative bigint, got ${n}`);
+  return n;
+}
+
+import { validateObject as vld } from '@noble/curves/utils.js';
+
+export function aarray<T>(
+  item: unknown,
+  title: string,
+  inner: (elm: T, title: string) => void = () => {}
+): T[] {
+  if (!Array.isArray(item))
+    throw new TypeError(`"${title}" expected array, got type=${typeof item}`);
+  for (let i = 0; i < item.length; i++) inner(item[i], `${title}[${i}]`);
+  return item;
+}
+/**
+ * Asserts something is a string.
+ * @param value - Value to validate.
+ * @param title - Label included in thrown errors.
+ * @returns The validated string.
+ * @throws On wrong argument types. {@link TypeError}
+ * @example
+ * Validate a label string.
+ *
+ * ```ts
+ * astring('example', 'label');
+ * ```
+ */
+export function astring(value: unknown, title: string = ''): string {
+  if (typeof value !== 'string') {
+    const prefix = title && `"${title}" `;
+    throw new TypeError(prefix + 'expected string, got type=' + typeof value);
+  }
+  return value;
+}
+export function validateObject(
+  object: Record<string, any>,
+  fields: Record<string, string> = {},
+  optFields: Record<string, string> = {},
+  _title = 'object'
+) {
+  return vld(object, fields, optFields);
+}
 const Point = /* @__PURE__ */ (() => secp.Point)();
 const Fn = /* @__PURE__ */ (() => Point.Fn)();
 const CURVE_ORDER = /* @__PURE__ */ (() => Point.Fn.ORDER)();
+// Be friendly to bad ECMAScript parsers by not using bigint literals.
+// prettier-ignore
+const _0n = /* @__PURE__ */ BigInt(0), _2n = /* @__PURE__ */ BigInt(2);
 /**
  * Checks whether a curve y-coordinate is even.
  * @param y - y-coordinate to inspect
@@ -24,7 +87,7 @@ const CURVE_ORDER = /* @__PURE__ */ (() => Point.Fn.ORDER)();
  * hasEven(2n);
  * ```
  */
-export const hasEven = (y: bigint) => y % 2n === 0n;
+export const hasEven = (y: bigint) => y % _2n === _0n;
 
 /**
  * Checks whether a value is a Uint8Array.
@@ -144,7 +207,10 @@ export const pubECDSA = (privateKey: TArg<Uint8Array>, isCompressed?: boolean):
 // noble/secp256k1 does not support the feature: it is not used outside of BTC.
 // We implement it manually, because in BTC it's common.
 // Not best way, but closest to bitcoin implementation (easier to check)
-const hasLowR = (sig: { r: bigint; s: bigint }) => sig.r < CURVE_ORDER / 2n;
+// Hoisted: the bound is constant; no need to redo the bigint division on every
+// grinding-loop iteration. n/2 < 2^255, so r < n/2 guarantees the 32-byte DER r.
+const LOW_R_BOUND = /* @__PURE__ */ (() => CURVE_ORDER / _2n)();
+const hasLowR = (sig: { r: bigint; s: bigint }) => sig.r < LOW_R_BOUND;
 /**
  * Signs a 32-byte hash with ECDSA and returns DER encoding.
  * @param hash - message hash to sign
@@ -345,10 +411,32 @@ export function taprootTweakPubkey(pubKey: TArg<Bytes>, h: TArg<Bytes>): TRet<[B
 // This is the fixed BIP 341 H example, not the privacy-preserving H + rG variant.
 // Downstream helpers use exact-byte equality with it to recognize
 // library-generated script-only outputs.
-/** Standard unspendable internal key used for script-only Taproot outputs. */
-export const TAPROOT_UNSPENDABLE_KEY: TRet<Bytes> = /* @__PURE__ */ (() =>
+// Keep the value used by library internals private: exported Uint8Arrays are mutable, so the
+// public compatibility export below cannot safely be a source of cryptographic key material.
+const INTERNAL_TAPROOT_NUMS: TRet<Bytes> = /* @__PURE__ */ (() =>
   sha256(Point.BASE.toBytes(false)) as TRet<Bytes>)();
 
+/**
+ * Standard unspendable internal key used for script-only Taproot outputs.
+ * @deprecated Use {@link taprootNumsKey} to receive an owned copy.
+ */
+export const TAPROOT_UNSPENDABLE_KEY: TRet<Bytes> = /* @__PURE__ */ (() =>
+  Uint8Array.from(INTERNAL_TAPROOT_NUMS) as TRet<Bytes>)();
+
+/**
+ * Returns an owned copy of the library's stable Taproot NUMS key.
+ * @returns A new 32-byte NUMS key copy.
+ * @example
+ * Obtain an internal key without sharing mutable exported storage.
+ * ```ts
+ * import { taprootNumsKey } from '@scure/btc-signer/utils.js';
+ * const internalKey = taprootNumsKey();
+ * ```
+ */
+export function taprootNumsKey(): TRet<Bytes> {
+  return Uint8Array.from(INTERNAL_TAPROOT_NUMS) as TRet<Bytes>;
+}
+
 /** Bitcoin network parameters. */
 export type BTC_NETWORK = {
   /** Human-readable prefix used by Bech32 and Bech32m addresses. */

package/src/utxo.ts

@@ -1,8 +1,15 @@
 import { hex } from '@scure/base';
 import * as P from 'micro-packed';
-import { Address, type CustomScript, OutScript, checkScript, tapLeafHash } from './payment.ts';
+import {
+  Address,
+  type CustomScript,
+  OutScript,
+  _WitnessOutScript,
+  checkScript,
+  tapLeafHash,
+} from './payment.ts';
 import * as psbt from './psbt.ts';
-import { CompactSizeLen, RawWitness, Script, VarBytes } from './script.ts';
+import { CompactSizeLen, RawWitness, Script } from './script.ts';
 import {
   SignatureHash,
   Transaction,
@@ -14,16 +21,22 @@ import {
   toVsize,
 } from './transaction.ts';
 import {
+  abigint,
+  aarray,
+  astring,
   type Bytes,
   NETWORK,
   PubT,
-  TAPROOT_UNSPENDABLE_KEY,
   type TArg,
+  type TRet,
   compareBytes,
   equalBytes,
   isBytes,
   sha256,
+  taprootNumsKey,
+  taprootTweakPubkey,
   validatePubkey,
+  validateObject,
 } from './utils.ts';
 
 // UTXO Select
@@ -39,73 +52,174 @@ export type Accumulated =
     }
   | undefined;
 type TapLeafScript = psbt.TransactionInput['tapLeafScript'];
+type TapLeaf = NonNullable<TapLeafScript>[number];
 type TB = Parameters<typeof psbt.TaprootControlBlock.encode>[0];
 const encodeTapBlock = (item: TB) => psbt.TaprootControlBlock.encode(item);
+// Be friendly to bad ECMAScript parsers by not using bigint literals.
+// prettier-ignore
+const _0n = /* @__PURE__ */ BigInt(0), _3n = /* @__PURE__ */ BigInt(3);
+// Serialized length of VarBytes(data) without allocating the encoded copy
+const varLen = (dataLen: number) => CompactSizeLen.encode(dataLen).length + dataLen;
+
+const tapLeafWitness = (
+  leaf: TArg<TapLeaf>,
+  sigSize: number,
+  customScripts?: TArg<CustomScript[]>,
+  pubkeys?: Set<string>,
+  unknownError = 'Finalize: Unknown tapLeafScript'
+): TRet<Bytes[] | undefined> => {
+  const [cb, _script] = leaf as TapLeaf;
+  const _customScripts = customScripts as CustomScript[] | undefined;
+  // Last byte is version
+  const script = _script.slice(0, -1);
+  const ver = _script[_script.length - 1];
+  const outs = OutScript.decode(script);
+  const available = (pubkey: TArg<Bytes>) => !pubkeys || pubkeys.has(hex.encode(pubkey as Bytes));
+  const empty = () => new Uint8Array(sigSize);
+  let signatures: Bytes[] = [];
+  if (outs.type === 'tr_ms') {
+    let added = 0;
+    for (const pubkey of outs.pubkeys) {
+      if (added === outs.m || !available(pubkey)) signatures.push(P.EMPTY);
+      else {
+        signatures.push(empty());
+        added++;
+      }
+    }
+    if (added !== outs.m) return;
+  } else if (outs.type === 'tr_ns') {
+    for (const pubkey of outs.pubkeys) {
+      if (!available(pubkey)) return;
+      signatures.push(empty());
+    }
+  } else {
+    if (!_customScripts) throw new Error(unknownError);
+    const leafHash = tapLeafHash(script, ver);
+    const scriptDecoded = Script.decode(script);
+    const scriptPubkeys = scriptDecoded.filter((i) => {
+      if (!isBytes(i)) return false;
+      try {
+        validatePubkey(i, PubT.schnorr);
+        return true;
+      } catch (e) {
+        return false;
+      }
+    }) as Bytes[];
+    const availablePubkeys = scriptPubkeys.filter(available);
+    // A custom finalizer may treat an unexpected empty signature list as malformed input. If the
+    // script embeds keys but none are owned, the path is unavailable without consulting the hook.
+    if (pubkeys && scriptPubkeys.length && !availablePubkeys.length) return;
+    let recognized = false;
+    for (const c of _customScripts) {
+      if (!c.finalizeTaproot) continue;
+      const csEncoded = c.encode(scriptDecoded);
+      if (csEncoded === undefined) continue;
+      recognized = true;
+      const finalized = c.finalizeTaproot(
+        script,
+        csEncoded,
+        availablePubkeys.map((pubKey) => [{ pubKey, leafHash }, empty()])
+      );
+      if (finalized) return finalized.concat(encodeTapBlock(cb)) as TRet<Bytes[]>;
+    }
+    if (recognized && pubkeys) return;
+    throw new Error(unknownError);
+  }
+  // Witness is stack, so last element will be used first
+  return signatures.reverse().concat([script, encodeTapBlock(cb)]) as TRet<Bytes[]>;
+};
 
 function iterLeafs(
   tapLeafScript: TArg<TapLeafScript>,
   sigSize: number,
   customScripts?: TArg<CustomScript[]>
-) {
+): TRet<Bytes[]> {
   const _tapLeafScript = tapLeafScript as TapLeafScript;
   const _customScripts = customScripts as CustomScript[] | undefined;
   if (!_tapLeafScript || !_tapLeafScript.length) throw new Error('no leafs');
-  // Dummy non-empty Schnorr signature bytes for weight estimation.
-  // Unsigned tr_ms slots use P.EMPTY below.
-  const empty = () => new Uint8Array(sigSize);
-  // If user want to select specific leaf, which can signed,
-  // it is possible to remove all other leafs manually.
-  // Sort leafs by control block length.
-  const leafs = _tapLeafScript.sort(
-    (a, b) => encodeTapBlock(a[0]).length - encodeTapBlock(b[0]).length
-  );
-  for (const [cb, _script] of leafs) {
-    // Last byte is version
-    const script = _script.slice(0, -1);
-    const ver = _script[_script.length - 1];
-    const outs = OutScript.decode(script);
+  // Start with the old shallowest-path order for stable equal-weight ties. Full witness size can
+  // reverse that order when a shallow leaf needs a larger script or more signatures.
+  const leafs = _tapLeafScript
+    .slice()
+    .sort((a, b) => encodeTapBlock(a[0]).length - encodeTapBlock(b[0]).length);
+  let smallest: Bytes[] | undefined;
+  let smallestSize = Number.POSITIVE_INFINITY;
+  for (const leaf of leafs) {
+    const witness = tapLeafWitness(leaf, sigSize, _customScripts);
+    if (!witness) continue;
+    const size = RawWitness.encode(witness).length;
+    if (size >= smallestSize) continue;
+    smallest = witness;
+    smallestSize = size;
+  }
+  if (!smallest) throw new Error('there was no witness');
+  return smallest as TRet<Bytes[]>;
+}
 
-    let signatures: Bytes[] = [];
-    if (outs.type === 'tr_ms') {
-      const m = outs.m;
-      const n = outs.pubkeys.length - m;
-      for (let i = 0; i < m; i++) signatures.push(empty());
-      for (let i = 0; i < n; i++) signatures.push(P.EMPTY);
-    } else if (outs.type === 'tr_ns') {
-      for (const _pub of outs.pubkeys) signatures.push(empty());
-    } else {
-      if (!_customScripts) throw new Error('Finalize: Unknown tapLeafScript');
-      const leafHash = tapLeafHash(script, ver);
-      for (const c of _customScripts) {
-        if (!c.finalizeTaproot) continue;
-        const scriptDecoded = Script.decode(script);
-        const csEncoded = c.encode(scriptDecoded);
-        if (csEncoded === undefined) continue;
-        const pubKeys = scriptDecoded.filter((i) => {
-          if (!isBytes(i)) return false;
-          try {
-            validatePubkey(i, PubT.schnorr);
-            return true;
-          } catch (e) {
-            return false;
-          }
-        }) as Bytes[];
-        const finalized = c.finalizeTaproot(
-          script,
-          csEncoded,
-          pubKeys.map((pubKey) => [{ pubKey, leafHash }, empty()])
-        );
-        if (!finalized) continue;
-        return finalized.concat(encodeTapBlock(cb));
-      }
-      // UTXO selection may run without the real signer/finalizer process. When no matching local
-      // finalizeTaproot hook exists, keep a minimal script-path witness lower bound here instead of
-      // failing selection; callers that need exact fee estimates must provide the matching hook.
+/**
+ * Removes Taproot spend paths that cannot be satisfied by the supplied Schnorr public keys.
+ * Non-Taproot inputs are retained, and caller-owned input metadata is never mutated.
+ * @param inputs - candidate PSBT input records to filter
+ * @param pubkeys - available x-only Schnorr public keys
+ * @returns Copies of inputs that retain at least one available path
+ * @example
+ * Filter wallet UTXOs before selecting coins.
+ * ```ts
+ * import { filterTaproot } from '@scure/btc-signer/utxo.js';
+ * import { pubSchnorr, randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * const spendable = filterTaproot([], [pubSchnorr(randomPrivateKeyBytes())]);
+ * ```
+ */
+export function filterTaproot(
+  inputs: TArg<psbt.TransactionInputUpdate[]>,
+  pubkeys: TArg<Bytes[]>
+): TRet<psbt.TransactionInputUpdate[]> {
+  aarray(inputs, 'inputs');
+  aarray(pubkeys, 'pubkeys');
+  const _inputs = inputs as psbt.TransactionInputUpdate[];
+  const _pubkeys = pubkeys as Bytes[];
+  const keys = new Set<string>();
+  for (const pubkey of _pubkeys) keys.add(hex.encode(validatePubkey(pubkey, PubT.schnorr)));
+  const res: psbt.TransactionInputUpdate[] = [];
+  for (const input of _inputs) {
+    const filtered = { ...input };
+    // BIP371 path fields are optional and empty keyed lists encode as absence, so the committed
+    // previous-output script is the authoritative input type.
+    const prevScript = _WitnessOutScript.decode(
+      getPrevOut(filtered as TArg<psbt.TransactionInput>).script
+    );
+    if (prevScript.type !== 'tr') {
+      res.push(filtered);
+      continue;
+    }
+    if (filtered.tapInternalKey) {
+      // A control block can reconstruct the root, but BIP371 does not require that inference.
+      // Omission may be broken data or an earlier filter deliberately disabling the key path.
+      // Recognize root omission only when the prevout proves this is an empty-tree commitment.
+      const hasRoot =
+        filtered.tapMerkleRoot !== undefined ||
+        equalBytes(taprootTweakPubkey(filtered.tapInternalKey, P.EMPTY)[0], prevScript.pubkey);
+      if (
+        !hasRoot ||
+        equalBytes(filtered.tapInternalKey, taprootNumsKey()) ||
+        (!keys.has(hex.encode(filtered.tapInternalKey)) && !keys.has(hex.encode(prevScript.pubkey)))
+      )
+        delete filtered.tapInternalKey;
+    }
+    if (filtered.tapLeafScript) {
+      const sigSize =
+        filtered.sighashType !== undefined && filtered.sighashType !== SignatureHash.DEFAULT
+          ? 65
+          : 64;
+      const leafs = filtered.tapLeafScript.filter((leaf) =>
+        tapLeafWitness(leaf, sigSize, undefined, keys, 'filterTaproot: unknown Taproot leaf')
+      );
+      if (leafs.length) filtered.tapLeafScript = leafs;
+      else delete filtered.tapLeafScript;
     }
-    // Witness is stack, so last element will be used first
-    return signatures.reverse().concat([script, encodeTapBlock(cb)]);
+    if (filtered.tapInternalKey || filtered.tapLeafScript) res.push(filtered);
   }
-  throw new Error('there was no witness');
+  return res as TRet<psbt.TransactionInputUpdate[]>;
 }
 
 function estimateInput(
@@ -121,13 +235,9 @@ function estimateInput(
   // schnorr sig is always 64 bytes. except for cases when sighash is not default!
   if (inputType.txType === 'taproot') {
     const SCHNORR_SIG_SIZE = inputType.sighash !== SignatureHash.DEFAULT ? 65 : 64;
-    // BIP371 `PSBT_IN_TAP_INTERNAL_KEY` is signer metadata, but UTXO selection
-    // runs before signer availability is known. We intentionally treat a
-    // present internal key as a key-path hint here to avoid overestimating fees
-    // on the online side. Callers that know only script-path signing is
-    // possible should omit `tapInternalKey` or pre-filter `tapLeafScript`
-    // before estimation.
-    if (_input.tapInternalKey && !equalBytes(_input.tapInternalKey, TAPROOT_UNSPENDABLE_KEY)) {
+    // A real internal key and every retained leaf declare paths available to this caller. Use
+    // filterTaproot before estimation when the supplied input contains unavailable paths.
+    if (_input.tapInternalKey && !equalBytes(_input.tapInternalKey, taprootNumsKey())) {
       witness = [new Uint8Array(SCHNORR_SIG_SIZE)];
     } else if (_input.tapLeafScript) {
       witness = iterLeafs(_input.tapLeafScript, SCHNORR_SIG_SIZE, _opts.customScripts);
@@ -175,10 +285,11 @@ function estimateInput(
     } else if (inputType.type.startsWith('wsh-')) {
     } else if (inputType.txType !== 'segwit') script = inputScript;
   }
-  let weight = 160 + 4 * VarBytes.encode(script).length;
+  let weight = 160 + 4 * varLen(script.length);
   let hasWitnesses = false;
   if (witness) {
-    weight += RawWitness.encode(witness).length;
+    weight += CompactSizeLen.encode(witness.length).length;
+    for (const w of witness) weight += varLen(w.length);
     hasWitnesses = true;
   }
   return { weight, hasWitnesses };
@@ -189,8 +300,8 @@ export const _cmpBig = (a: bigint, b: bigint): 0 | 1 | -1 => {
   // Array.sort comparators must return a number, so normalize bigint comparisons to -1/0/1
   // instead of coercing large differences through Number(...) and losing ordering precision.
   const n = a - b;
-  if (n < 0n) return -1;
-  else if (n > 0n) return 1;
+  if (n < _0n) return -1;
+  else if (n > _0n) return 1;
   return 0;
 };
 
@@ -209,9 +320,12 @@ export type EstimatorOpts = TxOpts & {
   createTx?: boolean; // Create tx inside selection
   requiredInputs?: psbt.TransactionInputUpdate[]; // these inputs always will be used
   allowSameUtxo?: boolean; // allow using UTXO multiple times (for test purposes)
+  /** Filter Taproot candidate paths to those satisfiable by these Schnorr public keys. */
+  filterTaproot?: Bytes[];
 };
 
 function getScript(o: TArg<Output>, opts: TArg<TxOpts> = {}, network = NETWORK) {
+  validateObject(o as Record<string, any>, {}, {}, 'output');
   const _o = o as Output;
   const _opts = opts as TxOpts;
   let script;
@@ -219,8 +333,7 @@ function getScript(o: TArg<Output>, opts: TArg<TxOpts> = {}, network = NETWORK)
     script = _o.script;
   }
   if ('address' in _o) {
-    if (typeof _o.address !== 'string')
-      throw new Error(`Estimator: wrong output address=${_o.address}`);
+    astring(_o.address, 'output.address');
     // Address.decode() only yields known descriptors for valid output addresses, but the wrapped
     // coder type still includes `undefined`, so narrow before re-encoding the script template.
     script = OutScript.encode(
@@ -228,16 +341,10 @@ function getScript(o: TArg<Output>, opts: TArg<TxOpts> = {}, network = NETWORK)
     );
   }
   if (!script) throw new Error('Estimator: wrong output script');
-  if (typeof _o.amount !== 'bigint')
-    throw new Error(
-      `Estimator: wrong output amount=${
-        _o.amount
-      }, should be of type bigint but got ${typeof _o.amount}.`
-    );
   // Keep selector-only `createTx: false` flows aligned with the transaction/PSBT output boundary:
   // satoshi-denominated outputs are not allowed to go negative.
-  if (_o.amount < 0n) throw new Error(`Estimator: wrong output amount=${_o.amount}`);
-  if (script && !_opts.allowUnknownOutputs && OutScript.decode(script).type === 'unknown') {
+  abigint(_o.amount, 'output.amount');
+  if (script && !_opts.allowUnknownOutputs && _WitnessOutScript.decode(script).type === 'unknown') {
     throw new Error(
       'Estimator: unknown output script type, there is a chance that input is unspendable. Pass allowUnknownOutputs=true, if you sure'
     );
@@ -254,10 +361,7 @@ type AccumStrategy = `accum${SortStrategy}`;
 
 /** Supported UTXO selection strategies. */
 export type SelectionStrategy =
-  | 'all'
-  | 'default'
-  | AccumStrategy
-  | `${ExactStrategy}/${AccumStrategy}`;
+  'all' | 'default' | AccumStrategy | `${ExactStrategy}/${AccumStrategy}`;
 
 // class, because we need to re-use normalized inputs, instead of parsing each time
 // internal stuff, exported for tests only
@@ -280,18 +384,14 @@ export class _Estimator {
   private outputs: Output[];
   private opts: EstimatorOpts;
   constructor(inputs: psbt.TransactionInputUpdate[], outputs: Output[], opts: EstimatorOpts) {
+    // EstimatorOpts extends TxOpts, so resolve the complete transaction policy once even when
+    // createTx=false. This keeps selection normalization and a returned Transaction identical.
+    opts = new Transaction(opts).opts as EstimatorOpts;
     this.outputs = outputs;
     this.opts = opts;
-    if (typeof opts.feePerByte !== 'bigint')
-      throw new Error(
-        `Estimator: wrong feePerByte=${
-          opts.feePerByte
-        }, should be of type bigint but got ${typeof opts.feePerByte}.`
-      );
     // Zero-fee estimation is useful on regtest/in tests, but negative fee rates would make
     // `getSatoshi(...)` produce nonsensical negative fees throughout selection.
-    if (opts.feePerByte < 0n)
-      throw new Error(`Estimator: feePerByte must be >= 0 satoshi per vbyte`);
+    abigint(opts.feePerByte, 'opts.feePerByte');
     // Dust stuff
     // TODO: think about this more:
     // - current dust filters tx which cannot be relayed by core
@@ -304,46 +404,37 @@ export class _Estimator {
     const inputsDust = 32 + 4 + 1 + 107 + 4; // NOTE: can be smaller for segwit tx?
     const outputDust = 34; // NOTE: 'nSize = GetSerializeSize(txout)'
     const dustBytes = opts.dust === undefined ? BigInt(inputsDust + outputDust) : opts.dust;
-    if (typeof dustBytes !== 'bigint') {
-      throw new Error(
-        `Estimator: wrong dust=${opts.dust}, should be of type bigint but got ${typeof opts.dust}.`
-      );
-    }
+    abigint(dustBytes, 'opts.dust');
     // 3 sat/vb is the default minimum fee rate used to calculate dust thresholds by bitcoin core.
     // 3000 sat/kvb -> 3 sat/vb.
     // https://github.com/bitcoin/bitcoin/blob/27a770b34b8f1dbb84760f442edb3e23a0c2420b/src/policy/policy.h#L55
-    const dustFee = opts.dustRelayFeeRate === undefined ? 3n : opts.dustRelayFeeRate;
-    if (typeof dustFee !== 'bigint') {
-      throw new Error(
-        `Estimator: wrong dustRelayFeeRate=${opts.dustRelayFeeRate}, should be of type bigint but got ${typeof opts.dustRelayFeeRate}.`
-      );
-    }
+    const dustFee = opts.dustRelayFeeRate === undefined ? _3n : opts.dustRelayFeeRate;
+    abigint(dustFee, 'opts.dustRelayFeeRate');
     // Dust uses feePerbyte by default, but we allow separate dust fee if needed
     this.dust = dustBytes * dustFee;
     if (opts.requiredInputs !== undefined && !Array.isArray(opts.requiredInputs))
       throw new Error(`Estimator: wrong required inputs=${opts.requiredInputs}`);
     const network = opts.network || NETWORK;
-    let amount = 0n;
+    let amount = _0n;
     // Base weight: tx with outputs, no inputs
     let baseWeight = 32;
     for (const o of outputs) {
       const script = getScript(o, opts, opts.network);
-      baseWeight += 32 + 4 * VarBytes.encode(script).length;
+      baseWeight += 32 + 4 * varLen(script.length);
       amount += o.amount;
     }
-    if (typeof opts.changeAddress !== 'string')
-      throw new Error(`Estimator: wrong change address=${opts.changeAddress}`);
+    astring(opts.changeAddress, 'opts.changeAddress');
     let changeWeight =
       baseWeight +
       32 +
       // Same Address.decode() narrowing as above: the estimator only reaches this path for a
       // concrete change output address, not an unknown descriptor.
       4 *
-        VarBytes.encode(
+        varLen(
           OutScript.encode(
             Address(network).decode(opts.changeAddress) as Parameters<typeof OutScript.encode>[0]
-          )
-        ).length;
+          ).length
+        );
     baseWeight += 4 * CompactSizeLen.encode(outputs.length).length;
     // If there a lot of outputs change can change fee
     changeWeight += 4 * CompactSizeLen.encode(outputs.length + 1).length;
@@ -362,7 +453,8 @@ export class _Estimator {
         undefined,
         undefined,
         opts.disableScriptCheck,
-        opts.allowUnknown
+        opts.unknown!,
+        opts.proprietary!
       );
       inputBeforeSign(normalized as TArg<psbt.TransactionInput>); // check fields
       const key = `${hex.encode(normalized.txid!)}:${normalized.index}`;
@@ -441,7 +533,7 @@ export class _Estimator {
     let weight = this.opts.alwaysChange ? this.changeWeight : this.baseWeight;
     let hasWitnesses = false;
     let num = 0;
-    let inputsAmount = 0n;
+    let inputsAmount = _0n;
     const targetAmount = this.amount;
     const res: Set<number> = new Set();
     let fee;
@@ -483,7 +575,7 @@ export class _Estimator {
       // Negative: cost of using input is more than value provided (negative)
       // By default 'blackjack' mode in coinselect doesn't use that, which means
       // it will use negative output if sorted by 'smallest'
-      if (skipNegative && value <= 0n) continue;
+      if (skipNegative && value <= _0n) continue;
       weight = newWeight;
       if (estimate.hasWitnesses) hasWitnesses = true;
       num = newNum;
@@ -495,6 +587,10 @@ export class _Estimator {
     }
     if (all) {
       const total = getTotal(weight, num);
+      // 'all' accumulates unconditionally, so sufficiency must be checked here; otherwise
+      // result() would report a negative fee (or throw its internal negative-change error).
+      // Insufficient funds are a selection failure, same as for accumulation strategies.
+      if (targetAmount + total.fee > inputsAmount) return undefined;
       return {
         indices: Array.from(res),
         fee: total.fee,
@@ -572,7 +668,7 @@ export class _Estimator {
     if (needChange) {
       fee = changeFee;
       // this shouldn't happen!
-      if (change < 0n) throw new Error(`Estimator.result: negative change=${change}`);
+      if (change < _0n) throw new Error(`Estimator.result: negative change=${change}`);
       outputs.push({ address: this.opts.changeAddress, amount: change });
     }
     if (this.opts.bip69) {
@@ -634,8 +730,22 @@ export function selectUTXO(
   strategy: SelectionStrategy,
   opts: TArg<EstimatorOpts>
 ) {
+  aarray(inputs, 'inputs');
+  aarray(outputs, 'outputs');
+  validateObject(opts as Record<string, any>, {}, {}, 'opts');
+  astring(strategy, 'strategy');
   // Public wrapper defaults to BIP69 ordering and tx construction unless callers override them.
   const _opts = { createTx: true, bip69: true, ...(opts as EstimatorOpts) };
-  const est = new _Estimator(inputs as psbt.TransactionInputUpdate[], outputs as Output[], _opts);
+  let candidates = inputs as psbt.TransactionInputUpdate[];
+  if (_opts.filterTaproot !== undefined) {
+    candidates = filterTaproot(candidates, _opts.filterTaproot);
+    if (_opts.requiredInputs) {
+      const requiredInputs = filterTaproot(_opts.requiredInputs, _opts.filterTaproot);
+      if (requiredInputs.length !== _opts.requiredInputs.length)
+        throw new Error('filterTaproot: required input has no available Taproot path');
+      _opts.requiredInputs = requiredInputs;
+    }
+  }
+  const est = new _Estimator(candidates, outputs as Output[], _opts);
   return est.result(strategy);
 }