@scure/btc-signer 2.0.0 → 2.2.0

package/psbt.js

@@ -1,95 +1,246 @@
 import { hex } from '@scure/base';
 import * as P from 'micro-packed';
 import { CompactSize, CompactSizeLen, RawOldTx, RawOutput, RawTx, RawWitness, VarBytes, } from "./script.js";
-import { compareBytes, equalBytes, PubT, validatePubkey } from "./utils.js";
+import { compareBytes, equalBytes, PubT, validatePubkey, } from "./utils.js";
 // PSBT BIP174, BIP370, BIP371
-// Can be 33 or 64 bytes
-const PubKeyECDSA = P.validate(P.bytes(null), (pub) => validatePubkey(pub, PubT.ecdsa));
-const PubKeySchnorr = P.validate(P.bytes(32), (pub) => validatePubkey(pub, PubT.schnorr));
-const SignatureSchnorr = P.validate(P.bytes(null), (sig) => {
+// 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 = /* @__PURE__ */ (() => P.validate(P.bytes(null), (pub) => validatePubkey(pub, PubT.ecdsa)))();
+// BIP32 serialized xpub payloads specifically store `ser_P(K)`, which is always the 33-byte
+// compressed SEC1 encoding of the public key rather than the looser legacy PSBT "any ECDSA pubkey".
+const PubKeyECDSACompressed = /* @__PURE__ */ (() => P.validate(P.bytes(33), (pub) => validatePubkey(pub, PubT.ecdsa)))();
+// BIP371 taproot PSBT key fields use 32-byte x-only pubkeys, so this coder keeps the
+// fixed-length check and then reuses the shared Schnorr pubkey validator.
+const PubKeySchnorr = /* @__PURE__ */ (() => P.validate(P.bytes(32), (pub) => validatePubkey(pub, PubT.schnorr)))();
+// BIP371 taproot signature fields carry the 64-byte Schnorr signature, plus an optional
+// trailing sighash byte when the signer used anything other than the default key-path mode.
+const SignatureSchnorr = /* @__PURE__ */ (() => P.validate(P.bytes(null), (sig) => {
     if (sig.length !== 64 && sig.length !== 65)
         throw new Error('Schnorr signature should be 64 or 65 bytes long');
     return sig;
-});
-const BIP32Der = P.struct({
+}))();
+// PSBTInput.finalScriptWitness should keep the historical decoded witness-stack shape even though
+// the exported RawWitness coder now uses TRet for declaration stability.
+const RawWitnessWire = RawWitness;
+// BIP174 stores the 4-byte master fingerprint as-is, then appends each child index in
+// 32-bit little-endian order; cross-field checks like xpub depth matching live above this.
+const BIP32Der = /* @__PURE__ */ (() => P.struct({
     fingerprint: P.U32BE,
     path: P.array(null, P.U32LE),
-});
-const TaprootBIP32Der = P.struct({
+}))();
+// BIP371 prepends the shared BIP32 derivation payload with the tapleaf-hash list; internal keys
+// use `hashes.length === 0`, while script-path keys list the leaves that actually use that pubkey.
+const TaprootBIP32Der = /* @__PURE__ */ (() => P.struct({
     hashes: P.array(CompactSizeLen, P.bytes(32)),
     der: BIP32Der,
-});
-// The 78 byte serialized extended public key as defined by BIP 32.
-const GlobalXPUB = P.bytes(78);
-const tapScriptSigKey = P.struct({ pubKey: PubKeySchnorr, leafHash: P.bytes(32) });
+}))();
+// BIP174 `PSBT_GLOBAL_XPUB` says the key is "The 78 byte serialized extended public key as
+// defined by BIP 32", so decode it to the actual BIP32 field layout instead of preserving an
+// opaque blob. We intentionally do not hardcode version-byte policy here because BIP32 version
+// bytes vary by network / deployment; this layer just parses the field and enforces the BIP32
+// import rules that are independent of network selection.
+const GlobalXPUB = /* @__PURE__ */ (() => P.validate(P.struct({
+    version: P.U32BE,
+    depth: P.U8,
+    parentFingerprint: P.U32BE,
+    childNumber: P.U32BE,
+    chainCode: P.bytes(32),
+    // BIP32 serialization stores the public key as the final 33-byte `ser_P(K)` field and says
+    // importing an extended public key must verify that point data corresponds to the curve.
+    publicKey: PubKeyECDSACompressed,
+}), (xpub) => {
+    // BIP32 serialization says master nodes use depth 0 with zero parent
+    // fingerprint and zero child number. The invalid examples explicitly
+    // include zero-depth xpubs with either field non-zero.
+    if (xpub.depth === 0 && xpub.parentFingerprint !== 0)
+        throw new Error('GlobalXPUB: depth=0 requires parentFingerprint=0');
+    if (xpub.depth === 0 && xpub.childNumber !== 0)
+        throw new Error('GlobalXPUB: depth=0 requires childNumber=0');
+    return xpub;
+}))();
+// BIP371 puts the x-only pubkey and leaf hash into the key side of `PSBT_IN_TAP_SCRIPT_SIG`;
+// the actual 64/65-byte Schnorr signature stays in the value side under `SignatureSchnorr`.
+const tapScriptSigKey = /* @__PURE__ */ (() => P.struct({ pubKey: PubKeySchnorr, leafHash: P.bytes(32) }))();
 // Complex structure for PSBT fields
 // <control byte with leaf version and parity bit> <internal key p> <C> <E> <AB>
