@scure/btc-signer 2.3.0 → 2.4.0

package/README.md

@@ -515,13 +515,28 @@ deepStrictEqual(hex.encode(btc.OutScript.encode(decoded)), '51024e73');
 
 ### Encode/decode
 
-We support both PSBTv0 and draft PSBTv2 (there is no PSBTv1). If PSBTv2 transaction is encoded into PSBTv1, all PSBTv2 fields will be stripped.
+We support both PSBTv0 and PSBTv2 (there is no PSBTv1). Explicit PSBTv0 conversion removes
+PSBTv2-only fields after translating the unsigned transaction representation.
 
-We strip 'unknown' keys inside PSBT, they needed for new version/features support,
-however any unsupported feature/new version can significantly break assumptions about code.
-If you have use-case where they are needed, create a github issue.
+Assigned fields from BIPs 322, 353, 372, 373, 375, and 376 are decoded explicitly and survive the
+default path. `TxOpts.unknown` and `TxOpts.proprietary` govern only genuinely unknown and
+proprietary records:
 
-PSBTv2 features tx_modifiable and taproot+bip32 are not supported yet.
+- `ignore` preserves them, but the library may operate without understanding future constraints.
+- `strip` accepts and removes them; this is the default and can break interoperability with future
+  extensions.
+- `strict` rejects them.
+
+Undefined bits in PSBTv2 `txModifiable` follow the `unknown` policy. `strip` and `strict` can also
+fingerprint this library or version, while `ignore` offers better forwarding compatibility at the
+cost of interpreting less protocol state. The deprecated `allowUnknown` boolean maps `true` to
+`ignore` and `false` to `strip`.
+
+When signing an untrusted or multi-party PSBT, pass
+`{ strictPrevoutValidation: true }` to `Transaction.fromPSBT`. This requires every input to include
+a full `nonWitnessUtxo` matching its outpoint before any signature is produced. It prevents forged
+`witnessUtxo` amounts from making the displayed transaction fee appear lower than the fee that the
+valid transaction will actually pay.
 
 ```text
 // Decode
@@ -937,10 +952,28 @@ when making an on-chain bitcoin payment. The library:
 - calculates weight with good precision
 - implements multiple strategies
 
-Taproot estimation is precise, but you have to pass sighash if you want to use non-default one,
-because it changes signature size. For complex taproot trees you need to filter tapLeafScript
-to include only leafs which you can sign we estimate size with smallest leaf (same as finalization),
-but in specific case keys for this leaf can be unavailable (complex multisig)
+Taproot estimation is precise, but you have to pass `sighashType` when using a non-default
+sighash because it changes signature size. A Taproot input can advertise paths that the current
+wallet cannot spend. Pass the wallet's x-only public keys as `filterTaproot` to remove unavailable
+internal-key and script paths before selection:
+
+```js
+import * as btc from '@scure/btc-signer';
+
+const select = (utxos, outputs, changeAddress, feePerByte, myPublicKey) =>
+  btc.selectUTXO(utxos, outputs, 'default', {
+    changeAddress,
+    feePerByte,
+    filterTaproot: [myPublicKey],
+  });
+```
+
+Filtering is opt-in: when `filterTaproot` is omitted, no paths are removed. The standalone
+`btc.filterTaproot(utxos, [myPublicKey])` utility returns the same filtered candidate records.
+Built-in `tr_ns` and `tr_ms` paths are checked directly. Custom or unknown leaves are rejected;
+callers must filter those paths using their own semantics before invoking this helper. Estimation
+and finalization choose the available path with the smallest complete witness, retaining the old
+shallowest-path order for equal weights.
 
 `Oldest` / `Newest` expects UTXO provided in historical order (oldest first),
 otherwise we have no way to detect age of tx.
@@ -1148,7 +1181,7 @@ const fetcher = ftch(fetch, {
   timeout: 10_000,
   concurrencyLimit: 4,
 });
-const net = new EsploraProvider(fetcher, 'http://127.0.0.1:3000')
+const net = new EsploraProvider(fetcher, 'http://127.0.0.1:3000');
 ```
 
 ## MuSig2
@@ -1156,6 +1189,12 @@ const net = new EsploraProvider(fetcher, 'http://127.0.0.1:3000')
 MuSig2 implementation conforming to [BIP-327](https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki)
 is available in `@scure/btc-signer/musig2.js`. Check out [bip327-musig2.test.ts](./test/bip327-musig2.test.ts) as well:
 
