@scure/btc-signer 2.2.0 → 2.4.0

package/utils.d.ts

@@ -1,10 +1,40 @@
 import { sha256 as nobleSha256 } from '@noble/hashes/sha2.js';
 import { type TArg, type TRet } from '@noble/hashes/utils.js';
+export { abytes, validateObject as vld } from '@noble/curves/utils.js';
 export { type TArg, type TRet } from '@noble/hashes/utils.js';
 /** Hex-like input accepted by helpers in this module. */
 export type Hex = string | Uint8Array;
 /** Byte array alias used across the library. */
 export type Bytes = Uint8Array;
+/**
+ * Validates that a value is a non-negative bigint.
+ * @param n - Value to validate.
+ * @param title - Label included in thrown errors.
+ * @returns The same bigint.
+ * @throws On wrong argument types. {@link TypeError}
+ * @example
+ * Validate a satoshi amount before transaction encoding.
+ * ```ts
+ * abigint(1n, 'amount');
+ * ```
+ */
+export declare function abigint(n: unknown, title?: string): bigint;
+export declare function aarray<T>(item: unknown, title: string, inner?: (elm: T, title: string) => void): T[];
+/**
+ * Asserts something is a string.
+ * @param value - Value to validate.
+ * @param title - Label included in thrown errors.
+ * @returns The validated string.
+ * @throws On wrong argument types. {@link TypeError}
+ * @example
+ * Validate a label string.
+ *
+ * ```ts
+ * astring('example', 'label');
+ * ```
+ */
+export declare function astring(value: unknown, title?: string): string;
+export declare function validateObject(object: Record<string, any>, fields?: Record<string, string>, optFields?: Record<string, string>, _title?: string): void;
 /**
  * Checks whether a curve y-coordinate is even.
  * @param y - y-coordinate to inspect
@@ -234,8 +264,22 @@ export declare function taprootTweakPrivKey(privKey: TArg<Bytes>, merkleRoot?: T
  * ```
  */
 export declare function taprootTweakPubkey(pubKey: TArg<Bytes>, h: TArg<Bytes>): TRet<[Bytes, number]>;
-/** Standard unspendable internal key used for script-only Taproot outputs. */
+/**
+ * Standard unspendable internal key used for script-only Taproot outputs.
+ * @deprecated Use {@link taprootNumsKey} to receive an owned copy.
+ */
 export declare const TAPROOT_UNSPENDABLE_KEY: TRet<Bytes>;
+/**
+ * Returns an owned copy of the library's stable Taproot NUMS key.
+ * @returns A new 32-byte NUMS key copy.
+ * @example
+ * Obtain an internal key without sharing mutable exported storage.
+ * ```ts
+ * import { taprootNumsKey } from '@scure/btc-signer/utils.js';
+ * const internalKey = taprootNumsKey();
+ * ```
+ */
+export declare function taprootNumsKey(): TRet<Bytes>;
 /** Bitcoin network parameters. */
 export type BTC_NETWORK = {
     /** Human-readable prefix used by Bech32 and Bech32m addresses. */
@@ -280,4 +324,3 @@ export declare function reverseObject<T extends Record<string, string | number>>
 };
 /** Union of all value types in an object type. */
 export type ValueOf<T> = T[keyof T];
-//# sourceMappingURL=utils.d.ts.map

package/utils.js

@@ -4,10 +4,64 @@ import { ripemd160 } from '@noble/hashes/legacy.js';
 import { sha256 as nobleSha256 } from '@noble/hashes/sha2.js';
 import {} from '@noble/hashes/utils.js';
 import { utils as packedUtils, U32LE } from 'micro-packed';
+export { abytes, validateObject as vld } from '@noble/curves/utils.js';
 export {} from '@noble/hashes/utils.js';
+/**
+ * Validates that a value is a non-negative bigint.
+ * @param n - Value to validate.
+ * @param title - Label included in thrown errors.
+ * @returns The same bigint.
+ * @throws On wrong argument types. {@link TypeError}
+ * @example
+ * Validate a satoshi amount before transaction encoding.
+ * ```ts
+ * abigint(1n, 'amount');
+ * ```
+ */
+export function abigint(n, title = 'value') {
+    if (typeof n !== 'bigint')
+        throw new TypeError(`"${title}" expected bigint, got type=${typeof n}`);
+    if (n < _0n)
+        throw new RangeError(`"${title}" expected non-negative bigint, got ${n}`);
+    return n;
+}
+import { validateObject as vld } from '@noble/curves/utils.js';
+export function aarray(item, title, inner = () => { }) {
+    if (!Array.isArray(item))
+        throw new TypeError(`"${title}" expected array, got type=${typeof item}`);
+    for (let i = 0; i < item.length; i++)
+        inner(item[i], `${title}[${i}]`);
+    return item;
+}
+/**
+ * Asserts something is a string.
+ * @param value - Value to validate.
+ * @param title - Label included in thrown errors.
+ * @returns The validated string.
+ * @throws On wrong argument types. {@link TypeError}
+ * @example
+ * Validate a label string.
+ *
+ * ```ts
+ * astring('example', 'label');
+ * ```
+ */
+export function astring(value, title = '') {
+    if (typeof value !== 'string') {
+        const prefix = title && `"${title}" `;
+        throw new TypeError(prefix + 'expected string, got type=' + typeof value);
+    }
+    return value;
+}
+export function validateObject(object, fields = {}, optFields = {}, _title = 'object') {
+    return vld(object, fields, optFields);
+}
 const Point = /* @__PURE__ */ (() => secp.Point)();
 const Fn = /* @__PURE__ */ (() => Point.Fn)();
 const CURVE_ORDER = /* @__PURE__ */ (() => Point.Fn.ORDER)();
