@scure/btc-signer 2.2.0 → 2.4.0

package/transaction.js

@@ -1,13 +1,18 @@
 import { hex } from '@scure/base';
+import { anumber } from '@noble/hashes/utils.js';
 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, 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";
+import { NETWORK, abigint, concatBytes, equalBytes, isBytes, validateObject, } from "./utils.js";
+// Be friendly to bad ECMAScript parsers by not using bigint literals.
+// prettier-ignore
+const _0n = /* @__PURE__ */ BigInt(0), _1n = /* @__PURE__ */ BigInt(1);
+const U64_MAX = /* @__PURE__ */ BigInt('0xffffffffffffffff');
 const EMPTY32 = /* @__PURE__ */ new Uint8Array(32);
 const EMPTY_OUTPUT = {
-    amount: 0xffffffffffffffffn,
+    amount: U64_MAX,
     script: P.EMPTY,
 };
 /**
@@ -195,6 +200,7 @@ function outputBeforeSign(i) {
  * ```
  */
 export function inputBeforeSign(i) {
+    validateObject(i, {}, {}, 'i');
     if (i.txid === undefined || i.index === undefined)
         throw new Error('Transaction/input: txid and index required');
     const res = {
@@ -208,13 +214,61 @@ export function inputBeforeSign(i) {
     RawInput.encode(res);
     return res;
 }
-function cleanFinalInput(i) {
+const cleanExtensions = (map, unknownMode, proprietaryMode, rejectStrip = false) => {
+    const out = { ...map };
+    for (const [name, mode] of [
+        ['unknown', unknownMode],
+        ['proprietary', proprietaryMode],
+    ]) {
+        const value = out[name];
+        // Policy cleanup must not reinterpret malformed caller metadata as an empty keyed map.
+        if (value !== undefined)
+            u.aarray(value, `${name} PSBT field`);
+        const rows = value;
+        if (!rows?.length) {
+            delete out[name];
+            continue;
+        }
+        if (mode === 'strict')
+            throw new Error(`PSBT: ${name} PSBT field is not allowed in strict mode`);
+        if (mode === 'strip') {
+            // Silent stripping is appropriate at relay/cleanup boundaries. On direct mutation it would
+            // hide a caller bug by accepting metadata that can never become transaction state.
+            if (rejectStrip)
+                throw new Error(`PSBT: ${name} PSBT field cannot be supplied when policy is strip`);
+            delete out[name];
+        }
+    }
+    return out;
+};
+const cleanTxModifiable = (value, mode) => {
+    if (value === undefined || !(value & ~0b111))
+        return value;
+    if (mode === 'strict')
+        throw new Error('PSBT: unknown txModifiable bits in strict mode');
+    return mode === 'strip' ? value & 0b111 : value;
+};
+function cleanFinalInput(i, unknownMode = 'strip', proprietaryMode = 'strip') {
     const _i = i;
+    const extensions = cleanExtensions(_i, unknownMode, proprietaryMode);
+    if (extensions.unknown)
+        _i.unknown = extensions.unknown;
+    else
+        delete _i.unknown;
+    if (extensions.proprietary)
+        _i.proprietary = extensions.proprietary;
+    else
+        delete _i.proprietary;
     // 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.
+    // until callers explicitly clear satisfaction by removing finalScriptSig/finalScriptWitness.
     for (const _k in _i) {
         const k = _k;
+        // Proprietary records are cleanup metadata too, but callers may need their opaque protocol
+        // state after finalization for PSBT coordination outside transaction extraction. An empty
+        // keyed list encodes no records, so canonicalize it to absence like its serialized clone.
+        if (proprietaryMode === 'ignore' && k === 'proprietary' && _i.proprietary?.length)
+            continue;
         if (!psbt.PSBTInputFinalKeys.includes(k))
             delete _i[k];
     }
@@ -234,9 +288,21 @@ function unpackSighash(hashType) {
         isSingle: masked === SignatureHash.SINGLE,
     };
 }
+const sighashScope = (sighash) => ({
+    sigInputs: sighash & SignatureHash.ANYONECANPAY,
+    sigOutputs: sighash === SignatureHash.DEFAULT ? SignatureHash.ALL : sighash & 0b11,
+});
+const normalizeUnknowns = (name, mode, legacy, fallback = 'strip') => {
+    const alias = legacy === undefined ? undefined : legacy ? 'ignore' : 'strip';
+    if (mode !== undefined && mode !== 'ignore' && mode !== 'strip' && mode !== 'strict')
+        throw new Error(`Transaction options wrong value: ${name}=${mode}`);
+    if (mode !== undefined && alias !== undefined && mode !== alias)
+        throw new Error(`Transaction options: conflicting ${name} options`);
+    return mode || alias || fallback;
+};
 function validateOpts(opts) {
-    if (opts !== undefined && {}.toString.call(opts) !== '[object Object]')
-        throw new Error(`Wrong object type for transaction options: ${opts}`);
+    if (opts !== undefined)
+        validateObject(opts, {}, {}, 'opts');
     const _opts = {
         ...opts,
         // Defaults
@@ -250,6 +316,8 @@ function validateOpts(opts) {
         _opts.allowUnknownInputs = _opts.allowUnknowInput;
     if (typeof _opts.allowUnknowOutput !== 'undefined')
         _opts.allowUnknownOutputs = _opts.allowUnknowOutput;
+    if (_opts.allowMissingTxModifiable === undefined)
+        _opts.allowMissingTxModifiable = true;
     if (typeof _opts.lockTime !== 'number')
         throw new Error('Transaction lock time should be number');
     P.U32LE.encode(_opts.lockTime); // Additional range checks that lockTime
@@ -265,7 +333,10 @@ function validateOpts(opts) {
         'disableScriptCheck',
         'bip174jsCompat',
         'allowLegacyWitnessUtxo',
+        'strictPrevoutValidation',
         'lowR',
+        'allowUnknown',
+        'allowMissingTxModifiable',
     ]) {
         const v = _opts[k];
         if (v === undefined)
@@ -273,11 +344,16 @@ function validateOpts(opts) {
         if (typeof v !== 'boolean')
             throw new Error(`Transation options wrong type: ${k}=${v} (${typeof v})`);
     }
+    _opts.unknown = normalizeUnknowns('unknown', _opts.unknown, _opts.allowUnknown);
+    _opts.proprietary = normalizeUnknowns('proprietary', _opts.proprietary, undefined, _opts.unknown);
     // 0 and -1 happens in tests
+    // With allowUnknownVersion any numeric version is fine; the ternary was inverted
+    // before 2026-07 (audit), which made the option throw for every numeric version.
     if (_opts.allowUnknownVersion
-        ? typeof _opts.version === 'number'
+        ? typeof _opts.version !== 'number'
         : ![-1, 0, 1, 2, 3].includes(_opts.version))
         throw new Error(`Unknown version: ${_opts.version}`);
+    P.I32LE.encode(_opts.version); // Validate the signed transaction-version wire domain.
     if (_opts.customScripts !== undefined) {
         const cs = _opts.customScripts;
         if (!Array.isArray(cs)) {
@@ -292,14 +368,105 @@ function validateOpts(opts) {
     }
     return Object.freeze(_opts);
 }
+function checkTaprootInputCommitments(input, prevScript) {
+    const output = _WitnessOutScript.decode(prevScript);
+    const hasTaprootCommitments = input.tapInternalKey !== undefined ||
+        input.tapMerkleRoot !== undefined ||
+        // Repeated keyed fields only exist on the PSBT wire when at least one entry is encoded.
+        !!input.tapLeafScript?.length;
+    if (output.type !== 'tr') {
+        if (hasTaprootCommitments)
+            throw new Error('validateInput: Taproot metadata without P2TR previous output');
+        return;
+    }
+    const checkOutputKey = (internalKey, merkleRoot, parity) => {
+        const [outputKey, outputParity] = u.taprootTweakPubkey(internalKey, merkleRoot);
+        if (!equalBytes(outputKey, output.pubkey))
+            throw new Error('validateInput: Taproot commitment does not match previous output');
+        if (parity !== undefined && outputParity !== parity)
+            throw new Error('validateInput: Taproot control-block parity does not match previous output');
+    };
+    if (input.tapLeafScript) {
+        for (const [controlBlock, scriptWithVersion] of input.tapLeafScript) {
+            const leafVersion = scriptWithVersion[scriptWithVersion.length - 1];
+            const script = scriptWithVersion.subarray(0, -1);
+            let merkleRoot = tapLeafHash(script, leafVersion);
+            for (const sibling of controlBlock.merklePath) {
+                merkleRoot =
+                    u.compareBytes(sibling, merkleRoot) === -1
+                        ? u.tagSchnorr('TapBranch', sibling, merkleRoot)
+                        : u.tagSchnorr('TapBranch', merkleRoot, sibling);
+            }
+            checkOutputKey(controlBlock.internalKey, merkleRoot, controlBlock.version & 1);
+            if (input.tapInternalKey && !equalBytes(input.tapInternalKey, controlBlock.internalKey))
+                throw new Error('validateInput: tapInternalKey does not match Taproot control block');
+            if (input.tapMerkleRoot && !equalBytes(input.tapMerkleRoot, merkleRoot))
+                throw new Error('validateInput: tapMerkleRoot does not match Taproot control block');
+        }
+    }
+    // A tree-bearing input can omit the aggregate root while still providing independently
+    // verifiable control blocks. With no leaves, an internal key without a root describes the
+    // standard key-only (empty-root) commitment.
+    if (input.tapInternalKey && (input.tapMerkleRoot || !input.tapLeafScript?.length))
+        checkOutputKey(input.tapInternalKey, input.tapMerkleRoot || P.EMPTY);
+}
+const LOCKTIME_THRESHOLD = 500_000_000;
+function validateRequiredLocktimes(input) {
+    const height = input.requiredHeightLocktime;
+    if (height !== undefined) {
+        anumber(height, 'requiredHeightLocktime');
+        if (height === 0 || height >= LOCKTIME_THRESHOLD)
+            throw new RangeError(`requiredHeightLocktime must be between 1 and ${LOCKTIME_THRESHOLD - 1}, got ${height}`);
+    }
+    const time = input.requiredTimeLocktime;
+    if (time !== undefined) {
+        anumber(time, 'requiredTimeLocktime');
+        if (time < LOCKTIME_THRESHOLD || time > 0xffffffff)
+            throw new RangeError(`requiredTimeLocktime must be between ${LOCKTIME_THRESHOLD} and 4294967295, got ${time}`);
+    }
+}
+function resolvePSBTLocktime(inputs, fallback = DEFAULT_LOCKTIME) {
+    let height = DEFAULT_LOCKTIME;
+    let time = DEFAULT_LOCKTIME;
+    let hasRequirements = false;
+    let heightSupported = true;
+    let timeSupported = true;
+    for (const input of inputs) {
+        validateRequiredLocktimes(input);
+        const hasHeight = input.requiredHeightLocktime !== undefined;
+        const hasTime = input.requiredTimeLocktime !== undefined;
+        if (!hasHeight && !hasTime)
+            continue;
+        hasRequirements = true;
+        if (hasHeight)
+            height = Math.max(height, input.requiredHeightLocktime);
+        else
+            heightSupported = false;
+        if (hasTime)
+            time = Math.max(time, input.requiredTimeLocktime);
+        else
+            timeSupported = false;
+    }
+    if (!hasRequirements)
+        return fallback;
+    // BIP370 requires height when every relevant input supports both domains.
+    if (heightSupported)
+        return height;
+    if (timeSupported)
+        return time;
+    throw new Error('PSBTv2: incompatible height-based and time-based locktime requirements');
+}
 // NOTE: we cannot do this inside PSBTInput coder, because there is no index/txid at this point!
-function validateInput(i) {
+function validateInput(i, disableScriptCheck = false) {
+    validateObject(i, {}, {}, 'i');
     const _i = i;
+    validateRequiredLocktimes(_i);
+    let prevOut;
     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];
+        prevOut = _i.nonWitnessUtxo.outputs[_i.index];
         if (_i.witnessUtxo &&
             (!equalBytes(_i.witnessUtxo.script, prevOut.script) ||
                 _i.witnessUtxo.amount !== prevOut.amount))
@@ -320,6 +487,9 @@ function validateInput(i) {
                 allowUnknownOutputs: true,
                 disableScriptCheck: true,
                 allowUnknownInputs: true,
+                // Consensus does not restrict nVersion; a previous tx with a non-standard
+                // version is still spendable and its txid must still be verifiable.
+                allowUnknownVersion: true,
             });
             const txid = hex.encode(_i.txid);
             // BIP174 requires the provided nonWitnessUtxo to hash to the prevout txid even when the
@@ -331,8 +501,43 @@ function validateInput(i) {
                 throw new Error(`nonWitnessUtxo: wrong txid, exp=${txid} got=${tx.id}`);
         }
     }
+    else if (_i.witnessUtxo)
+        prevOut = _i.witnessUtxo;
+    if (prevOut && !disableScriptCheck) {
+        checkScript(prevOut.script, _i.redeemScript, _i.witnessScript);
+        checkTaprootInputCommitments(_i, prevOut.script);
+    }
     return _i;
 }
+const inputSignatures = (input) => {
+    const _input = input;
+    const res = [];
+    const add = (signature, taproot, scriptPath = false) => {
+        const sig = signature;
+        if (!sig.length)
+            return;
+        // Taproot's 64-byte encoding omits the SIGHASH_DEFAULT byte; every other PSBT signature
+        // carries its sighash in the final byte, including signatures imported from another signer.
+        const sighash = taproot && sig.length === 64 ? SignatureHash.DEFAULT : sig[sig.length - 1];
+        res.push({ sighash, taproot, scriptPath });
+    };
+    for (const [, signature] of _input.partialSig || [])
+        add(signature, false);
+    if (_input.tapKeySig)
+        add(_input.tapKeySig, true);
+    for (const [, signature] of _input.tapScriptSig || [])
+        add(signature, true, true);
+    return res;
+};
+const inputSignedKeys = {
+    // sighashType is signer policy rather than a digest byte, but changing it after one signature
+    // exists would make later signers interpret the same input under a different policy.
+    self: ['txid', 'index', 'sequence', 'nonWitnessUtxo', 'witnessUtxo', 'sighashType'],
+    ecdsa: ['redeemScript', 'witnessScript'],
+    tapscript: ['tapLeafScript'],
+    cross: ['txid', 'index'],
+    prevout: ['nonWitnessUtxo', 'witnessUtxo'],
+};
 // Normalizes input
 /**
  * Extracts the previous output referenced by an input.
@@ -346,6 +551,7 @@ function validateInput(i) {
  * ```
  */
 export function getPrevOut(input) {
+    validateObject(input, {}, {}, 'input');
     const _input = input;
     if (_input.nonWitnessUtxo) {
         if (_input.index === undefined)
@@ -359,8 +565,15 @@ export function getPrevOut(input) {
             throw new Error(`Wrong input index=${_input.index}`);
         return _input.nonWitnessUtxo.outputs[_input.index];
     }
-    else if (_input.witnessUtxo)
-        return _input.witnessUtxo;
+    else if ('witnessUtxo' in _input) {
+        // The presence check catches malformed provided values; narrow after the guard for TS.
+        const prev = _input.witnessUtxo;
+        validateObject(prev, {}, {}, 'input.witnessUtxo');
+        abigint(prev.amount, 'input.witnessUtxo.amount');
+        if (!isBytes(prev.script))
+            throw new TypeError('"input.witnessUtxo.script" expected Uint8Array, got type=' + typeof prev.script);
+        return prev;
+    }
     else
         throw new Error('Cannot find previous output info');
 }
@@ -369,9 +582,12 @@ export function getPrevOut(input) {
  * @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
+ * @param disableScriptCheck - whether to skip wrapper and Taproot commitment sanity checks
+ * @param unknown - handling policy for unknown PSBT fields
+ * @param proprietary - handling policy for proprietary PSBT fields
  * @returns Normalized PSBT input.
+ * @throws If the update conflicts with the existing input or its signatures. {@link Error}
+ * @throws If a numeric input field is outside its wire or protocol range. {@link RangeError}
  * @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.
@@ -385,7 +601,12 @@ export function getPrevOut(input) {
  * });
  * ```
  */
-export function normalizeInput(i, cur, allowedFields, disableScriptCheck = false, allowUnknown = false) {
+export function normalizeInput(i, cur, allowedFields, disableScriptCheck = false, unknown = 'strip', proprietary = 'strip') {
+    validateObject(i, {}, {}, 'i');
+    if (cur !== undefined)
+        validateObject(cur, {}, {}, 'cur');
+    if (allowedFields !== undefined)
+        u.aarray(allowedFields, 'allowedFields');
     const _i = i;
     const _cur = cur;
     const _allowedFields = allowedFields;
@@ -412,18 +633,19 @@ export function normalizeInput(i, cur, allowedFields, disableScriptCheck = false
         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, unknown, proprietary);
+    // An actual empty repeated field emits no PSBT keypairs. Canonicalize only arrays so malformed
+    // falsy values still reach the PSBT coder's validation instead of becoming valid absence.
+    if (Array.isArray(res.tapLeafScript) && !res.tapLeafScript.length)
+        delete res.tapLeafScript;
+    validateRequiredLocktimes(res);
     // 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)
-        prevOut = res.nonWitnessUtxo.outputs[res.index];
-    else if (res.witnessUtxo)
-        prevOut = res.witnessUtxo;
-    if (prevOut && !disableScriptCheck)
-        checkScript(prevOut && prevOut.script, res.redeemScript, res.witnessScript);
-    return res;
+    // Direct construction and UTXO selection consume nonWitnessUtxo amounts without crossing a
+    // PSBT serialization boundary. Enforce the same outpoint binding here so a mismatched previous
+    // transaction cannot understate a legacy input amount and turn the difference into mining fees.
+    return validateInput(res, disableScriptCheck);
 }
 /**
  * Determines how an input should be signed and finalized.
@@ -454,10 +676,13 @@ export function getInputType(input, allowLegacyWitnessUtxo = false) {
     let txType = 'legacy';
     let defaultSighash = SignatureHash.ALL;
     const prevOut = getPrevOut(_input);
-    const first = OutScript.decode(prevOut.script);
+    const first = _WitnessOutScript.decode(prevOut.script);
     let type = first.type;
     let cur = first;
     const stack = [first];
+    // Classification is semantic, but legacy/BIP143 scriptCode and finalization must retain the
+    // exact committed spelling (including consensus-valid non-minimal pushes).
+    let lastScript = prevOut.script;
     if (first.type === 'tr') {
         // Expected invariant: taproot inputs use PSBT_IN_TAP_* metadata only;
         // legacy redeemScript/witnessScript fields belong to P2SH/P2WSH paths.
@@ -477,11 +702,12 @@ export function getInputType(input, allowLegacyWitnessUtxo = false) {
         if (first.type === 'sh') {
             if (!_input.redeemScript)
                 throw new Error('inputType: sh without redeemScript');
-            let child = OutScript.decode(_input.redeemScript);
+            let child = _WitnessOutScript.decode(_input.redeemScript);
             if (child.type === 'wpkh' || child.type === 'wsh')
                 txType = 'segwit';
             stack.push(child);
             cur = child;
+            lastScript = _input.redeemScript;
             type += `-${child.type}`;
         }
         // wsh can be inside sh
@@ -493,12 +719,12 @@ export function getInputType(input, allowLegacyWitnessUtxo = false) {
                 txType = 'segwit';
             stack.push(child);
             cur = child;
+            lastScript = _input.witnessScript;
             type += `-${child.type}`;
         }
         const last = stack[stack.length - 1];
         if (last.type === 'sh' || last.type === 'wsh')
             throw new Error('inputType: sh/wsh cannot be terminal type');
-        const lastScript = OutScript.encode(last);
         const res = {
             type,
             txType,
@@ -542,9 +768,61 @@ export class Transaction {
     constructor(opts = {}) {
         const _opts = (this.opts = validateOpts(opts));
         // Merge with global structure of PSBTv2
-        if (_opts.lockTime !== DEFAULT_LOCKTIME)
-            this.global.fallbackLocktime = _opts.lockTime;
+        // Bitcoin Core sets fallback even when it is zero. Matching its common encoding reduces the
+        // fingerprint of locally created PSBTv2s; imported PSBTs replace this map and retain omission.
+        this.global.fallbackLocktime = _opts.lockTime;
         this.global.txVersion = _opts.version;
+        // A locally-created PSBTv2 is still under construction. Imported PSBTs replace this global
+        // map below, so an omitted field there retains BIP370's immutable meaning.
+        if (_opts.PSBTVersion === 2)
+            this.global.txModifiable = 0b011;
+    }
+    isPSBTv2() {
+        return (this.global.version ?? this.opts.PSBTVersion) === 2;
+    }
+    requireTxModifiable(bit, kind) {
+        if (!this.isPSBTv2())
+            return;
+        if (!(this.txModifiablePolicy() & bit))
+            throw new Error(`PSBTv2: ${kind} are not modifiable`);
+    }
+    txModifiablePolicy(allowMissing = this.opts.allowMissingTxModifiable, unknownMode = this.opts.unknown) {
+        if (!this.isPSBTv2())
+            return 0b011;
+        if (this.global.txModifiable !== undefined)
+            return cleanTxModifiable(this.global.txModifiable, unknownMode);
+        return allowMissing ? 0b011 : 0;
+    }
+    modifiable(allowMissing = this.opts.allowMissingTxModifiable, unknownMode = this.opts.unknown) {
+        let flags = this.txModifiablePolicy(allowMissing, unknownMode);
+        let hasOpaqueFinal = false;
+        let hasSingle = false;
+        for (let idx = 0; idx < this.inputs.length; idx++) {
+            const signatures = inputSignatures(this.inputs[idx]);
+            if (!signatures.length && this.inputStatus(idx) === 'finalized')
+                hasOpaqueFinal = true;
+            for (const { sighash } of signatures) {
+                const { isAny, isNone, isSingle } = unpackSighash(sighash);
+                if (!isAny)
+                    flags &= ~0b001;
+                if (!isNone)
+                    flags &= ~0b010;
+                if (isSingle)
+                    hasSingle = true;
+            }
+        }
+        // Bit 2 summarizes signatures rather than granting policy. Preserve an imported summary for
+        // opaque or externally managed state, and union in every signature visible to this object.
+        if (hasSingle)
+            flags |= 0b100;
+        // PSBTv0 and legacy field-less PSBTv2 cannot describe an opaque finalized sighash. Promotion
+        // must therefore deny both mutations instead of manufacturing permissions from absence.
+        if (hasOpaqueFinal && this.global.txModifiable === undefined)
+            flags &= ~0b011;
+        return flags;
+    }
+    get txModifiable() {
+        return this.modifiable();
     }
     // Import
     static fromRaw(raw, opts = {}) {
@@ -584,24 +862,58 @@ export class Transaction {
         const tx = new Transaction({ ...opts, version, lockTime, PSBTVersion });
         // We need slice here, because otherwise
         const inputCount = PSBTVersion === 0 ? unsigned?.inputs.length : parsed.global.inputCount;
-        tx.inputs = parsed.inputs.slice(0, inputCount).map((i, j) => validateInput({
-            finalScriptSig: P.EMPTY,
-            ...parsed.global.unsignedTx?.inputs[j],
-            ...i,
-        }));
+        tx.inputs = parsed.inputs.slice(0, inputCount).map((i, j) => {
+            const input = {
+                ...parsed.global.unsignedTx?.inputs[j],
+                ...i,
+            };
+            // The unsigned transaction's empty scriptSig is framing, not a PSBT_IN_FINAL_SCRIPTSIG
+            // record. Keeping it makes combination conflict with an otherwise identical finalized PSBT.
+            if (!i.finalScriptSig?.length)
+                delete input.finalScriptSig;
+            return validateInput(input, tx.opts.disableScriptCheck);
+        });
         const outputCount = PSBTVersion === 0 ? unsigned?.outputs.length : parsed.global.outputCount;
-        tx.outputs = parsed.outputs.slice(0, outputCount).map((i, j) => ({
+        // bip174js writes a phantom empty input map when a PSBTv0 transaction has zero inputs. Raw v0
+        // framing necessarily reads it as the first output map, so skip it before pairing real maps
+        // with the unsigned transaction's declared outputs.
+        const hasBip174InputMap = PSBTVersion === 0 &&
+            inputCount === 0 &&
+            Object.keys(parsed.outputs[0] || {}).length === 0 &&
+            ((outputCount > 0 && parsed.outputs.length === outputCount + 1) ||
+                (outputCount === 0 &&
+                    parsed.outputs.length === 2 &&
+                    Object.keys(parsed.outputs[1]).length === 0));
+        const outputStart = hasBip174InputMap ? 1 : 0;
+        tx.outputs = parsed.outputs.slice(outputStart, outputStart + outputCount).map((i, j) => ({
             ...i,
             ...parsed.global.unsignedTx?.outputs[j],
         }));
-        tx.global = { ...parsed.global, txVersion: version }; // just in case proprietary/unknown fields
-        if (lockTime !== DEFAULT_LOCKTIME)
-            tx.global.fallbackLocktime = lockTime;
+        const unknownMode = tx.opts.unknown;
+        const proprietaryMode = tx.opts.proprietary;
+        // Unknown PSBT rows can carry opaque metadata between participants. The documented default is
+        // to strip them; callers that need forward compatibility must opt in explicitly. Proprietary
+        // (0xfc) rows follow the same explicit policy, which defaults to the resolved unknown mode.
+        tx.global = cleanExtensions({ ...parsed.global, txVersion: version }, unknownMode, proprietaryMode);
+        tx.inputs = tx.inputs.map((input) => cleanExtensions(input, unknownMode, proprietaryMode));
+        tx.outputs = tx.outputs.map((output) => cleanExtensions(output, unknownMode, proprietaryMode));
+        if (tx.global.txModifiable !== undefined)
+            tx.global.txModifiable = cleanTxModifiable(tx.global.txModifiable, unknownMode);
+        // A high-level Transaction must have a determinable nLockTime. Raw PSBT coders can still be
+        // used by callers that need to inspect or relay a structurally valid but incompatible PSBT.
+        resolvePSBTLocktime(tx.inputs, tx.global.fallbackLocktime ?? DEFAULT_LOCKTIME);
+        // PSBTv0 always provides nLockTime in its unsigned transaction. Retain zero internally too so
+        // promotion to v2 matches fresh construction and Bitcoin Core rather than gaining a
+        // fingerprint.
+        if (PSBTVersion === 0)
+            tx.global.fallbackLocktime = def(lockTime, DEFAULT_LOCKTIME);
         return tx;
     }
     // 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 !== undefined)
+            anumber(PSBTVersion, 'PSBTVersion');
         if (PSBTVersion !== 0 && PSBTVersion !== 2)
             throw new Error(`Wrong PSBT version=${PSBTVersion}`);
         // if (PSBTVersion === 0 && this.inputs.length === 0) {
@@ -609,10 +921,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) => 
+        const inputs = this.inputs.map((i) => cleanExtensions(
         // 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)));
+        psbt.cleanPSBTFields(PSBTVersion, psbt.PSBTInput, validateInput(i, this.opts.disableScriptCheck)), this.opts.unknown, this.opts.proprietary));
         for (const inp of inputs) {
             // Don't serialize empty fields
             if (inp.partialSig && !inp.partialSig.length)
@@ -622,8 +934,10 @@ export class Transaction {
             if (inp.finalScriptWitness && !inp.finalScriptWitness.length)
                 delete inp.finalScriptWitness;
         }
-        const outputs = this.outputs.map((i) => psbt.cleanPSBTFields(PSBTVersion, psbt.PSBTOutput, i));
-        const global = { ...this.global };
+        const outputs = this.outputs.map((i) => cleanExtensions(psbt.cleanPSBTFields(PSBTVersion, psbt.PSBTOutput, i), this.opts.unknown, this.opts.proprietary));
+        const global = cleanExtensions({ ...this.global }, this.opts.unknown, this.opts.proprietary);
+        if (global.txModifiable !== undefined)
+            global.txModifiable = cleanTxModifiable(global.txModifiable, this.opts.unknown);
         if (PSBTVersion === 0) {
             /*
             - Bitcoin raw transaction expects to have at least 1 input because it uses case with zero inputs as marker for SegWit
@@ -646,10 +960,12 @@ export class Transaction {
             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.
+            // PSBTv2 and reject the required `unsignedTx` field. Transaction-modifiable is also v2-only;
+            // its restrictions remain represented by the signatures when explicitly converting to v0.
             delete global.inputCount;
             delete global.outputCount;
             delete global.version;
+            delete global.txModifiable;
         }
         else {
             // Cross-version merges and v0->v2 re-exports can still carry the PSBTv0 unsignedTx blob in
@@ -660,15 +976,18 @@ export class Transaction {
             global.txVersion = this.version;
             global.inputCount = this.inputs.length;
             global.outputCount = this.outputs.length;
-            if (global.fallbackLocktime && global.fallbackLocktime === DEFAULT_LOCKTIME)
-                delete global.fallbackLocktime;
-        }
-        if (this.opts.bip174jsCompat) {
-            if (!inputs.length)
-                inputs.push({});
-            if (!outputs.length)
-                outputs.push({});
+            // Core serializes this optional field exactly as stored. Preserve no-op v2 round-trips;
+            // only v0 promotion and the explicit legacy-omission compatibility mode materialize policy.
+            if (!this.isPSBTv2() ||
+                (global.txModifiable === undefined && this.opts.allowMissingTxModifiable))
+                global.txModifiable = this.txModifiable;
         }
+        // bip174js historically emits one empty output map for a PSBTv0 transaction with no outputs.
+        // Input maps are count-framed by the unsigned transaction, so a phantom input map cannot be
+        // represented: with zero inputs it would be decoded as an output map instead. PSBTv2 has
+        // explicit counts for both map arrays and does not use this compatibility encoding.
+        if (this.opts.bip174jsCompat && PSBTVersion === 0 && !outputs.length)
+            outputs.push({});
         const raw = { global, inputs, outputs };
         return PSBTVersion === 0
             ? psbt.RawPSBTV0.encode(raw)
@@ -676,25 +995,7 @@ export class Transaction {
     }
     // BIP370 lockTime (https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki#determining-lock-time)
     get lockTime() {
-        let height = DEFAULT_LOCKTIME;
-        let heightCnt = 0;
-        let time = DEFAULT_LOCKTIME;
-        let timeCnt = 0;
-        for (const i of this.inputs) {
-            if (i.requiredHeightLocktime) {
-                height = Math.max(height, i.requiredHeightLocktime);
-                heightCnt++;
-            }
-            if (i.requiredTimeLocktime) {
-                time = Math.max(time, i.requiredTimeLocktime);
-                timeCnt++;
-            }
-        }
-        if (heightCnt && heightCnt >= timeCnt)
-            return height;
-        if (time !== DEFAULT_LOCKTIME)
-            return time;
-        return this.global.fallbackLocktime || DEFAULT_LOCKTIME;
+        return resolvePSBTLocktime(this.inputs, this.global.fallbackLocktime ?? DEFAULT_LOCKTIME);
     }
     get version() {
         // Should be not possible
@@ -720,6 +1021,13 @@ export class Transaction {
             return 'signed';
         return 'unsigned';
     }
+    cleanFinalInput(input) {
+        // Core preserves producer policy during finalization. Once cleanup makes signatures opaque,
+        // signStatus conservatively locks transaction mutation until the input is explicitly reopened.
+        cleanFinalInput(input, this.opts.unknown, this.opts.proprietary);
+        if (this.global.txModifiable !== undefined)
+            this.global.txModifiable = cleanTxModifiable(this.global.txModifiable, this.opts.unknown);
+    }
     // Cannot replace unpackSighash, tests rely on very generic implemenetation with signing inputs outside of range
     // We will lose some vectors -> smaller test coverage of preimages (very important!)
     inputSighash(idx) {
@@ -732,32 +1040,81 @@ export class Transaction {
         // ALL + ANYONE   -- specific input + all outputs
         // NONE + ANYONE  -- specific input + no outputs
         // SINGLE         -- specific inputs + output with same index
-        const sigOutputs = sighash === SignatureHash.DEFAULT ? SignatureHash.ALL : sighash & 0b11;
-        const sigInputs = sighash & SignatureHash.ANYONECANPAY;
-        return { sigInputs, sigOutputs };
+        return sighashScope(sighash);
     }
     // Very nice for debug purposes, but slow. If there is too much inputs/outputs to add, will be quadratic.
     // Some cache will be nice, but there chance to have bugs with cache invalidation
-    signStatus() {
+    signatures() {
+        const res = [];
+        for (let idx = 0; idx < this.inputs.length; idx++) {
+            const actual = inputSignatures(this.inputs[idx]);
+            for (const signature of actual)
+                res.push({ idx, ...signature });
+            if (actual.length || this.inputStatus(idx) !== 'finalized')
+                continue;
+            let taproot = true;
+            try {
+                taproot = _WitnessOutScript.decode(getPrevOut(this.inputs[idx]).script).type === 'tr';
+            }
+            catch {
+                // Finalization may remove the data needed to classify an imported opaque signature.
+                // Treating it as Taproot conservatively protects the larger all-prevout commitment.
+            }
+            const declared = this.inputs[idx].sighashType;
+            const sighash = declared === undefined ? SignatureHash.DEFAULT : declared;
+            res.push({ idx, sighash, taproot, scriptPath: taproot });
+        }
+        return res;
+    }
+    signedInputKeys(idx, signatures = this.signatures()) {
+        const res = new Set();
+        const add = (keys) => {
+            for (const key of keys)
+                res.add(key);
+        };
+        for (const signature of signatures) {
+            const { isAny, isNone, isSingle } = unpackSighash(signature.sighash);
+            if (signature.idx === idx) {
+                add(inputSignedKeys.self);
+                if (signature.taproot) {
+                    if (signature.scriptPath)
+                        add(inputSignedKeys.tapscript);
+                }
+                else
+                    add(inputSignedKeys.ecdsa);
+            }
+            else if (!isAny) {
+                add(inputSignedKeys.cross);
+                // Legacy and BIP143 omit other sequences for NONE/SINGLE. BIP341 commits every sequence
+                // whenever ANYONECANPAY is absent, independently of the output sighash mode.
+                if (signature.taproot || (!isNone && !isSingle))
+                    res.add('sequence');
+                if (signature.taproot)
+                    add(inputSignedKeys.prevout);
+            }
+        }
+        return [...res];
+    }
+    signStatus(signatures = this.signatures()) {
         // if addInput or addOutput is not possible, then all inputs or outputs are signed
         let addInput = true, addOutput = true;
         let inputs = [], outputs = [];
-        for (let idx = 0; idx < this.inputs.length; idx++) {
-            const status = this.inputStatus(idx);
-            // Unsigned input doesn't affect anything
-            if (status === 'unsigned')
-                continue;
-            const { sigInputs, sigOutputs } = this.inputSighash(idx);
+        for (const { idx, sighash } of signatures) {
+            const { sigInputs, sigOutputs } = sighashScope(sighash);
             // Input type
-            if (sigInputs === SignatureHash.ANYONECANPAY)
-                inputs.push(idx);
+            if (sigInputs === SignatureHash.ANYONECANPAY) {
+                if (!inputs.includes(idx))
+                    inputs.push(idx);
+            }
             else
                 addInput = false;
             // Output type
             if (sigOutputs === SignatureHash.ALL)
                 addOutput = false;
-            else if (sigOutputs === SignatureHash.SINGLE)
-                outputs.push(idx);
+            else if (sigOutputs === SignatureHash.SINGLE) {
+                if (!outputs.includes(idx))
+                    outputs.push(idx);
+            }
             else if (sigOutputs === SignatureHash.NONE) {
                 // Doesn't affect any outputs at all
             }
@@ -774,32 +1131,38 @@ export class Transaction {
     }
     // Info utils
     get hasWitnesses() {
-        let out = false;
         for (const i of this.inputs)
             if (i.finalScriptWitness && i.finalScriptWitness.length)
-                out = true;
-        return out;
+                return true;
+        return false;
     }
     // https://en.bitcoin.it/wiki/Weight_units
     get weight() {
         if (!this.isFinal)
             throw new Error('Transaction is not finalized');
+        // Serialized length of VarBytes(data) without allocating the encoded copy
+        const varLen = (dataLen) => CompactSizeLen.encode(dataLen).length + dataLen;
+        const hasWitnesses = this.hasWitnesses;
         let out = 32;
         // Outputs
         const outputs = this.outputs.map(outputBeforeSign);
         out += 4 * CompactSizeLen.encode(this.outputs.length).length;
         for (const o of outputs)
-            out += 32 + 4 * VarBytes.encode(o.script).length;
+            out += 32 + 4 * varLen(o.script.length);
         // Inputs
-        if (this.hasWitnesses)
+        if (hasWitnesses)
             out += 2;
         out += 4 * CompactSizeLen.encode(this.inputs.length).length;
         for (const i of this.inputs) {
-            out += 160 + 4 * VarBytes.encode(i.finalScriptSig || P.EMPTY).length;
+            out += 160 + 4 * varLen((i.finalScriptSig || P.EMPTY).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;
+            if (hasWitnesses) {
+                const witness = i.finalScriptWitness || [];
+                out += CompactSizeLen.encode(witness.length).length;
+                for (const w of witness)
+                    out += varLen(w.length);
+            }
         }
         return out;
     }
@@ -833,9 +1196,27 @@ export class Transaction {
     }
     // Input stuff
     checkInputIdx(idx) {
-        if (!Number.isSafeInteger(idx) || 0 > idx || idx >= this.inputs.length)
+        anumber(idx, 'idx');
+        if (idx >= this.inputs.length)
             throw new Error(`Wrong input index=${idx}`);
     }
+    validatePrevoutsForSigning() {
+        if (!this.opts.strictPrevoutValidation)
+            return;
+        for (let i = 0; i < this.inputs.length; i++) {
+            const input = this.inputs[i];
+            if (!input.nonWitnessUtxo) {
+                throw new Error(`Transaction/sign: strictPrevoutValidation requires nonWitnessUtxo for input=${i}`);
+            }
+            if (input.txid === undefined || input.index === undefined) {
+                throw new Error(`Transaction/sign: strictPrevoutValidation requires an outpoint for input=${i}`);
+            }
+            // A full previous transaction is only a trusted amount/script commitment after its txid and
+            // selected output have been checked against the unsigned transaction. Also cross-check a
+            // redundant witnessUtxo when one is present.
+            validateInput(input, this.opts.disableScriptCheck);
+        }
+    }
     getInput(idx) {
         this.checkInputIdx(idx);
         return cloneDeep(this.inputs[idx]);
@@ -845,28 +1226,63 @@ export class Transaction {
     }
     // Modification
     addInput(input, _ignoreSignStatus = false) {
-        if (!_ignoreSignStatus && !this.signStatus().addInput)
+        validateObject(input, {}, {}, 'input');
+        cleanExtensions(input, this.opts.unknown, this.opts.proprietary, true);
+        this.requireTxModifiable(0b001, 'inputs');
+        const signatures = _ignoreSignStatus ? undefined : this.signatures();
+        const status = signatures && this.signStatus(signatures);
+        if (status && !status.addInput)
             throw new Error('Tx has signed inputs, cannot add new one');
         // 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)));
+        const normalized = cloneDeep(normalizeInput(input, undefined, undefined, this.opts.disableScriptCheck, this.opts.unknown, this.opts.proprietary));
+        const nextLockTime = resolvePSBTLocktime([...this.inputs, normalized], this.global.fallbackLocktime ?? DEFAULT_LOCKTIME);
+        // ANYONECANPAY permits adding an outpoint, but every signature still commits to nLockTime.
+        if (signatures?.length && nextLockTime !== this.lockTime)
+            throw new Error('Tx has signed inputs, cannot change lockTime');
+        this.inputs.push(normalized);
         return this.inputs.length - 1;
     }
     updateInput(idx, input, _ignoreSignStatus = false) {
         this.checkInputIdx(idx);
-        let allowedFields = undefined;
-        if (!_ignoreSignStatus) {
-            const status = this.signStatus();
-            if (!status.addInput || status.inputs.includes(idx))
-                allowedFields = psbt.PSBTInputUnsignedKeys;
+        cleanExtensions(input, this.opts.unknown, this.opts.proprietary, true);
+        let allowedFields;
+        const signatures = _ignoreSignStatus ? undefined : this.signatures();
+        if (signatures?.length) {
+            if (this.inputStatus(idx) === 'finalized') {
+                // Once finalized, only already-present signature/final fields may be repeated or removed.
+                // In particular, do not let a native-SegWit final witness gain a stray finalScriptSig.
+                allowedFields = psbt.PSBTInputSignatureKeys.filter((key) => this.inputs[idx][key] !== undefined);
+            }
+            else {
+                const signed = new Set(this.signedInputKeys(idx, signatures));
+                if (signed.size)
+                    allowedFields = Object.keys(psbt.PSBTInput).filter((key) => !signed.has(key));
+            }
         }
         // 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));
+        const normalized = cloneDeep(normalizeInput(input, this.inputs[idx], allowedFields, this.opts.disableScriptCheck, this.opts.unknown, this.opts.proprietary));
+        const inputs = this.inputs.slice();
+        inputs[idx] = normalized;
+        const nextLockTime = resolvePSBTLocktime(inputs, this.global.fallbackLocktime ?? DEFAULT_LOCKTIME);
+        if (signatures?.length && nextLockTime !== this.lockTime)
+            throw new Error('Tx has signed inputs, cannot change lockTime');
+        const current = this.inputs[idx];
+        const transactionChanged = current.index !== normalized.index ||
+            def(current.sequence, DEFAULT_SEQUENCE) !== def(normalized.sequence, DEFAULT_SEQUENCE) ||
+            (current.txid === undefined
+                ? normalized.txid !== undefined
+                : normalized.txid === undefined || !equalBytes(current.txid, normalized.txid)) ||
+            nextLockTime !== this.lockTime;
+        if (transactionChanged)
+            this.requireTxModifiable(0b001, 'inputs');
+        this.inputs[idx] = normalized;
     }
     // Output stuff
     checkOutputIdx(idx) {
-        if (!Number.isSafeInteger(idx) || 0 > idx || idx >= this.outputs.length)
+        anumber(idx, 'idx');
+        if (idx >= this.outputs.length)
             throw new Error(`Wrong output index=${idx}`);
     }
     getOutput(idx) {
@@ -877,17 +1293,17 @@ export class Transaction {
         const out = this.getOutput(idx);
         if (!out.script)
             return;
-        return Address(network).encode(OutScript.decode(out.script));
+        return Address(network).encode(_WitnessOutScript.decode(out.script));
     }
     get outputsLength() {
         return this.outputs.length;
     }
     normalizeOutput(o, cur, allowedFields) {
+        validateObject(o, {}, {}, 'o');
         let { amount, script } = o;
         if (amount === undefined)
             amount = cur?.amount;
-        if (typeof amount !== 'bigint')
-            throw new Error(`Wrong amount type, should be of type bigint in sats, but got ${amount} of type ${typeof amount}`);
+        amount = abigint(amount, 'o.amount');
         if (typeof script === 'string')
             script = hex.decode(script);
         if (script === undefined)
@@ -895,11 +1311,11 @@ export class Transaction {
         let res = { ...cur, ...o, amount, script };
         if (res.amount === undefined)
             delete res.amount;
-        res = psbt.mergeKeyMap(psbt.PSBTOutput, res, cur, allowedFields, this.opts.allowUnknown);
+        res = psbt.mergeKeyMap(psbt.PSBTOutput, res, cur, allowedFields, this.opts.unknown, this.opts.proprietary);
         psbt.PSBTOutputCoder.encode(res);
         if (res.script &&
             !this.opts.allowUnknownOutputs &&
-            OutScript.decode(res.script).type === 'unknown') {
+            _WitnessOutScript.decode(res.script).type === 'unknown') {
             throw new Error('Transaction/output: unknown output script type, there is a chance that input is unspendable. Pass allowUnknownOutputs=true, if you sure');
         }
         if (!this.opts.disableScriptCheck)
@@ -907,7 +1323,11 @@ export class Transaction {
         return res;
     }
     addOutput(o, _ignoreSignStatus = false) {
-        if (!_ignoreSignStatus && !this.signStatus().addOutput)
+        cleanExtensions(o, this.opts.unknown, this.opts.proprietary, true);
+        this.requireTxModifiable(0b010, 'outputs');
+        const status = _ignoreSignStatus ? undefined : this.signStatus();
+        // Appending the previously missing same-index output changes a SIGHASH_SINGLE digest.
+        if (status && (!status.addOutput || status.outputs.includes(this.outputs.length)))
             throw new Error('Tx has signed outputs, cannot add new one');
         // 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.
@@ -916,6 +1336,7 @@ export class Transaction {
     }
     updateOutput(idx, output, _ignoreSignStatus = false) {
         this.checkOutputIdx(idx);
+        cleanExtensions(output, this.opts.unknown, this.opts.proprietary, true);
         let allowedFields = undefined;
         if (!_ignoreSignStatus) {
             const status = this.signStatus();
@@ -924,7 +1345,15 @@ export class Transaction {
         }
         // 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));
+        const current = this.outputs[idx];
+        const normalized = cloneDeep(this.normalizeOutput(output, current, allowedFields));
+        const transactionChanged = current.amount !== normalized.amount ||
+            (current.script === undefined
+                ? normalized.script !== undefined
+                : normalized.script === undefined || !equalBytes(current.script, normalized.script));
+        if (transactionChanged)
+            this.requireTxModifiable(0b010, 'outputs');
+        this.outputs[idx] = normalized;
     }
     addOutputAddress(address, amount, network = NETWORK) {
         return this.addOutput({
@@ -936,7 +1365,7 @@ export class Transaction {
     }
     // Utils
     get fee() {
-        let res = 0n;
+        let res = _0n;
         for (const i of this.inputs) {
             const prevOut = getPrevOut(i);
             if (!prevOut)
@@ -957,7 +1386,8 @@ export class Transaction {
         if (idx < 0 || !Number.isSafeInteger(idx))
             throw new Error(`Invalid input idx=${idx}`);
         if ((isSingle && idx >= this.outputs.length) || idx >= this.inputs.length)
-            return P.U256BE.encode(1n);
+            // Bitcoin Core passes uint256::ONE's internal little-endian bytes directly to ECDSA.
+            return P.U256LE.encode(_1n);
         prevOutScript = stripCodeSeparator(prevOutScript);
         let inputs = this.inputs
             .map(inputBeforeSign)
@@ -994,7 +1424,8 @@ export class Transaction {
     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)
+        anumber(idx, 'idx');
+        if (idx >= this.inputs.length)
             throw new Error(`Invalid input idx=${idx}`);
         const { isAny, isNone, isSingle } = unpackSighash(hashType);
         let inputHash = EMPTY32;
@@ -1015,15 +1446,18 @@ export class Transaction {
         return u.sha256x2(P.I32LE.encode(this.version), inputHash, sequenceHash, P.bytes(32, true).encode(input.txid), P.U32LE.encode(input.index), VarBytes.encode(prevOutScript), P.U64LE.encode(amount), P.U32LE.encode(input.sequence), outputHash, P.U32LE.encode(this.lockTime), P.U32LE.encode(hashType));
     }
     preimageWitnessV1(idx, prevOutScript, hashType, amount, codeSeparator = -1, leafScript, leafVer = 0xc0, annex) {
-        if (!Array.isArray(amount) || this.inputs.length !== amount.length)
-            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)
+        anumber(idx, 'idx');
+        if (idx >= this.inputs.length)
             throw new Error(`Invalid input idx=${idx}`);
+        u.aarray(amount, 'amount');
+        u.aarray(prevOutScript, 'prevOutScript');
+        if (this.inputs.length !== amount.length)
+            throw new Error(`Invalid amounts array=${amount}`);
+        if (this.inputs.length !== prevOutScript.length)
+            throw new Error(`Invalid prevOutScript array=${prevOutScript}`);
         const out = [
             P.U8.encode(0),
             P.U8.encode(hashType), // U8 sigHash
@@ -1034,6 +1468,12 @@ export class Transaction {
         const inType = hashType & SignatureHash.ANYONECANPAY;
         const inputs = this.inputs.map(inputBeforeSign);
         const outputs = this.outputs.map(outputBeforeSign);
+        // Unlike legacy and segwit v0, BIP341 defines no digest for SINGLE when the
+        // corresponding output does not exist. Returning a digest here would produce
+        // signatures that consensus can never accept.
+        if (outType === SignatureHash.SINGLE && idx >= outputs.length) {
+            throw new Error(`Input with sighash SINGLE, but there is no output with corresponding index=${idx}`);
+        }
         if (inType !== SignatureHash.ANYONECANPAY) {
             out.push(...[
                 inputs.map(TxHashIdx.encode),
@@ -1056,15 +1496,24 @@ export class Transaction {
         if (spendType & 1)
             out.push(u.sha256(VarBytes.encode(annex || P.EMPTY)));
         if (outType === SignatureHash.SINGLE)
-            out.push(idx < outputs.length ? u.sha256(RawOutput.encode(outputs[idx])) : EMPTY32);
+            out.push(u.sha256(RawOutput.encode(outputs[idx])));
         if (leafScript)
             out.push(tapLeafHash(leafScript, leafVer), P.U8.encode(0), P.I32LE.encode(codeSeparator));
         return u.tagSchnorr('TapSighash', ...out);
     }
     // Signer can be privateKey OR instance of bip32 HD stuff
     signIdx(privateKey, idx, allowedSighash, _auxRand) {
+        if (!isBytes(privateKey)) {
+            // HDKey is a structural external instance, so plain-object validation would
+            // reject valid signers.
+            if (!privateKey ||
+                typeof privateKey !== 'object' ||
+                typeof privateKey.deriveChild !== 'function')
+                throw new TypeError('"privateKey" expected Uint8Array or HDKey, got type=' + typeof privateKey);
+        }
         this.checkInputIdx(idx);
-        const input = this.inputs[idx];
+        this.validatePrevoutsForSigning();
+        const input = validateInput(this.inputs[idx], this.opts.disableScriptCheck);
         const inputType = getInputType(input, this.opts.allowLegacyWitnessUtxo);
         const canSign = (privateKey) => {
             if (inputType.txType === 'taproot') {
@@ -1246,6 +1695,9 @@ export class Transaction {
     // Even worse: another user can add bip32 derivation, and spend money from different address.
     // Better api: signIdx
     sign(privateKey, allowedSighash, _auxRand) {
+        // Check transaction-wide strict requirements outside the per-input catch below so callers get
+        // the actionable validation error instead of the generic "No inputs signed" result.
+        this.validatePrevoutsForSigning();
         let num = 0;
         for (let i = 0; i < this.inputs.length; i++) {
             try {
@@ -1260,18 +1712,26 @@ export class Transaction {
     }
     finalizeIdx(idx) {
         this.checkInputIdx(idx);
-        if (this.fee < 0n)
+        if (this.fee < _0n)
             throw new Error('Outputs spends more than inputs amount');
         const input = this.inputs[idx];
+        // Validate strict extension policy before constructing satisfaction so a rejection is atomic.
+        cleanExtensions(input, this.opts.unknown, this.opts.proprietary);
+        cleanTxModifiable(this.global.txModifiable, this.opts.unknown);
         const inputType = getInputType(input, this.opts.allowLegacyWitnessUtxo);
         // Taproot finalize
         if (inputType.txType === 'taproot') {
             if (input.tapKeySig)
                 input.finalScriptWitness = [input.tapKeySig];
             else if (input.tapLeafScript && input.tapScriptSig) {
-                // Sort leafs by control block length.
-                const leafs = input.tapLeafScript.sort((a, b) => psbt.TaprootControlBlock.encode(a[0]).length -
+                // Preserve the old shallowest-path tie-break without mutating caller-visible leaf order.
+                const leafs = input.tapLeafScript
+                    .slice()
+                    .sort((a, b) => psbt.TaprootControlBlock.encode(a[0]).length -
                     psbt.TaprootControlBlock.encode(b[0]).length);
+                let smallest;
+                let smallestSize = Number.POSITIVE_INFINITY;
+                let unsupported = false;
                 for (const [cb, _script] of leafs) {
                     // Last byte is version
                     const script = _script.slice(0, -1);
@@ -1280,6 +1740,7 @@ export class Transaction {
                     const hash = tapLeafHash(script, ver);
                     const scriptSig = input.tapScriptSig.filter((i) => equalBytes(i[0].leafHash, hash));
                     let signatures = [];
+                    let witness;
                     if (outScript.type === 'tr_ms') {
                         const m = outScript.m;
                         const pubkeys = outScript.pubkeys;
@@ -1326,6 +1787,7 @@ export class Transaction {
                     }
                     else {
                         const custom = this.opts.customScripts;
+                        let recognized = false;
                         if (custom) {
                             for (const c of custom) {
                                 if (!c.finalizeTaproot)
@@ -1334,31 +1796,44 @@ export class Transaction {
                                 const csEncoded = c.encode(scriptDecoded);
                                 if (csEncoded === undefined)
                                     continue;
+                                recognized = true;
+                                // Do not catch hook errors here. `undefined` means no satisfaction, while a throw
+                                // from a matching custom finalizer reports broken leaf/signature data and must
+                                // abort even when another leaf has already produced a valid witness candidate.
                                 const finalized = c.finalizeTaproot(script, csEncoded, scriptSig);
                                 if (!finalized)
                                     continue;
-                                input.finalScriptWitness = finalized.concat(psbt.TaprootControlBlock.encode(cb));
-                                delete input.finalScriptSig;
-                                cleanFinalInput(input);
-                                return;
+                                witness = finalized.concat(psbt.TaprootControlBlock.encode(cb));
+                                break;
                             }
                         }
-                        throw new Error('Finalize: Unknown tapLeafScript');
+                        // Minimum search inspects every leaf, so an unsupported path cannot block an already
+                        // complete known path merely because it appears later. Retain the old error when no
+                        // supported satisfaction exists at all.
+                        if (!witness && !recognized && scriptSig.length)
+                            unsupported = true;
+                        if (!witness)
+                            continue;
                     }
                     // Witness is stack, so last element will be used first
-                    input.finalScriptWitness = signatures
-                        .reverse()
-                        .concat([script, psbt.TaprootControlBlock.encode(cb)]);
-                    break;
+                    witness ||= signatures.reverse().concat([script, psbt.TaprootControlBlock.encode(cb)]);
+                    const size = RawWitness.encode(witness).length;
+                    if (size >= smallestSize)
+                        continue;
+                    smallest = witness;
+                    smallestSize = size;
                 }
-                if (!input.finalScriptWitness)
+                if (!smallest && unsupported)
+                    throw new Error('Finalize: Unknown tapLeafScript');
+                if (!smallest)
                     throw new Error('finalize/taproot: empty witness');
+                input.finalScriptWitness = smallest;
             }
             else
                 throw new Error('finalize/taproot: unknown input');
             // BIP174 Input Finalizer: if scriptSig is empty for an input, 0x07 remains unset.
             delete input.finalScriptSig;
-            cleanFinalInput(input);
+            this.cleanFinalInput(input);
             return;
         }
         if (!input.partialSig || !input.partialSig.length)
@@ -1429,7 +1904,7 @@ export class Transaction {
             input.finalScriptSig = finalScriptSig;
         if (finalScriptWitness)
             input.finalScriptWitness = finalScriptWitness;
-        cleanFinalInput(input);
+        this.cleanFinalInput(input);
     }
     finalize() {
         for (let i = 0; i < this.inputs.length; i++)
@@ -1440,18 +1915,28 @@ export class Transaction {
             throw new Error('Transaction has unfinalized inputs');
         if (!this.outputs.length)
             throw new Error('Transaction has no outputs');
-        if (this.fee < 0n)
+        if (this.fee < _0n)
             throw new Error('Outputs spends more than inputs amount');
         return this.toBytes(true, true);
     }
     combine(other) {
+        if (!(other instanceof Transaction))
+            throw new TypeError('"other" expected Transaction, got type=' + typeof other);
+        // Match main's accumulator model: operation policy belongs to the receiver that is mutated.
+        const opts = this.opts;
         // 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]}`);
-            }
+        if (this.opts.version !== other.opts.version)
+            throw new Error(`Transaction/combine: different version this=${this.opts.version} ` +
+                `other=${other.opts.version}`);
+        const thisV2 = this.isPSBTv2();
+        const otherV2 = other.isPSBTv2();
+        if (!thisV2 || !otherV2) {
+            const thisLockTime = this.lockTime;
+            const otherLockTime = other.lockTime;
+            if (thisLockTime !== otherLockTime)
+                throw new Error(`Transaction/combine: different lockTime this=${thisLockTime} other=${otherLockTime}`);
         }
         for (const k of ['inputs', 'outputs']) {
             if (this[k].length !== other[k].length) {
@@ -1460,15 +1945,122 @@ export class Transaction {
         }
         // 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))
+        const unsignedTx = this.unsignedTx;
+        if (!equalBytes(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);
+        let txModifiable;
+        if (thisV2 && otherV2) {
+            // Core combines the stored optional bytes without deriving replacements from signatures.
+            // Only explicit legacy-omission compatibility gives an absent field an effective value.
+            const policy = (tx) => {
+                if (tx.global.txModifiable !== undefined)
+                    return cleanTxModifiable(tx.global.txModifiable, opts.unknown);
+                return opts.allowMissingTxModifiable ? tx.modifiable(true, opts.unknown) : 0;
+            };
+            const a = policy(this);
+            const b = policy(other);
+            // Known mutability permissions use intersection and SIGHASH_SINGLE presence uses union.
+            // Future flag bits must agree because this implementation does not know how to merge them.
+            if ((a & ~0b111) !== (b & ~0b111))
+                throw new Error('Transaction/combine: conflicting unknown txModifiable flags');
+            txModifiable = (a & ~0b111) | (a & b & 0b011) | ((a | b) & 0b100);
+            // Preserve Core's optional-field semantics when neither participant supplied policy.
+            if (txModifiable === 0 &&
+                this.global.txModifiable === undefined &&
+                other.global.txModifiable === undefined &&
+                !opts.allowMissingTxModifiable)
+                txModifiable = undefined;
+        }
+        else if (thisV2)
+            txModifiable = this.modifiable(opts.allowMissingTxModifiable, opts.unknown);
+        else if (otherV2)
+            txModifiable = other.modifiable(opts.allowMissingTxModifiable, opts.unknown);
+        const thisGlobal = { ...this.global };
+        const otherGlobal = { ...other.global };
+        // PSBTv0 has no fallback-locktime field: fromPSBT caches unsignedTx.nLockTime there only for
+        // effective-locktime resolution and v2 promotion. Do not merge that cache as a v2 wire value.
+        if (thisV2 !== otherV2) {
+            if (!thisV2)
+                delete thisGlobal.fallbackLocktime;
+            if (!otherV2)
+                delete otherGlobal.fallbackLocktime;
+            // BIP174 permits v0 to encode version zero explicitly or omit it. Remove only that v0
+            // spelling before scalar conflicts; retaining the v2 field anchors repeated promotion when
+            // the accumulator's original options still target v0.
+            if (!thisV2)
+                delete thisGlobal.version;
+            if (!otherV2)
+                delete otherGlobal.version;
+        }
+        // Transaction-modifiable has dedicated bitwise merge rules above. Fallback locktime is only
+        // one input to the effective locktime resolved from the combined input maps, so retain receiver
+        // precedence and validate the resulting unsigned transaction after those maps merge below.
+        const fallbackLocktime = thisGlobal.fallbackLocktime !== undefined
+            ? thisGlobal.fallbackLocktime
+            : otherGlobal.fallbackLocktime;
+        delete thisGlobal.txModifiable;
+        delete otherGlobal.txModifiable;
+        delete thisGlobal.fallbackLocktime;
+        delete otherGlobal.fallbackLocktime;
+        // Every ordinary global scalar must agree when both participants provide it; silently choosing
+        // either value can detach extension metadata such as a BIP322 message from its signatures.
+        const global = psbt.combineKeyMap(psbt.PSBTGlobal, thisGlobal, otherGlobal, opts.unknown, opts.proprietary);
+        if (fallbackLocktime !== undefined)
+            global.fallbackLocktime = fallbackLocktime;
         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++)
-            this.updateOutput(i, other.outputs[i], true);
+            global.version = PSBTVersion;
+        if (txModifiable === undefined)
+            delete global.txModifiable;
+        else
+            global.txModifiable = txModifiable;
+        let hasOpaqueFinalizedV0 = false;
+        const inputs = this.inputs.map((current, i) => {
+            const currentFinal = this.inputStatus(i) === 'finalized';
+            const otherFinal = other.inputStatus(i) === 'finalized';
+            // Finalized v0 maps no longer contain the partial signatures needed to derive v2 flags.
+            if ((!thisV2 && currentFinal) || (!otherV2 && otherFinal))
+                hasOpaqueFinalizedV0 = true;
+            if (currentFinal && otherFinal) {
+                // Two finalized PSBTs must describe the same complete satisfaction. Requiring matching
+                // presence as well as matching values prevents combining witness-only and scriptSig-only
+                // final states into a third, unreviewed satisfaction.
+                for (const k of ['finalScriptSig', 'finalScriptWitness']) {
+                    const currentHas = !!this.inputs[i][k]?.length;
+                    const otherHas = !!other.inputs[i][k]?.length;
+                    if (currentHas !== otherHas)
+                        throw new Error(`Transaction/combine: different finalized field=${k} input=${i}`);
+                }
+            }
+            const combined = psbt.combineKeyMap(psbt.PSBTInput, current, other.inputs[i], opts.unknown, opts.proprietary);
+            // A final satisfaction supersedes partial signatures and transient signing metadata. This
+            // also avoids manufacturing a contradictory final+partial input from two valid PSBTs.
+            if (currentFinal || otherFinal)
+                cleanFinalInput(combined, opts.unknown, opts.proprietary);
+            return cloneDeep(normalizeInput(combined, undefined, undefined, opts.disableScriptCheck, opts.unknown, opts.proprietary));
+        });
+        // A promoted opaque satisfaction may commit to both transaction halves. Clear only known
+        // permissions; retain a v2 participant's SIGHASH_SINGLE indicator and any future flag bits.
+        if (hasOpaqueFinalizedV0 && global.txModifiable !== undefined)
+            global.txModifiable &= ~0b011;
+        const candidate = new Transaction({ ...opts, PSBTVersion });
+        const outputs = this.outputs.map((current, i) => {
+            const combined = psbt.combineKeyMap(psbt.PSBTOutput, current, other.outputs[i], opts.unknown, opts.proprietary);
+            return cloneDeep(candidate.normalizeOutput(combined));
+        });
+        // Build and validate a detached candidate before touching the receiver. Combining
+        // complementary v2 locktime fields can otherwise create a different unsigned transaction.
+        candidate.global = global;
+        candidate.inputs = inputs;
+        candidate.outputs = outputs;
+        // A v0 input map can contribute signatures while the combined transaction is promoted to v2.
+        // All-v2 restrictions were already intersected above, preserving mutual field omission.
+        if ((!thisV2 || !otherV2) && candidate.isPSBTv2())
+            candidate.global.txModifiable = candidate.txModifiable;
+        if (!equalBytes(candidate.unsignedTx, unsignedTx))
+            throw new Error('Transaction/combine: combined unsigned tx differs');
+        this.global = candidate.global;
+        this.inputs = candidate.inputs;
+        this.outputs = candidate.outputs;
         return this;
     }
     clone() {
@@ -1479,6 +2071,7 @@ export class Transaction {
 /**
  * Merges multiple PSBT blobs into one.
  * @param psbts - PSBT byte arrays to combine
+ * @param opts - Transaction parsing, combination, and serialization options. See {@link TxOpts}.
  * @returns Combined PSBT bytes.
  * @throws If the PSBT list is empty or the partial transactions cannot be combined. {@link Error}
  * @example
@@ -1489,13 +2082,15 @@ export class Transaction {
  * PSBTCombine([psbt, psbt]);
  * ```
  */
-export function PSBTCombine(psbts) {
+export function PSBTCombine(psbts, opts = {}) {
     if (!psbts || !Array.isArray(psbts) || !psbts.length)
         throw new Error('PSBTCombine: wrong PSBT list');
-    const tx = Transaction.fromPSBT(psbts[0]);
+    // Options affect both map cleanup during combination and the encoding of the returned PSBT.
+    const combineOpts = opts;
+    const tx = Transaction.fromPSBT(psbts[0], combineOpts);
     for (let i = 1; i < psbts.length; i++)
-        tx.combine(Transaction.fromPSBT(psbts[i]));
-    return tx.toPSBT();
+        tx.combine(Transaction.fromPSBT(psbts[i], tx.opts));
+    return tx.toPSBT(combineOpts.PSBTVersion);
 }
 // Copy-pasted from bip32 derive, maybe do something like 'bip32.parsePath'?
 const HARDENED_OFFSET = 0x80000000;
@@ -1538,4 +2133,3 @@ export function bip32Path(path) {
     }
     return out;
 }
-//# sourceMappingURL=transaction.js.map