@scure/btc-signer 2.3.0 → 2.4.0

package/psbt.js

@@ -1,9 +1,17 @@
 import { hex } from '@scure/base';
-import { anumber } from '@noble/hashes/utils.js';
+import { anumber, concatBytes } from '@noble/hashes/utils.js';
 import * as P from 'micro-packed';
 import { CompactSize, CompactSizeLen, RawOldTx, RawOutput, RawTx, RawWitness, VarBytes, } from "./script.js";
 import { aarray, compareBytes, equalBytes, PubT, validateObject, validatePubkey, } from "./utils.js";
-// PSBT BIP174, BIP370, BIP371
+const unknowns = (mode, name) => {
+    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);
@@ -136,11 +144,58 @@ const tapTree = /* @__PURE__ */ (() => P.validate(P.array(null, P.struct({
 // 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);
+// 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 = /* @__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);
+const Bytes64 = /* @__PURE__ */ P.bytes(64);
+const Bytes66 = /* @__PURE__ */ P.bytes(66);
+// BIP373 uses the same aggregate-key participant list in input and output maps.
+const MuSig2Participants = /* @__PURE__ */ (() => P.array(null, PubKeyECDSACompressed))();
+// 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) => {
+        const _key = key;
+        return concatBytes(PubKeyECDSACompressed.encode(_key.participantPubkey), PubKeyECDSACompressed.encode(_key.aggregatePubkey), _key.leafHash === undefined ? P.EMPTY : Bytes32.encode(_key.leafHash));
+    },
+    encode: (raw) => {
+        const _raw = raw;
+        if (_raw.length !== 66 && _raw.length !== 98)
+            throw new Error(`MuSig2 key: expected 66 or 98 bytes, got ${_raw.length}`);
+        const key = {
+            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;
+    },
+}))();
+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 }))();
 // 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) => 
@@ -179,8 +234,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),
 }))();
 // prettier-ignore
 /**
@@ -228,7 +287,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),
 }))();
 // All other keys removed when finalizing
 /**
@@ -243,37 +310,43 @@ export const PSBTInput = /* @__PURE__ */ (() => Object.freeze({
  */
 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)
+    // 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([
-    // 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([
     'partialSig',
     'finalScriptSig',
     'finalScriptWitness',
     'tapKeySig',
     '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.
@@ -297,7 +370,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),
 }))();
 // Can be modified even on signed input
 /**
@@ -610,22 +687,27 @@ function validatePSBT(tx) {
         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;
 }
@@ -635,7 +717,8 @@ function validatePSBT(tx) {
  * @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
@@ -653,7 +736,7 @@ function validatePSBT(tx) {
  * );
  * ```
  */
-export function mergeKeyMap(psbtEnum, val, cur, allowedFields, allowUnknown) {
+export function mergeKeyMap(psbtEnum, val, cur, allowedFields, unknown = 'strip', proprietary = 'strip') {
     validateObject(psbtEnum, {}, {}, 'psbtEnum');
     validateObject(val, {}, {}, 'val');
     if (cur !== undefined)
@@ -663,10 +746,24 @@ export function mergeKeyMap(psbtEnum, val, cur, allowedFields, allowUnknown) {
     const _val = val;
     const _cur = cur;
     const _allowedFields = allowedFields;
+    const unknownMode = unknowns(unknown, 'unknown');
+    const proprietaryMode = unknowns(proprietary, 'proprietary');
+    for (const [name, mode] of [
+        ['unknown', unknownMode],
+        ['proprietary', proprietaryMode],
+    ]) {
+        if (mode !== 'strict')
+            continue;
+        if (_val[name]?.length ||
+            _cur?.[name]?.length)
+            throw new Error(`PSBT: ${name} PSBT field is not allowed in strict mode`);
+    }
     const res = { ..._cur, ..._val };
     // All arguments can be provided as hex
     for (const k in psbtEnum) {
         const key = k;
+        if (k === 'proprietary' && proprietaryMode !== 'ignore')
+            continue;
         const [_, kC, vC] = psbtEnum[key];
         const cannotChange = _allowedFields && !_allowedFields.includes(k);
         if (_val[k] === undefined && k in _val) {
@@ -712,22 +809,31 @@ export function mergeKeyMap(psbtEnum, val, cur, allowedFields, allowUnknown) {
                             throw new Error(`Cannot remove signed field=${key}/${k}`);
                         delete map[kStr];
                     }
-                    else
+                    else {
+                        if (cannotChange && map[kStr] === undefined)
+                            throw new Error(`Cannot add signed field=${key}/${kStr}`);
                         add(kStr, k, v);
+                    }
                 }
                 res[key] = Object.values(map);
             }
         }
-        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])))
-                throw new Error(`Cannot change signed field=${k}`);
+        else {
+            if (typeof res[k] === 'string')
+                res[k] = vC.decode(hex.decode(res[k]));
+            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 = {};
         for (const [k, v] of _cur?.unknown || [])
@@ -745,16 +851,59 @@ export function mergeKeyMap(psbtEnum, val, cur, allowedFields, allowUnknown) {
         }
         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')
+            if (unknownMode === 'ignore' && k === 'unknown')
                 continue;
             delete res[k];
         }
     }
