@scure/btc-signer 2.2.0 → 2.4.0

package/src/psbt.ts

@@ -1,4 +1,5 @@
 import { hex } from '@scure/base';
+import { anumber, concatBytes } from '@noble/hashes/utils.js';
 import * as P from 'micro-packed';
 import {
   CompactSize,
@@ -10,17 +11,42 @@ import {
   VarBytes,
 } from './script.ts';
 import {
+  aarray,
   type Bytes,
   compareBytes,
   equalBytes,
   PubT,
   type TArg,
   type TRet,
+  validateObject,
   validatePubkey,
 } from './utils.ts';
 
 // PSBT BIP174, BIP370, BIP371
 
+/**
+ * Policy for PSBT fields this version does not understand.
+ *
+ * `ignore` preserves data for forward interoperability, but the library may operate without
+ * understanding future constraints. `strip` accepts then removes it, which can itself break
+ * interoperability with newer participants; `strict` rejects it. Non-`ignore` behavior also
+ * fingerprints noble/scure and potentially its version. When the original boolean handling was
+ * added, the PSBT registry had no assigned fields unknown to this library; assigned extensions are
+ * now explicit table entries and do not use this policy.
+ */
+export type Unknowns = 'ignore' | 'strip' | 'strict';
+type UnknownsArg = Unknowns | boolean;
+const unknowns = (mode: UnknownsArg, name: string): Unknowns => {
+  if (mode === true) return 'ignore';
+  if (mode === false) return 'strip';
+  if (mode === 'ignore' || mode === 'strip' || mode === 'strict') return mode;
+  throw new Error(`PSBT: invalid ${name} policy=${mode}`);
+};
+
+// Be friendly to bad ECMAScript parsers by not using bigint literals.
+// prettier-ignore
+const _0n = /* @__PURE__ */ BigInt(0), _1n = /* @__PURE__ */ BigInt(1);
+
 // BIP174 keydata only says "public key", so legacy PSBT ECDSA fields still accept both
 // compressed (33-byte) and uncompressed (65-byte) SEC1 encodings, but not x-only keys.
 const PubKeyECDSA: P.CoderType<Bytes> = /* @__PURE__ */ (() =>
@@ -157,9 +183,9 @@ const tapTree = /* @__PURE__ */ (() =>
         while (next.length < depth) next.push(0);
         path = next;
       }
-      let leaves = 0n;
-      for (let i = 0; i < tree.length; i++) leaves += 1n << BigInt(maxDepth - tree[i].depth);
-      if (leaves !== 1n << BigInt(maxDepth))
+      let leaves = _0n;
+      for (let i = 0; i < tree.length; i++) leaves += _1n << BigInt(maxDepth - tree[i].depth);
+      if (leaves !== _1n << BigInt(maxDepth))
         throw new Error('tapTree: tuples must describe a complete binary tree');
       return tree;
     }
@@ -169,11 +195,67 @@ const tapTree = /* @__PURE__ */ (() =>
 // field-specific structure and length checks still live at the individual field definitions.
 // Keep a distinct name here so the byte coder does not collide with the Bytes type alias.
 const BytesInf: P.CoderType<Bytes> = /* @__PURE__ */ P.bytes(null);
+// PSBTKeyMap emits the 0xfc type byte itself, so the public value remains only the bytes after it.
+// Validate that raw suffix here: otherwise a caller-supplied leading 0xfc becomes a 252-byte
+// identifier declaration which scure can relay but Bitcoin Core cannot parse.
+const ProprietaryKey = /* @__PURE__ */ (() => {
+  const suffix = P.struct({
+    identifier: P.bytes(CompactSizeLen),
+    subtype: CompactSizeLen,
+    data: BytesInf,
+  });
+  return P.validate(BytesInf, (key) => {
+    try {
+      suffix.decode(key);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Proprietary key: expected BIP174 identifier and subtype, got ${message}`);
+    }
+    return key;
+  });
+})();
 // Shared 20-byte key-data helper for the BIP174 RIPEMD160 and HASH160 preimage maps.
 const Bytes20: P.CoderType<Bytes> = /* @__PURE__ */ P.bytes(20);
 // Shared 32-byte helper for fixed-size hash / txid / merkle-root byte fields; any stronger
 // semantics such as x-only pubkey validity still need to be enforced by the field that uses it.
 const Bytes32: P.CoderType<Bytes> = /* @__PURE__ */ P.bytes(32);
+const Bytes64: P.CoderType<Bytes> = /* @__PURE__ */ P.bytes(64);
+const Bytes66: P.CoderType<Bytes> = /* @__PURE__ */ P.bytes(66);
+// BIP373 uses the same aggregate-key participant list in input and output maps.
+const MuSig2Participants = /* @__PURE__ */ (() => P.array(null, PubKeyECDSACompressed))();
+type MuSig2Key = {
+  participantPubkey: Bytes;
+  aggregatePubkey: Bytes;
+  leafHash?: Bytes;
+};
+// BIP373 keys append an optional tapleaf hash to participant || aggregate. A structured key keeps
+// the optional hash distinct while preserving the exact 66/98-byte wire encoding.
+const MuSig2Key = /* @__PURE__ */ (() =>
+  P.apply(BytesInf, {
+    decode: (key: TArg<MuSig2Key>) => {
+      const _key = key as MuSig2Key;
+      return concatBytes(
+        PubKeyECDSACompressed.encode(_key.participantPubkey),
+        PubKeyECDSACompressed.encode(_key.aggregatePubkey),
+        _key.leafHash === undefined ? P.EMPTY : Bytes32.encode(_key.leafHash)
+      );
+    },
+    encode: (raw: TArg<Bytes>): TRet<MuSig2Key> => {
+      const _raw = raw as Bytes;
+      if (_raw.length !== 66 && _raw.length !== 98)
+        throw new Error(`MuSig2 key: expected 66 or 98 bytes, got ${_raw.length}`);
+      const key: MuSig2Key = {
+        participantPubkey: PubKeyECDSACompressed.decode(_raw.subarray(0, 33)),
+        aggregatePubkey: PubKeyECDSACompressed.decode(_raw.subarray(33, 66)),
+      };
+      if (_raw.length === 98) key.leafHash = Bytes32.decode(_raw.subarray(66));
+      return key as TRet<MuSig2Key>;
+    },
+  }))();
+const SilentPaymentInfo = /* @__PURE__ */ (() =>
+  P.struct({ scanKey: PubKeyECDSACompressed, spendKey: PubKeyECDSACompressed }))();
+// BIP353 prefixes the human-readable name with one byte; the RFC9102 proof is opaque here.
+const DNSSECProof = /* @__PURE__ */ (() => P.struct({ name: P.bytes(P.U8), proof: BytesInf }))();
 type PSBTKeyCoder = P.CoderType<any> | false;
 type PSBTKeyMapInfo = Readonly<
   [
@@ -237,8 +319,12 @@ export const PSBTGlobal = /* @__PURE__ */ (() => Object.freeze({
   outputCount:      PSBTInfo(0x05, false,      CompactSizeLen, [2], [2],    false),
   // TODO: bitfield
   txModifiable:     PSBTInfo(0x06, false,      P.U8,           [],  [2],    false),
+  // These assigned extension fields must not fall through the unknown-field policy.
+  spEcdhShare:      PSBTInfo(0x07, PubKeyECDSACompressed, PubKeyECDSACompressed, [], [2], false),
+  spDleq:           PSBTInfo(0x08, PubKeyECDSACompressed, Bytes64, [], [2], false),
+  genericSignedMessage: PSBTInfo(0x09, false, BytesInf, [], [0, 2], false),
   version:          PSBTInfo(0xfb, false,      P.U32LE,        [],  [0, 2], false),
-  proprietary:      PSBTInfo(0xfc, BytesInf,   BytesInf,       [],  [0, 2], false),
+  proprietary:      PSBTInfo(0xfc, ProprietaryKey, BytesInf,   [],  [0, 2], false),
 } as const))();
 // prettier-ignore
 /**
@@ -286,7 +372,15 @@ export const PSBTInput = /* @__PURE__ */ (() => Object.freeze({
   tapBip32Derivation:     PSBTInfo(0x16, PubKeySchnorr,       TaprootBIP32Der,   [],  [0, 2], false),
   tapInternalKey:         PSBTInfo(0x17, false,               PubKeySchnorr,     [],  [0, 2], false),
   tapMerkleRoot:          PSBTInfo(0x18, false,               Bytes32,           [],  [0, 2], false),
-  proprietary:            PSBTInfo(0xfc, BytesInf,            BytesInf,          [],  [0, 2], false),
+  p2cKeyTweak:            PSBTInfo(0x19, PubKeyECDSACompressed, Bytes32,          [],  [0, 2], false),
+  musig2ParticipantPubkeys: PSBTInfo(0x1a, PubKeyECDSACompressed, MuSig2Participants, [], [0, 2], false),
+  musig2PubNonce:         PSBTInfo(0x1b, MuSig2Key,            Bytes66,           [],  [0, 2], false),
+  musig2PartialSig:       PSBTInfo(0x1c, MuSig2Key,            Bytes32,           [],  [0, 2], false),
+  spEcdhShare:            PSBTInfo(0x1d, PubKeyECDSACompressed, PubKeyECDSACompressed, [], [2], false),
+  spDleq:                 PSBTInfo(0x1e, PubKeyECDSACompressed, Bytes64,           [],  [2], false),
+  spSpendBip32Derivation: PSBTInfo(0x1f, PubKeyECDSACompressed, BIP32Der,          [],  [2], false),
+  spTweak:                PSBTInfo(0x20, false,                 Bytes32,           [],  [2], false),
+  proprietary:            PSBTInfo(0xfc, ProprietaryKey,      BytesInf,          [],  [0, 2], false),
 } as const))();
 // All other keys removed when finalizing
 /**
@@ -301,32 +395,31 @@ export const PSBTInput = /* @__PURE__ */ (() => Object.freeze({
  */
 export const PSBTInputFinalKeys = /* @__PURE__ */ Object.freeze<(keyof TransactionInput)[]>([
   // PSBTv2 extractors rebuild the final transaction from per-input fields, so
-  // finalized inputs still need txid/index (and any non-default sequence)
+  // finalized inputs still need txid/index, any non-default sequence, and locktime requirements
   // even though BIP174's generic cleanup is stricter.
   'txid',
   'sequence',
   'index',
   'witnessUtxo',
   'nonWitnessUtxo',
+  'requiredTimeLocktime',
+  'requiredHeightLocktime',
   'finalScriptSig',
   'finalScriptWitness',
   'unknown',
 ]);
 
-// Can be modified even on signed input
 /**
- * Input fields that may still change after signing starts.
+ * Signature and final-satisfaction fields used while reopening a finalized input.
  * @example
- * Signed inputs may still update these fields while new signatures are being added.
+ * Finalized inputs may remove their existing satisfaction before further mutation.
  * ```ts
- * import { PSBTInputUnsignedKeys } from '@scure/btc-signer/psbt.js';
- * const mutableKeys = new Set(PSBTInputUnsignedKeys);
+ * import { PSBTInputSignatureKeys } from '@scure/btc-signer/psbt.js';
+ * const mutableKeys = new Set(PSBTInputSignatureKeys);
  * mutableKeys.has('tapScriptSig');
  * ```
  */
-export const PSBTInputUnsignedKeys = /* @__PURE__ */ Object.freeze<(keyof TransactionInput)[]>([
-  // This is the replace/remove allowlist for signed inputs; mergeKeyMap() can still append
-  // previously absent metadata or new KV entries for other fields when they don't conflict.
+export const PSBTInputSignatureKeys = /* @__PURE__ */ Object.freeze<(keyof TransactionInput)[]>([
   'partialSig',
   'finalScriptSig',
   'finalScriptWitness',
@@ -334,6 +427,14 @@ export const PSBTInputUnsignedKeys = /* @__PURE__ */ Object.freeze<(keyof Transa
   'tapScriptSig',
 ]);
 
+/**
+ * A static list cannot describe mutable input fields because that depends on each signature's
+ * algorithm, sighash, and target index.
+ * @deprecated Use {@link PSBTInputSignatureKeys} only for signature/final-satisfaction records;
+ * transaction mutation is enforced by {@link Transaction.updateInput}.
+ */
+export const PSBTInputUnsignedKeys = PSBTInputSignatureKeys;
+
 // prettier-ignore
 /**
  * PSBT output key definitions.
@@ -357,7 +458,11 @@ export const PSBTOutput = /* @__PURE__ */ (() => Object.freeze({
   // reconstruct the same Taproot tree, not just an arbitrary list of serialized leaves.
   tapTree:            PSBTInfo(0x06, false,         tapTree,         [],  [0, 2], false),
   tapBip32Derivation: PSBTInfo(0x07, PubKeySchnorr, TaprootBIP32Der, [],  [0, 2], false),
-  proprietary:        PSBTInfo(0xfc, BytesInf,      BytesInf,        [],  [0, 2], false),
+  musig2ParticipantPubkeys: PSBTInfo(0x08, PubKeyECDSACompressed, MuSig2Participants, [], [0, 2], false),
+  spV0Info:            PSBTInfo(0x09, false,         SilentPaymentInfo, [],  [2],    false),
+  spV0Label:           PSBTInfo(0x0a, false,         P.U32LE,           [],  [2],    false),
+  dnssecProof:         PSBTInfo(0x35, false,         DNSSECProof,       [],  [0, 2], false),
+  proprietary:        PSBTInfo(0xfc, ProprietaryKey, BytesInf,        [],  [0, 2], false),
 } as const))();
 
 // Can be modified even on signed input
@@ -593,7 +698,7 @@ export const PSBTOutputCoder = /* @__PURE__ */ (() =>
       // in the field coder itself because BIP371 constrains the tuple value, not just the row shape.
       // BIP174/BIP370 define PSBT_OUT_AMOUNT as a signed int64 transport field, but it still
       // represents the transaction output amount in satoshis, so negative output values are invalid.
-      if (o.amount !== undefined && o.amount < 0n)
+      if (o.amount !== undefined && o.amount < _0n)
         throw new Error(`validateOutput: wrong amount=${o.amount}`);
       if (o.bip32Derivation) for (const [k] of o.bip32Derivation) validatePubkey(k, PubT.ecdsa);
       return o;
@@ -726,6 +831,9 @@ export function cleanPSBTFields<T extends PSBTKeyMap>(
   info: T,
   lst: TArg<PSBTKeyMapKeys<T>>
 ): TRet<PSBTKeyMapKeys<T>> {
+  anumber(version, 'version');
+  validateObject(info as Record<string, any>, {}, {}, 'info');
+  validateObject(lst as Record<string, any>, {}, {}, 'lst');
   const _lst = lst as PSBTKeyMapKeys<T>;
   const out: PSBTKeyMapKeys<T> = {};
   for (const _k in _lst) {
@@ -747,27 +855,35 @@ export function cleanPSBTFields<T extends PSBTKeyMap>(
   return out as TRet<PSBTKeyMapKeys<T>>;
 }
 
-function validatePSBT(tx: P.UnwrapCoder<PSBTRaw>) {
+function validatePSBT(tx: P.UnwrapCoder<PSBTRaw>): P.UnwrapCoder<PSBTRaw> {
   const version = (tx && tx.global && tx.global.version) || 0;
   validatePSBTFields(version, PSBTGlobal, tx.global);
   for (const i of tx.inputs) validatePSBTFields(version, PSBTInput, i);
   for (const o of tx.outputs) validatePSBTFields(version, PSBTOutput, o);
   // BIP174 defines `<psbt> := <magic> <global-map> <input-map>* <output-map>*`, so after decode the
   // number of input/output maps should match the unsigned tx. PSBTv2 makes the same shape explicit
-  // through `inputCount` / `outputCount`. We intentionally violate that strict reading for one case:
-  // keep accepting exactly one trailing empty map because the separate bitcoinjs compatibility PSBT
-  // fixture corpus still contains that encoding. Anything non-empty or more than one extra map is
-  // still rejected here.
+  // through `inputCount` / `outputCount`. Input maps are count-framed and must match exactly.
   const inputCount = !version ? tx.global.unsignedTx!.inputs.length : tx.global.inputCount!;
-  if (tx.inputs.length < inputCount) throw new Error('Not enough inputs');
-  const inputsLeft = tx.inputs.slice(inputCount);
-  if (inputsLeft.length > 1 || (inputsLeft.length && Object.keys(inputsLeft[0]).length))
-    throw new Error(`Unexpected inputs left in tx=${inputsLeft}`);
-  // Same carve-out for outputs.
+  if (tx.inputs.length !== inputCount)
+    throw new Error(`Wrong number of input maps=${tx.inputs.length}, expected=${inputCount}`);
+  // PSBTv0 compatibility mode may append exactly one empty output map when the unsigned
+  // transaction has no outputs. bip174js additionally inserts an empty input map when there are
+  // no inputs; count-framing makes that map appear before the real output maps in this array.
+  // PSBTv2 map counts remain strict.
   const outputCount = !version ? tx.global.unsignedTx!.outputs.length : tx.global.outputCount!;
   if (tx.outputs.length < outputCount) throw new Error('Not outputs inputs');
+  const hasBip174InputMap =
+    version === 0 &&
+    inputCount === 0 &&
+    Object.keys(tx.outputs[0] || {}).length === 0 &&
+    ((outputCount > 0 && tx.outputs.length === outputCount + 1) ||
+      (outputCount === 0 && tx.outputs.length === 2 && Object.keys(tx.outputs[1]).length === 0));
+  if (hasBip174InputMap) return tx;
   const outputsLeft = tx.outputs.slice(outputCount);
-  if (outputsLeft.length > 1 || (outputsLeft.length && Object.keys(outputsLeft[0]).length))
+  if (
+    outputsLeft.length > 1 ||
+    (outputsLeft.length && (version !== 0 || Object.keys(outputsLeft[0]).length))
+  )
     throw new Error(`Unexpected outputs left in tx=${outputsLeft}`);
   return tx;
 }
@@ -778,7 +894,8 @@ function validatePSBT(tx: P.UnwrapCoder<PSBTRaw>) {
  * @param val - new values to merge in
  * @param cur - existing decoded PSBT key map
  * @param allowedFields - fields still allowed to change
- * @param allowUnknown - whether to preserve unknown PSBT fields
+ * @param unknown - handling policy for unknown PSBT fields
+ * @param proprietary - handling policy for proprietary PSBT fields
  * @returns Merged PSBT key map.
  * @throws If keyed PSBT fields conflict or signed fields would be removed. {@link Error}
  * @example
@@ -801,15 +918,34 @@ export function mergeKeyMap<T extends PSBTKeyMap>(
   val: TArg<PSBTKeyMapKeys<T>>,
   cur?: TArg<PSBTKeyMapKeys<T>>,
   allowedFields?: TArg<readonly (keyof PSBTKeyMapKeys<T>)[]>,
-  allowUnknown?: boolean
+  unknown: UnknownsArg = 'strip',
+  proprietary: UnknownsArg = 'strip'
 ): TRet<PSBTKeyMapKeys<T>> {
+  validateObject(psbtEnum as Record<string, any>, {}, {}, 'psbtEnum');
+  validateObject(val as Record<string, any>, {}, {}, 'val');
+  if (cur !== undefined) validateObject(cur as Record<string, any>, {}, {}, 'cur');
+  if (allowedFields !== undefined) aarray(allowedFields, 'allowedFields');
   const _val = val as PSBTKeyMapKeys<T>;
   const _cur = cur as PSBTKeyMapKeys<T> | undefined;
   const _allowedFields = allowedFields as readonly (keyof PSBTKeyMapKeys<T>)[] | undefined;
+  const unknownMode = unknowns(unknown, 'unknown');
+  const proprietaryMode = unknowns(proprietary, 'proprietary');
+  for (const [name, mode] of [
+    ['unknown', unknownMode],
+    ['proprietary', proprietaryMode],
+  ] as const) {
+    if (mode !== 'strict') continue;
+    if (
+      (_val[name] as unknown[] | undefined)?.length ||
+      (_cur?.[name] as unknown[] | undefined)?.length
+    )
+      throw new Error(`PSBT: ${name} PSBT field is not allowed in strict mode`);
+  }
   const res: PSBTKeyMapKeys<T> = { ..._cur, ..._val };
   // All arguments can be provided as hex
   for (const k in psbtEnum) {
     const key = k as keyof typeof psbtEnum;
+    if (k === 'proprietary' && proprietaryMode !== 'ignore') continue;
     const [_, kC, vC] = psbtEnum[key];
     type _KV = [P.UnwrapCoder<typeof kC>, P.UnwrapCoder<typeof vC>];
     const cannotChange = _allowedFields && !_allowedFields.includes(k);
@@ -852,19 +988,27 @@ export function mergeKeyMap<T extends PSBTKeyMap>(
           if (v === undefined) {
             if (cannotChange) throw new Error(`Cannot remove signed field=${key as string}/${k}`);
             delete map[kStr];
-          } else add(kStr, k, v);
+          } else {
+            if (cannotChange && map[kStr] === undefined)
+              throw new Error(`Cannot add signed field=${key as string}/${kStr}`);
+            add(kStr, k, v);
+          }
         }
         (res as any)[key] = Object.values(map) as _KV[];
       }
-    } else if (typeof res[k] === 'string') {
-      res[k] = vC.decode(hex.decode(res[k] as string));
-    } else if (cannotChange && k in _val && _cur && _cur[k] !== undefined) {
-      if (!equalBytes(vC.encode(_val[k]), vC.encode(_cur[k])))
-        throw new Error(`Cannot change signed field=${k}`);
+    } else {
+      if (typeof res[k] === 'string') res[k] = vC.decode(hex.decode(res[k] as string));
+      if (cannotChange && k in _val) {
+        if (!_cur || _cur[k] === undefined) throw new Error(`Cannot add signed field=${k}`);
+        let current = _cur[k];
+        if (typeof current === 'string') current = vC.decode(hex.decode(current));
+        if (!equalBytes(vC.encode(res[k]), vC.encode(current)))
+          throw new Error(`Cannot change signed field=${k}`);
+      }
     }
   }
-  if (allowUnknown && _val.unknown) {
-    // Unknown PSBT rows are stripped by default here, but explicit allowUnknown mode is pass-through.
+  if (unknownMode === 'ignore' && _val.unknown) {
+    // Unknown PSBT rows are stripped by default here, but explicit ignore mode is pass-through.
     // Merge them by full serialized unknown key so repeated updates do not clobber earlier opaque rows.
     const map: Record<string, [P.UnwrapCoder<typeof PSBTUnknownKey>, Bytes]> = {};
     for (const [k, v] of _cur?.unknown || []) map[hex.encode(PSBTUnknownKey.encode(k))] = [k, v];
@@ -881,16 +1025,61 @@ export function mergeKeyMap<T extends PSBTKeyMap>(
     }
     res.unknown = Object.values(map);
   }
-  // Remove unknown keys except the "unknown" array if allowUnknown is true
+  // Remove properties outside the table, except opaque rows in explicit ignore mode.
   for (const k in res) {
     if (!psbtEnum[k]) {
-      if (allowUnknown && k === 'unknown') continue;
+      if (unknownMode === 'ignore' && k === 'unknown') continue;
       delete res[k];
     }
   }
+  if (unknownMode !== 'ignore') delete res.unknown;
+  if (proprietaryMode !== 'ignore') delete res.proprietary;
   return res as TRet<PSBTKeyMapKeys<T>>;
 }
 
+/**
+ * Combines two independently produced PSBT maps without choosing between conflicting scalar
+ * values. Keyed fields retain {@link mergeKeyMap}'s union semantics.
+ * @param psbtEnum - PSBT field definition table
+ * @param current - first map
+ * @param other - second map
+ * @param unknown - handling policy for unknown PSBT fields
+ * @param proprietary - handling policy for proprietary PSBT fields
+ * @returns The symmetric map union.
+ * @throws If both maps provide different values for the same scalar field. {@link Error}
+ * @example
+ * Combine disjoint global metadata without choosing an operand as authoritative.
+ * ```ts
+ * import { combineKeyMap, PSBTGlobal } from '@scure/btc-signer/psbt.js';
+ * combineKeyMap(PSBTGlobal, { txVersion: 2 }, { fallbackLocktime: 0 });
+ * ```
+ */
+export function combineKeyMap<T extends PSBTKeyMap>(
+  psbtEnum: T,
+  current: TArg<PSBTKeyMapKeys<T>>,
+  other: TArg<PSBTKeyMapKeys<T>>,
+  unknown: UnknownsArg = 'strip',
+  proprietary: UnknownsArg = 'strip'
+): TRet<PSBTKeyMapKeys<T>> {
+  validateObject(psbtEnum as Record<string, any>, {}, {}, 'psbtEnum');
+  validateObject(current as Record<string, any>, {}, {}, 'current');
+  validateObject(other as Record<string, any>, {}, {}, 'other');
+  const _current = current as PSBTKeyMapKeys<T>;
+  const _other = other as PSBTKeyMapKeys<T>;
+  for (const k in psbtEnum) {
+    const key = k as keyof typeof psbtEnum;
+    const [_, keyCoder, valueCoder] = psbtEnum[key];
+    if (keyCoder || _current[key] === undefined || _other[key] === undefined) continue;
+    let a = _current[key];
+    let b = _other[key];
+    if (typeof a === 'string') a = valueCoder.decode(hex.decode(a));
+    if (typeof b === 'string') b = valueCoder.decode(hex.decode(b));
+    if (!equalBytes(valueCoder.encode(a), valueCoder.encode(b)))
+      throw new Error(`Cannot combine conflicting field=${k}`);
+  }
+  return mergeKeyMap(psbtEnum, _other, _current, undefined, unknown, proprietary);
+}
+
 /** Validated PSBTv0 coder. */
 // This wrapper only layers `validatePSBT`'s PSBTv0 field/count reconciliation on top of
 // `_RawPSBTV0`; field-specific payload invariants still depend on the nested coders/tables.

package/src/script.ts

@@ -1,5 +1,14 @@
 import * as P from 'micro-packed';
-import { isBytes, reverseObject, type ValueOf, type Bytes, type TArg, type TRet } from './utils.ts';
+import {
+  aarray,
+  abytes,
+  isBytes,
+  reverseObject,
+  type Bytes,
+  type TArg,
+  type TRet,
+  type ValueOf,
+} from './utils.ts';
 
 /**
  * Maximum byte size allowed for a single pushed script element.
@@ -8,6 +17,12 @@ import { isBytes, reverseObject, type ValueOf, type Bytes, type TArg, type TRet
  */
 export const MAX_SCRIPT_BYTE_LENGTH = 520;
 
+// Be friendly to bad ECMAScript parsers by not using bigint literals.
+// prettier-ignore
+const _0n = /* @__PURE__ */ BigInt(0), _1n = /* @__PURE__ */ BigInt(1), _2n = /* @__PURE__ */ BigInt(2), _8n = /* @__PURE__ */ BigInt(8);
+const U8_MAX = /* @__PURE__ */ BigInt(0xff);
+const COMPACT_DIRECT_MAX = /* @__PURE__ */ BigInt(0xfc);
+
 // prettier-ignore
 /**
  * Bitcoin Script opcode table.
@@ -87,11 +102,11 @@ export type ScriptType = ScriptOP[];
 export function ScriptNum(bytesLimit = 6, forceMinimal = false): P.CoderType<bigint> {
   return P.wrap({
     encodeStream: (w: P.Writer, value: bigint) => {
-      if (value === 0n) return;
+      if (value === _0n) return;
       const neg = value < 0;
       const val = BigInt(value);
       const nums = [];
-      for (let abs = neg ? -val : val; abs; abs >>= 8n) nums.push(Number(abs & 0xffn));
+      for (let abs = neg ? -val : val; abs; abs >>= _8n) nums.push(Number(abs & U8_MAX));
       if (nums[nums.length - 1] >= 0x80) nums.push(neg ? 0x80 : 0);
       else if (neg) nums[nums.length - 1] |= 0x80;
       w.bytes(new Uint8Array(nums));
@@ -100,24 +115,22 @@ export function ScriptNum(bytesLimit = 6, forceMinimal = false): P.CoderType<big
       const len = r.leftBytes;
       if (len > bytesLimit)
         throw new Error(`ScriptNum: number (${len}) bigger than limit=${bytesLimit}`);
-      if (len === 0) return 0n;
+      if (len === 0) return _0n;
+      // Read the payload once instead of peeking for the minimality check and
+      // then re-reading it byte-by-byte through the Reader.
+      const data = r.bytes(len);
       if (forceMinimal) {
-        const data = r.bytes(len, true);
         // MSB is zero (without sign bit) -> not minimally encoded
-        if ((data[data.length - 1] & 0x7f) === 0) {
+        if ((data[len - 1] & 0x7f) === 0) {
           // exception
-          if (len <= 1 || (data[data.length - 2] & 0x80) === 0)
+          if (len <= 1 || (data[len - 2] & 0x80) === 0)
             throw new Error('Non-minimally encoded ScriptNum');
         }
       }
-      let last = 0;
-      let res = 0n;
-      for (let i = 0; i < len; ++i) {
-        last = r.byte();
-        res |= BigInt(last) << (8n * BigInt(i));
-      }
-      if (last >= 0x80) {
-        res &= (2n ** BigInt(len * 8) - 1n) >> 1n;
+      let res = _0n;
+      for (let i = 0; i < len; ++i) res |= BigInt(data[i]) << (_8n * BigInt(i));
+      if (data[len - 1] >= 0x80) {
+        res &= (_2n ** BigInt(len * 8) - _1n) >> _1n;
         res = -res;
       }
       return res;
@@ -148,7 +161,9 @@ export function OpToNum(
   if (isBytes(op)) {
     try {
       const val = ScriptNum(bytesLimit, forceMinimal).decode(op);
-      if (val > Number.MAX_SAFE_INTEGER) return;
+      // Symmetric safe-integer bound: large negative values would otherwise
+      // coerce through Number() with silent precision loss.
+      if (val > Number.MAX_SAFE_INTEGER || val < -Number.MAX_SAFE_INTEGER) return;
       return Number(val);
     } catch (e) {
       return;
@@ -203,10 +218,14 @@ export const Script: TRet<P.CoderType<ScriptType>> = /* @__PURE__ */ (() =>
   Object.freeze(
     P.wrap({
       encodeStream: (w: P.Writer, value: TArg<ScriptType>) => {
+        aarray(value, 'value');
         for (let o of value) {
           if (typeof o === 'string') {
-            if (OP[o] === undefined) throw new Error(`Unknown opcode=${o}`);
-            w.byte(OP[o]);
+            const op = OP[o];
+            // OP is a plain object, so inherited Object.prototype keys ('toString',
+            // 'constructor', ...) are not opcodes and must be rejected here too.
+            if (typeof op !== 'number') throw new Error(`Unknown opcode=${o}`);
+            w.byte(op);
             continue;
           } else if (typeof o === 'number') {
             if (o === 0x00) {
@@ -224,7 +243,7 @@ export const Script: TRet<P.CoderType<ScriptType>> = /* @__PURE__ */ (() =>
           }
           // Encode big numbers
           if (typeof o === 'number') o = ScriptNum().encode(BigInt(o));
-          if (!isBytes(o)) throw new Error(`Wrong Script OP=${o} (${typeof o})`);
+          abytes(o, undefined, 'value');
           // Bytes
           const len = o.length;
           if (len < OP.PUSHDATA1) w.byte(len);
@@ -267,13 +286,6 @@ export const Script: TRet<P.CoderType<ScriptType>> = /* @__PURE__ */ (() =>
     })
   ))() as TRet<P.CoderType<ScriptType>>;
 
-// BTC specific variable length integer encoding
-// https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer
-const CSLimits: Record<number, [number, number, bigint, bigint]> = {
-  0xfd: [0xfd, 2, 253n, 65535n],
-  0xfe: [0xfe, 4, 65536n, 4294967295n],
-  0xff: [0xff, 8, 4294967296n, 18446744073709551615n],
-};
 /**
  * Bitcoin CompactSize integer coder.
  * @example
@@ -282,16 +294,25 @@ const CSLimits: Record<number, [number, number, bigint, bigint]> = {
  * CompactSize.encode(1n);
  * ```
  */
-export const CompactSize: P.CoderType<bigint> = /* @__PURE__ */ (() =>
-  Object.freeze(
+export const CompactSize: P.CoderType<bigint> = /* @__PURE__ */ (() => {
+  // BTC specific variable length integer encoding
+  // https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer
+  const limits: Record<number, [number, number, bigint, bigint]> = {
+    0xfd: [0xfd, 2, BigInt(0xfd), BigInt(0xffff)],
+    0xfe: [0xfe, 4, BigInt(0x10000), BigInt(0xffffffff)],
+    0xff: [0xff, 8, BigInt(0x100000000), BigInt('0xffffffffffffffff')],
+  };
+  // Hoisted: Object.values() would otherwise allocate a fresh array on every encode.
+  const limitsList = Object.values(limits);
+  return Object.freeze(
     P.wrap({
       encodeStream: (w: P.Writer, value: bigint) => {
         if (typeof value === 'number') value = BigInt(value);
-        if (0n <= value && value <= 252n) return w.byte(Number(value));
-        for (const [flag, bytes, start, stop] of Object.values(CSLimits)) {
+        if (_0n <= value && value <= COMPACT_DIRECT_MAX) return w.byte(Number(value));
+        for (const [flag, bytes, start, stop] of limitsList) {
           if (start > value || value > stop) continue;
           w.byte(flag);
-          for (let i = 0; i < bytes; i++) w.byte(Number((value >> (8n * BigInt(i))) & 0xffn));
+          for (let i = 0; i < bytes; i++) w.byte(Number((value >> (_8n * BigInt(i))) & U8_MAX));
           return;
         }
         throw w.err(`VarInt too big: ${value}`);
@@ -299,16 +320,17 @@ export const CompactSize: P.CoderType<bigint> = /* @__PURE__ */ (() =>
       decodeStream: (r: P.Reader): bigint => {
         const b0 = r.byte();
         if (b0 <= 0xfc) return BigInt(b0);
-        const [_, bytes, start] = CSLimits[b0];
-        let num = 0n;
-        for (let i = 0; i < bytes; i++) num |= BigInt(r.byte()) << (8n * BigInt(i));
+        const [_, bytes, start] = limits[b0];
+        let num = _0n;
+        for (let i = 0; i < bytes; i++) num |= BigInt(r.byte()) << (_8n * BigInt(i));
         // BIP 152 / BIP 174: CompactSize fields must use the shortest encoding,
         // so wider prefixes for smaller values are rejected here.
         if (num < start) throw r.err(`Wrong CompactSize(${8 * bytes})`);
         return num;
       },
     })
-  ))();
+  );
+})();
 
 // Same thing, but in number instead of bigint. Checks for safe integer inside
 /**