@scure/btc-signer 2.3.0 → 2.4.0

package/utils.d.ts

@@ -264,8 +264,22 @@ export declare function taprootTweakPrivKey(privKey: TArg<Bytes>, merkleRoot?: T
  * ```
  */
 export declare function taprootTweakPubkey(pubKey: TArg<Bytes>, h: TArg<Bytes>): TRet<[Bytes, number]>;
-/** Standard unspendable internal key used for script-only Taproot outputs. */
+/**
+ * Standard unspendable internal key used for script-only Taproot outputs.
+ * @deprecated Use {@link taprootNumsKey} to receive an owned copy.
+ */
 export declare const TAPROOT_UNSPENDABLE_KEY: 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 declare function taprootNumsKey(): TRet<Bytes>;
 /** Bitcoin network parameters. */
 export type BTC_NETWORK = {
     /** Human-readable prefix used by Bech32 and Bech32m addresses. */

package/utils.js

@@ -373,8 +373,27 @@ export function taprootTweakPubkey(pubKey, h) {
 // 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 = /* @__PURE__ */ (() => sha256(Point.BASE.toBytes(false)))();
+// 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 = /* @__PURE__ */ (() => sha256(Point.BASE.toBytes(false)))();
+/**
+ * Standard unspendable internal key used for script-only Taproot outputs.
+ * @deprecated Use {@link taprootNumsKey} to receive an owned copy.
+ */
+export const TAPROOT_UNSPENDABLE_KEY = /* @__PURE__ */ (() => Uint8Array.from(INTERNAL_TAPROOT_NUMS))();
+/**
+ * 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() {
+    return Uint8Array.from(INTERNAL_TAPROOT_NUMS);
+}
 /** Bitcoin mainnet network parameters. */
 export const NETWORK = /* @__PURE__ */ Object.freeze({
     bech32: 'bc',

package/utxo.d.ts

@@ -1,7 +1,7 @@
 import * as P from 'micro-packed';
 import * as psbt from './psbt.ts';
 import { Transaction, type TxOpts } from './transaction.ts';
-import { type Bytes, NETWORK, type TArg } from './utils.ts';
+import { type Bytes, NETWORK, type TArg, type TRet } from './utils.ts';
 /** Minimal output target accepted by the UTXO selector. */
 export type Output = {
     address: string;
@@ -17,6 +17,21 @@ export type Accumulated = {
     weight: number;
     total: bigint;
 } | undefined;
+/**
+ * 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 declare function filterTaproot(inputs: TArg<psbt.TransactionInputUpdate[]>, pubkeys: TArg<Bytes[]>): TRet<psbt.TransactionInputUpdate[]>;
 export declare const _cmpBig: (a: bigint, b: bigint) => 0 | 1 | -1;
 /** Options for fee estimation and UTXO selection. */
 export type EstimatorOpts = TxOpts & {
@@ -30,6 +45,8 @@ export type EstimatorOpts = TxOpts & {
     createTx?: boolean;
     requiredInputs?: psbt.TransactionInputUpdate[];
     allowSameUtxo?: boolean;
+    /** Filter Taproot candidate paths to those satisfiable by these Schnorr public keys. */
+    filterTaproot?: Bytes[];
 };
 type SortStrategy = 'Newest' | 'Oldest' | 'Smallest' | 'Biggest';
 type ExactStrategy = `exact${SortStrategy}`;
@@ -118,6 +135,25 @@ export declare class _Estimator {
             }>][] | undefined;
             tapInternalKey?: Bytes | undefined;
             tapMerkleRoot?: Bytes | undefined;
+            p2cKeyTweak?: [Bytes, Bytes][] | undefined;
+            musig2ParticipantPubkeys?: [Bytes, Bytes[]][] | undefined;
+            musig2PubNonce?: [TArg<{
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            }>, Bytes][] | undefined;
+            musig2PartialSig?: [TArg<{
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            }>, Bytes][] | undefined;
+            spEcdhShare?: [Bytes, Bytes][] | undefined;
+            spDleq?: [Bytes, Bytes][] | undefined;
+            spSpendBip32Derivation?: [Bytes, P.StructInput<{
+                fingerprint: number;
+                path: number[];
+            }>][] | undefined;
+            spTweak?: Bytes | undefined;
             proprietary?: [Bytes, Bytes][] | undefined;
         } & {
             unknown?: [P.UnwrapCoder<P.CoderType<P.StructInput<{
@@ -270,6 +306,74 @@ export declare class _Estimator {
             }])[]) | undefined;
             tapInternalKey?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
             tapMerkleRoot?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
+            p2cKeyTweak?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+            musig2ParticipantPubkeys?: ([Bytes, Bytes[]][] & ([Bytes, Bytes[]] & [Bytes & Uint8Array<ArrayBuffer>, Bytes[] & (Bytes & Uint8Array<ArrayBuffer>)[]])[]) | undefined;
+            musig2PubNonce?: ([TArg<{
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            }>, Bytes][] & ([TArg<{
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            }>, Bytes] & [({
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            } & {
+                participantPubkey: Bytes & Uint8Array<ArrayBuffer>;
+                aggregatePubkey: Bytes & Uint8Array<ArrayBuffer>;
+                leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
+            }) | ({
+                participantPubkey: TArg<Bytes>;
+                aggregatePubkey: TArg<Bytes>;
+                leafHash?: TArg<Bytes | undefined>;
+            } & {
+                participantPubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+                aggregatePubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+                leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>) | undefined;
+            }), Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+            musig2PartialSig?: ([TArg<{
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            }>, Bytes][] & ([TArg<{
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            }>, Bytes] & [({
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            } & {
+                participantPubkey: Bytes & Uint8Array<ArrayBuffer>;
+                aggregatePubkey: Bytes & Uint8Array<ArrayBuffer>;
+                leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
+            }) | ({
+                participantPubkey: TArg<Bytes>;
+                aggregatePubkey: TArg<Bytes>;
+                leafHash?: TArg<Bytes | undefined>;
+            } & {
+                participantPubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+                aggregatePubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+                leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>) | undefined;
+            }), Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+            spEcdhShare?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+            spDleq?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+            spSpendBip32Derivation?: ([Bytes, P.StructInput<{
+                fingerprint: number;
+                path: number[];
+            }>][] & ([Bytes, P.StructInput<{
+                fingerprint: number;
+                path: number[];
+            }>] & [Bytes & Uint8Array<ArrayBuffer>, {
+                path: number[];
+                fingerprint: number;
+            } & {} & {
+                path: number[] & number[];
+                fingerprint: number;
+            }])[]) | undefined;
+            spTweak?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
             proprietary?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
             unknown?: ([P.StructInput<{
                 type: number;
@@ -383,6 +487,25 @@ export declare function selectUTXO(inputs: TArg<psbt.TransactionInputUpdate[]>,
         }>][] | undefined;
         tapInternalKey?: Bytes | undefined;
         tapMerkleRoot?: Bytes | undefined;
+        p2cKeyTweak?: [Bytes, Bytes][] | undefined;
+        musig2ParticipantPubkeys?: [Bytes, Bytes[]][] | undefined;
+        musig2PubNonce?: [TArg<{
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        }>, Bytes][] | undefined;
+        musig2PartialSig?: [TArg<{
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        }>, Bytes][] | undefined;
+        spEcdhShare?: [Bytes, Bytes][] | undefined;
+        spDleq?: [Bytes, Bytes][] | undefined;
+        spSpendBip32Derivation?: [Bytes, P.StructInput<{
+            fingerprint: number;
+            path: number[];
+        }>][] | undefined;
+        spTweak?: Bytes | undefined;
         proprietary?: [Bytes, Bytes][] | undefined;
     } & {
         unknown?: [P.UnwrapCoder<P.CoderType<P.StructInput<{
@@ -535,6 +658,74 @@ export declare function selectUTXO(inputs: TArg<psbt.TransactionInputUpdate[]>,
         }])[]) | undefined;
         tapInternalKey?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
         tapMerkleRoot?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
+        p2cKeyTweak?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+        musig2ParticipantPubkeys?: ([Bytes, Bytes[]][] & ([Bytes, Bytes[]] & [Bytes & Uint8Array<ArrayBuffer>, Bytes[] & (Bytes & Uint8Array<ArrayBuffer>)[]])[]) | undefined;
+        musig2PubNonce?: ([TArg<{
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        }>, Bytes][] & ([TArg<{
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        }>, Bytes] & [({
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        } & {
+            participantPubkey: Bytes & Uint8Array<ArrayBuffer>;
+            aggregatePubkey: Bytes & Uint8Array<ArrayBuffer>;
+            leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
+        }) | ({
+            participantPubkey: TArg<Bytes>;
+            aggregatePubkey: TArg<Bytes>;
+            leafHash?: TArg<Bytes | undefined>;
+        } & {
+            participantPubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+            aggregatePubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+            leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>) | undefined;
+        }), Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+        musig2PartialSig?: ([TArg<{
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        }>, Bytes][] & ([TArg<{
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        }>, Bytes] & [({
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        } & {
+            participantPubkey: Bytes & Uint8Array<ArrayBuffer>;
+            aggregatePubkey: Bytes & Uint8Array<ArrayBuffer>;
+            leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
+        }) | ({
+            participantPubkey: TArg<Bytes>;
+            aggregatePubkey: TArg<Bytes>;
+            leafHash?: TArg<Bytes | undefined>;
+        } & {
+            participantPubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+            aggregatePubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+            leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>) | undefined;
+        }), Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+        spEcdhShare?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+        spDleq?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+        spSpendBip32Derivation?: ([Bytes, P.StructInput<{
+            fingerprint: number;
+            path: number[];
+        }>][] & ([Bytes, P.StructInput<{
+            fingerprint: number;
+            path: number[];
+        }>] & [Bytes & Uint8Array<ArrayBuffer>, {
+            path: number[];
+            fingerprint: number;
+        } & {} & {
+            path: number[] & number[];
+            fingerprint: number;
+        }])[]) | undefined;
+        spTweak?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
         proprietary?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
         unknown?: ([P.StructInput<{
             type: number;

package/utxo.js

@@ -1,81 +1,169 @@
 import { hex } from '@scure/base';
 import * as P from 'micro-packed';
-import { Address, OutScript, checkScript, tapLeafHash } from "./payment.js";
+import { Address, OutScript, _WitnessOutScript, checkScript, tapLeafHash, } from "./payment.js";
 import * as psbt from "./psbt.js";
-import { CompactSizeLen, Script } from "./script.js";
+import { CompactSizeLen, RawWitness, Script } from "./script.js";
 import { SignatureHash, Transaction, getInputType, getPrevOut, inputBeforeSign, normalizeInput, toVsize, } from "./transaction.js";
-import { abigint, aarray, astring, NETWORK, PubT, TAPROOT_UNSPENDABLE_KEY, compareBytes, equalBytes, isBytes, sha256, validatePubkey, validateObject, } from "./utils.js";
+import { abigint, aarray, astring, NETWORK, PubT, compareBytes, equalBytes, isBytes, sha256, taprootNumsKey, taprootTweakPubkey, validatePubkey, validateObject, } from "./utils.js";
 const encodeTapBlock = (item) => 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) => CompactSizeLen.encode(dataLen).length + dataLen;
+const tapLeafWitness = (leaf, sigSize, customScripts, pubkeys, unknownError = 'Finalize: Unknown tapLeafScript') => {
+    const [cb, _script] = leaf;
+    const _customScripts = customScripts;
+    // Last byte is version
+    const script = _script.slice(0, -1);
+    const ver = _script[_script.length - 1];
+    const outs = OutScript.decode(script);
+    const available = (pubkey) => !pubkeys || pubkeys.has(hex.encode(pubkey));
+    const empty = () => new Uint8Array(sigSize);
+    let signatures = [];
+    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;
+            }
+        });
+        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));
+        }
+        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)]);
+};
 function iterLeafs(tapLeafScript, sigSize, customScripts) {
     const _tapLeafScript = tapLeafScript;
     const _customScripts = customScripts;
     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);
-        let signatures = [];
-        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);
+    // 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;
+    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;
+}
+/**
+ * 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, pubkeys) {
+    aarray(inputs, 'inputs');
+    aarray(pubkeys, 'pubkeys');
+    const _inputs = inputs;
+    const _pubkeys = pubkeys;
+    const keys = new Set();
+    for (const pubkey of _pubkeys)
+        keys.add(hex.encode(validatePubkey(pubkey, PubT.schnorr)));
+    const res = [];
+    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).script);
+        if (prevScript.type !== 'tr') {
+            res.push(filtered);
+            continue;
         }
-        else if (outs.type === 'tr_ns') {
-            for (const _pub of outs.pubkeys)
-                signatures.push(empty());
+        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;
         }
-        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;
-                    }
-                });
-                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.
+        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;
 }
 function estimateInput(inputType, input, opts) {
     const _input = input;
@@ -85,13 +173,9 @@ function estimateInput(inputType, input, opts) {
     // 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) {
@@ -195,7 +279,7 @@ function getScript(o, opts = {}, network = NETWORK) {
     // Keep selector-only `createTx: false` flows aligned with the transaction/PSBT output boundary:
     // satoshi-denominated outputs are not allowed to go negative.
     abigint(_o.amount, 'output.amount');
-    if (script && !_opts.allowUnknownOutputs && OutScript.decode(script).type === 'unknown') {
+    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');
     }
     if (!_opts.disableScriptCheck)
@@ -217,6 +301,9 @@ export class _Estimator {
     outputs;
     opts;
     constructor(inputs, outputs, opts) {
+        // 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;
         this.outputs = outputs;
         this.opts = opts;
         // Zero-fee estimation is useful on regtest/in tests, but negative fee rates would make
@@ -273,7 +360,7 @@ export class _Estimator {
         }
         const inputKeys = new Set();
         this.normalizedInputs = allInputs.map((i) => {
-            const normalized = normalizeInput(i, undefined, undefined, opts.disableScriptCheck, opts.allowUnknown);
+            const normalized = normalizeInput(i, undefined, undefined, opts.disableScriptCheck, opts.unknown, opts.proprietary);
             inputBeforeSign(normalized); // check fields
             const key = `${hex.encode(normalized.txid)}:${normalized.index}`;
             if (!opts.allowSameUtxo && inputKeys.has(key))
@@ -557,6 +644,16 @@ export function selectUTXO(inputs, outputs, strategy, opts) {
     astring(strategy, 'strategy');
     // Public wrapper defaults to BIP69 ordering and tx construction unless callers override them.
     const _opts = { createTx: true, bip69: true, ...opts };
-    const est = new _Estimator(inputs, outputs, _opts);
+    let candidates = inputs;
+    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, _opts);
     return est.result(strategy);
 }