-const _TaprootControlBlock = P.struct({
+// Raw BIP341 control-block layout only; the exported TaprootControlBlock wrapper adds the
+// `0..128` Merkle-depth bound, and later taproot logic checks version/parity semantics.
+const _TaprootControlBlock = /* @__PURE__ */ (() => P.struct({
     version: P.U8, // With parity :(
     internalKey: P.bytes(32),
     merklePath: P.array(null, P.bytes(32)),
-});
-export const TaprootControlBlock = P.validate(_TaprootControlBlock, (cb) => {
+}))();
+/**
+ * Taproot control block coder.
+ * @example
+ * Encode the Taproot control block attached to a script-path witness.
+ * ```ts
+ * import { TaprootControlBlock } from '@scure/btc-signer/psbt.js';
+ * import { pubSchnorr, randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * TaprootControlBlock.encode({
+ *   version: 0xc0,
+ *   internalKey: pubSchnorr(randomPrivateKeyBytes()),
+ *   merklePath: [],
+ * });
+ * ```
+ */
+export const TaprootControlBlock = /* @__PURE__ */ (() => Object.freeze(P.validate(_TaprootControlBlock, (cb) => {
+    // BIP 341 control blocks are raw 33+32m byte records; this PSBT coder only enforces
+    // the length/depth shape here and leaves curve / leaf-version validation to taproot logic.
     if (cb.merklePath.length > 128)
         throw new Error('TaprootControlBlock: merklePath should be of length 0..128 (inclusive)');
     return cb;
-});
+})))();
+// BIP371 says PSBT_OUT_TAP_TREE is one or more tuples in DFS order so the Taproot tree can be
+// reconstructed. Validate both the non-empty requirement and that the leaf-depth sequence really
+// describes a complete left-to-right DFS walk of a binary tree, not just arbitrary tuples.
 // {<8-bit uint depth> <8-bit uint leaf version> <compact size uint scriptlen> <bytes script>}*
-const tapTree = P.array(null, P.struct({
+const tapTree = /* @__PURE__ */ (() => P.validate(P.array(null, P.struct({
     depth: P.U8,
     version: P.U8,
     script: VarBytes,
-}));
-const BytesInf = P.bytes(null); // Bytes will conflict with Bytes type
-const Bytes20 = P.bytes(20);
-const Bytes32 = P.bytes(32);
+})), (tree) => {
+    if (tree.length < 1)
+        throw new Error('tapTree: expected at least one tuple');
+    let path = Array(tree[0].depth).fill(0);
+    let maxDepth = tree[0].depth;
+    for (let i = 1; i < tree.length; i++) {
+        const { depth } = tree[i];
+        if (depth > maxDepth)
+            maxDepth = depth;
+        let j = path.length - 1;
+        while (j >= 0 && path[j] === 1)
+            j--;
+        if (j < 0)
+            throw new Error('tapTree: tuples must be in DFS order');
+        const next = path.slice(0, j);
+        next.push(1);
+        if (depth < next.length)
+            throw new Error('tapTree: tuples must be in DFS order');
+        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))
+        throw new Error('tapTree: tuples must describe a complete binary tree');
+    return tree;
+}))();
+// Shared raw PSBT byte payload coder for fields whose BIP174 value format is just opaque bytes;
+// 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 = /* @__PURE__ */ P.bytes(null);
+// Shared 20-byte key-data helper for the BIP174 RIPEMD160 and HASH160 preimage maps.
+const Bytes20 = /* @__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 = /* @__PURE__ */ P.bytes(32);
+// jsbt mutate checks exported PSBT tables recursively, so freeze each field tuple and its
+// nested version arrays here while preserving the original coder slot types for local inference.
+const PSBTInfo = (type, kc, vc, reqInc, allowInc, silentIgnore) => 
+/* @__PURE__ */ Object.freeze([
+    type,
+    kc && typeof kc === 'object' ? Object.freeze(kc) : kc,
+    vc && typeof vc === 'object' ? Object.freeze(vc) : vc,
+    Object.freeze([...reqInc]),
+    Object.freeze([...allowInc]),
+    silentIgnore,
+]);
 // versionsRequiringExclusing = !versionsAllowsInclusion (as set)
-// {name: [tag, keyCoder, valueCoder, versionsRequiringInclusion, versionsRequiringExclusing, versionsAllowsInclusion, silentIgnore]}
-// SilentIgnore: we use some v2 fields for v1 representation too, so we just clean them before serialize
+// {name: [tag, keyCoder, valueCoder, versionsRequiringInclusion,
+// versionsRequiringExclusing, versionsAllowsInclusion, silentIgnore]}
+// SilentIgnore: we use some v2 fields for v1 representation too,
+// so we just clean them before serialize.
 // Tables from BIP-0174 (https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki)
 // prettier-ignore
