@scure/btc-signer 2.0.1 → 2.2.0

package/transaction.js

@@ -2,22 +2,110 @@ import { hex } from '@scure/base';
 import * as P from 'micro-packed';
 import { Address, OutScript, checkScript, tapLeafHash } from "./payment.js";
 import * as psbt from "./psbt.js";
-import { CompactSizeLen, RawOldTx, RawOutput, RawTx, RawWitness, Script, VarBytes, } from "./script.js";
+import { CompactSizeLen, OP, RawOldTx, RawInput, RawOutput, RawTx, RawWitness, Script, scriptPushLen, VarBytes, } from "./script.js";
 import * as u from "./utils.js";
-import { NETWORK, concatBytes, equalBytes, isBytes } from "./utils.js";
-const EMPTY32 = new Uint8Array(32);
+import { NETWORK, concatBytes, equalBytes, isBytes, } from "./utils.js";
+const EMPTY32 = /* @__PURE__ */ new Uint8Array(32);
 const EMPTY_OUTPUT = {
     amount: 0xffffffffffffffffn,
     script: P.EMPTY,
 };
+/**
+ * Converts transaction weight units into virtual bytes.
+ * @param weight - transaction weight
+ * @returns Rounded-up virtual size.
+ * @example
+ * Convert transaction weight units into virtual bytes.
+ * ```ts
+ * toVsize(4);
+ * ```
+ */
 export const toVsize = (weight) => Math.ceil(weight / 4);
+const stripCodeSeparator = (script) => {
+    // Reuse Script's raw pushdata-length parser here. Legacy sighash must remove
+    // only actual OP_CODESEPARATOR opcodes while preserving every other original
+    // byte, because semantic decode/re-encode would change the signed digest.
+    let start = 0;
+    const out = [];
+    for (let i = 0; i < script.length;) {
+        const pos = i;
+        const op = script[i++];
+        if (op === OP.CODESEPARATOR) {
+            if (start < pos)
+                out.push(script.subarray(start, pos));
+            start = i;
+            continue;
+        }
+        const len = scriptPushLen(op, (bytes) => {
+            if (i + bytes > script.length)
+                throw new Error('Unexpected end of script');
+            let len = 0;
+            for (let j = 0; j < bytes; j++)
+                len |= script[i + j] << (8 * j);
+            i += bytes;
+            return len;
+        });
+        if (len === undefined)
+            continue;
+        i += len;
+        if (i > script.length)
+            throw new Error('Unexpected end of script');
+    }
+    if (start === 0)
+        return script;
+    if (start < script.length)
+        out.push(script.subarray(start));
+    return (out.length ? concatBytes(...out) : P.EMPTY);
+};
+/** Decimal precision used for BTC string formatting. */
 export const PRECISION = 8;
+/** Default transaction version used for newly created transactions. */
 export const DEFAULT_VERSION = 2;
+/** Default transaction locktime. */
 export const DEFAULT_LOCKTIME = 0;
+/** Default input sequence number.
+ * Final (`0xffffffff`): matches the PSBT omission default and disables nLockTime/CLTV semantics
+ * unless callers choose a lower sequence explicitly (for example `0xfffffffe` with lockTime).
+ */
 export const DEFAULT_SEQUENCE = 4294967295;
-export const Decimal = P.coders.decimal(PRECISION);
+/**
+ * Decimal coder for BTC-denominated strings.
+ * This is a fixed-precision BTC-string to satoshi-bigint helper, not a validator
+ * for transaction/PSBT output amounts. Signed values are intentional here, so
+ * callers can reuse the helper for display/history-style deltas as well as
+ * unsigned transfer amounts. It keeps the BTC scale at 8 fractional digits and
+ * rejects over-precise inputs instead of rounding.
+ * @example
+ * Convert between satoshi bigint values and BTC-denominated decimal strings.
+ * ```ts
+ * Decimal.encode(1n);
+ * ```
+ */
+export const Decimal = /* @__PURE__ */ (() => Object.freeze(P.coders.decimal(PRECISION)))();
 // Same as value || def, but doesn't overwrites zero ('0', 0, 0n, etc)
+/**
+ * Returns a fallback only when the value is `undefined`.
+ * @param value - optional value
+ * @param def - fallback value
+ * @returns `value` when defined, otherwise `def`.
+ * @example
+ * Keep zero-like values but replace `undefined` with a fallback.
+ * ```ts
+ * def(undefined, 1);
+ * ```
+ */
 export const def = (value, def) => (value === undefined ? def : value);
+/**
+ * Deep-clones plain transaction data structures.
+ * @param obj - value to clone
+ * @returns Deep copy of the input value.
+ * @throws If the value contains an unsupported runtime type. {@link Error}
+ * @example
+ * Clone plain transaction data structures before mutating them.
+ * ```ts
+ * cloneDeep({ a: [new Uint8Array([1])] });
+ * ```
+ */
 export function cloneDeep(obj) {
     if (Array.isArray(obj))
         return obj.map((i) => cloneDeep(i));
@@ -34,30 +122,48 @@ export function cloneDeep(obj) {
     else if (typeof obj === 'object') {
         return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, cloneDeep(v)]));
     }
-    throw new Error(`cloneDeep: unknown type=${obj} (${typeof obj})`);
+    // Don't interpolate unsupported values here: Symbol string coercion would
+    // throw before cloneDeep can surface its own stable helper error.
+    throw new Error(`cloneDeep: unknown type=${typeof obj}`);
 }
 /**
  * Internal, exported only for backwards-compat. Use `SigHash` instead.
- * @deprecated
+ * @deprecated Use {@link SigHash} instead.
+ * @example
+ * Combine the legacy bit flags when interoperating with older code.
+ * ```ts
+ * SignatureHash.ALL | SignatureHash.ANYONECANPAY;
+ * ```
  */
