@scure/btc-signer 2.0.1 → 2.3.0

package/index.d.ts

@@ -1,22 +1,31 @@
 /*! scure-btc-signer - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+import type { TArg, TRet } from './utils.ts';
 import { compareBytes, taprootTweakPubkey } from './utils.ts';
 export { multisig, p2ms, p2pk, p2pkh, p2sh, p2tr, p2tr_ms, p2tr_ns, p2tr_pk, p2wpkh, p2wsh } from './payment.ts';
 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 { TArg, TRet } from './utils.ts';
 export { selectUTXO } from './utxo.ts';
-export declare const utils: {
+/**
+ * Small collection of commonly used utility exports.
+ * @example
+ * Reach for the grouped helpers when you want the common byte and Taproot utilities.
+ * ```ts
+ * utils.compareBytes(new Uint8Array([1]), new Uint8Array([2]));
+ * ```
+ */
+export declare const utils: TRet<Readonly<{
     isBytes: (a: unknown) => a is Uint8Array;
-    concatBytes: (...arrays: Uint8Array[]) => Uint8Array;
+    concatBytes: (...arrays: TArg<Uint8Array[]>) => TRet<Uint8Array>;
     compareBytes: typeof compareBytes;
-    pubSchnorr: (priv: string | Uint8Array) => Uint8Array;
-    randomPrivateKeyBytes: () => Uint8Array;
+    pubSchnorr: (priv: TArg<Uint8Array>) => TRet<Uint8Array>;
+    randomPrivateKeyBytes: () => TRet<Uint8Array>;
     taprootTweakPubkey: typeof taprootTweakPubkey;
-};
+}>>;
 export { _sortPubkeys, Address, combinations, getAddress, 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';
 export { _cmpBig, _Estimator } from './utxo.ts';
-//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,4 +1,3 @@
-/*! scure-btc-signer - MIT License (c) 2022 Paul Miller (paulmillr.com) */
 import { compareBytes, concatBytes, isBytes, pubSchnorr, randomPrivateKeyBytes, taprootTweakPubkey, } from "./utils.js";
 // should multisig be exported as classicMultisig?
 // prettier-ignore
@@ -7,16 +6,26 @@ export { CompactSize, MAX_SCRIPT_BYTE_LENGTH, OP, RawTx, RawWitness, Script, Scr
 export { getInputType, Transaction } from "./transaction.js";
 export { NETWORK, TAPROOT_UNSPENDABLE_KEY, TEST_NETWORK } from "./utils.js";
 export { selectUTXO } from "./utxo.js";
-export const utils = {
+/**
+ * Small collection of commonly used utility exports.
+ * @example
+ * Reach for the grouped helpers when you want the common byte and Taproot utilities.
+ * ```ts
+ * utils.compareBytes(new Uint8Array([1]), new Uint8Array([2]));
+ * ```
+ */
+// Convenience subset; import from `./utils.ts` when you need the full helper surface.
+export const utils = /* @__PURE__ */ (() => Object.freeze({
     isBytes,
     concatBytes,
     compareBytes,
     pubSchnorr,
     randomPrivateKeyBytes,
     taprootTweakPubkey,
-};
-export { _sortPubkeys, Address, combinations, getAddress, OutScript, sortedMultisig, taprootListToTree, WIF, } from "./payment.js"; // remove
-export { _DebugPSBT, TaprootControlBlock } from "./psbt.js"; // remove
-export { bip32Path, Decimal, DEFAULT_SEQUENCE, PSBTCombine, SigHash } from "./transaction.js"; // remove
+}))();
+export { _sortPubkeys, Address, combinations, getAddress, OutScript, sortedMultisig, taprootListToTree, WIF, } from "./payment.js";
+// remove
+export { _DebugPSBT, TaprootControlBlock } from "./psbt.js";
+// remove
+export { bip32Path, Decimal, DEFAULT_SEQUENCE, PSBTCombine, SigHash } from "./transaction.js";
 export { _cmpBig, _Estimator } from "./utxo.js";
-//# sourceMappingURL=index.js.map

package/musig2.d.ts

@@ -1,74 +1,197 @@
-/**
- * Represents a pair of public and secret nonces used in MuSig2 signing.
- */
+import type { WeierstrassPoint } from '@noble/curves/abstract/weierstrass.js';
+import { type TArg, type TRet } from './utils.ts';
+/** Represents a pair of public and secret nonces used in MuSig2 signing. */
 export type Nonces = {
+    /** Public nonce that gets shared with the other participants. */
     public: Uint8Array;
+    /** Secret nonce that stays local until partial signing finishes. */
     secret: Uint8Array;
 };
 /**
- * Represents a deterministic nonce, including its public part and the resulting partial signature.
+ * Represents a deterministic nonce, including its public part and the
+ * resulting partial signature.
  */
 export type DetNonce = {
+    /** Public nonce that the signer shares for this deterministic signing round. */
     publicNonce: Uint8Array;
+    /** Partial signature produced after combining all participant data. */
     partialSig: Uint8Array;
 };
+/** MuSig2 key aggregation context used by signing sessions. */
+export type KeyAggregate = {
+    /** Aggregate public key before x-only export. */
+    aggPublicKey: WeierstrassPoint<bigint>;
+    /** Accumulated sign from x-only tweaks. */
+    gAcc: bigint;
+    /** Accumulated tweak scalar. */
+    tweakAcc: bigint;
+};
 /**
  * Represents an error indicating an invalid contribution from a signer.
  * This allows pointing out which participant is malicious and what specifically is wrong.
+ * @param idx - signer index with the invalid contribution
+ * @param m - error message
+ * @example
+ * Create an error that points to the participant who sent invalid data.
+ * ```ts
+ * new InvalidContributionErr(0, 'pubkey');
+ * ```
  */
 export declare class InvalidContributionErr extends Error {
     readonly idx: number;
     constructor(idx: number, m: string);
 }
-export declare function IndividualPubkey(seckey: Uint8Array): Uint8Array;
+/**
+ * Derives a compressed secp256k1 public key from a private key.
+ * @param seckey - signer private key
+ * @returns Compressed public key bytes.
+ * @example
+ * Turn a signer's secret key into the compressed key format MuSig2 expects.
+ * ```ts
+ * import { schnorr } from '@noble/curves/secp256k1.js';
+ * import { IndividualPubkey } from '@scure/btc-signer/musig2.js';
+ * IndividualPubkey(schnorr.utils.randomSecretKey());
+ * ```
+ */
+export declare function IndividualPubkey(seckey: TArg<Uint8Array>): TRet<Uint8Array>;
 /**
  * Lexicographically sorts an array of public keys.
- * @param publicKeys An array of public keys (Uint8Array).
+ * @param publicKeys - array of public keys
  * @returns A new array containing the sorted public keys.
- * @throws {Error} If the input is not an array or if any element is not a Uint8Array of the correct length.
+ * @throws On wrong argument types. {@link TypeError}
+ * @throws On wrong argument ranges or values. {@link RangeError}
+ * @example
+ * Sort participant public keys before building the aggregate MuSig2 key.
+ * ```ts
+ * import { IndividualPubkey, sortKeys } from '@scure/btc-signer/musig2.js';
+ * import { randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * sortKeys([
+ *   IndividualPubkey(randomPrivateKeyBytes()),
+ *   IndividualPubkey(randomPrivateKeyBytes()),
+ * ]);
+ * ```
  */
-export declare function sortKeys(publicKeys: Uint8Array[]): Uint8Array[];
+export declare function sortKeys(publicKeys: TArg<Uint8Array[]>): TRet<Uint8Array[]>;
 /**
  * Aggregates multiple public keys using the MuSig2 key aggregation algorithm.
- * @param publicKeys An array of individual public keys (Uint8Array).
- * @param tweaks An optional array of tweaks (Uint8Array) to apply to the aggregate public key.
- * @param isXonly An optional array of booleans indicating whether each tweak is an X-only tweak.
- * @returns An object containing the aggregate public key, accumulated sign, and accumulated tweak.
- * @throws {Error} If the input is invalid, such as non array publicKeys, tweaks and isXonly array length not matching.
- * @throws {InvalidContributionErr} If any of the public keys are invalid and cannot be processed.
+ * @param publicKeys - individual participant public keys
+ * @param tweaks - optional tweaks applied to the aggregate key
+ * @param isXonly - whether each tweak uses x-only semantics
+ * @returns An object containing the aggregate public key, accumulated sign,
+ * and accumulated tweak.
+ * @throws If the input is invalid, such as non-array public keys or mismatched
+ * tweak metadata. {@link Error}
+ * @throws On wrong argument types. {@link TypeError}
+ * @throws On wrong argument ranges or values. {@link RangeError}
+ * @throws If any of the public keys are invalid and cannot be processed.
+ * {@link InvalidContributionErr}
+ * @example
+ * Combine all participant public keys into the shared MuSig2 context.
+ * ```ts
+ * import { IndividualPubkey, keyAggregate } from '@scure/btc-signer/musig2.js';
+ * import { randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * keyAggregate([
+ *   IndividualPubkey(randomPrivateKeyBytes()),
+ *   IndividualPubkey(randomPrivateKeyBytes()),
+ * ]);
+ * ```
  */
-export declare function keyAggregate(publicKeys: Uint8Array[], tweaks?: Uint8Array[], isXonly?: boolean[]): {
-    aggPublicKey: import("@noble/curves/abstract/weierstrass.js").WeierstrassPoint<bigint>;
-    gAcc: bigint;
-    tweakAcc: bigint;
-};
+export declare function keyAggregate(publicKeys: TArg<Uint8Array[]>, tweaks?: TArg<Uint8Array[]>, isXonly?: boolean[]): KeyAggregate;
 /**
  * Exports the aggregate public key to a byte array.
- * @param ctx The result of the keyAggregate function.
+ * @param ctx - result of {@link keyAggregate}
  * @returns The aggregate public key as a byte array.
+ * @example
+ * Serialize the aggregate key after building the MuSig2 context.
+ * ```ts
+ * import { IndividualPubkey, keyAggregate, keyAggExport } from '@scure/btc-signer/musig2.js';
+ * import { randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * const ctx = keyAggregate([
+ *   IndividualPubkey(randomPrivateKeyBytes()),
+ *   IndividualPubkey(randomPrivateKeyBytes()),
+ * ]);
+ * keyAggExport(ctx);
+ * ```
  */
-export declare function keyAggExport(ctx: ReturnType<typeof keyAggregate>): Uint8Array;
+export declare function keyAggExport(ctx: ReturnType<typeof keyAggregate>): TRet<Uint8Array>;
 /**
  * Generates a nonce pair (public and secret) for MuSig2 signing.
- * @param publicKey The individual public key of the signer (Uint8Array).
- * @param secretKey The secret key of the signer (Uint8Array). Optional, included to xor randomness
- * @param aggPublicKey The aggregate public key of all signers (Uint8Array).
- * @param msg The message to be signed (Uint8Array).
- * @param extraIn Extra input for nonce generation (Uint8Array).
- * @param rand Random 32-bytes for generating the nonces (Uint8Array).
+ * @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
+ * @param msg - message to be signed
+ * @param extraIn - extra input mixed into nonce generation
+ * @param rand - random 32-byte seed for the nonce derivation
  * @returns An object containing the public and secret nonces.
- * @throws {Error} If the input is invalid, such as non array publicKey, secretKey, aggPublicKey.
+ * @throws If the input is invalid, such as non-array public keys or malformed
+ * nonce inputs. {@link Error}
+ * @throws On wrong argument ranges or values. {@link RangeError}
+ * @example
+ * Generate the signer-local nonce pair before sharing the public nonce with peers.
+ * ```ts
+ * import { IndividualPubkey, nonceGen } from '@scure/btc-signer/musig2.js';
+ * import { randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * const secretKey = randomPrivateKeyBytes();
+ * nonceGen(IndividualPubkey(secretKey), secretKey);
+ * ```
  */
-export declare function nonceGen(publicKey: Uint8Array, secretKey?: Uint8Array, aggPublicKey?: Uint8Array, msg?: Uint8Array, extraIn?: Uint8Array, rand?: Uint8Array): Nonces;
+export declare function nonceGen(publicKey: TArg<Uint8Array>, secretKey?: TArg<Uint8Array>, aggPublicKey?: TArg<Uint8Array>, msg?: TArg<Uint8Array>, extraIn?: TArg<Uint8Array>, rand?: TArg<Uint8Array>): TRet<Nonces>;
 /**
  * Aggregates public nonces from multiple signers into a single aggregate nonce.
- * @param pubNonces An array of public nonces from each signer (Uint8Array). Each pubnonce is assumed to be 66 bytes (two 33‐byte parts).
+ * @param pubNonces - public nonces from each signer
  * @returns The aggregate nonce (Uint8Array).
- * @throws {Error} If the input is not an array or if any element is not a Uint8Array of the correct length.
- * @throws {InvalidContributionErr} If any of the public nonces are invalid and cannot be processed.
+ * @throws If the nonce payloads are malformed or contain infinity points. {@link Error}
+ * @throws On wrong argument types. {@link TypeError}
+ * @throws On wrong argument ranges or values. {@link RangeError}
+ * @throws If any of the public nonces are invalid and cannot be processed.
+ * {@link InvalidContributionErr}
+ * @example
+ * Combine all participant public nonces before building the session.
+ * ```ts
+ * import { IndividualPubkey, nonceAggregate, nonceGen } from '@scure/btc-signer/musig2.js';
+ * import { randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * const alice = randomPrivateKeyBytes();
+ * const bob = randomPrivateKeyBytes();
+ * nonceAggregate([
+ *   nonceGen(IndividualPubkey(alice), alice).public,
+ *   nonceGen(IndividualPubkey(bob), bob).public,
+ * ]);
+ * ```
+ */
+export declare function nonceAggregate(pubNonces: TArg<Uint8Array[]>): TRet<Uint8Array>;
+/**
+ * MuSig2 session context for partial signing and aggregation.
+ * @param aggNonce - aggregate nonce from all participants combined
+ * @param publicKeys - all participant public keys
+ * @param msg - message to be signed
+ * @param tweaks - optional tweaks applied to the aggregate public key
+ * @param isXonly - whether each tweak uses x-only semantics
+ * @example
+ * Build one session object and reuse it for all partial-signature steps.
+ * ```ts
+ * import {
+ *   IndividualPubkey,
+ *   Session,
+ *   keyAggregate,
+ *   keyAggExport,
+ *   nonceAggregate,
+ *   nonceGen,
+ * } from '@scure/btc-signer/musig2.js';
+ * import { randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * const alice = randomPrivateKeyBytes();
+ * const bob = randomPrivateKeyBytes();
+ * const publicKeys = [IndividualPubkey(alice), IndividualPubkey(bob)];
+ * const agg = keyAggregate(publicKeys);
+ * const aggNonce = nonceAggregate([
+ *   nonceGen(publicKeys[0], alice, keyAggExport(agg)).public,
+ *   nonceGen(publicKeys[1], bob, keyAggExport(agg)).public,
+ * ]);
+ * const msg = new TextEncoder().encode('hello musig2');
+ * new Session(aggNonce, publicKeys, msg);
+ * ```
  */
-export declare function nonceAggregate(pubNonces: Uint8Array[]): Uint8Array;
 export declare class Session {
+    private aggNonce;
     private publicKeys;
     private Q;
     private gAcc;
@@ -84,65 +207,85 @@ export declare class Session {
      * Constructor for the Session class.
      * It precomputes and stores values derived from the aggregate nonce, public keys,
      * message, and optional tweaks, optimizing the signing process.
-     * @param aggNonce The aggregate nonce (Uint8Array) from all participants combined, must be 66 bytes.
-     * @param publicKeys An array of public keys (Uint8Array) from each participant, must be 33 bytes.
-     * @param msg The message (Uint8Array) to be signed.
-     * @param tweaks Optional array of tweaks (Uint8Array) to be applied to the aggregate public key, each must be 32 bytes. Defaults to [].
-     * @param isXonly Optional array of booleans indicating whether each tweak is an X-only tweak. Defaults to [].
-     * @throws {Error} If the input is invalid, such as wrong array sizes or lengths.
+     * @param aggNonce - aggregate nonce from all participants combined
+     * @param publicKeys - participant public keys
+     * @param msg - message to be signed
+     * @param tweaks - tweaks applied to the aggregate public key
+     * @param isXonly - whether each tweak uses x-only semantics
+     * @throws If the input is invalid, such as wrong array sizes or lengths. {@link Error}
      */
     constructor(aggNonce: Uint8Array, publicKeys: Uint8Array[], msg: Uint8Array, tweaks?: Uint8Array[], isXonly?: boolean[]);
     /**
      * Calculates the key aggregation coefficient for a given point.
      * @private
-     * @param P The point to calculate the coefficient for.
+     * @param P - point to calculate the coefficient for
      * @returns The key aggregation coefficient as a bigint.
-     * @throws {Error} If the provided public key is not included in the list of pubkeys.
+     * @throws If the provided public key is not included in the list of pubkeys. {@link Error}
      */
     private getSessionKeyAggCoeff;
     private partialSigVerifyInternal;
     /**
-     * Generates a partial signature for a given message, secret nonce, secret key, and session context.
-     * @param secretNonce The secret nonce for this signing session (Uint8Array). MUST be securely erased after use.
-     * @param secret The secret key of the signer (Uint8Array).
-     * @param sessionCtx The session context containing all necessary information for signing.
-     * @param fastSign if set to true, the signature is created without checking validity.
+     * 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
+     * @param secret - secret key of the signer
+     * @param fastSign - if `true`, skip the self-verification pass
      * @returns The partial signature (Uint8Array).
-     * @throws {Error} If the input is invalid, such as wrong array sizes, invalid nonce or secret key.
+     * @throws If the input is invalid, such as wrong array sizes,
+     * invalid nonce, or invalid secret key. {@link Error}
      */
     sign(secretNonce: Uint8Array, secret: Uint8Array, fastSign?: boolean): Uint8Array;
     /**
      * Verifies a partial signature against the aggregate public key and other session parameters.
-     * @param partialSig The partial signature to verify (Uint8Array).
-     * @param pubNonces An array of public nonces from each signer (Uint8Array).
-     * @param pubKeys An array of public keys from each signer (Uint8Array).
-     * @param tweaks An array of tweaks applied to the aggregate public key.
-     * @param isXonly An array of booleans indicating whether each tweak is an X-only tweak.
-     * @param msg The message that was signed (Uint8Array).
-     * @param i The index of the signer whose partial signature is being verified.
-     * @returns True if the partial signature is valid, false otherwise.
-     * @throws {Error} If the input is invalid, such as non array partialSig, pubNonces, pubKeys, tweaks.
+     * @param partialSig - partial signature to verify
+     * @param pubNonces - public nonces from each signer
+     * @param i - index of the signer whose partial signature is being verified
+     * @returns `true` if the partial signature is valid.
+     * @throws If the input is invalid, such as non-array partial signatures
+     * or mismatched nonce counts. {@link Error}
      */
     partialSigVerify(partialSig: Uint8Array, pubNonces: Uint8Array[], i: number): boolean;
     /**
      * Aggregates partial signatures from multiple signers into a single final signature.
-     * @param partialSigs An array of partial signatures from each signer (Uint8Array).
-     * @param sessionCtx The session context containing all necessary information for signing.
+     * @param partialSigs - partial signatures from each signer
      * @returns The final aggregate signature (Uint8Array).
-     * @throws {Error} If the input is invalid, such as wrong array sizes, invalid signature.
+     * @throws If the input is invalid, such as wrong array sizes or malformed
+     * signatures. {@link Error}
      */
-    partialSigAgg(partialSigs: Uint8Array[]): Uint8Array;
+    partialSigAgg(partialSigs: TArg<Uint8Array[]>): TRet<Uint8Array>;
 }
 /**
  * Generates a nonce pair and partial signature deterministically for a single signer.
- * @param secret The secret key of the signer (Uint8Array).
- * @param aggOtherNonce The aggregate public nonce of all other signers (Uint8Array).
- * @param publicKeys An array of all signers' public keys (Uint8Array).
- * @param tweaks An array of tweaks to apply to the aggregate public key.
- * @param isXonly An array of booleans indicating whether each tweak is an X-only tweak.
- * @param msg The message to be signed (Uint8Array).
- * @param rand Optional extra randomness (Uint8Array).
+ * @param secret - secret key of the signer
+ * @param aggOtherNonce - aggregate public nonce of the other signers
+ * @param publicKeys - public keys of all signers
+ * @param msg - message to be signed
+ * @param tweaks - tweaks applied to the aggregate public key
+ * @param isXonly - whether each tweak uses x-only semantics
+ * @param rand - optional extra randomness
+ * @param fastSign - whether to skip partial-signature self-verification
  * @returns An object containing the public nonce and partial signature.
+ * @throws If MuSig2 session setup or signing fails. {@link Error}
+ * @throws On wrong argument types. {@link TypeError}
+ * @throws On wrong argument ranges or values. {@link RangeError}
+ * @throws If one of the aggregated public keys or nonces is invalid. {@link InvalidContributionErr}
+ * @example
+ * Generate one signer's deterministic nonce and partial signature in one step.
+ * ```ts
+ * import {
+ *   IndividualPubkey,
+ *   deterministicSign,
+ *   keyAggregate,
+ *   keyAggExport,
+ *   nonceGen,
+ * } from '@scure/btc-signer/musig2.js';
+ * import { randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';
+ * const alice = randomPrivateKeyBytes();
+ * const bob = randomPrivateKeyBytes();
+ * const publicKeys = [IndividualPubkey(alice), IndividualPubkey(bob)];
+ * const agg = keyAggregate(publicKeys);
+ * const otherNonce = nonceGen(publicKeys[1], bob, keyAggExport(agg)).public;
+ * deterministicSign(alice, otherNonce, publicKeys, new TextEncoder().encode('hello musig2'));
+ * ```
  */
-export declare function deterministicSign(secret: Uint8Array, aggOtherNonce: Uint8Array, publicKeys: Uint8Array[], msg: Uint8Array, tweaks?: Uint8Array[], isXonly?: boolean[], rand?: Uint8Array, fastSign?: boolean): DetNonce;
-//# sourceMappingURL=musig2.d.ts.map
+export declare function deterministicSign(secret: TArg<Uint8Array>, aggOtherNonce: TArg<Uint8Array>, publicKeys: TArg<Uint8Array[]>, msg: TArg<Uint8Array>, tweaks?: TArg<Uint8Array[]>, isXonly?: boolean[], rand?: TArg<Uint8Array>, fastSign?: boolean): TRet<DetNonce>;