@scure/btc-signer 2.0.1 → 2.3.0

package/utils.js

@@ -1,27 +1,208 @@
 import { schnorr, secp256k1 as secp } from '@noble/curves/secp256k1.js';
-import { bytesToNumberBE, numberToBytesBE } from '@noble/curves/utils.js';
+import { abytes, bytesToNumberBE, numberToBytesBE } from '@noble/curves/utils.js';
 import { ripemd160 } from '@noble/hashes/legacy.js';
-import { sha256 } from '@noble/hashes/sha2.js';
+import { sha256 as nobleSha256 } from '@noble/hashes/sha2.js';
+import {} from '@noble/hashes/utils.js';
 import { utils as packedUtils, U32LE } from 'micro-packed';
-const Point = secp.Point;
-const Fn = Point.Fn;
-const CURVE_ORDER = Point.Fn.ORDER;
-export const hasEven = (y) => y % 2n === 0n;
-const isBytes = packedUtils.isBytes;
-const concatBytes = packedUtils.concatBytes;
-const equalBytes = packedUtils.equalBytes;
-export { concatBytes, equalBytes, isBytes, sha256 };
+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
+ * @returns `true` when the coordinate is even.
+ * @example
+ * Check whether a point coordinate has even parity.
+ * ```ts
+ * hasEven(2n);
+ * ```
+ */
+export const hasEven = (y) => y % _2n === _0n;
+/**
+ * Checks whether a value is a Uint8Array.
+ * @param a - value to inspect
+ * @returns `true` when the value is a Uint8Array.
+ * @example
+ * Check whether an unknown value is already bytes.
+ * ```ts
+ * isBytes(new Uint8Array([1]));
+ * ```
+ */
+export const isBytes = /* @__PURE__ */ (() => packedUtils.isBytes)();
+/**
+ * Concatenates byte arrays into a single Uint8Array.
+ * @param arrays - byte arrays to concatenate
+ * @returns Concatenated byte array.
+ * @example
+ * Join several byte chunks before hashing or signing them.
+ * ```ts
+ * concatBytes(new Uint8Array([1]), new Uint8Array([2]));
+ * ```
+ */
+export const concatBytes = 
+/* @__PURE__ */ (() => packedUtils.concatBytes)();
+/**
+ * Compares two byte arrays for equality.
+ * @param a - first byte array
+ * @param b - second byte array
+ * @returns `true` when both arrays contain the same bytes.
+ * @example
+ * Compare two serialized values without converting them first.
+ * ```ts
+ * equalBytes(new Uint8Array([1]), new Uint8Array([1]));
+ * ```
+ */
+export const equalBytes = 
+/* @__PURE__ */ (() => packedUtils.equalBytes)();
+/**
+ * SHA-256 hash function.
+ * @param msg - bytes to hash
+ * @returns SHA-256 digest.
+ * @example
+ * Hash a byte array with SHA-256.
+ * ```ts
+ * sha256(new Uint8Array([1, 2, 3]));
+ * ```
+ */
+export const sha256 = /* @__PURE__ */ (() => nobleSha256)();
+/**
+ * HASH160 helper used by classic Bitcoin addresses.
+ * @param msg - bytes to hash
+ * @returns RIPEMD160(SHA256(msg)).
+ * @example
+ * Derive the HASH160 used by legacy address formats.
+ * ```ts
+ * hash160(new Uint8Array([1, 2, 3]));
+ * ```
+ */
 export const hash160 = (msg) => ripemd160(sha256(msg));
+/**
+ * Double-SHA256 helper used by Bitcoin transaction ids.
+ * @param msgs - message parts to concatenate and hash
+ * @returns SHA256(SHA256(concat(msgs))).
+ * @example
+ * Compute the double-SHA256 used by txids and sighashes.
+ * ```ts
+ * sha256x2(new Uint8Array([1]), new Uint8Array([2]));
+ * ```
+ */
 export const sha256x2 = (...msgs) => sha256(sha256(concatBytes(...msgs)));