-export const PSBTGlobal = {
-    unsignedTx: [0x00, false, RawOldTx, [0], [0], false],
-    xpub: [0x01, GlobalXPUB, BIP32Der, [], [0, 2], false],
-    txVersion: [0x02, false, P.U32LE, [2], [2], false],
-    fallbackLocktime: [0x03, false, P.U32LE, [], [2], false],
-    inputCount: [0x04, false, CompactSizeLen, [2], [2], false],
-    outputCount: [0x05, false, CompactSizeLen, [2], [2], false],
-    txModifiable: [0x06, false, P.U8, [], [2], false], // TODO: bitfield
-    version: [0xfb, false, P.U32LE, [], [0, 2], false],
-    proprietary: [0xfc, BytesInf, BytesInf, [], [0, 2], false],
-};
+/**
+ * PSBT global key definitions.
+ * @example
+ * Keep only the fields that are valid for the target PSBT version before serializing.
+ * ```ts
+ * import { PSBTGlobal, cleanPSBTFields } from '@scure/btc-signer/psbt.js';
+ * cleanPSBTFields(2, PSBTGlobal, { txVersion: 2, inputCount: 1, outputCount: 1 });
+ * ```
+ */
+export const PSBTGlobal = /* @__PURE__ */ (() => Object.freeze({
+    unsignedTx: PSBTInfo(0x00, false, RawOldTx, [0], [0], false),
+    // BIP174 also requires the serialized xpub depth to match the number of path elements in the
+    // paired derivation value, so callers still need that cross-field check above this raw table.
+    xpub: PSBTInfo(0x01, GlobalXPUB, BIP32Der, [], [0, 2], false),
+    txVersion: PSBTInfo(0x02, false, P.U32LE, [2], [2], false),
+    fallbackLocktime: PSBTInfo(0x03, false, P.U32LE, [], [2], false),
+    inputCount: PSBTInfo(0x04, false, CompactSizeLen, [2], [2], false),
+    outputCount: PSBTInfo(0x05, false, CompactSizeLen, [2], [2], false),
+    // TODO: bitfield
+    txModifiable: PSBTInfo(0x06, false, P.U8, [], [2], false),
+    version: PSBTInfo(0xfb, false, P.U32LE, [], [0, 2], false),
+    proprietary: PSBTInfo(0xfc, BytesInf, BytesInf, [], [0, 2], false),
+}))();
 // prettier-ignore
-export const PSBTInput = {
-    nonWitnessUtxo: [0x00, false, RawTx, [], [0, 2], false],
-    witnessUtxo: [0x01, false, RawOutput, [], [0, 2], false],
-    partialSig: [0x02, PubKeyECDSA, BytesInf, [], [0, 2], false],
-    sighashType: [0x03, false, P.U32LE, [], [0, 2], false],
-    redeemScript: [0x04, false, BytesInf, [], [0, 2], false],
-    witnessScript: [0x05, false, BytesInf, [], [0, 2], false],
-    bip32Derivation: [0x06, PubKeyECDSA, BIP32Der, [], [0, 2], false],
-    finalScriptSig: [0x07, false, BytesInf, [], [0, 2], false],
-    finalScriptWitness: [0x08, false, RawWitness, [], [0, 2], false],
-    porCommitment: [0x09, false, BytesInf, [], [0, 2], false],
-    ripemd160: [0x0a, Bytes20, BytesInf, [], [0, 2], false],
-    sha256: [0x0b, Bytes32, BytesInf, [], [0, 2], false],
-    hash160: [0x0c, Bytes20, BytesInf, [], [0, 2], false],
-    hash256: [0x0d, Bytes32, BytesInf, [], [0, 2], false],
-    txid: [0x0e, false, Bytes32, [2], [2], true],
-    index: [0x0f, false, P.U32LE, [2], [2], true],
-    sequence: [0x10, false, P.U32LE, [], [2], true],
-    requiredTimeLocktime: [0x11, false, P.U32LE, [], [2], false],
-    requiredHeightLocktime: [0x12, false, P.U32LE, [], [2], false],
-    tapKeySig: [0x13, false, SignatureSchnorr, [], [0, 2], false],
-    tapScriptSig: [0x14, tapScriptSigKey, SignatureSchnorr, [], [0, 2], false],
-    tapLeafScript: [0x15, TaprootControlBlock, BytesInf, [], [0, 2], false],
-    tapBip32Derivation: [0x16, Bytes32, TaprootBIP32Der, [], [0, 2], false],
-    tapInternalKey: [0x17, false, PubKeySchnorr, [], [0, 2], false],
-    tapMerkleRoot: [0x18, false, Bytes32, [], [0, 2], false],
-    proprietary: [0xfc, BytesInf, BytesInf, [], [0, 2], false],
-};
+/**
+ * PSBT input key definitions.
+ * @example
+ * Strip input fields that do not belong in the requested PSBT version.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { PSBTInput, cleanPSBTFields } from '@scure/btc-signer/psbt.js';
+ * cleanPSBTFields(2, PSBTInput, {
+ *   txid: hex.decode('0000000000000000000000000000000000000000000000000000000000000001'),
+ *   index: 0,
+ *   witnessUtxo: { amount: 2n, script: new Uint8Array([0x51]) },
+ * });
+ * ```
+ */
+export const PSBTInput = /* @__PURE__ */ (() => Object.freeze({
+    nonWitnessUtxo: PSBTInfo(0x00, false, RawTx, [], [0, 2], false),
+    witnessUtxo: PSBTInfo(0x01, false, RawOutput, [], [0, 2], false),
+    partialSig: PSBTInfo(0x02, PubKeyECDSA, BytesInf, [], [0, 2], false),
+    sighashType: PSBTInfo(0x03, false, P.U32LE, [], [0, 2], false),
+    redeemScript: PSBTInfo(0x04, false, BytesInf, [], [0, 2], false),
+    witnessScript: PSBTInfo(0x05, false, BytesInf, [], [0, 2], false),
+    bip32Derivation: PSBTInfo(0x06, PubKeyECDSA, BIP32Der, [], [0, 2], false),
+    finalScriptSig: PSBTInfo(0x07, false, BytesInf, [], [0, 2], false),
+    finalScriptWitness: PSBTInfo(0x08, false, RawWitnessWire, [], [0, 2], false),
+    porCommitment: PSBTInfo(0x09, false, BytesInf, [], [0, 2], false),
+    ripemd160: PSBTInfo(0x0a, Bytes20, BytesInf, [], [0, 2], false),
+    sha256: PSBTInfo(0x0b, Bytes32, BytesInf, [], [0, 2], false),
+    hash160: PSBTInfo(0x0c, Bytes20, BytesInf, [], [0, 2], false),
+    hash256: PSBTInfo(0x0d, Bytes32, BytesInf, [], [0, 2], false),
+    // BIP174/BIP370 serialize PREVIOUS_TXID in standard byte order, while the rest of this repo
+    // historically keeps TransactionInput.txid in display-order bytes matching `Transaction.id`.
+    // Reverse at this PSBTv2 boundary so internal txid semantics stay aligned with the raw-tx path.
+    txid: PSBTInfo(0x0e, false, P.bytes(32, true), [2], [2], true),
+    index: PSBTInfo(0x0f, false, P.U32LE, [2], [2], true),
+    sequence: PSBTInfo(0x10, false, P.U32LE, [], [2], true),
+    requiredTimeLocktime: PSBTInfo(0x11, false, P.U32LE, [], [2], false),
+    requiredHeightLocktime: PSBTInfo(0x12, false, P.U32LE, [], [2], false),
+    tapKeySig: PSBTInfo(0x13, false, SignatureSchnorr, [], [0, 2], false),
+    tapScriptSig: PSBTInfo(0x14, tapScriptSigKey, SignatureSchnorr, [], [0, 2], false),
+    tapLeafScript: PSBTInfo(0x15, TaprootControlBlock, BytesInf, [], [0, 2], false),
+    // BIP371 key data here is a 32-byte x-only pubkey, so reuse the shared Schnorr pubkey coder
+    // instead of accepting arbitrary 32-byte blobs that only fail much later in taproot flows.
+    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),
+}))();
 // All other keys removed when finalizing
