@scure/btc-signer 2.0.1 → 2.3.0

package/utils.d.ts

@@ -1,41 +1,312 @@
-import { schnorr } from '@noble/curves/secp256k1.js';
-import { sha256 } from '@noble/hashes/sha2.js';
+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
+ * @returns `true` when the coordinate is even.
+ * @example
+ * Check whether a point coordinate has even parity.
+ * ```ts
+ * hasEven(2n);
+ * ```
+ */
 export declare const hasEven: (y: bigint) => boolean;
-declare const isBytes: (a: unknown) => a is Uint8Array;
-declare const concatBytes: (...arrays: Uint8Array[]) => Uint8Array;
-declare const equalBytes: (a: Uint8Array, b: Uint8Array) => boolean;
-export { concatBytes, equalBytes, isBytes, sha256 };
-export declare const hash160: (msg: Uint8Array) => Uint8Array;
-export declare const sha256x2: (...msgs: Uint8Array[]) => Uint8Array;
-export declare const randomPrivateKeyBytes: () => Uint8Array;
-export declare const pubSchnorr: (priv: string | Uint8Array) => Uint8Array;
-export declare const pubECDSA: (privateKey: Uint8Array, isCompressed?: boolean) => Uint8Array;
-export declare function signECDSA(hash: Bytes, privateKey: Bytes, lowR?: boolean): Bytes;
-export declare const signSchnorr: typeof schnorr.sign;
-export declare const tagSchnorr: typeof schnorr.utils.taggedHash;
-export declare const PubT: {
-    ecdsa: number;
-    schnorr: number;
-};
+/**
+ * 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 declare const isBytes: (a: unknown) => a is Uint8Array;
+/**
+ * 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 declare const concatBytes: (...arrays: TArg<Uint8Array[]>) => TRet<Uint8Array>;
+/**
+ * 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 declare const equalBytes: (a: TArg<Uint8Array>, b: TArg<Uint8Array>) => boolean;
+/**
+ * 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 declare const sha256: typeof 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 declare const hash160: (msg: TArg<Uint8Array>) => TRet<Uint8Array>;
+/**
+ * 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 declare const sha256x2: (...msgs: TArg<Uint8Array[]>) => TRet<Uint8Array>;
+/**
+ * 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 declare const randomPrivateKeyBytes: () => TRet<Uint8Array>;
+/**
+ * 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 declare const pubSchnorr: (priv: TArg<Uint8Array>) => TRet<Uint8Array>;
+/**
+ * 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 declare const pubECDSA: (privateKey: TArg<Uint8Array>, isCompressed?: boolean) => TRet<Uint8Array>;
+/**
+ * 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 declare function signECDSA(hash: TArg<Bytes>, privateKey: TArg<Bytes>, lowR?: boolean): TRet<Bytes>;
+/**
+ * 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 declare const signSchnorr: (message: TArg<Uint8Array>, secretKey: TArg<Uint8Array>, auxRand?: TArg<Uint8Array>) => TRet<Uint8Array>;
+/**
+ * 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 declare const tagSchnorr: (tag: string, ...messages: TArg<Uint8Array[]>) => TRet<Uint8Array>;
+/** Public key format tags used by validation helpers. */
+export declare const PubT: Readonly<{
+    ecdsa: 0;
+    schnorr: 1;
+}>;
+/** Numeric public key format tag from {@link PubT}. */
 export type PubT = ValueOf<typeof PubT>;
-export declare function validatePubkey(pub: Bytes, type: PubT): Bytes;
-export declare function tapTweak(a: Bytes, b: Bytes): bigint;
-export declare function taprootTweakPrivKey(privKey: Bytes, merkleRoot?: Bytes): Bytes;
-export declare function taprootTweakPubkey(pubKey: Bytes, h: Bytes): [Bytes, number];
-export declare const TAPROOT_UNSPENDABLE_KEY: Bytes;
+/**
+ * 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 declare function validatePubkey(pub: TArg<Bytes>, type: PubT): TRet<Bytes>;
+/**
+ * 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 declare function tapTweak(a: TArg<Bytes>, b: TArg<Bytes>): bigint;
+/**
+ * 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 declare function taprootTweakPrivKey(privKey: TArg<Bytes>, merkleRoot?: TArg<Bytes>): TRet<Bytes>;
+/**
+ * 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 declare function taprootTweakPubkey(pubKey: TArg<Bytes>, h: TArg<Bytes>): TRet<[Bytes, number]>;
+/** Standard unspendable internal key used for script-only Taproot outputs. */
+export declare const TAPROOT_UNSPENDABLE_KEY: TRet<Bytes>;
+/** Bitcoin network parameters. */
 export type BTC_NETWORK = {
+    /** Human-readable prefix used by Bech32 and Bech32m addresses. */
     bech32: string;
+    /** Base58 version byte for pay-to-public-key-hash addresses. */
     pubKeyHash: number;
+    /** Base58 version byte for pay-to-script-hash addresses. */
     scriptHash: number;
+    /** Base58 version byte for wallet-import-format private keys. */
     wif: number;
 };
+/** Bitcoin mainnet network parameters. */
 export declare const NETWORK: BTC_NETWORK;
+/** Bitcoin testnet network parameters. */
 export declare const TEST_NETWORK: BTC_NETWORK;
-export declare function compareBytes(a: Bytes, b: Bytes): number;
+/**
+ * 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 declare function compareBytes(a: TArg<Bytes>, b: TArg<Bytes>): number;
+/**
+ * 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 declare function reverseObject<T extends Record<string, string | number>>(obj: T): {
     [K in T[keyof T]]: Extract<keyof T, string>;
 };
+/** Union of all value types in an object type. */
 export type ValueOf<T> = T[keyof T];
-//# sourceMappingURL=utils.d.ts.map