+// Be friendly to bad ECMAScript parsers by not using bigint literals.
+// prettier-ignore
+const _0n = /* @__PURE__ */ BigInt(0), _2n = /* @__PURE__ */ BigInt(2);
 /**
  * Checks whether a curve y-coordinate is even.
  * @param y - y-coordinate to inspect
@@ -18,7 +72,7 @@ const CURVE_ORDER = /* @__PURE__ */ (() => Point.Fn.ORDER)();
  * hasEven(2n);
  * ```
  */
-export const hasEven = (y) => y % 2n === 0n;
+export const hasEven = (y) => y % _2n === _0n;
 /**
  * Checks whether a value is a Uint8Array.
  * @param a - value to inspect
@@ -127,7 +181,10 @@ export const pubECDSA = (privateKey, isCompressed) => secp.getPublicKey(privateK
 // noble/secp256k1 does not support the feature: it is not used outside of BTC.
 // We implement it manually, because in BTC it's common.
 // Not best way, but closest to bitcoin implementation (easier to check)
-const hasLowR = (sig) => sig.r < CURVE_ORDER / 2n;
+// Hoisted: the bound is constant; no need to redo the bigint division on every
+// grinding-loop iteration. n/2 < 2^255, so r < n/2 guarantees the 32-byte DER r.
+const LOW_R_BOUND = /* @__PURE__ */ (() => CURVE_ORDER / _2n)();
+const hasLowR = (sig) => sig.r < LOW_R_BOUND;
 /**
  * Signs a 32-byte hash with ECDSA and returns DER encoding.
  * @param hash - message hash to sign
@@ -316,8 +373,27 @@ export function taprootTweakPubkey(pubKey, h) {
 // This is the fixed BIP 341 H example, not the privacy-preserving H + rG variant.
 // Downstream helpers use exact-byte equality with it to recognize
 // library-generated script-only outputs.
-/** Standard unspendable internal key used for script-only Taproot outputs. */
-export const TAPROOT_UNSPENDABLE_KEY = /* @__PURE__ */ (() => sha256(Point.BASE.toBytes(false)))();
+// Keep the value used by library internals private: exported Uint8Arrays are mutable, so the
+// public compatibility export below cannot safely be a source of cryptographic key material.
+const INTERNAL_TAPROOT_NUMS = /* @__PURE__ */ (() => sha256(Point.BASE.toBytes(false)))();
+/**
+ * Standard unspendable internal key used for script-only Taproot outputs.
+ * @deprecated Use {@link taprootNumsKey} to receive an owned copy.
+ */
+export const TAPROOT_UNSPENDABLE_KEY = /* @__PURE__ */ (() => Uint8Array.from(INTERNAL_TAPROOT_NUMS))();
+/**
+ * Returns an owned copy of the library's stable Taproot NUMS key.
+ * @returns A new 32-byte NUMS key copy.
+ * @example
+ * Obtain an internal key without sharing mutable exported storage.
+ * ```ts
+ * import { taprootNumsKey } from '@scure/btc-signer/utils.js';
+ * const internalKey = taprootNumsKey();
+ * ```
+ */
+export function taprootNumsKey() {
+    return Uint8Array.from(INTERNAL_TAPROOT_NUMS);
+}
 /** Bitcoin mainnet network parameters. */
 export const NETWORK = /* @__PURE__ */ Object.freeze({
     bech32: 'bc',
@@ -378,4 +454,3 @@ export function reverseObject(obj) {
     }
     return res;
 }
-//# sourceMappingURL=utils.js.map

package/utxo.d.ts

@@ -1,7 +1,7 @@
 import * as P from 'micro-packed';
 import * as psbt from './psbt.ts';
 import { Transaction, type TxOpts } from './transaction.ts';
-import { type Bytes, NETWORK, type TArg } from './utils.ts';
+import { type Bytes, NETWORK, type TArg, type TRet } from './utils.ts';
 /** Minimal output target accepted by the UTXO selector. */
 export type Output = {
     address: string;
@@ -17,6 +17,21 @@ export type Accumulated = {
     weight: number;
     total: bigint;
 } | undefined;
+/**
+ * Removes Taproot spend paths that cannot be satisfied by the supplied Schnorr public keys.
+ * Non-Taproot inputs are retained, and caller-owned input metadata is never mutated.
+ * @param inputs - candidate PSBT input records to filter
+ * @param pubkeys - available x-only Schnorr public keys
+ * @returns Copies of inputs that retain at least one available path
+ * @example
+ * Filter wallet UTXOs before selecting coins.
+ * ```ts
+ * import { filterTaproot } from '@scure/btc-signer/utxo.js';
+ * import { pubSchnorr, randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * const spendable = filterTaproot([], [pubSchnorr(randomPrivateKeyBytes())]);
+ * ```
+ */
+export declare function filterTaproot(inputs: TArg<psbt.TransactionInputUpdate[]>, pubkeys: TArg<Bytes[]>): TRet<psbt.TransactionInputUpdate[]>;
 export declare const _cmpBig: (a: bigint, b: bigint) => 0 | 1 | -1;
 /** Options for fee estimation and UTXO selection. */
 export type EstimatorOpts = TxOpts & {
@@ -30,6 +45,8 @@ export type EstimatorOpts = TxOpts & {
     createTx?: boolean;
     requiredInputs?: psbt.TransactionInputUpdate[];
     allowSameUtxo?: boolean;
+    /** Filter Taproot candidate paths to those satisfiable by these Schnorr public keys. */
+    filterTaproot?: Bytes[];
 };
 type SortStrategy = 'Newest' | 'Oldest' | 'Smallest' | 'Biggest';
 type ExactStrategy = `exact${SortStrategy}`;
@@ -118,6 +135,25 @@ export declare class _Estimator {
             }>][] | undefined;
             tapInternalKey?: Bytes | undefined;
             tapMerkleRoot?: Bytes | undefined;
+            p2cKeyTweak?: [Bytes, Bytes][] | undefined;
+            musig2ParticipantPubkeys?: [Bytes, Bytes[]][] | undefined;
+            musig2PubNonce?: [TArg<{
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            }>, Bytes][] | undefined;
+            musig2PartialSig?: [TArg<{
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            }>, Bytes][] | undefined;
+            spEcdhShare?: [Bytes, Bytes][] | undefined;
+            spDleq?: [Bytes, Bytes][] | undefined;
+            spSpendBip32Derivation?: [Bytes, P.StructInput<{
+                fingerprint: number;
+                path: number[];
+            }>][] | undefined;
+            spTweak?: Bytes | undefined;
             proprietary?: [Bytes, Bytes][] | undefined;
         } & {
             unknown?: [P.UnwrapCoder<P.CoderType<P.StructInput<{
@@ -270,6 +306,74 @@ export declare class _Estimator {
             }])[]) | undefined;
             tapInternalKey?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
             tapMerkleRoot?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
+            p2cKeyTweak?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+            musig2ParticipantPubkeys?: ([Bytes, Bytes[]][] & ([Bytes, Bytes[]] & [Bytes & Uint8Array<ArrayBuffer>, Bytes[] & (Bytes & Uint8Array<ArrayBuffer>)[]])[]) | undefined;
+            musig2PubNonce?: ([TArg<{
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            }>, Bytes][] & ([TArg<{
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            }>, Bytes] & [({
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            } & {
+                participantPubkey: Bytes & Uint8Array<ArrayBuffer>;
+                aggregatePubkey: Bytes & Uint8Array<ArrayBuffer>;
+                leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
+            }) | ({
+                participantPubkey: TArg<Bytes>;
+                aggregatePubkey: TArg<Bytes>;
+                leafHash?: TArg<Bytes | undefined>;
+            } & {
+                participantPubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+                aggregatePubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+                leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>) | undefined;
+            }), Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+            musig2PartialSig?: ([TArg<{
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            }>, Bytes][] & ([TArg<{
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            }>, Bytes] & [({
+                participantPubkey: Bytes;
+                aggregatePubkey: Bytes;
+                leafHash?: Bytes;
+            } & {
+                participantPubkey: Bytes & Uint8Array<ArrayBuffer>;
+                aggregatePubkey: Bytes & Uint8Array<ArrayBuffer>;
+                leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
+            }) | ({
+                participantPubkey: TArg<Bytes>;
+                aggregatePubkey: TArg<Bytes>;
+                leafHash?: TArg<Bytes | undefined>;
+            } & {
+                participantPubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+                aggregatePubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+                leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>) | undefined;
+            }), Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+            spEcdhShare?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+            spDleq?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+            spSpendBip32Derivation?: ([Bytes, P.StructInput<{
+                fingerprint: number;
+                path: number[];
+            }>][] & ([Bytes, P.StructInput<{
+                fingerprint: number;
+                path: number[];
+            }>] & [Bytes & Uint8Array<ArrayBuffer>, {
+                path: number[];
+                fingerprint: number;
+            } & {} & {
+                path: number[] & number[];
+                fingerprint: number;
+            }])[]) | undefined;
+            spTweak?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
             proprietary?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
             unknown?: ([P.StructInput<{
                 type: number;
@@ -383,6 +487,25 @@ export declare function selectUTXO(inputs: TArg<psbt.TransactionInputUpdate[]>,
         }>][] | undefined;
         tapInternalKey?: Bytes | undefined;
         tapMerkleRoot?: Bytes | undefined;
+        p2cKeyTweak?: [Bytes, Bytes][] | undefined;
+        musig2ParticipantPubkeys?: [Bytes, Bytes[]][] | undefined;
+        musig2PubNonce?: [TArg<{
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        }>, Bytes][] | undefined;
+        musig2PartialSig?: [TArg<{
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        }>, Bytes][] | undefined;
+        spEcdhShare?: [Bytes, Bytes][] | undefined;
+        spDleq?: [Bytes, Bytes][] | undefined;
+        spSpendBip32Derivation?: [Bytes, P.StructInput<{
+            fingerprint: number;
+            path: number[];
+        }>][] | undefined;
+        spTweak?: Bytes | undefined;
         proprietary?: [Bytes, Bytes][] | undefined;
     } & {
         unknown?: [P.UnwrapCoder<P.CoderType<P.StructInput<{
@@ -535,6 +658,74 @@ export declare function selectUTXO(inputs: TArg<psbt.TransactionInputUpdate[]>,
         }])[]) | undefined;
         tapInternalKey?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
         tapMerkleRoot?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
+        p2cKeyTweak?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+        musig2ParticipantPubkeys?: ([Bytes, Bytes[]][] & ([Bytes, Bytes[]] & [Bytes & Uint8Array<ArrayBuffer>, Bytes[] & (Bytes & Uint8Array<ArrayBuffer>)[]])[]) | undefined;
+        musig2PubNonce?: ([TArg<{
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        }>, Bytes][] & ([TArg<{
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        }>, Bytes] & [({
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        } & {
+            participantPubkey: Bytes & Uint8Array<ArrayBuffer>;
+            aggregatePubkey: Bytes & Uint8Array<ArrayBuffer>;
+            leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
+        }) | ({
+            participantPubkey: TArg<Bytes>;
+            aggregatePubkey: TArg<Bytes>;
+            leafHash?: TArg<Bytes | undefined>;
+        } & {
+            participantPubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+            aggregatePubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+            leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>) | undefined;
+        }), Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+        musig2PartialSig?: ([TArg<{
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        }>, Bytes][] & ([TArg<{
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        }>, Bytes] & [({
+            participantPubkey: Bytes;
+            aggregatePubkey: Bytes;
+            leafHash?: Bytes;
+        } & {
+            participantPubkey: Bytes & Uint8Array<ArrayBuffer>;
+            aggregatePubkey: Bytes & Uint8Array<ArrayBuffer>;
+            leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
+        }) | ({
+            participantPubkey: TArg<Bytes>;
+            aggregatePubkey: TArg<Bytes>;
+            leafHash?: TArg<Bytes | undefined>;
+        } & {
+            participantPubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+            aggregatePubkey: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>);
+            leafHash?: (Bytes & Uint8Array<ArrayBuffer>) | (Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>) | undefined;
+        }), Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+        spEcdhShare?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+        spDleq?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
+        spSpendBip32Derivation?: ([Bytes, P.StructInput<{
+            fingerprint: number;
+            path: number[];
+        }>][] & ([Bytes, P.StructInput<{
+            fingerprint: number;
+            path: number[];
+        }>] & [Bytes & Uint8Array<ArrayBuffer>, {
+            path: number[];
+            fingerprint: number;
+        } & {} & {
+            path: number[] & number[];
+            fingerprint: number;
+        }])[]) | undefined;
+        spTweak?: (Bytes & Uint8Array<ArrayBuffer>) | undefined;
         proprietary?: ([Bytes, Bytes][] & ([Bytes, Bytes] & [Bytes & Uint8Array<ArrayBuffer>, Bytes & Uint8Array<ArrayBuffer>])[]) | undefined;
         unknown?: ([P.StructInput<{
             type: number;
@@ -558,4 +749,3 @@ export declare function selectUTXO(inputs: TArg<psbt.TransactionInputUpdate[]>,
     tx: Transaction | undefined;
 }) | undefined;
 export {};
-//# sourceMappingURL=utxo.d.ts.map