@scure/btc-signer 2.2.0 → 2.4.0

package/src/transaction.ts

@@ -1,6 +1,14 @@
 import { hex } from '@scure/base';
+import { anumber } from '@noble/hashes/utils.js';
 import * as P from 'micro-packed';
-import { Address, type CustomScript, OutScript, checkScript, tapLeafHash } from './payment.ts';
+import {
+  Address,
+  type CustomScript,
+  OutScript,
+  _WitnessOutScript,
+  checkScript,
+  tapLeafHash,
+} from './payment.ts';
 import * as psbt from './psbt.ts';
 import {
   CompactSizeLen,
@@ -18,16 +26,22 @@ import * as u from './utils.ts';
 import {
   type Bytes,
   NETWORK,
+  abigint,
   concatBytes,
   equalBytes,
   isBytes,
   type TArg,
   type TRet,
+  validateObject,
 } from './utils.ts';
 
+// 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: Uint8Array = /* @__PURE__ */ new Uint8Array(32);
 const EMPTY_OUTPUT: P.UnwrapCoder<typeof RawOutput> = {
-  amount: 0xffffffffffffffffn,
+  amount: U64_MAX,
   script: P.EMPTY,
 };
 /**
@@ -48,7 +62,7 @@ const stripCodeSeparator = (script: TArg<Bytes>): TRet<Bytes> => {
   // byte, because semantic decode/re-encode would change the signed digest.
   let start = 0;
   const out: Uint8Array[] = [];
-  for (let i = 0; i < script.length; ) {
+  for (let i = 0; i < script.length;) {
     const pos = i;
     const op = script[i++];
     if (op === OP.CODESEPARATOR) {
@@ -158,6 +172,8 @@ export function cloneDeep<T>(obj: T): T {
 
 // Mostly security features, hardened defaults;
 // but you still can parse other people tx with unspendable outputs and stuff if you want
+/** PSBT unknown/proprietary-field handling policy. */
+export type Unknowns = psbt.Unknowns;
 /** Transaction construction and parsing options. */
 export interface TxOpts {
   /** Transaction version to place into new transactions and imported PSBTs. */
@@ -187,7 +203,7 @@ export interface TxOpts {
   /** Allow signing and finalizing inputs with unknown script shapes. */
   allowUnknownInputs?: boolean;
   // Check input/output scripts for sanity
-  /** Skip redeem-script and witness-script consistency checks. */
+  /** Skip redeem/witness-script and Taproot commitment consistency checks. */
   disableScriptCheck?: boolean;
   // There is strange behaviour where tx without outputs encoded with empty output in the end,
   // tx without outputs in BIP174 doesn't have itb
@@ -197,12 +213,30 @@ export interface TxOpts {
   // result paying higher mining fee
   /** Permit legacy inputs that only provide witness UTXO data. */
   allowLegacyWitnessUtxo?: boolean;
+  /**
+   * Before signing, require every input to provide a full previous transaction whose txid and
+   * selected output match the input. Use this for untrusted or multi-party PSBTs to prevent forged
+   * witness-UTXO amounts from hiding an excessive transaction fee.
+   */
+  strictPrevoutValidation?: boolean;
   /** Grind ECDSA signatures until they use a low-R encoding. */
   lowR?: boolean;
   /** UNSAFE: additional custom payment-script codecs and finalizers. */
   customScripts?: CustomScript[];
-  // Allow to add additional unknown keys/values to the "unknown" array member
-  /** Preserve unknown PSBT key/value pairs instead of stripping them. */
+  /** Unknown PSBT field policy. Defaults to `strip`. */
+  unknown?: Unknowns;
+  /** Proprietary PSBT field policy. Defaults to the resolved {@link unknown} policy. */
+  proprietary?: Unknowns;
+  /**
+   * Treat an absent PSBTv2 transaction-modifiable field as allowing input/output changes. Older
+   * scure versions emitted PSBTv2 without this field, so this opts out of strict BIP370 behavior
+   * when upgrading and editing their PSBTs.
+   */
+  allowMissingTxModifiable?: boolean;
+  /**
+   * Deprecated alias for {@link unknown}: true selects `ignore`, false selects `strip`.
+   * @deprecated Use `unknown`.
+   */
   allowUnknown?: boolean;
 }
 
@@ -301,6 +335,7 @@ function outputBeforeSign(i: TArg<psbt.TransactionOutput>): TRet<psbt.Transactio
  * ```
  */
 export function inputBeforeSign(i: TArg<psbt.TransactionInput>): TRet<TransactionInputRequired> {
+  validateObject(i as Record<string, any>, {}, {}, 'i');
   if (i.txid === undefined || i.index === undefined)
     throw new Error('Transaction/input: txid and index required');
   const res = {
@@ -314,13 +349,65 @@ export function inputBeforeSign(i: TArg<psbt.TransactionInput>): TRet<Transactio
   RawInput.encode(res);
   return res as TRet<TransactionInputRequired>;
 }
-function cleanFinalInput(i: TArg<PSBTInputs>) {
+type ExtensionMap = { unknown?: unknown[]; proprietary?: unknown[] };
+const cleanExtensions = <T extends ExtensionMap>(
+  map: T,
+  unknownMode: Unknowns,
+  proprietaryMode: Unknowns,
+  rejectStrip = false
+): T => {
+  const out = { ...map } as T & Record<string, unknown>;
+  for (const [name, mode] of [
+    ['unknown', unknownMode],
+    ['proprietary', proprietaryMode],
+  ] as const) {
+    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 as unknown[] | undefined;
+    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: number | undefined, mode: Unknowns): number | undefined => {
+  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: TArg<PSBTInputs>,
+  unknownMode: Unknowns = 'strip',
+  proprietaryMode: Unknowns = 'strip'
+) {
   const _i = i as PSBTInputs;
+  const extensions = cleanExtensions(_i as ExtensionMap, unknownMode, proprietaryMode);
+  if (extensions.unknown) _i.unknown = extensions.unknown as PSBTInputs['unknown'];
+  else delete _i.unknown;
+  if (extensions.proprietary) _i.proprietary = extensions.proprietary as PSBTInputs['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 as keyof PSBTInputs;
+    // 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];
   }
 }
@@ -343,9 +430,27 @@ function unpackSighash(hashType: number) {
   };
 }
 
+const sighashScope = (sighash: number) => ({
+  sigInputs: sighash & SignatureHash.ANYONECANPAY,
+  sigOutputs: sighash === SignatureHash.DEFAULT ? SignatureHash.ALL : sighash & 0b11,
+});
+
+const normalizeUnknowns = (
+  name: 'unknown' | 'proprietary',
+  mode: Unknowns | undefined,
+  legacy: boolean | undefined,
+  fallback: Unknowns = 'strip'
+): Unknowns => {
+  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: TArg<TxOpts>): TRet<Readonly<TxOpts>> {
-  if (opts !== undefined && {}.toString.call(opts) !== '[object Object]')
-    throw new Error(`Wrong object type for transaction options: ${opts}`);
+  if (opts !== undefined) validateObject(opts as Record<string, any>, {}, {}, 'opts');
 
   const _opts = {
     ...opts,
@@ -360,6 +465,7 @@ function validateOpts(opts: TArg<TxOpts>): TRet<Readonly<TxOpts>> {
     _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
   // There is no PSBT v1, and any new version will probably have fields which we don't know how to parse, which
@@ -374,20 +480,28 @@ function validateOpts(opts: TArg<TxOpts>): TRet<Readonly<TxOpts>> {
     'disableScriptCheck',
     'bip174jsCompat',
     'allowLegacyWitnessUtxo',
+    'strictPrevoutValidation',
     'lowR',
+    'allowUnknown',
+    'allowMissingTxModifiable',
   ] as const) {
     const v = _opts[k];
     if (v === undefined) continue; // optional
     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)) {
@@ -405,13 +519,117 @@ function validateOpts(opts: TArg<TxOpts>): TRet<Readonly<TxOpts>> {
   return Object.freeze(_opts) as TRet<Readonly<TxOpts>>;
 }
 
+function checkTaprootInputCommitments(input: TArg<PSBTInputs>, prevScript: TArg<Bytes>): void {
+  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: TArg<Bytes>,
+    merkleRoot: TArg<Bytes>,
+    parity?: number
+  ): void => {
+    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: TArg<PSBTInputs>): void {
+  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: TArg<readonly PSBTInputs[]>,
+  fallback = DEFAULT_LOCKTIME
+): number {
+  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: TArg<psbt.TransactionInput>): TRet<PSBTInputs> {
+function validateInput(
+  i: TArg<psbt.TransactionInput>,
+  disableScriptCheck = false
+): TRet<PSBTInputs> {
+  validateObject(i as Record<string, any>, {}, {}, 'i');
   const _i = i as PSBTInputs;
+  validateRequiredLocktimes(_i);
+  let prevOut: P.UnwrapCoder<typeof RawOutput> | undefined;
   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) ||
@@ -433,6 +651,9 @@ function validateInput(i: TArg<psbt.TransactionInput>): TRet<PSBTInputs> {
         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
@@ -442,6 +663,10 @@ function validateInput(i: TArg<psbt.TransactionInput>): TRet<PSBTInputs> {
       // 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}`);
     }
+  } else if (_i.witnessUtxo) prevOut = _i.witnessUtxo;
+  if (prevOut && !disableScriptCheck) {
+    checkScript(prevOut.script, _i.redeemScript, _i.witnessScript);
+    checkTaprootInputCommitments(_i, prevOut.script);
   }
   return _i as TRet<PSBTInputs>;
 }