-export const PSBTInputFinalKeys = [
+/**
+ * Input fields preserved after finalization.
+ * @example
+ * Use the allowlist when stripping transient signing fields after finalization.
+ * ```ts
+ * import { PSBTInputFinalKeys } from '@scure/btc-signer/psbt.js';
+ * const finalKeys = new Set(PSBTInputFinalKeys);
+ * finalKeys.has('finalScriptWitness');
+ * ```
+ */
+export const PSBTInputFinalKeys = /* @__PURE__ */ Object.freeze([
+    // PSBTv2 extractors rebuild the final transaction from per-input fields, so
+    // finalized inputs still need txid/index (and any non-default sequence)
+    // even though BIP174's generic cleanup is stricter.
     'txid',
     'sequence',
     'index',
@@ -98,40 +249,83 @@ export const PSBTInputFinalKeys = [
     'finalScriptSig',
     'finalScriptWitness',
     'unknown',
-];
+]);
 // Can be modified even on signed input
-export const PSBTInputUnsignedKeys = [
+/**
+ * Input fields that may still change after signing starts.
+ * @example
+ * Signed inputs may still update these fields while new signatures are being added.
+ * ```ts
+ * import { PSBTInputUnsignedKeys } from '@scure/btc-signer/psbt.js';
+ * const mutableKeys = new Set(PSBTInputUnsignedKeys);
+ * mutableKeys.has('tapScriptSig');
+ * ```
+ */
+export const PSBTInputUnsignedKeys = /* @__PURE__ */ Object.freeze([
+    // 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.
     'partialSig',
     'finalScriptSig',
     'finalScriptWitness',
     'tapKeySig',
     'tapScriptSig',
-];
+]);
 // prettier-ignore
-export const PSBTOutput = {
-    redeemScript: [0x00, false, BytesInf, [], [0, 2], false],
-    witnessScript: [0x01, false, BytesInf, [], [0, 2], false],
-    bip32Derivation: [0x02, PubKeyECDSA, BIP32Der, [], [0, 2], false],
-    amount: [0x03, false, P.I64LE, [2], [2], true],
-    script: [0x04, false, BytesInf, [2], [2], true],
-    tapInternalKey: [0x05, false, PubKeySchnorr, [], [0, 2], false],
-    tapTree: [0x06, false, tapTree, [], [0, 2], false],
-    tapBip32Derivation: [0x07, PubKeySchnorr, TaprootBIP32Der, [], [0, 2], false],
-    proprietary: [0xfc, BytesInf, BytesInf, [], [0, 2], false],
-};
+/**
+ * PSBT output key definitions.
+ * @example
+ * Strip output fields that are not valid for the target PSBT version.
+ * ```ts
+ * import { PSBTOutput, cleanPSBTFields } from '@scure/btc-signer/psbt.js';
+ * cleanPSBTFields(2, PSBTOutput, { amount: 2n, script: new Uint8Array([0x51]) });
+ * ```
+ */
+export const PSBTOutput = /* @__PURE__ */ (() => Object.freeze({
+    redeemScript: PSBTInfo(0x00, false, BytesInf, [], [0, 2], false),
+    witnessScript: PSBTInfo(0x01, false, BytesInf, [], [0, 2], false),
+    bip32Derivation: PSBTInfo(0x02, PubKeyECDSA, BIP32Der, [], [0, 2], false),
+    // BIP174/BIP370 serialize PSBT_OUT_AMOUNT as a signed int64 on the wire; semantic output
+    // validity still rejects negative transaction amounts in `PSBTOutputCoder` below.
+    amount: PSBTInfo(0x03, false, P.I64LE, [2], [2], true),
+    script: PSBTInfo(0x04, false, BytesInf, [2], [2], true),
+    tapInternalKey: PSBTInfo(0x05, false, PubKeySchnorr, [], [0, 2], false),
+    // BIP371 expects a non-empty DFS-ordered list of tapleaf tuples here so wallets can
+    // 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),
+}))();
 // Can be modified even on signed input
-export const PSBTOutputUnsignedKeys = [];
-const PSBTKeyPair = P.array(P.NULL, P.struct({
+/**
+ * Output fields that may still change after signing starts.
+ * @example
+ * PSBTv2 outputs are fully committed once signing starts, so the set stays empty.
+ * ```ts
+ * import { PSBTOutputUnsignedKeys } from '@scure/btc-signer/psbt.js';
+ * const mutableKeys = new Set(PSBTOutputUnsignedKeys);
+ * mutableKeys.size; // 0
+ * ```
+ */
+export const PSBTOutputUnsignedKeys = /* @__PURE__ */ Object.freeze([]);
+// Signed outputs have no replace/remove exceptions: once a signature actually commits to a given
+// output, every field on that output is frozen. SIGHASH_NONE leaves outputs fully mutable, and
+// SIGHASH_SINGLE only freezes the matching output index.
+// Raw BIP174 keypair framing only: `<key><value>` records terminated by `0x00`.
+// Uniqueness, keyed-vs-unkeyed rules, and per-type decoding live one layer up in `PSBTKeyMap`.
+const PSBTKeyPair = /* @__PURE__ */ (() => P.array(P.NULL, P.struct({
     //  <key> := <keylen> <keytype> <keydata> WHERE keylen = len(keytype)+len(keydata)
     key: P.prefix(CompactSizeLen, P.struct({ type: CompactSizeLen, key: P.bytes(null) })),
     //  <value> := <valuelen> <valuedata>
     value: P.bytes(CompactSizeLen),
-}));
+})))();
 function PSBTKeyInfo(info) {
+    // Name the tuple slots once so version-filter helpers do not depend on raw positional indexing.
     const [type, kc, vc, reqInc, allowInc, silentIgnore] = info;
     return { type, kc, vc, reqInc, allowInc, silentIgnore };
 }
-const PSBTUnknownKey = P.struct({ type: CompactSizeLen, key: P.bytes(null) });
+const PSBTUnknownKey = /* @__PURE__ */ (() => 
+// Raw unknown/proprietary field key: compact-size keytype plus opaque keydata for pass-through.
+P.struct({ type: CompactSizeLen, key: P.bytes(null) }))();
 // Key cannot be 'unknown', value coder cannot be array for elements with empty key
 function PSBTKeyMap(psbtEnum) {
     // -> Record<type, [keyName, ...coders]>
@@ -142,18 +336,32 @@ function PSBTKeyMap(psbtEnum) {
     }
     return P.wrap({
         encodeStream: (w, value) => {
+            const _value = value;
             let out = [];
+            const seen = {};
+            const add = (key, value) => {
+                const _value = value;
+                // BIP174 defines `<key> := <keylen> <keytype> <keydata>` and says repeated `<keytype>`
+                // entries are allowed within one `<map>` as long as the full `<key>` stays unique.
+                // `<keylen>` is derived from `<keytype><keydata>`, so `PSBTUnknownKey` is enough here.
+                const kStr = hex.encode(PSBTUnknownKey.encode(key));
+                if (seen[kStr])
+                    throw new Error(`PSBT: duplicate key=${kStr}`);
+                seen[kStr] = true;
+                out.push({ key, value: _value });
+            };
             // Because we use order of psbtEnum, keymap is sorted here
             for (const name in psbtEnum) {
-                const val = value[name];
+                const val = _value[name];
                 if (val === undefined)
                     continue;
                 const [type, kc, vc] = psbtEnum[name];
                 if (!kc) {
-                    out.push({ key: { type, key: P.EMPTY }, value: vc.encode(val) });
+                    add({ type, key: P.EMPTY }, vc.encode(val));
                 }
                 else {
-                    // Low level interface, returns keys as is (with duplicates). Useful for debug
+                    // BIP174 allows repeated `<keytype>` values inside one `<map>`, but the full `<key>`
+                    // must stay unique, so keyed rows are sorted and then deduped by serialized key bytes.
                     const kv = val.map(([k, v]) => [
                         kc.encode(k),
                         vc.encode(v),
@@ -161,13 +369,13 @@ function PSBTKeyMap(psbtEnum) {
                     // sort by keys
                     kv.sort((a, b) => compareBytes(a[0], b[0]));
                     for (const [key, value] of kv)
-                        out.push({ key: { key, type }, value });
+                        add({ key, type }, value);
                 }
             }
-            if (value.unknown) {
-                value.unknown.sort((a, b) => compareBytes(a[0].key, b[0].key));
-                for (const [k, v] of value.unknown)
-                    out.push({ key: k, value: v });
+            if (_value.unknown) {
+                _value.unknown.sort((a, b) => compareBytes(a[0].key, b[0].key));
+                for (const [k, v] of _value.unknown)
+                    add(k, v);
             }
             PSBTKeyPair.encodeStream(w, out);
         },
@@ -175,7 +383,12 @@ function PSBTKeyMap(psbtEnum) {
             const raw = PSBTKeyPair.decodeStream(r);
             const out = {};
             const noKey = {};
+            const seen = {};
             for (const elm of raw) {
+                const kStr = hex.encode(PSBTUnknownKey.encode(elm.key));
+                if (seen[kStr])
+                    throw new Error(`PSBT: duplicate key=${kStr}`);
+                seen[kStr] = true;
                 let name = 'unknown';
                 let key = elm.key.key;
                 let value = elm.value;
@@ -199,7 +412,9 @@ function PSBTKeyMap(psbtEnum) {
                     // For unknown: add key type inside key
                     key = { type: elm.key.type, key: elm.key.key };
                 }
-                // Only keyed elements at this point
+                // Only keyed elements at this point.
+                // BIP174 uniqueness is over the full serialized `<key>` bytes within one map, not only keytype.
+                // Empty-key rows are rejected above; keyed duplicates need an explicit check before this append path.
                 if (noKey[name])
                     throw new Error(`PSBT: Key type with empty key and no key=${name} val=${value}`);
                 if (!out[name])
@@ -210,7 +425,23 @@ function PSBTKeyMap(psbtEnum) {
         },
     });
 }
-export const PSBTInputCoder = P.validate(PSBTKeyMap(PSBTInput), (i) => {
+/**
+ * Validated PSBT input coder.
+ * @example
+ * Validate a decoded PSBT input before serializing it back to bytes.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { PSBTInputCoder } from '@scure/btc-signer/psbt.js';
+ * PSBTInputCoder.encode({
+ *   txid: hex.decode('0000000000000000000000000000000000000000000000000000000000000001'),
+ *   index: 0,
+ *   witnessUtxo: { amount: 1n, script: new Uint8Array([0x51]) },
+ * });
+ * ```
+ */
+export const PSBTInputCoder = /* @__PURE__ */ (() => Object.freeze(P.validate(PSBTKeyMap(PSBTInput), (i) => {
+    // This wrapper adds input-level invariants after raw PSBT key-map decoding.
+    // Row-level key validation and duplicate-key rejection still depend on the underlying table/map helpers.
     if (i.finalScriptWitness && !i.finalScriptWitness.length)
         throw new Error('validateInput: empty finalScriptWitness');
     //if (i.finalScriptSig && !i.finalScriptSig.length) throw new Error('validateInput: empty finalScriptSig');
@@ -239,14 +470,33 @@ export const PSBTInputCoder = P.validate(PSBTKeyMap(PSBTInput), (i) => {
         }
     }
     return i;
-});
-export const PSBTOutputCoder = P.validate(PSBTKeyMap(PSBTOutput), (o) => {
+})))();
+/**
+ * Validated PSBT output coder.
+ * @example
+ * Validate a decoded PSBT output before serializing it back to bytes.
+ * ```ts
+ * import { PSBTOutputCoder } from '@scure/btc-signer/psbt.js';
+ * PSBTOutputCoder.encode({ amount: 1n, script: new Uint8Array([0x51]) });
+ * ```
+ */
+export const PSBTOutputCoder = /* @__PURE__ */ (() => Object.freeze(P.validate(PSBTKeyMap(PSBTOutput), (o) => {
+    // This wrapper only adds output-level invariants after raw key-map decoding.
+    // Duplicate-key rejection still depends on the key-map helper; tapTree structure is validated
+    // 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)
+        throw new Error(`validateOutput: wrong amount=${o.amount}`);
     if (o.bip32Derivation)
         for (const [k] of o.bip32Derivation)
             validatePubkey(k, PubT.ecdsa);
     return o;
-});
-const PSBTGlobalCoder = P.validate(PSBTKeyMap(PSBTGlobal), (g) => {
+})))();
+const PSBTGlobalCoder = /* @__PURE__ */ (() => P.validate(PSBTKeyMap(PSBTGlobal), (g) => {
+    // This wrapper adds the BIP174/BIP370 cross-field invariants after raw global key-map decoding.
+    // `PSBT_GLOBAL_XPUB` stores the serialized xpub plus a separate derivation value, and BIP174
+    // says the number of 32-bit indexes in that derivation path must match the xpub depth.
     const version = g.version || 0;
     if (version === 0) {
         if (!g.unsignedTx)
@@ -255,26 +505,42 @@ const PSBTGlobalCoder = P.validate(PSBTKeyMap(PSBTGlobal), (g) => {
             if (inp.finalScriptSig && inp.finalScriptSig.length)
                 throw new Error('PSBTv0: input scriptSig found in unsignedTx');
     }
+    for (const [xpub, der] of g.xpub || []) {
+        if (xpub.depth !== der.path.length)
+            throw new Error(`PSBT_GLOBAL_XPUB: xpub depth=${xpub.depth} must match derivation path length=${der.path.length}`);
+    }
     return g;
-});
-export const _RawPSBTV0 = P.struct({
+}))();
+export const _RawPSBTV0 = /* @__PURE__ */ (() => Object.freeze(P.struct({
     magic: P.magic(P.string(new Uint8Array([0xff])), 'psbt'),
     global: PSBTGlobalCoder,
+    // Raw v0 framing follows the unsigned transaction for input-map count; the stricter
+    // one-map-per-input/output reconciliation happens in `RawPSBTV0` / `validatePSBT`.
     inputs: P.array('global/unsignedTx/inputs/length', PSBTInputCoder),
     outputs: P.array(null, PSBTOutputCoder),
-});
-export const _RawPSBTV2 = P.struct({
+})))();
+export const _RawPSBTV2 = /* @__PURE__ */ (() => Object.freeze(P.struct({
     magic: P.magic(P.string(new Uint8Array([0xff])), 'psbt'),
     global: PSBTGlobalCoder,
+    // Raw v2 framing takes map counts from the global PSBTv2 count fields; deeper version
+    // and per-field validation still happens in `RawPSBTV2` / `validatePSBT`.
     inputs: P.array('global/inputCount', PSBTInputCoder),
     outputs: P.array('global/outputCount', PSBTOutputCoder),
-});
-export const _DebugPSBT = P.struct({
+})))();
+export const _DebugPSBT = /* @__PURE__ */ (() => Object.freeze(P.struct({
     magic: P.magic(P.string(new Uint8Array([0xff])), 'psbt'),
+    // Debug-only normalized view: maps become plain objects, so key order is intentionally ignored
+    // and duplicate keys fail while decoding instead of being preserved for byte-level diagnostics.
+    // Each `items[i]` is one raw PSBT map (`global`, then inputs, then outputs), keyed by the
+    // full serialized PSBT key bytes as hex rather than decoded field names.
     items: P.array(null, P.apply(P.array(P.NULL, P.tuple([P.hex(CompactSizeLen), P.bytes(CompactSize)])), P.coders.dict())),
-});
+})))();
 function validatePSBTFields(version, info, lst) {
-    for (const k in lst) {
+    const _lst = lst;
+    // Enforce the BIP174/BIP370 field-table columns directly: reject rows whose
+    // "Versions Allowing Inclusion" excludes this version and require rows whose
+    // "Versions Requiring Inclusion" includes it.
+    for (const k in _lst) {
         if (k === 'unknown')
             continue;
         if (!info[k])
@@ -285,14 +551,35 @@ function validatePSBTFields(version, info, lst) {
     }
     for (const k in info) {
         const { reqInc } = PSBTKeyInfo(info[k]);
-        if (reqInc.includes(version) && lst[k] === undefined)
+        if (reqInc.includes(version) && _lst[k] === undefined)
             throw new Error(`PSBTv${version}: missing required field ${k}`);
     }
 }
+/**
+ * Removes fields that are not valid for the requested PSBT version.
+ * @param version - target PSBT version
+ * @param info - PSBT field definition table
+ * @param lst - decoded PSBT key map
+ * @returns Filtered PSBT key map.
+ * @throws If a field cannot be serialized in the requested PSBT version. {@link Error}
+ * @example
+ * Drop fields that are not allowed in the target PSBT version before encoding.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { PSBTInput, cleanPSBTFields } from '@scure/btc-signer/psbt.js';
+ * cleanPSBTFields(2, PSBTInput, {
+ *   txid: hex.decode('0000000000000000000000000000000000000000000000000000000000000001'),
+ *   index: 0,
+ * });
+ * ```
+ */
 export function cleanPSBTFields(version, info, lst) {
+    const _lst = lst;
     const out = {};
-    for (const _k in lst) {
+    for (const _k in _lst) {
         const k = _k;
+        // Serializer-side compatibility filter: preserve unknown pass-through fields, silently drop
+        // rows explicitly marked `silentIgnore`, and throw on other rows the target version forbids.
         if (k !== 'unknown') {
             if (!info[k])
                 continue;
@@ -303,7 +590,7 @@ export function cleanPSBTFields(version, info, lst) {
                 throw new Error(`Failed to serialize in PSBTv${version}: ${k} but versions allows inclusion=${allowInc}`);
             }
         }
-        out[k] = lst[k];
+        out[k] = _lst[k];
     }
     return out;
 }
@@ -314,14 +601,19 @@ function validatePSBT(tx) {
         validatePSBTFields(version, PSBTInput, i);
     for (const o of tx.outputs)
         validatePSBTFields(version, PSBTOutput, o);
-    // We allow only one empty element at the end of map (compat with bitcoinjs-lib bug)
+    // 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.
     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 for inputs
+    // Same carve-out for outputs.
     const outputCount = !version ? tx.global.unsignedTx.outputs.length : tx.global.outputCount;
     if (tx.outputs.length < outputCount)
         throw new Error('Not outputs inputs');
@@ -330,21 +622,48 @@ function validatePSBT(tx) {
         throw new Error(`Unexpected outputs left in tx=${outputsLeft}`);
     return tx;
 }
+/**
+ * Merges two PSBT key maps while preserving keyed-field uniqueness.
+ * @param psbtEnum - PSBT field definition table
+ * @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
+ * @returns Merged PSBT key map.
+ * @throws If keyed PSBT fields conflict or signed fields would be removed. {@link Error}
+ * @example
+ * Merge an updated `witnessUtxo` into an existing decoded input map.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { PSBTInput, mergeKeyMap } from '@scure/btc-signer/psbt.js';
+ * mergeKeyMap(
+ *   PSBTInput,
+ *   { witnessUtxo: { amount: 2n, script: new Uint8Array([0x51]) } },
+ *   {
+ *     txid: hex.decode('0000000000000000000000000000000000000000000000000000000000000001'),
+ *     index: 0,
+ *   }
+ * );
+ * ```
+ */
 export function mergeKeyMap(psbtEnum, val, cur, allowedFields, allowUnknown) {
-    const res = { ...cur, ...val };
+    const _val = val;
+    const _cur = cur;
+    const _allowedFields = allowedFields;
+    const res = { ..._cur, ..._val };
     // All arguments can be provided as hex
     for (const k in psbtEnum) {
         const key = k;
         const [_, kC, vC] = psbtEnum[key];
-        const cannotChange = allowedFields && !allowedFields.includes(k);
-        if (val[k] === undefined && k in val) {
+        const cannotChange = _allowedFields && !_allowedFields.includes(k);
+        if (_val[k] === undefined && k in _val) {
             if (cannotChange)
                 throw new Error(`Cannot remove signed field=${k}`);
             delete res[k];
         }
         else if (kC) {
-            const oldKV = (cur && cur[k] ? cur[k] : []);
-            let newKV = val[key];
+            const oldKV = (_cur && _cur[k] ? _cur[k] : []);
+            let newKV = _val[key];
             if (newKV) {
                 if (!Array.isArray(newKV))
                     throw new Error(`keyMap(${k}): KV pairs should be [k, v][]`);
@@ -389,11 +708,30 @@ export function mergeKeyMap(psbtEnum, val, cur, allowedFields, allowUnknown) {
         else if (typeof res[k] === 'string') {
             res[k] = vC.decode(hex.decode(res[k]));
         }
-        else if (cannotChange && k in val && cur && cur[k] !== undefined) {
-            if (!equalBytes(vC.encode(val[k]), vC.encode(cur[k])))
+        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}`);
         }
     }
+    if (allowUnknown && _val.unknown) {
+        // Unknown PSBT rows are stripped by default here, but explicit allowUnknown mode is pass-through.
+        // Merge them by full serialized unknown key so repeated updates do not clobber earlier opaque rows.
+        const map = {};
+        for (const [k, v] of _cur?.unknown || [])
+            map[hex.encode(PSBTUnknownKey.encode(k))] = [k, v];
+        for (const [k, v] of _val.unknown) {
+            const kStr = hex.encode(PSBTUnknownKey.encode(k));
+            if (map[kStr] === undefined) {
+                map[kStr] = [k, v];
+                continue;
+            }
+            const oldVal = hex.encode(BytesInf.encode(map[kStr][1]));
+            const newVal = hex.encode(BytesInf.encode(v));
+            if (oldVal !== newVal)
+                throw new Error(`keyMap(unknown): same key=${kStr} oldVal=${oldVal} newVal=${newVal}`);
+        }
+        res.unknown = Object.values(map);
+    }
     // Remove unknown keys except the "unknown" array if allowUnknown is true
     for (const k in res) {
         if (!psbtEnum[k]) {
@@ -404,6 +742,12 @@ export function mergeKeyMap(psbtEnum, val, cur, allowedFields, allowUnknown) {
     }
     return res;
 }
-export const RawPSBTV0 = P.validate(_RawPSBTV0, validatePSBT);
-export const RawPSBTV2 = P.validate(_RawPSBTV2, validatePSBT);
+/** 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.
+export const RawPSBTV0 = /* @__PURE__ */ (() => Object.freeze(P.validate(_RawPSBTV0, validatePSBT)))();
+/** Validated PSBTv2 coder. */
+// This wrapper only layers `validatePSBT`'s PSBTv2 required-field/count reconciliation on top
+// of `_RawPSBTV2`; nested input/output/global field invariants still depend on the coders below.
+export const RawPSBTV2 = /* @__PURE__ */ (() => Object.freeze(P.validate(_RawPSBTV2, validatePSBT)))();
 //# sourceMappingURL=psbt.js.map