-export const SignatureHash = {
+export const SignatureHash = /* @__PURE__ */ (() => Object.freeze({
     DEFAULT: 0,
     ALL: 1,
     NONE: 2,
     SINGLE: 3,
     ANYONECANPAY: 0x80,
-};
-export const SigHash = {
+}))();
+/**
+ * Common signature hash flag combinations.
+ * @example
+ * Use the predefined signature-hash combinations exported by the library.
+ * ```ts
+ * SigHash.SINGLE_ANYONECANPAY;
+ * ```
+ */
+export const SigHash = /* @__PURE__ */ (() => Object.freeze({
     DEFAULT: SignatureHash.DEFAULT,
     ALL: SignatureHash.ALL,
     NONE: SignatureHash.NONE,
     SINGLE: SignatureHash.SINGLE,
-    DEFAULT_ANYONECANPAY: SignatureHash.DEFAULT | SignatureHash.ANYONECANPAY,
+    // BIP341 only permits 0x00, 0x01, 0x02, 0x03, 0x81, 0x82, and 0x83 for taproot, so
+    // the mechanical `DEFAULT | ANYONECANPAY` combination (0x80) is invalid and not exported.
+    // DEFAULT_ANYONECANPAY: SignatureHash.DEFAULT | SignatureHash.ANYONECANPAY,
     ALL_ANYONECANPAY: SignatureHash.ALL | SignatureHash.ANYONECANPAY,
     NONE_ANYONECANPAY: SignatureHash.NONE | SignatureHash.ANYONECANPAY,
     SINGLE_ANYONECANPAY: SignatureHash.SINGLE | SignatureHash.ANYONECANPAY,
-};
-export const SigHashNames = u.reverseObject(SigHash);
+}))();
+/** Reverse lookup table for signature hash flag names. */
+export const SigHashNames = /* @__PURE__ */ (() => Object.freeze(u.reverseObject(SigHash)))();
 function getTaprootKeys(privKey, pubKey, internalKey, merkleRoot = P.EMPTY) {
     if (equalBytes(internalKey, pubKey)) {
         privKey = u.taprootTweakPrivKey(privKey, merkleRoot);
@@ -72,25 +178,49 @@ function outputBeforeSign(i) {
     return { script: i.script, amount: i.amount };
 }
 // Force check index/txid/sequence
+/**
+ * Normalizes a PSBT input into the fields needed for signing.
+ * @param i - PSBT input to validate
+ * @returns Input fields required for signing.
+ * @throws If the input is missing `txid` or `index`. {@link Error}
+ * @example
+ * Fill in defaults for the fields the signer expects to see.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { inputBeforeSign } from '@scure/btc-signer/transaction.js';
+ * inputBeforeSign({
+ *   txid: hex.decode('0000000000000000000000000000000000000000000000000000000000000001'),
+ *   index: 0,
+ * });
+ * ```
+ */
 export function inputBeforeSign(i) {
     if (i.txid === undefined || i.index === undefined)
         throw new Error('Transaction/input: txid and index required');
-    return {
+    const res = {
         txid: i.txid,
         index: i.index,
         sequence: def(i.sequence, DEFAULT_SEQUENCE),
         finalScriptSig: def(i.finalScriptSig, P.EMPTY),
     };
+    // This helper is the public "normalize for signing" boundary, so reuse RawInput's existing
+    // wire-shape checks here instead of letting malformed runtime field types fail much later.
+    RawInput.encode(res);
+    return res;
 }
 function cleanFinalInput(i) {
-    for (const _k in i) {
+    const _i = i;
+    // BIP174 finalizers clear non-final input metadata after constructing final scripts/witnesses.
+    // That intentionally drops sighashType here, so post-finalize mutation becomes conservative
+    // until callers explicitly reopen the input by removing finalScriptSig/finalScriptWitness.
+    for (const _k in _i) {
         const k = _k;
         if (!psbt.PSBTInputFinalKeys.includes(k))
-            delete i[k];
+            delete _i[k];
     }
 }
 // (TxHash, Idx)
-const TxHashIdx = P.struct({ txid: P.bytes(32, true), index: P.U32LE });
+const TxHashIdx = /* @__PURE__ */ (() => P.struct({ txid: P.bytes(32, true), index: P.U32LE }))();
 function validateSigHash(s) {
     if (typeof s !== 'number' || typeof SigHashNames[s] !== 'string')
         throw new Error(`Invalid SigHash=${s}`);
@@ -114,10 +244,12 @@ function validateOpts(opts) {
         lockTime: def(opts.lockTime, 0),
         PSBTVersion: def(opts.PSBTVersion, 0),
     };
+    // Normalize deprecated aliases on the owned copy so they still affect tx.opts without rewriting the
+    // caller-owned options object passed to the constructor.
     if (typeof _opts.allowUnknowInput !== 'undefined')
-        opts.allowUnknownInputs = _opts.allowUnknowInput;
+        _opts.allowUnknownInputs = _opts.allowUnknowInput;
     if (typeof _opts.allowUnknowOutput !== 'undefined')
-        opts.allowUnknownOutputs = _opts.allowUnknowOutput;
+        _opts.allowUnknownOutputs = _opts.allowUnknowOutput;
     if (typeof _opts.lockTime !== 'number')
         throw new Error('Transaction lock time should be number');
     P.U32LE.encode(_opts.lockTime); // Additional range checks that lockTime
@@ -162,17 +294,19 @@ function validateOpts(opts) {
 }
 // NOTE: we cannot do this inside PSBTInput coder, because there is no index/txid at this point!
 function validateInput(i) {
-    if (i.nonWitnessUtxo && i.index !== undefined) {
-        const last = i.nonWitnessUtxo.outputs.length - 1;
-        if (i.index > last)
-            throw new Error(`validateInput: index(${i.index}) not in nonWitnessUtxo`);
-        const prevOut = i.nonWitnessUtxo.outputs[i.index];
-        if (i.witnessUtxo &&
-            (!equalBytes(i.witnessUtxo.script, prevOut.script) || i.witnessUtxo.amount !== prevOut.amount))
+    const _i = i;
+    if (_i.nonWitnessUtxo && _i.index !== undefined) {
+        const last = _i.nonWitnessUtxo.outputs.length - 1;
+        if (_i.index > last)
+            throw new Error(`validateInput: index(${_i.index}) not in nonWitnessUtxo`);
+        const prevOut = _i.nonWitnessUtxo.outputs[_i.index];
+        if (_i.witnessUtxo &&
+            (!equalBytes(_i.witnessUtxo.script, prevOut.script) ||
+                _i.witnessUtxo.amount !== prevOut.amount))
             throw new Error('validateInput: witnessUtxo different from nonWitnessUtxo');
-        if (i.txid) {
-            const outputs = i.nonWitnessUtxo.outputs;
-            if (outputs.length - 1 < i.index)
+        if (_i.txid) {
+            const outputs = _i.nonWitnessUtxo.outputs;
+            if (outputs.length - 1 < _i.index)
                 throw new Error('nonWitnessUtxo: incorect output index');
             // At this point, we are using previous tx output to create new input.
             // Script safety checks are unnecessary:
@@ -182,33 +316,80 @@ function validateInput(i) {
             //   in case user wants to use wrong input by mistake
             // - Worst case: tx will be rejected by nodes. Still better than disallowing user
             //   to spend real input, no matter how broken it looks
-            const tx = Transaction.fromRaw(RawTx.encode(i.nonWitnessUtxo), {
+            const tx = Transaction.fromRaw(RawTx.encode(_i.nonWitnessUtxo), {
                 allowUnknownOutputs: true,
                 disableScriptCheck: true,
                 allowUnknownInputs: true,
             });
-            const txid = hex.encode(i.txid);
-            // PSBTv2 vectors have non-final tx in inputs
-            if (tx.isFinal && tx.id !== txid)
+            const txid = hex.encode(_i.txid);
+            // BIP174 requires the provided nonWitnessUtxo to hash to the prevout txid even when the
+            // previous transaction is otherwise non-final; finality does not make its serialized txid optional.
+            // Keep the historical TransactionInput.txid convention here: internal txid bytes match
+            // `Transaction.id` (display-order hex), while raw-tx / PSBT boundary coders are responsible
+            // for any byte-order conversions required by their wire formats.
+            if (tx.id !== txid)
                 throw new Error(`nonWitnessUtxo: wrong txid, exp=${txid} got=${tx.id}`);
         }
     }
-    return i;
+    return _i;
 }
 // Normalizes input
+/**
+ * Extracts the previous output referenced by an input.
+ * @param input - PSBT input with previous output data
+ * @returns Previous output information.
+ * @throws If the input does not contain usable previous-output information. {@link Error}
+ * @example
+ * Read the previous output from either `witnessUtxo` or `nonWitnessUtxo`.
+ * ```ts
+ * getPrevOut({ witnessUtxo: { amount: 1n, script: new Uint8Array([0x51]) } });
+ * ```
+ */
 export function getPrevOut(input) {
-    if (input.nonWitnessUtxo) {
-        if (input.index === undefined)
+    const _input = input;
+    if (_input.nonWitnessUtxo) {
+        if (_input.index === undefined)
             throw new Error('Unknown input index');
-        return input.nonWitnessUtxo.outputs[input.index];
+        // BIP174 `PSBT_IN_NON_WITNESS_UTXO` is the full spent transaction, so the
+        // input outpoint index must name an existing output instead of leaking a
+        // synthetic `undefined` prevout into later signing / estimation callers.
+        if (!Number.isSafeInteger(_input.index) ||
+            _input.index < 0 ||
+            _input.index >= _input.nonWitnessUtxo.outputs.length)
+            throw new Error(`Wrong input index=${_input.index}`);
+        return _input.nonWitnessUtxo.outputs[_input.index];
     }
-    else if (input.witnessUtxo)
-        return input.witnessUtxo;
+    else if (_input.witnessUtxo)
+        return _input.witnessUtxo;
     else
         throw new Error('Cannot find previous output info');
 }
+/**
+ * Normalizes a transaction input update into canonical PSBT form.
+ * @param i - input update to normalize
+ * @param cur - existing input value to merge with
+ * @param allowedFields - fields that may still change on signed inputs
+ * @param disableScriptCheck - whether to skip redeem/witness script sanity checks
+ * @param allowUnknown - whether to keep unknown PSBT fields
+ * @returns Normalized PSBT input.
+ * @example
+ * Accept hex txids from callers in the same display-order form used by `Transaction.id`, then
+ * normalize them into the repo's internal `TransactionInput` shape.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { normalizeInput } from '@scure/btc-signer/transaction.js';
+ * normalizeInput({
+ *   txid: '0000000000000000000000000000000000000000000000000000000000000001',
+ *   index: 0,
+ *   witnessUtxo: { amount: 1n, script: new Uint8Array([0x51]) },
+ * });
+ * ```
+ */
 export function normalizeInput(i, cur, allowedFields, disableScriptCheck = false, allowUnknown = false) {
-    let { nonWitnessUtxo, txid } = i;
+    const _i = i;
+    const _cur = cur;
+    const _allowedFields = allowedFields;
+    let { nonWitnessUtxo, txid } = _i;
     // String support for common fields. We usually prefer Uint8Array to avoid errors
     // like hex looking string accidentally passed, however, in case of nonWitnessUtxo
     // it is better to expect string, since constructing this complex object will be
@@ -217,21 +398,23 @@ export function normalizeInput(i, cur, allowedFields, disableScriptCheck = false
         nonWitnessUtxo = hex.decode(nonWitnessUtxo);
     if (isBytes(nonWitnessUtxo))
         nonWitnessUtxo = RawTx.decode(nonWitnessUtxo);
-    if (!('nonWitnessUtxo' in i) && nonWitnessUtxo === undefined)
-        nonWitnessUtxo = cur?.nonWitnessUtxo;
+    if (!('nonWitnessUtxo' in _i) && nonWitnessUtxo === undefined)
+        nonWitnessUtxo = _cur?.nonWitnessUtxo;
     if (typeof txid === 'string')
         txid = hex.decode(txid);
     // TODO: if we have nonWitnessUtxo, we can extract txId from here
     if (txid === undefined)
-        txid = cur?.txid;
-    let res = { ...cur, ...i, nonWitnessUtxo, txid };
-    if (!('nonWitnessUtxo' in i) && res.nonWitnessUtxo === undefined)
+        txid = _cur?.txid;
+    let res = { ..._cur, ..._i, nonWitnessUtxo, txid };
+    if (!('nonWitnessUtxo' in _i) && res.nonWitnessUtxo === undefined)
         delete res.nonWitnessUtxo;
     if (res.sequence === undefined)
         res.sequence = DEFAULT_SEQUENCE;
     if (res.tapMerkleRoot === null)
         delete res.tapMerkleRoot;
-    res = psbt.mergeKeyMap(psbt.PSBTInput, res, cur, allowedFields, allowUnknown);
+    res = psbt.mergeKeyMap(psbt.PSBTInput, res, _cur, _allowedFields, allowUnknown);
+    // Public PSBT coder surface is wrapped with TArg/TRet for TS compatibility; normalizeInput keeps
+    // the repo's historical raw internal shape and casts only at the validation boundary here.
     psbt.PSBTInputCoder.encode(res); // Validates that everything is correct at this point
     let prevOut;
     if (res.nonWitnessUtxo && res.index !== undefined)
@@ -242,15 +425,42 @@ export function normalizeInput(i, cur, allowedFields, disableScriptCheck = false
         checkScript(prevOut && prevOut.script, res.redeemScript, res.witnessScript);
     return res;
 }
+/**
+ * Determines how an input should be signed and finalized.
+ * Wrapper consistency is expected to be validated earlier by {@link normalizeInput}
+ * and {@link checkScript}; this helper classifies already-normalized inputs and is
+ * not a standalone redeemScript/witnessScript correctness gate for raw caller input.
+ * @param input - PSBT input to inspect
+ * @param allowLegacyWitnessUtxo - whether legacy inputs may rely on witness UTXO data only
+ * @returns Input classification including transaction type and sighash defaults.
+ * @throws If a documented runtime validation or state check fails. {@link Error}
+ * @example
+ * Detect how the signer should treat a SegWit input from its previous output script.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { p2wpkh } from '@scure/btc-signer/payment.js';
+ * import { getInputType } from '@scure/btc-signer/transaction.js';
+ * import { pubECDSA, randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * getInputType({
+ *   witnessUtxo: {
+ *     amount: 1n,
+ *     script: p2wpkh(pubECDSA(randomPrivateKeyBytes())).script,
+ *   },
+ * });
+ * ```
+ */
 export function getInputType(input, allowLegacyWitnessUtxo = false) {
+    const _input = input;
     let txType = 'legacy';
     let defaultSighash = SignatureHash.ALL;
-    const prevOut = getPrevOut(input);
+    const prevOut = getPrevOut(_input);
     const first = OutScript.decode(prevOut.script);
     let type = first.type;
     let cur = first;
     const stack = [first];
     if (first.type === 'tr') {
+        // Expected invariant: taproot inputs use PSBT_IN_TAP_* metadata only;
+        // legacy redeemScript/witnessScript fields belong to P2SH/P2WSH paths.
         defaultSighash = SignatureHash.DEFAULT;
         return {
             txType: 'taproot',
@@ -258,16 +468,16 @@ export function getInputType(input, allowLegacyWitnessUtxo = false) {
             last: first,
             lastScript: prevOut.script,
             defaultSighash,
-            sighash: input.sighashType || defaultSighash,
+            sighash: _input.sighashType || defaultSighash,
         };
     }
     else {
         if (first.type === 'wpkh' || first.type === 'wsh')
             txType = 'segwit';
         if (first.type === 'sh') {
-            if (!input.redeemScript)
+            if (!_input.redeemScript)
                 throw new Error('inputType: sh without redeemScript');
-            let child = OutScript.decode(input.redeemScript);
+            let child = OutScript.decode(_input.redeemScript);
             if (child.type === 'wpkh' || child.type === 'wsh')
                 txType = 'segwit';
             stack.push(child);
@@ -276,9 +486,9 @@ export function getInputType(input, allowLegacyWitnessUtxo = false) {
         }
         // wsh can be inside sh
         if (cur.type === 'wsh') {
-            if (!input.witnessScript)
+            if (!_input.witnessScript)
                 throw new Error('inputType: wsh without witnessScript');
-            let child = OutScript.decode(input.witnessScript);
+            let child = OutScript.decode(_input.witnessScript);
             if (child.type === 'wsh')
                 txType = 'segwit';
             stack.push(child);
@@ -295,14 +505,35 @@ export function getInputType(input, allowLegacyWitnessUtxo = false) {
             last,
             lastScript,
             defaultSighash,
-            sighash: input.sighashType || defaultSighash,
+            sighash: _input.sighashType || defaultSighash,
         };
-        if (txType === 'legacy' && !allowLegacyWitnessUtxo && !input.nonWitnessUtxo) {
+        if (txType === 'legacy' && !allowLegacyWitnessUtxo && !_input.nonWitnessUtxo) {
             throw new Error(`Transaction/sign: legacy input without nonWitnessUtxo, can result in attack that forces paying higher fees. Pass allowLegacyWitnessUtxo=true, if you sure`);
         }
         return res;
     }
 }
+/**
+ * Mutable Bitcoin transaction and PSBT helper.
+ * @param opts - Transaction construction and PSBT serialization options. See {@link TxOpts}.
+ * @example
+ * Create a transaction, add one spend, and export it as PSBT.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { p2wpkh } from '@scure/btc-signer/payment.js';
+ * import { Transaction } from '@scure/btc-signer/transaction.js';
+ * import { pubECDSA, randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * const spend = p2wpkh(pubECDSA(randomPrivateKeyBytes()));
+ * const tx = new Transaction();
+ * tx.addInput({
+ *   txid: hex.decode('0000000000000000000000000000000000000000000000000000000000000001'),
+ *   index: 0,
+ *   witnessUtxo: { amount: 2n, script: spend.script },
+ * });
+ * tx.addOutput({ script: spend.script, amount: 1n });
+ * tx.toPSBT();
+ * ```
+ */
 export class Transaction {
     global = {};
     inputs = []; // use getInput()
@@ -368,7 +599,9 @@ export class Transaction {
             tx.global.fallbackLocktime = lockTime;
         return tx;
     }
-    toPSBT(PSBTVersion = this.opts.PSBTVersion) {
+    // Prefer `global.version` when present so cross-version combiners can serialize at the highest
+    // required PSBT version without mutating the frozen transaction options object.
+    toPSBT(PSBTVersion = this.global.version || this.opts.PSBTVersion) {
         if (PSBTVersion !== 0 && PSBTVersion !== 2)
             throw new Error(`Wrong PSBT version=${PSBTVersion}`);
         // if (PSBTVersion === 0 && this.inputs.length === 0) {
@@ -376,7 +609,10 @@ export class Transaction {
         //     'PSBT version=0 export for transaction without inputs disabled, please use version=2. Please check `toPSBT` method for explanation.'
         //   );
         // }
-        const inputs = this.inputs.map((i) => validateInput(psbt.cleanPSBTFields(PSBTVersion, psbt.PSBTInput, i)));
+        const inputs = this.inputs.map((i) => 
+        // For PSBTv0 the prevout txid/index live in global.unsignedTx rather than the input map, so
+        // validate the full transaction input before version filtering drops those fields.
+        psbt.cleanPSBTFields(PSBTVersion, psbt.PSBTInput, validateInput(i)));
         for (const inp of inputs) {
             // Don't serialize empty fields
             if (inp.partialSig && !inp.partialSig.length)
@@ -398,16 +634,28 @@ export class Transaction {
             global.unsignedTx = RawOldTx.decode(RawOldTx.encode({
                 version: this.version,
                 lockTime: this.lockTime,
-                inputs: this.inputs.map(inputBeforeSign).map((i) => ({
+                inputs: this.inputs
+                    .map((i) => inputBeforeSign(i))
+                    .map((i) => ({
                     ...i,
                     finalScriptSig: P.EMPTY,
                 })),
-                outputs: this.outputs.map(outputBeforeSign),
+                outputs: this.outputs.map((o) => outputBeforeSign(o)),
             }));
             delete global.fallbackLocktime;
             delete global.txVersion;
+            // PSBTv0 carries the unsigned transaction as one blob, so the PSBTv2 framing fields must be
+            // removed here. Keeping `global.version` would make validation treat this rebuilt v0 map as
+            // PSBTv2 and reject the required `unsignedTx` field.
+            delete global.inputCount;
+            delete global.outputCount;
+            delete global.version;
         }
         else {
+            // Cross-version merges and v0->v2 re-exports can still carry the PSBTv0 unsignedTx blob in
+            // `this.global`, but PSBTv2 serializes the transaction through split global/input/output
+            // fields instead, so drop the stale v0-only field before PSBTv2 validation/encoding.
+            delete global.unsignedTx;
             global.version = PSBTVersion;
             global.txVersion = this.version;
             global.inputCount = this.inputs.length;
@@ -421,11 +669,10 @@ export class Transaction {
             if (!outputs.length)
                 outputs.push({});
         }
-        return (PSBTVersion === 0 ? psbt.RawPSBTV0 : psbt.RawPSBTV2).encode({
-            global,
-            inputs,
-            outputs,
-        });
+        const raw = { global, inputs, outputs };
+        return PSBTVersion === 0
+            ? psbt.RawPSBTV0.encode(raw)
+            : psbt.RawPSBTV2.encode(raw);
     }
     // BIP370 lockTime (https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki#determining-lock-time)
     get lockTime() {
@@ -549,8 +796,10 @@ export class Transaction {
         out += 4 * CompactSizeLen.encode(this.inputs.length).length;
         for (const i of this.inputs) {
             out += 160 + 4 * VarBytes.encode(i.finalScriptSig || P.EMPTY).length;
-            if (this.hasWitnesses && i.finalScriptWitness)
-                out += RawWitness.encode(i.finalScriptWitness).length;
+            // Once segwit serialization is active, every input contributes one witness vector, including
+            // legacy inputs whose empty vector still encodes as a single zero-item-count byte.
+            if (this.hasWitnesses)
+                out += RawWitness.encode(i.finalScriptWitness || []).length;
         }
         return out;
     }
@@ -598,7 +847,9 @@ export class Transaction {
     addInput(input, _ignoreSignStatus = false) {
         if (!_ignoreSignStatus && !this.signStatus().addInput)
             throw new Error('Tx has signed inputs, cannot add new one');
-        this.inputs.push(normalizeInput(input, undefined, undefined, this.opts.disableScriptCheck));
+        // normalizeInput preserves nested caller-owned byte arrays, so detach them here before the
+        // new input becomes transaction state and later caller mutation can rewrite it by aliasing.
+        this.inputs.push(cloneDeep(normalizeInput(input, undefined, undefined, this.opts.disableScriptCheck)));
         return this.inputs.length - 1;
     }
     updateInput(idx, input, _ignoreSignStatus = false) {
@@ -609,7 +860,9 @@ export class Transaction {
             if (!status.addInput || status.inputs.includes(idx))
                 allowedFields = psbt.PSBTInputUnsignedKeys;
         }
-        this.inputs[idx] = normalizeInput(input, this.inputs[idx], allowedFields, this.opts.disableScriptCheck, this.opts.allowUnknown);
+        // normalizeInput preserves nested caller-owned byte arrays, so detach the merged result here
+        // before the updated input becomes transaction state and later caller mutation can rewrite it.
+        this.inputs[idx] = cloneDeep(normalizeInput(input, this.inputs[idx], allowedFields, this.opts.disableScriptCheck, this.opts.allowUnknown));
     }
     // Output stuff
     checkOutputIdx(idx) {
@@ -656,7 +909,9 @@ export class Transaction {
     addOutput(o, _ignoreSignStatus = false) {
         if (!_ignoreSignStatus && !this.signStatus().addOutput)
             throw new Error('Tx has signed outputs, cannot add new one');
-        this.outputs.push(this.normalizeOutput(o));
+        // normalizeOutput preserves nested caller-owned script bytes, so detach them here before the
+        // new output becomes transaction state and later caller mutation can rewrite it by aliasing.
+        this.outputs.push(cloneDeep(this.normalizeOutput(o)));
         return this.outputs.length - 1;
     }
     updateOutput(idx, output, _ignoreSignStatus = false) {
@@ -667,10 +922,17 @@ export class Transaction {
             if (!status.addOutput || status.outputs.includes(idx))
                 allowedFields = psbt.PSBTOutputUnsignedKeys;
         }
-        this.outputs[idx] = this.normalizeOutput(output, this.outputs[idx], allowedFields);
+        // updateOutput replaces stored state with normalizeOutput(...) directly, so detach the result
+        // before storing it or later caller mutation of `output.script` will rewrite transaction state.
+        this.outputs[idx] = cloneDeep(this.normalizeOutput(output, this.outputs[idx], allowedFields));
     }
     addOutputAddress(address, amount, network = NETWORK) {
-        return this.addOutput({ script: OutScript.encode(Address(network).decode(address)), amount });
+        return this.addOutput({
+            // Address.decode() only returns recognized descriptors here, but its wrapped output type
+            // still carries `undefined` for coder parity, so narrow before feeding OutScript.encode().
+            script: OutScript.encode(Address(network).decode(address)),
+            amount,
+        });
     }
     // Utils
     get fee() {
@@ -696,7 +958,7 @@ export class Transaction {
             throw new Error(`Invalid input idx=${idx}`);
         if ((isSingle && idx >= this.outputs.length) || idx >= this.inputs.length)
             return P.U256BE.encode(1n);
-        prevOutScript = Script.encode(Script.decode(prevOutScript).filter((i) => i !== 'CODESEPARATOR'));
+        prevOutScript = stripCodeSeparator(prevOutScript);
         let inputs = this.inputs
             .map(inputBeforeSign)
             .map((input, inputIdx) => ({
@@ -715,7 +977,10 @@ export class Transaction {
         if (isNone)
             outputs = [];
         else if (isSingle) {
-            outputs = outputs.slice(0, idx).fill(EMPTY_OUTPUT).concat([outputs[idx]]);
+            outputs = outputs
+                .slice(0, idx)
+                .fill(EMPTY_OUTPUT)
+                .concat([outputs[idx]]);
         }
         const tmpTx = RawTx.encode({
             lockTime: this.lockTime,
@@ -727,6 +992,10 @@ export class Transaction {
         return u.sha256x2(tmpTx, P.I32LE.encode(hashType));
     }
     preimageWitnessV0(idx, prevOutScript, hashType, amount) {
+        // BIP143 serializes txTo.vin[nIn].prevout and txTo.vin[nIn].nSequence, so reject an invalid
+        // nIn explicitly instead of leaking a later undefined-input TypeError from inputs[idx].
+        if (idx < 0 || !Number.isSafeInteger(idx) || idx >= this.inputs.length)
+            throw new Error(`Invalid input idx=${idx}`);
         const { isAny, isNone, isSingle } = unpackSighash(hashType);
         let inputHash = EMPTY32;
         let sequenceHash = EMPTY32;
@@ -750,6 +1019,11 @@ export class Transaction {
             throw new Error(`Invalid amounts array=${amount}`);
         if (!Array.isArray(prevOutScript) || this.inputs.length !== prevOutScript.length)
             throw new Error(`Invalid prevOutScript array=${prevOutScript}`);
+        // BIP341 SigMsg commits either to input_index or to the selected input's outpoint/amount/script/
+        // sequence under ANYONECANPAY, so reject an invalid index explicitly instead of hashing a
+        // nonexistent input or leaking a later integer-encoding RangeError for negative idx.
+        if (idx < 0 || !Number.isSafeInteger(idx) || idx >= this.inputs.length)
+            throw new Error(`Invalid input idx=${idx}`);
         const out = [
             P.U8.encode(0),
             P.U8.encode(hashType), // U8 sigHash
@@ -792,29 +1066,80 @@ export class Transaction {
         this.checkInputIdx(idx);
         const input = this.inputs[idx];
         const inputType = getInputType(input, this.opts.allowLegacyWitnessUtxo);
-        // Handle BIP32 HDKey
+        const canSign = (privateKey) => {
+            if (inputType.txType === 'taproot') {
+                const pubKey = u.pubSchnorr(privateKey);
+                if (input.tapInternalKey && equalBytes(pubKey, input.tapInternalKey))
+                    return true;
+                if (!input.tapLeafScript)
+                    return false;
+                for (const [_, leaf] of input.tapLeafScript) {
+                    for (const op of Script.decode(leaf.subarray(0, -1))) {
+                        if (isBytes(op) && equalBytes(op, pubKey))
+                            return true;
+                    }
+                }
+                return false;
+            }
+            const pubKey = u.pubECDSA(privateKey);
+            const pubKeyHash = u.hash160(pubKey);
+            for (const op of Script.decode(inputType.lastScript)) {
+                if (isBytes(op) && (equalBytes(op, pubKey) || equalBytes(op, pubKeyHash)))
+                    return true;
+            }
+            return false;
+        };
+        // Expected invariant: HD signing should use bip32Derivation for legacy/segwit inputs,
+        // tapBip32Derivation for taproot inputs, and preserve caller sighash/auxRand constraints.
         if (!isBytes(privateKey)) {
-            if (!input.bip32Derivation || !input.bip32Derivation.length)
-                throw new Error('bip32Derivation: empty');
-            const signers = input.bip32Derivation
-                .filter((i) => i[1].fingerprint == privateKey.fingerprint)
-                .map(([pubKey, { path }]) => {
-                let s = privateKey;
-                for (const i of path)
-                    s = s.deriveChild(i);
-                if (!equalBytes(s.publicKey, pubKey))
-                    throw new Error('bip32Derivation: wrong pubKey');
-                if (!s.privateKey)
-                    throw new Error('bip32Derivation: no privateKey');
-                return s;
-            });
-            if (!signers.length)
-                throw new Error(`bip32Derivation: no items with fingerprint=${privateKey.fingerprint}`);
+            const root = privateKey;
+            const deriveSigners = (label, rows, pubKey) => {
+                if (!rows || !rows.length)
+                    throw new Error(`${label}: empty`);
+                const signers = rows
+                    .filter((row) => row.fingerprint == root.fingerprint)
+                    .map((row) => {
+                    let s = root;
+                    for (const i of row.path)
+                        s = s.deriveChild(i);
+                    if (!equalBytes(pubKey(s), row.pubKey))
+                        throw new Error(`${label}: wrong pubKey`);
+                    if (!s.privateKey)
+                        throw new Error(`${label}: no privateKey`);
+                    return s;
+                });
+                if (!signers.length)
+                    throw new Error(`${label}: no items with fingerprint=${root.fingerprint}`);
+                return signers;
+            };
+            const signers = inputType.txType === 'taproot'
+                ? // BIP371 PSBT_IN_TAP_BIP32_DERIVATION stores x-only pubkeys plus `der`, so taproot HD
+                    // signing must derive against that map instead of legacy bip32Derivation.
+                    deriveSigners('tapBip32Derivation', input.tapBip32Derivation?.map(([pubKey, { der }]) => ({
+                        pubKey,
+                        fingerprint: der.fingerprint,
+                        path: der.path,
+                    })), (s) => s.publicKey.slice(1))
+                : deriveSigners('bip32Derivation', input.bip32Derivation?.map(([pubKey, der]) => ({
+                    pubKey,
+                    fingerprint: der.fingerprint,
+                    path: der.path,
+                })), (s) => s.publicKey);
             let signed = false;
-            for (const s of signers)
-                if (this.signIdx(s.privateKey, idx))
+            for (const s of signers) {
+                // PSBT may legitimately carry multiple same-fingerprint derivation entries (multisig or
+                // taproot internal/script-path keys). Skip unrelated derived children instead of aborting
+                // the whole HD signing attempt on the first non-applicable candidate.
+                if (!canSign(s.privateKey))
+                    continue;
+                if (this.signIdx(s.privateKey, idx, allowedSighash, _auxRand))
                     signed = true;
-            return signed;
+            }
+            if (signed)
+                return true;
+            if (inputType.txType === 'taproot')
+                throw new Error('No taproot scripts signed');
+            throw new Error(`Input script doesn't have pubKey: ${inputType.lastScript}`);
         }
         // Sighash checks
         // Just for compat with bitcoinjs-lib, so users won't face unexpected behaviour.
@@ -1013,7 +1338,7 @@ export class Transaction {
                                 if (!finalized)
                                     continue;
                                 input.finalScriptWitness = finalized.concat(psbt.TaprootControlBlock.encode(cb));
-                                input.finalScriptSig = P.EMPTY;
+                                delete input.finalScriptSig;
                                 cleanFinalInput(input);
                                 return;
                             }
@@ -1031,7 +1356,8 @@ export class Transaction {
             }
             else
                 throw new Error('finalize/taproot: unknown input');
-            input.finalScriptSig = P.EMPTY;
+            // BIP174 Input Finalizer: if scriptSig is empty for an input, 0x07 remains unset.
+            delete input.finalScriptSig;
             cleanFinalInput(input);
             return;
         }
@@ -1119,7 +1445,10 @@ export class Transaction {
         return this.toBytes(true, true);
     }
     combine(other) {
-        for (const k of ['PSBTVersion', 'version', 'lockTime']) {
+        // BIP174 combiners merge same-transaction PSBTs across versions and emit the highest required
+        // version, so PSBTVersion mismatches are normalized below instead of treated as conflicts.
+        const PSBTVersion = Math.max(this.opts.PSBTVersion || 0, other.opts.PSBTVersion || 0);
+        for (const k of ['version', 'lockTime']) {
             if (this.opts[k] !== other.opts[k]) {
                 throw new Error(`Transaction/combine: different ${k} this=${this.opts[k]} other=${other.opts[k]}`);
             }
@@ -1129,13 +1458,13 @@ export class Transaction {
                 throw new Error(`Transaction/combine: different ${k} length this=${this[k].length} other=${other[k].length}`);
             }
         }
-        const thisUnsigned = this.global.unsignedTx ? RawOldTx.encode(this.global.unsignedTx) : P.EMPTY;
-        const otherUnsigned = other.global.unsignedTx
-            ? RawOldTx.encode(other.global.unsignedTx)
-            : P.EMPTY;
-        if (!equalBytes(thisUnsigned, otherUnsigned))
+        // Same-transaction checks must compare the normalized unsigned tx bytes here: PSBTv0 stores
+        // `global.unsignedTx`, while PSBTv2 reconstructs the same transaction from split fields.
+        if (!equalBytes(this.unsignedTx, other.unsignedTx))
             throw new Error(`Transaction/combine: different unsigned tx`);
         this.global = psbt.mergeKeyMap(psbt.PSBTGlobal, this.global, other.global, undefined, this.opts.allowUnknown);
+        if (PSBTVersion)
+            this.global.version = PSBTVersion;
         for (let i = 0; i < this.inputs.length; i++)
             this.updateInput(i, other.inputs[i], true);
         for (let i = 0; i < this.outputs.length; i++)
@@ -1144,9 +1473,22 @@ export class Transaction {
     }
     clone() {
         // deepClone probably faster, but this enforces that encoding is valid
-        return Transaction.fromPSBT(this.toPSBT(this.opts.PSBTVersion), this.opts);
+        return Transaction.fromPSBT(this.toPSBT(), this.opts);
     }
 }
+/**
+ * Merges multiple PSBT blobs into one.
+ * @param psbts - PSBT byte arrays to combine
+ * @returns Combined PSBT bytes.
+ * @throws If the PSBT list is empty or the partial transactions cannot be combined. {@link Error}
+ * @example
+ * Merge separate partially signed PSBTs that share the same unsigned transaction.
+ * ```ts
+ * import { PSBTCombine, Transaction } from '@scure/btc-signer/transaction.js';
+ * const psbt = new Transaction().toPSBT();
+ * PSBTCombine([psbt, psbt]);
+ * ```
+ */
 export function PSBTCombine(psbts) {
     if (!psbts || !Array.isArray(psbts) || !psbts.length)
         throw new Error('PSBTCombine: wrong PSBT list');
@@ -1157,13 +1499,31 @@ export function PSBTCombine(psbts) {
 }
 // Copy-pasted from bip32 derive, maybe do something like 'bip32.parsePath'?
 const HARDENED_OFFSET = 0x80000000;
+/**
+ * Parses a BIP32 path string into child indices.
+ * @param path - derivation path such as `m/0'/1`
+ * @returns Array of encoded child indices.
+ * @throws If the derivation path syntax or child indices are invalid. {@link Error}
+ * @example
+ * Parse a BIP32 derivation path into hardened and unhardened indices.
+ * ```ts
+ * bip32Path("m/0'/1");
+ * ```
+ */
 export function bip32Path(path) {
     const out = [];
+    // PSBT key-origin records only carry raw child indices, so this convenience
+    // parser normalizes textual BIP32 roots into the same integer path array and
+    // uses apostrophe suffixes for hardening.
     if (!/^[mM]'?/.test(path))
         throw new Error('Path must start with "m" or "M"');
     if (/^[mM]'?$/.test(path))
         return out;
     const parts = path.replace(/^[mM]'?\//, '').split('/');
+    // BIP32 Serialization format `* 1 byte: depth`: extended keys cap depth at
+    // 255, so deeper text paths cannot roundtrip.
+    if (parts.length > 255)
+        throw new Error('Path depth exceeds 255');
     for (const c of parts) {
         const m = /^(\d+)('?)$/.exec(c);
         if (!m || m.length !== 3)