-export const randomPrivateKeyBytes = schnorr.utils.randomSecretKey;
-export const pubSchnorr = schnorr.getPublicKey;
-export const pubECDSA = secp.getPublicKey;
+/**
+ * Generates a random secp256k1 private key.
+ * @returns Random 32-byte private key.
+ * @example
+ * Generate a fresh secp256k1 private key for signing.
+ * ```ts
+ * const privKey = randomPrivateKeyBytes();
+ * ```
+ */
+export const randomPrivateKeyBytes = () => schnorr.utils.randomSecretKey();
+/**
+ * Derives a BIP340 Schnorr public key from a private key.
+ * @param priv - private key bytes
+ * @returns X-only public key bytes.
+ * @example
+ * Derive the x-only public key used by Schnorr and Taproot.
+ * ```ts
+ * import { pubSchnorr, randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * pubSchnorr(randomPrivateKeyBytes());
+ * ```
+ */
+export const pubSchnorr = (priv) => schnorr.getPublicKey(priv);
+/**
+ * Derives a secp256k1 ECDSA public key from a private key.
+ * @param privateKey - private key bytes
+ * @param isCompressed - whether to return the compressed form
+ * @returns Serialized public key bytes.
+ * @example
+ * Derive the normal secp256k1 public key for legacy or SegWit scripts.
+ * ```ts
+ * import { pubECDSA, randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * pubECDSA(randomPrivateKeyBytes());
+ * ```
+ */
+export const pubECDSA = (privateKey, isCompressed) => secp.getPublicKey(privateKey, isCompressed);
 // low-r signature grinding. Used to reduce tx size by 1 byte.
 // 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