+    if (unknownMode !== 'ignore')
+        delete res.unknown;
+    if (proprietaryMode !== 'ignore')
+        delete res.proprietary;
     return res;
 }
+/**
+ * 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(psbtEnum, current, other, unknown = 'strip', proprietary = 'strip') {
+    validateObject(psbtEnum, {}, {}, 'psbtEnum');
+    validateObject(current, {}, {}, 'current');
+    validateObject(other, {}, {}, 'other');
+    const _current = current;
+    const _other = other;
+    for (const k in psbtEnum) {
+        const key = k;
+        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/_type_test.ts

@@ -1,6 +1,20 @@
 import { secp256k1 as secp } from '@noble/curves/secp256k1.js';
 import { hex } from '@scure/base';
 import * as btc from './index.ts';
+import type { TxOpts, Unknowns } from './index.ts';
+import type { TArg } from './utils.ts';
+
+const unknownPolicy: Unknowns = 'strip';
+const extensionOpts: TxOpts = { unknown: unknownPolicy, proprietary: 'strict' };
+new btc.Transaction(extensionOpts);
+
+declare const combineOpts: TArg<TxOpts>;
+btc.PSBTCombine([], combineOpts);
+declare const first: btc.Transaction;
+declare const second: btc.Transaction;
+// Direct combination retains main's receiver-options API; byte-only PSBTCombine owns policy opts.
+// @ts-expect-error Transaction.combine does not accept operation-specific options.
+first.combine(second, combineOpts);
 
 const privKey1 = hex.decode('0101010101010101010101010101010101010101010101010101010101010101');
 const P1 = secp.getPublicKey(privKey1, true);

package/src/index.ts

@@ -25,9 +25,10 @@ export {
 } from './script.ts';
 export type { ScriptType } from './script.ts';
 export { getInputType, Transaction } from './transaction.ts';
-export { NETWORK, TAPROOT_UNSPENDABLE_KEY, TEST_NETWORK } from './utils.ts';
+export type { TxOpts, Unknowns } from './transaction.ts';
+export { NETWORK, TAPROOT_UNSPENDABLE_KEY, TEST_NETWORK, taprootNumsKey } from './utils.ts';
 export type { TArg, TRet } from './utils.ts';
-export { selectUTXO } from './utxo.ts';
+export { filterTaproot, selectUTXO } from './utxo.ts';
 
 /**
  * Small collection of commonly used utility exports.
@@ -62,6 +63,7 @@ export {
   Address,
   combinations,
   getAddress,
+  MAX_COMBINATIONS,
   OutScript,
   sortedMultisig,
   taprootListToTree,

package/src/musig2.ts

@@ -11,9 +11,16 @@ The implementation can be used to create own protocol,
 but you need to implement nonce/partial signatures exchange yourself.
 Someday BIP-373 will be more "implementable" and we can use this from PSBT.
 
+SECURITY: A secret nonce MUST be used for exactly one partial signature. Session.sign() zeroes
+only the Uint8Array instance passed to it; copies, serialized values, database records, and process
+snapshots are not erased. Reusing the same nonce scalars in distinct sessions can reveal the
+signer's secret key. Stateful integrations must keep one authoritative nonce record and atomically
+consume it before releasing a partial signature.
+
 Links:
 - https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki#user-content-Test_Vectors_and_Reference_Code
-- https://github.com/bitcoin/bips/blob/master/bip-0373.mediawiki (PSBT MUSIG2): very raw, no vectors, not implemented for now.
+- https://github.com/bitcoin/bips/blob/master/bip-0373.mediawiki (PSBT MuSig2): psbt.ts supports
+  its transport fields and vectors, but this module does not orchestrate the signing protocol.
 - https://github.com/bitcoin/bips/blob/master/bip-0327/reference.py
 */
 // Types