@@ -452,6 +677,35 @@ export type PSBTInputs = psbt.PSBTKeyMapKeys<typeof psbt.PSBTInput>;
 /** Canonical PSBT output shape used by the coder layer. */
 export type PSBTOutputs = psbt.PSBTKeyMapKeys<typeof psbt.PSBTOutput>;
 
+type InputSignature = { sighash: number; taproot: boolean; scriptPath: boolean };
+
+const inputSignatures = (input: TArg<PSBTInputs>): InputSignature[] => {
+  const _input = input as PSBTInputs;
+  const res: InputSignature[] = [];
+  const add = (signature: TArg<Bytes>, taproot: boolean, scriptPath = false) => {
+    const sig = signature as Bytes;
+    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'],
+} as const satisfies Record<string, readonly (keyof PSBTInputs)[]>;
+
 // Normalizes input
 /**
  * Extracts the previous output referenced by an input.
@@ -465,6 +719,7 @@ export type PSBTOutputs = psbt.PSBTKeyMapKeys<typeof psbt.PSBTOutput>;
  * ```
  */
 export function getPrevOut(input: TArg<psbt.TransactionInput>): P.UnwrapCoder<typeof RawOutput> {
+  validateObject(input as Record<string, any>, {}, {}, 'input');
   const _input = input as PSBTInputs;
   if (_input.nonWitnessUtxo) {
     if (_input.index === undefined) throw new Error('Unknown input index');
@@ -478,8 +733,17 @@ export function getPrevOut(input: TArg<psbt.TransactionInput>): P.UnwrapCoder<ty
     )
       throw new Error(`Wrong input index=${_input.index}`);
     return _input.nonWitnessUtxo.outputs[_input.index];
-  } else if (_input.witnessUtxo) return _input.witnessUtxo;
-  else throw new Error('Cannot find previous output info');
+  } else if ('witnessUtxo' in _input) {
+    // The presence check catches malformed provided values; narrow after the guard for TS.
+    const prev = _input.witnessUtxo as P.UnwrapCoder<typeof RawOutput>;
+    validateObject(prev as Record<string, any>, {}, {}, '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');
 }
 
 /**
@@ -487,9 +751,12 @@ export function getPrevOut(input: TArg<psbt.TransactionInput>): P.UnwrapCoder<ty
  * @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.
@@ -508,8 +775,12 @@ export function normalizeInput(
   cur?: TArg<PSBTInputs>,
   allowedFields?: TArg<readonly (keyof PSBTInputs)[]>,
   disableScriptCheck = false,
-  allowUnknown = false
+  unknown: Unknowns | boolean = 'strip',
+  proprietary: Unknowns | boolean = 'strip'
 ): TRet<PSBTInputs> {
+  validateObject(i as Record<string, any>, {}, {}, 'i');
+  if (cur !== undefined) validateObject(cur as Record<string, any>, {}, {}, 'cur');
+  if (allowedFields !== undefined) u.aarray(allowedFields, 'allowedFields');
   const _i = i as psbt.TransactionInputUpdate;
   const _cur = cur as PSBTInputs | undefined;
   const _allowedFields = allowedFields as readonly (keyof PSBTInputs)[] | undefined;
@@ -529,18 +800,26 @@ export function normalizeInput(
   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) as PSBTInputs;
+  res = psbt.mergeKeyMap(
+    psbt.PSBTInput,
+    res,
+    _cur,
+    _allowedFields,
+    unknown,
+    proprietary
+  ) as PSBTInputs;
+  // 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 as Parameters<typeof psbt.PSBTInputCoder.encode>[0]); // 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 as TRet<PSBTInputs>;
+  // 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 as TArg<psbt.TransactionInput>, disableScriptCheck);
 }
 
 /**
@@ -572,10 +851,13 @@ export function getInputType(input: TArg<psbt.TransactionInput>, allowLegacyWitn
   let txType = 'legacy';
   let defaultSighash: number = SignatureHash.ALL;
   const prevOut = getPrevOut(_input as TArg<psbt.TransactionInput>);
-  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.
@@ -592,10 +874,11 @@ export function getInputType(input: TArg<psbt.TransactionInput>, allowLegacyWitn
     if (first.type === 'wpkh' || first.type === 'wsh') txType = 'segwit';
     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
@@ -605,12 +888,12 @@ export function getInputType(input: TArg<psbt.TransactionInput>, allowLegacyWitn
       if (child.type === 'wsh') 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,
@@ -657,8 +940,62 @@ export class Transaction {
   constructor(opts: TxOpts = {}) {
     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;
+  }
+
+  private isPSBTv2(): boolean {
+    return (this.global.version ?? this.opts.PSBTVersion) === 2;
+  }
+
+  private requireTxModifiable(bit: number, kind: 'inputs' | 'outputs'): void {
+    if (!this.isPSBTv2()) return;
+    if (!(this.txModifiablePolicy() & bit)) throw new Error(`PSBTv2: ${kind} are not modifiable`);
+  }
+
+  private txModifiablePolicy(
+    allowMissing = this.opts.allowMissingTxModifiable,
+    unknownMode = this.opts.unknown!
+  ): number {
+    if (!this.isPSBTv2()) return 0b011;
+    if (this.global.txModifiable !== undefined)
+      return cleanTxModifiable(this.global.txModifiable, unknownMode)!;
+    return allowMissing ? 0b011 : 0;
+  }
+
+  private modifiable(
+    allowMissing = this.opts.allowMissingTxModifiable,
+    unknownMode = this.opts.unknown!
+  ): number {
+    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;
+  }
+
+  private get txModifiable(): number {
+    return this.modifiable();
   }
 
   // Import
@@ -696,21 +1033,54 @@ 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,
-        }) as PSBTInputs
-    );
+    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) as PSBTInputs;
+    });
     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
@@ -718,6 +1088,7 @@ export class Transaction {
   toPSBT(
     PSBTVersion: number | undefined = this.global.version || this.opts.PSBTVersion
   ): Uint8Array {
+    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) {
@@ -726,9 +1097,17 @@ export class Transaction {
     //   );
     // }
     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) as TArg<PSBTInputs>)
+      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, this.opts.disableScriptCheck) as TArg<PSBTInputs>
+        ),
+        this.opts.unknown!,
+        this.opts.proprietary!
+      )
     );
     for (const inp of inputs) {
       // Don't serialize empty fields
@@ -736,8 +1115,16 @@ export class Transaction {
       if (inp.finalScriptSig && !inp.finalScriptSig.length) delete inp.finalScriptSig;
       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
@@ -762,10 +1149,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
       // `this.global`, but PSBTv2 serializes the transaction through split global/input/output
@@ -775,13 +1164,19 @@ 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 as Parameters<typeof psbt.RawPSBTV0.encode>[0])
@@ -790,23 +1185,7 @@ export class Transaction {
 
   // BIP370 lockTime (https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki#determining-lock-time)
   get lockTime(): number {
-    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(): number {
@@ -828,6 +1207,13 @@ export class Transaction {
     if (input.partialSig && input.partialSig.length) return 'signed';
     return 'unsigned';
   }
+  private cleanFinalInput(input: PSBTInputs): void {
+    // Core preserves producer policy during finalization. Once cleanup makes signatures opaque,
+    // signStatus conservatively locks transaction mutation until the input is explicitly reopened.
+    cleanFinalInput(input as TArg<PSBTInputs>, 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!)
   private inputSighash(idx: number) {
@@ -840,30 +1226,70 @@ 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
-  private signStatus() {
+  private signatures() {
+    const res: (InputSignature & { idx: number })[] = [];
+    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;
+  }
+
+  private signedInputKeys(idx: number, signatures = this.signatures()): (keyof PSBTInputs)[] {
+    const res = new Set<keyof PSBTInputs>();
+    const add = (keys: readonly (keyof PSBTInputs)[]) => {
+      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];
+  }
+
+  private 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);
+    let inputs: number[] = [],
+      outputs: number[] = [];
+    for (const { idx, sighash } of signatures) {
+      const { sigInputs, sigOutputs } = sighashScope(sighash);
       // Input type
-      if (sigInputs === SignatureHash.ANYONECANPAY) inputs.push(idx);
-      else addInput = false;
+      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.NONE) {
+      else if (sigOutputs === SignatureHash.SINGLE) {
+        if (!outputs.includes(idx)) outputs.push(idx);
+      } else if (sigOutputs === SignatureHash.NONE) {
         // Doesn't affect any outputs at all
       } else throw new Error(`Wrong signature hash output type: ${sigOutputs}`);
     }
@@ -878,27 +1304,33 @@ export class Transaction {
 
   // Info utils
   get hasWitnesses(): boolean {
-    let out = false;
     for (const i of this.inputs)
-      if (i.finalScriptWitness && i.finalScriptWitness.length) out = true;
-    return out;
+      if (i.finalScriptWitness && i.finalScriptWitness.length) return true;
+    return false;
   }
   // https://en.bitcoin.it/wiki/Weight_units
   get weight(): number {
     if (!this.isFinal) throw new Error('Transaction is not finalized');
+    // Serialized length of VarBytes(data) without allocating the encoded copy
+    const varLen = (dataLen: number) => 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;
+    for (const o of outputs) out += 32 + 4 * varLen(o.script.length);
     // Inputs
-    if (this.hasWitnesses) out += 2;
+    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;
   }
@@ -933,8 +1365,28 @@ export class Transaction {
   }
   // Input stuff
   private checkInputIdx(idx: number) {
-    if (!Number.isSafeInteger(idx) || 0 > idx || idx >= this.inputs.length)
-      throw new Error(`Wrong input index=${idx}`);
+    anumber(idx, 'idx');
+    if (idx >= this.inputs.length) throw new Error(`Wrong input index=${idx}`);
+  }
+  private validatePrevoutsForSigning(): void {
+    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 as TArg<psbt.TransactionInput>, this.opts.disableScriptCheck);
+    }
   }
   getInput(idx: number): psbt.TransactionInput {
     this.checkInputIdx(idx);
@@ -945,15 +1397,32 @@ export class Transaction {
   }
   // Modification
   addInput(input: TArg<psbt.TransactionInputUpdate>, _ignoreSignStatus = false): number {
-    if (!_ignoreSignStatus && !this.signStatus().addInput)
-      throw new Error('Tx has signed inputs, cannot add new one');
+    validateObject(input as Record<string, any>, {}, {}, 'input');
+    cleanExtensions(input as ExtensionMap, 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)
-      ) as PSBTInputs
+    const normalized = cloneDeep(
+      normalizeInput(
+        input,
+        undefined,
+        undefined,
+        this.opts.disableScriptCheck,
+        this.opts.unknown!,
+        this.opts.proprietary!
+      )
+    ) as PSBTInputs;
+    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(
@@ -962,28 +1431,59 @@ export class Transaction {
     _ignoreSignStatus = false
   ): void {
     this.checkInputIdx(idx);
-    let allowedFields = undefined;
-    if (!_ignoreSignStatus) {
-      const status = this.signStatus();
-      if (!status.addInput || status.inputs.includes(idx))
-        allowedFields = psbt.PSBTInputUnsignedKeys;
+    cleanExtensions(input as ExtensionMap, this.opts.unknown!, this.opts.proprietary!, true);
+    let allowedFields: (keyof PSBTInputs)[] | undefined;
+    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) as (keyof PSBTInputs)[]).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(
+    const normalized = cloneDeep(
       normalizeInput(
         input,
         this.inputs[idx],
         allowedFields,
         this.opts.disableScriptCheck,
-        this.opts.allowUnknown
+        this.opts.unknown!,
+        this.opts.proprietary!
       )
     ) as PSBTInputs;
+    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
   private checkOutputIdx(idx: number) {
-    if (!Number.isSafeInteger(idx) || 0 > idx || idx >= this.outputs.length)
-      throw new Error(`Wrong output index=${idx}`);
+    anumber(idx, 'idx');
+    if (idx >= this.outputs.length) throw new Error(`Wrong output index=${idx}`);
   }
   getOutput(idx: number): psbt.TransactionOutput {
     this.checkOutputIdx(idx);
@@ -993,7 +1493,7 @@ export class Transaction {
     const out = this.getOutput(idx);
     if (!out.script) return;
     return Address(network).encode(
-      OutScript.decode(out.script) as Parameters<ReturnType<typeof Address>['encode']>[0]
+      _WitnessOutScript.decode(out.script) as Parameters<ReturnType<typeof Address>['encode']>[0]
     );
   }
 
@@ -1005,22 +1505,27 @@ export class Transaction {
     cur?: PSBTOutputs,
     allowedFields?: readonly (keyof typeof psbt.PSBTOutput)[]
   ): PSBTOutputs {
+    validateObject(o as Record<string, any>, {}, {}, '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) script = cur?.script;
     let res: PSBTOutputs = { ...cur, ...(o as PSBTOutputs & { script?: string }), 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 as Parameters<typeof psbt.PSBTOutputCoder.encode>[0]);
     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'
@@ -1030,7 +1535,11 @@ export class Transaction {
     return res;
   }
   addOutput(o: TArg<psbt.TransactionOutputUpdate>, _ignoreSignStatus = false): number {
-    if (!_ignoreSignStatus && !this.signStatus().addOutput)
+    cleanExtensions(o as ExtensionMap, 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.
@@ -1043,6 +1552,7 @@ export class Transaction {
     _ignoreSignStatus = false
   ): void {
     this.checkOutputIdx(idx);
+    cleanExtensions(output as ExtensionMap, this.opts.unknown!, this.opts.proprietary!, true);
     let allowedFields = undefined;
     if (!_ignoreSignStatus) {
       const status = this.signStatus();
@@ -1051,7 +1561,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: string, amount: bigint, network: u.BTC_NETWORK = NETWORK): number {
     return this.addOutput({
@@ -1065,7 +1583,7 @@ export class Transaction {
   }
   // Utils
   get fee(): bigint {
-    let res = 0n;
+    let res = _0n;
     for (const i of this.inputs) {
       const prevOut = getPrevOut(i);
       if (!prevOut) throw new Error('Empty input amount');
@@ -1084,7 +1602,8 @@ export class Transaction {
     const { isAny, isNone, isSingle } = unpackSighash(hashType);
     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: TransactionInputRequired[] = this.inputs
       .map(inputBeforeSign)
@@ -1124,8 +1643,8 @@ export class Transaction {
   ): Uint8Array {
     // 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}`);
+    anumber(idx, 'idx');
+    if (idx >= this.inputs.length) throw new Error(`Invalid input idx=${idx}`);
     const { isAny, isNone, isSingle } = unpackSighash(hashType);
     let inputHash = EMPTY32;
     let sequenceHash = EMPTY32;
@@ -1164,15 +1683,16 @@ export class Transaction {
     leafVer = 0xc0,
     annex?: Bytes
   ): Uint8Array {
-    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)
-      throw new Error(`Invalid input idx=${idx}`);
+    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: Bytes[] = [
       P.U8.encode(0),
       P.U8.encode(hashType), // U8 sigHash
@@ -1183,6 +1703,14 @@ 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(
         ...[
@@ -1208,16 +1736,31 @@ export class Transaction {
       );
     } else out.push(P.U32LE.encode(idx));
     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);
+    if (outType === SignatureHash.SINGLE) 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: Signer, idx: number, allowedSighash?: SigHash[], _auxRand?: Bytes): boolean {
+    if (!isBytes(privateKey)) {
+      // HDKey is a structural external instance, so plain-object validation would
+      // reject valid signers.
+      if (
+        !privateKey ||
+        typeof privateKey !== 'object' ||
+        typeof (privateKey as HDKey).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] as TArg<psbt.TransactionInput>,
+      this.opts.disableScriptCheck
+    );
     const inputType = getInputType(
       input as TArg<psbt.TransactionInput>,
       this.opts.allowLegacyWitnessUtxo
@@ -1426,6 +1969,9 @@ export class Transaction {
   // Even worse: another user can add bip32 derivation, and spend money from different address.
   // Better api: signIdx
   sign(privateKey: Signer, allowedSighash?: number[], _auxRand?: Bytes): number {
+    // 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 {
@@ -1438,19 +1984,27 @@ export class Transaction {
 
   finalizeIdx(idx: number): void {
     this.checkInputIdx(idx);
-    if (this.fee < 0n) throw new Error('Outputs spends more than inputs amount');
+    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 -
-            psbt.TaprootControlBlock.encode(b[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: Bytes[] | undefined;
+        let smallestSize = Number.POSITIVE_INFINITY;
+        let unsupported = false;
         for (const [cb, _script] of leafs) {
           // Last byte is version
           const script = _script.slice(0, -1);
@@ -1459,6 +2013,7 @@ export class Transaction {
           const hash = tapLeafHash(script, ver);
           const scriptSig = input.tapScriptSig.filter((i) => equalBytes(i[0].leafHash, hash));
           let signatures: Bytes[] = [];
+          let witness: Bytes[] | undefined;
           if (outScript.type === 'tr_ms') {
             const m = outScript.m;
             const pubkeys = outScript.pubkeys;
@@ -1498,33 +2053,43 @@ export class Transaction {
             if (!signatures.length) continue;
           } else {
             const custom = this.opts.customScripts;
+            let recognized = false;
             if (custom) {
               for (const c of custom) {
                 if (!c.finalizeTaproot) continue;
                 const scriptDecoded = Script.decode(script);
                 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 as TArg<PSBTInputs>);
-                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) throw new Error('finalize/taproot: empty witness');
+        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 as TArg<PSBTInputs>);
+      this.cleanFinalInput(input);
       return;
     }
     if (!input.partialSig || !input.partialSig.length) throw new Error('Not enough partial sign');
@@ -1584,7 +2149,7 @@ export class Transaction {
     if (!finalScriptSig && !finalScriptWitness) throw new Error('Unknown error finalizing input');
     if (finalScriptSig) input.finalScriptSig = finalScriptSig;
     if (finalScriptWitness) input.finalScriptWitness = finalScriptWitness;
-    cleanFinalInput(input as TArg<PSBTInputs>);
+    this.cleanFinalInput(input);
   }
   finalize(): void {
     for (let i = 0; i < this.inputs.length; i++) this.finalizeIdx(i);
@@ -1592,19 +2157,31 @@ export class Transaction {
   extract(): Uint8Array {
     if (!this.isFinal) throw new Error('Transaction has unfinalized inputs');
     if (!this.outputs.length) throw new Error('Transaction has no outputs');
-    if (this.fee < 0n) throw new Error('Outputs spends more than inputs amount');
+    if (this.fee < _0n) throw new Error('Outputs spends more than inputs amount');
     return this.toBytes(true, true);
   }
   combine(other: Transaction): this {
+    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'] as const) {
-      if (this.opts[k] !== 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 ${k} this=${this.opts[k]} other=${other.opts[k]}`
+          `Transaction/combine: different lockTime this=${thisLockTime} other=${otherLockTime}`
         );
-      }
     }
     for (const k of ['inputs', 'outputs'] as const) {
       if (this[k].length !== other[k].length) {
@@ -1615,18 +2192,139 @@ 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(
+    let txModifiable: number | undefined;
+    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: Transaction) => {
+        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,
-      this.global,
-      other.global,
-      undefined,
-      this.opts.allowUnknown
+      thisGlobal,
+      otherGlobal,
+      opts.unknown!,
+      opts.proprietary!
     );
-    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);
+    if (fallbackLocktime !== undefined) global.fallbackLocktime = fallbackLocktime;
+    if (PSBTVersion) 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'] as const) {
+          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!
+      ) as PSBTInputs;
+      // 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 as TArg<PSBTInputs>, opts.unknown!, opts.proprietary!);
+      return cloneDeep(
+        normalizeInput(
+          combined,
+          undefined,
+          undefined,
+          opts.disableScriptCheck,
+          opts.unknown!,
+          opts.proprietary!
+        )
+      ) as PSBTInputs;
+    });
+    // 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(): Transaction {
@@ -1638,6 +2336,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
@@ -1648,12 +2347,14 @@ export class Transaction {
  * PSBTCombine([psbt, psbt]);
  * ```
  */
-export function PSBTCombine(psbts: TArg<Bytes[]>): TRet<Bytes> {
+export function PSBTCombine(psbts: TArg<Bytes[]>, opts: TArg<TxOpts> = {}): TRet<Bytes> {
   if (!psbts || !Array.isArray(psbts) || !psbts.length)
     throw new Error('PSBTCombine: wrong PSBT list');
-  const tx = Transaction.fromPSBT(psbts[0]);
-  for (let i = 1; i < psbts.length; i++) tx.combine(Transaction.fromPSBT(psbts[i]));
-  return tx.toPSBT() as TRet<Bytes>;
+  // Options affect both map cleanup during combination and the encoding of the returned PSBT.
+  const combineOpts = opts as TxOpts;
+  const tx = Transaction.fromPSBT(psbts[0], combineOpts);
+  for (let i = 1; i < psbts.length; i++) tx.combine(Transaction.fromPSBT(psbts[i], tx.opts));
+  return tx.toPSBT(combineOpts.PSBTVersion) as TRet<Bytes>;
 }
 
 // Copy-pasted from bip32 derive, maybe do something like 'bip32.parsePath'?