+**Security warning:** every MuSig2 secret nonce must be used for exactly one partial signature.
+`Session.sign()` zeroes only the exact `Uint8Array` passed to it; clones, serialized values,
+database records, and process snapshots remain live. Reusing the same nonce in distinct sessions
+can reveal the signer's secret key. Stateful signers must keep one authoritative nonce record and
+atomically consume it before releasing a partial signature.
+
 > `npm install @noble/curves`
 
 ```ts

package/index.d.ts

@@ -5,9 +5,10 @@ export { multisig, p2ms, p2pk, p2pkh, p2sh, p2tr, p2tr_ms, p2tr_ns, p2tr_pk, p2w
 export { CompactSize, MAX_SCRIPT_BYTE_LENGTH, OP, RawTx, RawWitness, Script, ScriptNum, } 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.
  * @example
@@ -24,7 +25,7 @@ export declare const utils: TRet<Readonly<{
     randomPrivateKeyBytes: () => TRet<Uint8Array>;
     taprootTweakPubkey: typeof taprootTweakPubkey;
 }>>;
-export { _sortPubkeys, Address, combinations, getAddress, OutScript, sortedMultisig, taprootListToTree, WIF, } from './payment.ts';
+export { _sortPubkeys, Address, combinations, getAddress, MAX_COMBINATIONS, OutScript, sortedMultisig, taprootListToTree, WIF, } from './payment.ts';
 export type { CustomScript, OptScript } from './payment.ts';
 export { _DebugPSBT, TaprootControlBlock } from './psbt.ts';
 export { bip32Path, Decimal, DEFAULT_SEQUENCE, PSBTCombine, SigHash } from './transaction.ts';

package/index.js

@@ -4,8 +4,8 @@ import { compareBytes, concatBytes, isBytes, pubSchnorr, randomPrivateKeyBytes,
 export { multisig, p2ms, p2pk, p2pkh, p2sh, p2tr, p2tr_ms, p2tr_ns, p2tr_pk, p2wpkh, p2wsh } from "./payment.js";
 export { CompactSize, MAX_SCRIPT_BYTE_LENGTH, OP, RawTx, RawWitness, Script, ScriptNum, } from "./script.js";
 export { getInputType, Transaction } from "./transaction.js";
-export { NETWORK, TAPROOT_UNSPENDABLE_KEY, TEST_NETWORK } from "./utils.js";
-export { selectUTXO } from "./utxo.js";
+export { NETWORK, TAPROOT_UNSPENDABLE_KEY, TEST_NETWORK, taprootNumsKey } from "./utils.js";
+export { filterTaproot, selectUTXO } from "./utxo.js";
 /**
  * Small collection of commonly used utility exports.
  * @example
@@ -23,7 +23,7 @@ export const utils = /* @__PURE__ */ (() => Object.freeze({
     randomPrivateKeyBytes,
     taprootTweakPubkey,
 }))();
-export { _sortPubkeys, Address, combinations, getAddress, OutScript, sortedMultisig, taprootListToTree, WIF, } from "./payment.js";
+export { _sortPubkeys, Address, combinations, getAddress, MAX_COMBINATIONS, OutScript, sortedMultisig, taprootListToTree, WIF, } from "./payment.js";
 // remove
 export { _DebugPSBT, TaprootControlBlock } from "./psbt.js";
 // remove

package/musig2.d.ts

@@ -4,7 +4,10 @@ import { type TArg, type TRet } from './utils.ts';
 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;
 };
 /**
@@ -116,6 +119,12 @@ export declare function keyAggregate(publicKeys: TArg<Uint8Array[]>, tweaks?: TA
 export declare function keyAggExport(ctx: ReturnType<typeof keyAggregate>): TRet<Uint8Array>;
 /**
  * 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
@@ -227,7 +236,12 @@ export declare 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).
@@ -247,7 +261,7 @@ export declare class Session {
     partialSigVerify(partialSig: Uint8Array, pubNonces: Uint8Array[], i: number): boolean;
     /**
      * 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}

package/musig2.js

@@ -288,6 +288,12 @@ const nonceHash = (rand, publicKey, aggPublicKey, i, msgPrefixed, extraIn) =>
 taggedInt('MuSig/nonce', rand, new Uint8Array([publicKey.length]), publicKey, new Uint8Array([aggPublicKey.length]), aggPublicKey, msgPrefixed, numberToBytesBE(extraIn.length, 4), extraIn, new Uint8Array([i]));
 /**
  * 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
@@ -505,7 +511,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).
@@ -587,17 +598,18 @@ 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) {
         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/net.js

@@ -724,8 +724,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scure/btc-signer",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Audited & minimal library for Bitcoin. Handle transactions, Schnorr, Taproot, UTXO & PSBT",
   "files": [
     "*.js",
@@ -9,20 +9,21 @@
     "!_type_test.*"
   ],
   "dependencies": {
-    "@noble/curves": "~2.3.0",
-    "@noble/hashes": "~2.3.0",
-    "@scure/base": "~2.3.0",
-    "micro-packed": "~0.11.0"
+    "@noble/curves": "2.4.0",
+    "@noble/hashes": "2.4.0",
+    "@scure/base": "2.4.0",
+    "micro-packed": "0.11.0"
   },
   "devDependencies": {
-    "@paulmillr/jsbt": "0.6.5",
-    "@scure/bip32": "2.2.0",
-    "micro-ftch": "^1.1.0",
-    "prettier": "3.6.2",
-    "typescript": "6.0.2"
+    "@paulmillr/jsbt": "0.7.1",
+    "bismar": "0.1.8",
+    "@scure/bip32": "2.4.0",
+    "micro-ftch": "1.2.0",
+    "prettier": "3.9.6",
+    "typescript": "6.0.3"
   },
   "scripts": {
-    "benchmark:size": "npx bismar@0.1.3 -s",
+    "benchmark:size": "bismar -bsm",
     "build": "tsc",
     "build:clean": "rm -f *.{js,d.ts}",
     "check": "jsbt-check",

package/payment.d.ts

@@ -91,6 +91,7 @@ export type CustomScript = Coder<OptScript, CustomScriptOut | undefined> & {
 export declare const OutScript: TRet<P.CoderType<NonNullable<OutP2AType | OutPKType | OutPKHType | OutSHType | OutWSHType | OutWPKHType | OutMSType | OutTRType | OutTRNSType | OutTRMSType | OutUnknownType | undefined>>>;
 /** Type of the output-script coder. */
 export type OutScriptType = typeof OutScript;
+export declare const _WitnessOutScript: OutScriptType;
 type AddressValue = NonNullable<ReturnType<OutScriptType['decode']>>;
 /**
  * Validates that nested redeem and witness scripts match their wrappers.
@@ -186,6 +187,7 @@ export type P2SHReturn<T extends P2Ret> = T extends {
  * Wraps a child script inside P2SH.
  * @param child - child payment descriptor to wrap
  * @param network - address network parameters
+ * @param allowNonCanonicalScript - whether to create an address for a non-minimal child script
  * @returns P2SH descriptor preserving witness metadata when present.
  * @throws If the wrapped script combination is invalid or unsupported. {@link Error}
  * @example
@@ -196,7 +198,7 @@ export type P2SHReturn<T extends P2Ret> = T extends {
  * p2sh(p2wsh(p2pk(hex.decode('0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'))));
  * ```
  */