+ * @param privateKey - signer private key
+ * @param lowR - whether to grind for low-R signatures
+ * @returns DER-encoded signature bytes.
+ * @throws If low-R grinding overflows or ECDSA signing fails validation. {@link Error}
+ * @example
+ * Hash a message first, then create the DER-encoded ECDSA signature.
+ * ```ts
+ * import { randomPrivateKeyBytes, sha256, signECDSA } from '@scure/btc-signer/utils.js';
+ * signECDSA(sha256(new Uint8Array([1, 2, 3])), randomPrivateKeyBytes());
+ * ```
+ */
 export function signECDSA(hash, privateKey, lowR = false) {
+    // signECDSA is the 32-byte sighash wrapper for BTC callers, so reject arbitrary-length
+    // messages here instead of silently signing them with prehash disabled.
+    abytes(hash, 32, 'hash');
     let sig = secp.Signature.fromBytes(secp.sign(hash, privateKey, { prehash: false }));
     if (lowR && !hasLowR(sig)) {
         const extraEntropy = new Uint8Array(32);
@@ -35,30 +216,89 @@ export function signECDSA(hash, privateKey, lowR = false) {
     }
     return sig.toBytes('der');
 }
-export const signSchnorr = schnorr.sign;
-export const tagSchnorr = schnorr.utils.taggedHash;
-export const PubT = {
+/**
+ * BIP340 Schnorr signing function.
+ * @param message - 32-byte message digest
+ * @param secretKey - signer private key
+ * @param auxRand - optional auxiliary randomness
+ * @returns Schnorr signature bytes.
+ * @example
+ * Sign a 32-byte digest with the built-in BIP340 helper.
+ * ```ts
+ * import { randomPrivateKeyBytes, sha256, signSchnorr } from '@scure/btc-signer/utils.js';
+ * const msg = sha256(new Uint8Array([1, 2, 3]));
+ * signSchnorr(msg, randomPrivateKeyBytes());
+ * ```
+ */
+export const signSchnorr = (message, secretKey, auxRand) => schnorr.sign(message, secretKey, auxRand);
+/**
+ * Tagged-hash helper used by Schnorr and taproot constructions.
+ * @param tag - tagged-hash domain separator
+ * @param messages - message parts hashed under the tag
+ * @returns Tagged SHA-256 digest.
+ * @example
+ * Build the tagged hash used by Taproot leaves or tweaks.
+ * ```ts
+ * import { tagSchnorr } from '@scure/btc-signer/utils.js';
+ * tagSchnorr('TapLeaf', Uint8Array.of(0xc0), Uint8Array.of(0x51));
+ * ```
+ */
+export const tagSchnorr = (tag, ...messages) => schnorr.utils.taggedHash(tag, ...messages);
+/** Public key format tags used by validation helpers. */
+export const PubT = /* @__PURE__ */ (() => Object.freeze({
     ecdsa: 0,
     schnorr: 1,
-};
+}))();
+/**
+ * Validates a public key against the expected Bitcoin key encoding.
+ * @param pub - public key bytes to validate
+ * @param type - expected public key format
+ * @returns The validated public key bytes.
+ * @throws On wrong argument types. {@link TypeError}
+ * @throws On wrong argument ranges or values. {@link RangeError}
+ * @example
+ * Reject keys that do not match the encoding required by the current script path.
+ * ```ts
+ * import {
+ *   PubT,
+ *   pubECDSA,
+ *   randomPrivateKeyBytes,
+ *   validatePubkey,
+ * } from '@scure/btc-signer/utils.js';
+ * validatePubkey(pubECDSA(randomPrivateKeyBytes()), PubT.ecdsa);
+ * ```
+ */
 export function validatePubkey(pub, type) {
     const len = pub.length;
     if (type === PubT.ecdsa) {
         if (len === 32)
-            throw new Error('Expected non-Schnorr key');
+            throw new RangeError('Expected non-Schnorr key');
         Point.fromBytes(pub); // does assertValidity
         return pub;
     }
     else if (type === PubT.schnorr) {
         if (len !== 32)
-            throw new Error('Expected 32-byte Schnorr key');
+            throw new RangeError('Expected 32-byte Schnorr key');
         schnorr.utils.lift_x(bytesToNumberBE(pub));
         return pub;
     }
     else {
-        throw new Error('Unknown key type');
+        throw new TypeError('Unknown key type');
     }
 }
+/**
+ * Computes the Taproot tweak scalar from an internal key and merkle root.
+ * @param a - internal key bytes
+ * @param b - optional merkle root bytes
+ * @returns Taproot tweak scalar.
+ * @throws If the tweak scalar is outside the curve order. {@link Error}
+ * @example
+ * Combine the internal key and Merkle root into the Taproot tweak scalar.
+ * ```ts
+ * import { pubSchnorr, randomPrivateKeyBytes, tapTweak } from '@scure/btc-signer/utils.js';
+ * tapTweak(pubSchnorr(randomPrivateKeyBytes()), new Uint8Array());
+ * ```
+ */
 export function tapTweak(a, b) {
     const u = schnorr.utils;
     const t = u.taggedHash('TapTweak', a, b);
@@ -67,8 +307,24 @@ export function tapTweak(a, b) {
         throw new Error('tweak higher than curve order');
     return tn;
 }
+/**
+ * Tweaks a private key for Taproot key-path spending.
+ * @param privKey - internal private key bytes
+ * @param merkleRoot - optional taproot merkle root
+ * @returns Tweaked private key bytes.
+ * @throws If the Taproot tweak scalar is outside the curve order. {@link Error}
+ * @example
+ * Derive the tweaked Taproot key-path secret from the internal private key.
+ * ```ts
+ * import { randomPrivateKeyBytes, taprootTweakPrivKey } from '@scure/btc-signer/utils.js';
+ * taprootTweakPrivKey(randomPrivateKeyBytes());
+ * ```
+ */
 export function taprootTweakPrivKey(privKey, merkleRoot = Uint8Array.of()) {
     const u = schnorr.utils;
+    // BIP341 taproot_tweak_seckey starts with `seckey0 = int_from_bytes(seckey0)`, and
+    // BIP340 defines `int(x)` only for `x` as a 32-byte array, so reject other widths here.
+    abytes(privKey, 32, 'privKey');
     const seckey0 = bytesToNumberBE(privKey); // seckey0 = int_from_bytes(seckey0)
     const P = Point.BASE.multiply(seckey0); // P = point_mul(G, seckey0)
     // seckey = seckey0 if has_even_y(P) else SECP256K1_ORDER - seckey0
@@ -79,8 +335,28 @@ export function taprootTweakPrivKey(privKey, merkleRoot = Uint8Array.of()) {
     // bytes_from_int((seckey + t) % SECP256K1_ORDER)
     return numberToBytesBE(Fn.add(seckey, t), 32);
 }
+/**
+ * Tweaks a Schnorr public key for Taproot key-path spending.
+ * @param pubKey - x-only internal public key
+ * @param h - taproot merkle root
+ * @returns Tweaked public key and output-key parity.
+ * @throws If the Taproot tweak scalar is outside the curve order. {@link Error}
+ * @example
+ * Derive the final Taproot output key from the internal key and Merkle root.
+ * ```ts
+ * import {
+ *   pubSchnorr,
+ *   randomPrivateKeyBytes,
+ *   taprootTweakPubkey,
+ * } from '@scure/btc-signer/utils.js';
+ * taprootTweakPubkey(pubSchnorr(randomPrivateKeyBytes()), new Uint8Array());
+ * ```
+ */
 export function taprootTweakPubkey(pubKey, h) {
     const u = schnorr.utils;
+    // BIP341 taproot_tweak_pubkey feeds `pubkey` into `int_from_bytes(pubkey)`, and
+    // BIP340 defines `int(x)` only for `x` as a 32-byte array, so reject other widths here.
+    abytes(pubKey, 32, 'pubKey');
     const t = tapTweak(pubKey, h); // t = int_from_bytes(tagged_hash("TapTweak", pubkey + h))
     const P = u.lift_x(bytesToNumberBE(pubKey)); // P = lift_x(int_from_bytes(pubkey))
     const Q = P.add(Point.BASE.multiply(t)); // Q = point_add(P, point_mul(G, t))
@@ -89,27 +365,46 @@ export function taprootTweakPubkey(pubKey, h) {
 }
 // Another stupid decision, where lack of standard affects security.
 // Multisig needs to be generated with some key.
-// We are using approach from BIP 341/bitcoinjs-lib: SHA256(uncompressedDER(SECP256K1_GENERATOR_POINT))
+// We are using the BIP 341/bitcoinjs-lib approach:
+// SHA256(uncompressedDER(SECP256K1_GENERATOR_POINT))
 // It is possible to switch SECP256K1_GENERATOR_POINT with some random point;
 // but it's too complex to prove.
 // Also used by bitcoin-core and bitcoinjs-lib
-export const TAPROOT_UNSPENDABLE_KEY = sha256(Point.BASE.toBytes(false));
-export const NETWORK = {
+// 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)))();
+/** Bitcoin mainnet network parameters. */
+export const NETWORK = /* @__PURE__ */ Object.freeze({
     bech32: 'bc',
     pubKeyHash: 0x00,
     scriptHash: 0x05,
     wif: 0x80,
-};
-export const TEST_NETWORK = {
+});
+/** Bitcoin testnet network parameters. */
+export const TEST_NETWORK = /* @__PURE__ */ Object.freeze({
     bech32: 'tb',
     pubKeyHash: 0x6f,
     scriptHash: 0xc4,
     wif: 0xef,
-};
+});
 // Exported for tests, internal method
+/**
+ * Lexicographically compares two byte arrays.
+ * @param a - first byte array
+ * @param b - second byte array
+ * @returns `-1`, `0`, or `1` depending on the ordering.
+ * @throws On wrong argument types. {@link TypeError}
+ * @example
+ * Compare two serialized keys using Bitcoin's byte ordering.
+ * ```ts
+ * compareBytes(new Uint8Array([1]), new Uint8Array([2]));
+ * ```
+ */
 export function compareBytes(a, b) {
     if (!isBytes(a) || !isBytes(b))
-        throw new Error(`cmp: wrong type a=${typeof a} b=${typeof b}`);
+        throw new TypeError(`cmp: wrong type a=${typeof a} b=${typeof b}`);
     // -1 -> a<b, 0 -> a==b, 1 -> a>b
     const len = Math.min(a.length, b.length);
     for (let i = 0; i < len; i++)
@@ -118,8 +413,21 @@ export function compareBytes(a, b) {
     return Math.sign(a.length - b.length);
 }
 // Reverses key<->values
+/**
+ * Reverses an object's keys and values.
+ * @param obj - object to reverse
+ * @returns Object with original values mapped back to keys.
+ * @throws If duplicate values would collide while reversing the object. {@link Error}
+ * @example
+ * Flip a lookup table so the values become keys.
+ * ```ts
+ * reverseObject({ a: 1, b: 2 });
+ * ```
+ */
 export function reverseObject(obj) {
-    const res = {};
+    // Keep a raw dictionary shape so enum-like tables can reverse values like
+    // `toString` without colliding with inherited Object prototype properties.
+    const res = Object.create(null);
     for (const k in obj) {
         if (res[obj[k]] !== undefined)
             throw new Error('duplicate key');
@@ -127,4 +435,3 @@ export function reverseObject(obj) {
     }
     return res;
 }
-//# sourceMappingURL=utils.js.map