@@ -21,7 +28,10 @@ Links:
 export type Nonces = {
   /** Public nonce that gets shared with the other participants. */
   public: Uint8Array;
-  /** Secret nonce that stays local until partial signing finishes. */
+  /**
+   * Secret nonce that stays local until partial signing finishes. It MUST be consumed exactly once;
+   * never retain a copy that could be loaded for another signing session.
+   */
   secret: Uint8Array;
 };
 /**
@@ -362,6 +372,12 @@ const nonceHash = (
 
 /**
  * Generates a nonce pair (public and secret) for MuSig2 signing.
+ *
+ * SECURITY: The returned secret nonce MUST be used for exactly one partial signature. Keep one
+ * authoritative copy and atomically consume it when calling {@link Session.sign}. That method
+ * zeroes only the exact `Uint8Array` passed to it; clones, serialized values, database records, and
+ * snapshots remain live. Reusing a secret nonce in distinct sessions can reveal the secret key.
+ *
  * @param publicKey - individual public key of the signer
  * @param secretKey - optional secret key, mixed in to blind the randomness source
  * @param aggPublicKey - aggregate public key of all signers
@@ -595,7 +611,12 @@ export class Session {
   /**
    * Generates a partial signature for a given message, secret nonce,
    * secret key, and session context.
-   * @param secretNonce - secret nonce for this signing session; it is zeroed after use
+   *
+   * SECURITY: `secretNonce` MUST be used exactly once. This method zeroes the first 64 bytes of the
+   * supplied array, including when later validation fails, but cannot erase copies or persisted
+   * representations. Reusing those nonce scalars in a distinct session can reveal the secret key.
+   *
+   * @param secretNonce - sole authoritative secret-nonce buffer for this signing session
    * @param secret - secret key of the signer
    * @param fastSign - if `true`, skip the self-verification pass
    * @returns The partial signature (Uint8Array).
@@ -670,16 +691,20 @@ export class Session {
   }
   /**
    * Aggregates partial signatures from multiple signers into a single final signature.
-   * @param partialSigs - partial signatures from each signer
+   * @param partialSigs - exactly one positional partial signature per session participant
    * @returns The final aggregate signature (Uint8Array).
    * @throws If the input is invalid, such as wrong array sizes or malformed
    * signatures. {@link Error}
    */
   partialSigAgg(partialSigs: TArg<Uint8Array[]>): TRet<Uint8Array> {
     abytesArray(partialSigs, 32);
-    // BIP327 PartialSigAgg is defined for a non-empty psig_1..u list tied to this session_ctx;
-    // [] is not a valid aggregate-signature input even though the sum starts from zero.
-    if (partialSigs.length < 1) throw new RangeError('partialSigs.length must be >= 1');
+    // BIP327 PartialSigAgg consumes psig_1..u for the same u signers in session_ctx. Accepting
+    // fewer or more scalars would return a signature-shaped value for a different equation.
+    if (partialSigs.length !== this.publicKeys.length)
+      throw new RangeError(
+        `partialSigs.length=${partialSigs.length} must equal ` +
+          `participant count=${this.publicKeys.length}`
+      );
     const { Q, tweakAcc, R, e } = this;
     let s = _0n;
     for (let i = 0; i < partialSigs.length; i++) {

package/src/net.ts

@@ -950,8 +950,13 @@ export class EsploraProvider {
       const remaining =
         options.timeoutMs === undefined ? pollIntervalMs : options.timeoutMs - (Date.now() - start);
       if (remaining <= 0) throw new EsploraError('waitForTx: timeout');
-      // Cap the sleep so the next loop checks the deadline before another poll.
-      await sleep(Math.min(pollIntervalMs, remaining), options.signal);
+      if (options.timeoutMs !== undefined && remaining <= pollIntervalMs) {
+        // Sleeping the rest of the window reaches the deadline; the timer may
+        // wake before Date.now() agrees, so don't re-poll on a clock check.
+        await sleep(remaining, options.signal);
+        throw new EsploraError('waitForTx: timeout');
+      }
+      await sleep(pollIntervalMs, options.signal);
     }
   }
   async txInfo(txid: string): Promise<TxInfo> {