-export declare const p2sh: <T extends P2Ret>(child: TArg<T>, network?: BTC_NETWORK) => TRet<Extends<P2SHReturn<T>, P2Ret>>;
+export declare const p2sh: <T extends P2Ret>(child: TArg<T>, network?: BTC_NETWORK, allowNonCanonicalScript?: boolean) => TRet<Extends<P2SHReturn<T>, P2Ret>>;
 /** Pay-to-witness-script-hash descriptor. */
 export type P2WSH = {
     /** Payment-script tag for pay-to-witness-script-hash outputs. */
@@ -214,6 +216,7 @@ export type P2WSH = {
  * Wraps a child script inside native SegWit P2WSH.
  * @param child - child payment descriptor to wrap
  * @param network - address network parameters
+ * @param allowNonCanonicalScript - whether to create an address for a non-minimal child script
  * @returns P2WSH descriptor.
  * @throws If the wrapped script combination is invalid or unsupported. {@link Error}
  * @example
@@ -224,7 +227,7 @@ export type P2WSH = {
  * p2wsh(p2pk(hex.decode('0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798')));
  * ```
  */
-export declare const p2wsh: (child: TArg<P2Ret>, network?: BTC_NETWORK) => TRet<Extends<P2WSH, P2Ret>>;
+export declare const p2wsh: (child: TArg<P2Ret>, network?: BTC_NETWORK, allowNonCanonicalScript?: boolean) => TRet<Extends<P2WSH, P2Ret>>;
 /** Pay-to-witness-public-key-hash descriptor. */
 export type P2WPKH = {
     /** Payment-script tag for pay-to-witness-public-key-hash outputs. */
@@ -380,6 +383,7 @@ export type P2TRRet<T> = T extends TaprootScriptTree ? P2TR_TREE : P2TR;
  * @param customScripts - optional custom script codecs for taproot leaves
  * @returns Taproot descriptor with optional script-path metadata.
  * @throws If the internal key or taproot script tree is invalid. {@link Error}
+ * @throws If a numeric script value is outside its supported range. {@link RangeError}
  * @example
  * Combine script leaves into a final taproot output descriptor and address.
  * ```ts
@@ -393,23 +397,27 @@ export type P2TRRet<T> = T extends TaprootScriptTree ? P2TR_TREE : P2TR;
  */
 export declare function p2tr(internalPubKey: TArg<Bytes | string>, tree?: undefined, network?: BTC_NETWORK, allowUnknownOutputs?: boolean, customScripts?: TArg<CustomScript[]>): TRet<Extends<P2TR, P2Ret>>;
 export declare function p2tr(internalPubKey: TArg<Bytes | string | undefined>, tree: TArg<TaprootScriptTree>, network?: BTC_NETWORK, allowUnknownOutputs?: boolean, customScripts?: TArg<CustomScript[]>): TRet<Extends<P2TR_TREE, P2Ret>>;
+/** Maximum number of combinations materialized by one default helper call. */
+export declare const MAX_COMBINATIONS = 4096;
 /**
  * Returns all size-`m` combinations from a list.
  * @param m - size of each combination
  * @param list - input items to combine
+ * @param maxCombinations - maximum result rows to materialize
  * @returns Array of combinations.
  * @throws If the combination size or input list is invalid. {@link Error}
+ * @throws If the requested result exceeds the materialization limit. {@link RangeError}
  * @example
  * Enumerate all size-two subsets of a short list.
  * ```ts
  * combinations(2, [1, 2, 3]);
  * ```
  */
-export declare function combinations<T>(m: number, list: T[]): T[][];
+export declare function combinations<T>(m: number, list: T[], maxCombinations?: number): T[][];
 /**
  * M-of-N multi-leaf wallet via p2tr_ns. If m == n, single script is emitted.
- * Takes O(n^2) if m != n. 99-of-100 is ok, 5-of-100 is not.
- * It materializes C(n, m) leaves, so middle-of-the-range thresholds blow up combinatorially.
+ * It materializes C(n, m) leaves up to {@link MAX_COMBINATIONS}; middle-of-the-range thresholds
+ * above that bound are rejected before allocation.
  * `2-of-[A,B,C] => [A,B] | [A,C] | [B,C]`
  */
 export type P2TR_NS = {
@@ -425,6 +433,7 @@ export type P2TR_NS = {
  * @param allowSamePubkeys - whether duplicate keys are allowed
  * @returns Array of taproot leaf descriptors.
  * @throws If the taproot multisig parameters are invalid. {@link Error}
+ * @throws If the requested leaf set exceeds the materialization limit. {@link RangeError}
  * @example
  * Build the leaf set for an M-of-N taproot `CHECKSIGVERIFY` policy.
  * ```ts
@@ -443,6 +452,7 @@ export type P2TR_PK = P2TR_NS;
  * @param pubkey - Schnorr public key
  * @returns Taproot single-key leaf descriptor.
  * @throws If the taproot single-key leaf cannot be encoded. {@link Error}
+ * @throws If the delegated leaf policy exceeds its supported range. {@link RangeError}
  * @example
  * Build a single-key tapscript leaf.
  * ```ts
@@ -482,6 +492,7 @@ export declare function p2tr_ms(m: number, pubkeys: TArg<Bytes[]>, allowSamePubk
  * @param network - address network parameters
  * @returns Encoded Bitcoin address.
  * @throws If the requested address type is unknown. {@link Error}
+ * @throws If a key-derived script value is outside its supported range. {@link RangeError}
  * @example
  * Pick the output type first, then derive the matching address from the private key.
  * ```ts