xpi-ts 0.2.22 → 0.2.24

package/dist/types/lib/bitcore/crypto/musig2.d.ts

@@ -1,32 +1,314 @@
+/**
+ * Copyright 2025-2026 The Lotusia Stewardship
+ * Github: https://github.com/LotusiaStewardship
+ * License: MIT
+ *
+ * MuSig2 Multi-Signature Scheme for Lotus
+ *
+ * Implements MuSig2 (BIP327) adapted for Lotus Schnorr signatures.
+ *
+ * Key Differences from BIP327:
+ * - Uses 33-byte compressed public keys (not x-only 32-byte)
+ * - Challenge hash: e = Hash(R.x || compressed(Q) || m) (33-byte key!)
+ * - Nonce handling accounts for Lotus quadratic residue checks
+ *
+ * WARNING: This is a multi-party signature scheme. Improper use can lead to:
+ * - Loss of funds (nonce reuse reveals private keys)
+ * - Security vulnerabilities (rogue key attacks)
+ * - Protocol failures (equivocation, invalid signatures)
+ *
+ * Always:
+ * - Use fresh nonces for each message
+ * - Verify partial signatures before aggregation
+ * - Use secure random number generation
+ * - Clear secret nonces from memory after use
+ *
+ * Reference: BIP327 - MuSig2 for BIP340-compatible Multi-Signatures
+ *            (adapted for Lotus Schnorr)
+ *
+ * @module MuSig2
+ */
 import { PublicKey } from '../publickey';
 import { PrivateKey } from '../privatekey';
 import { Point } from './point';
 import { BN } from './bn';
 import { Signature } from './signature';
 import type { Buffer } from 'buffer/';
+/**
+ * Key Aggregation Context
+ *
+ * Contains the aggregated public key and per-key coefficients needed for
+ * signing and verification.
+ */
 export interface MuSig2KeyAggContext {
+    /** Original public keys in order */
     pubkeys: PublicKey[];
+    /** Key aggregation coefficient for each public key (keyed by pubkey string) */
     keyAggCoeff: Map<string, BN>;
+    /** Aggregated public key Q = Σ(aᵢ · Pᵢ) */
     aggregatedPubKey: PublicKey;
 }
+/**
+ * Secret and Public Nonce Pair
+ *
+ * Each signer generates two nonce pairs for security against Wagner's attack.
+ */
 export interface MuSig2Nonce {
+    /** Secret nonces (k₁, k₂) - MUST be kept secret and cleared after use */
     secretNonces: [BN, BN];
+    /** Public nonces (R₁, R₂) = (k₁·G, k₂·G) - shared with other signers */
     publicNonces: [Point, Point];
 }
+/**
+ * Aggregated Nonce
+ *
+ * Result of combining all signers' public nonces.
+ */
 export interface MuSig2AggregatedNonce {
+    /** Aggregated first nonce R₁ = Σ(R₁,ᵢ) */
     R1: Point;
+    /** Aggregated second nonce R₂ = Σ(R₂,ᵢ) */
     R2: Point;
 }
+/** Tag for key aggregation list hash (BIP327) */
 export declare const MUSIG2_TAG_KEYSORT = "KeyAgg list";
+/** Tag for key aggregation coefficient (BIP327) */
 export declare const MUSIG2_TAG_KEYAGG_COEFF = "KeyAgg coefficient";
+/** Tag for nonce aggregation coefficient (BIP327) */
 export declare const MUSIG2_TAG_NONCE_COEFF = "MuSig/noncecoef";
+/** Tag for auxiliary random data in nonce generation (BIP327) */
 export declare const MUSIG2_TAG_AUX = "MuSig/aux";
+/** Tag for nonce generation (BIP327) */
 export declare const MUSIG2_TAG_NONCE = "MuSig/nonce";
+/**
+ * Tagged hash for MuSig2
+ *
+ * Same as Taproot tagged hashing:
+ * tag_hash = SHA256(tag)
+ * tagged_hash = SHA256(tag_hash || tag_hash || data)
+ *
+ * @param tag - Tag string for domain separation
+ * @param data - Data to hash
+ * @returns 32-byte hash
+ */
 export declare function muSig2TaggedHash(tag: string, data: Buffer): Buffer;
+/**
+ * Aggregate multiple public keys into a single key
+ *
+ * This is the first step in MuSig2. Each signer provides their public key,
+ * and this function computes the aggregated public key that will be used
+ * for signing.
+ *
+ * Algorithm:
+ * 1. Sort public keys lexicographically (ensures deterministic ordering)
+ * 2. Compute L = H("KeyAgg list", P₁ || P₂ || ... || Pₙ)
+ * 3. For each key Pᵢ: compute aᵢ = H("KeyAgg coefficient", L || Pᵢ)
+ * 4. Q = Σ(aᵢ · Pᵢ)
+ *
+ * Security: The key coefficients prevent rogue key attacks where an attacker
+ * chooses their key maliciously to control the aggregated key.
+ *
+ * IMPORTANT: Public keys are sorted lexicographically BEFORE aggregation to ensure
+ * all participants generate the same aggregated key and Taproot address regardless
+ * of the order keys are provided. This is critical for multi-party coordination.
+ *
+ * @param pubkeys - Array of public keys to aggregate (will be sorted, must be unique)
+ * @returns Key aggregation context with aggregated key and coefficients
+ * @throws Error if pubkeys array is empty or contains invalid keys
+ *
+ * @example
+ * ```typescript
+ * const alice = new PrivateKey()
+ * const bob = new PrivateKey()
+ *
+ * // Keys will be sorted automatically - order doesn't matter
+ * const ctx = muSig2KeyAgg([alice.publicKey, bob.publicKey])
+ * console.log('Aggregated key:', ctx.aggregatedPubKey.toString())
+ * ```
+ */
 export declare function muSig2KeyAgg(pubkeys: PublicKey[]): MuSig2KeyAggContext;
+/**
+ * Generate secret and public nonces for MuSig2 signing
+ *
+ * Each signer must generate fresh nonces for each message. MuSig2 uses two
+ * nonce pairs (k₁, k₂) for security against Wagner's attack.
+ *
+ * ⚠️ SECURITY CRITICAL ⚠️
+ * - NEVER reuse nonces! Nonce reuse reveals your private key!
+ * - This function uses RFC6979-style deterministic nonce generation
+ * - Deterministic nonces prevent reuse even with hardware failures
+ * - Protects against weak/backdoored random number generators
+ * - Nonces are reproducible and can be unit tested
+ *
+ * Nonce Generation (RFC6979-style):
+ * 1. Compute auxiliary hash: aux = H("MuSig/aux", privkey || Q || m || extra)
+ * 2. Generate k₁ = H("MuSig/nonce", aux || 0x01) mod n
+ * 3. Generate k₂ = H("MuSig/nonce", aux || 0x02) mod n
+ * 4. Compute R₁ = k₁ · G, R₂ = k₂ · G
+ *
+ * For additional randomness (recommended), provide `extraInput` with 32 random bytes.
+ * This makes nonces non-deterministic while maintaining security properties.
+ *
+ * Reference:
+ * - BIP327 (MuSig2)
+ * - RFC6979 (Deterministic ECDSA)
+ * - Lotus Schnorr Specification (secure signature generation)
+ *
+ * @param privateKey - Signer's private key
+ * @param aggregatedPubKey - Aggregated public key (from musigKeyAgg)
+ * @param message - Optional message to be signed (for deterministic nonces)
+ * @param extraInput - Optional extra randomness (32 bytes recommended). Use crypto.randomBytes(32) for non-deterministic nonces.
+ * @returns Secret and public nonce pair
+ *
+ * @example Deterministic nonces (for testing)
+ * ```typescript
+ * const nonce = musigNonceGen(
+ *   privateKey,
+ *   ctx.aggregatedPubKey,
+ *   message
+ * )
+ * ```
+ *
+ * @example Non-deterministic nonces with extra randomness (recommended for production)
+ * ```typescript
+ * import crypto from 'crypto'
+ * const nonce = musigNonceGen(
+ *   privateKey,
+ *   ctx.aggregatedPubKey,
+ *   message,
+ *   crypto.randomBytes(32)  // Add 32 bytes of random entropy
+ * )
+ * ```
+ */
 export declare function muSig2NonceGen(privateKey: PrivateKey, aggregatedPubKey: PublicKey, message?: Buffer, extraInput?: Buffer): MuSig2Nonce;
+/**
+ * Aggregate public nonces from all signers
+ *
+ * After each signer generates their nonces, they share their public nonces.
+ * This function aggregates them into a single nonce pair.
+ *
+ * Algorithm:
+ * 1. R₁ = Σ(R₁,ᵢ) - Sum of first public nonces
+ * 2. R₂ = Σ(R₂,ᵢ) - Sum of second public nonces
+ *
+ * @param publicNonces - Array of public nonce pairs from all signers
+ * @returns Aggregated nonce pair
+ * @throws Error if array is empty or contains invalid nonces
+ *
+ * @example
+ * ```typescript
+ * const aggNonce = musigNonceAgg([
+ *   aliceNonce.publicNonces,
+ *   bobNonce.publicNonces
+ * ])
+ * ```
+ */
 export declare function muSig2NonceAgg(publicNonces: Array<[Point, Point]>): MuSig2AggregatedNonce;
+/**
+ * Create a partial signature
+ *
+ * Each signer creates a partial signature using their secret nonce and
+ * private key. These partial signatures are later aggregated into a full
+ * Schnorr signature.
+ *
+ * Algorithm (Lotus Schnorr adaptation):
+ * 1. Compute b = H("MuSig/noncecoef", Q || R₁ || R₂ || m)
+ * 2. Compute effective nonce: k = k₁ + b·k₂ (mod n)
+ * 3. Compute effective public nonce: R = R₁ + b·R₂
+ * 4. Check if R.y is quadratic residue, negate k if not (Lotus specific!)
+ * 5. Compute challenge: e = H(R.x || compressed(Q) || m) (Lotus format!)
+ * 6. Compute partial signature: sᵢ = k + e·aᵢ·xᵢ (mod n)
+ *
+ * @param secretNonce - Signer's secret nonce (from musigNonceGen)
+ * @param privateKey - Signer's private key
+ * @param keyAggContext - Key aggregation context (from musigKeyAgg)
+ * @param signerIndex - Index of this signer in the pubkeys array
+ * @param aggregatedNonce - Aggregated nonces (from musigNonceAgg)
+ * @param message - Message to sign (typically transaction sighash)
+ * @returns Partial signature sᵢ
+ *
+ * @example
+ * ```typescript
+ * const partialSig = musigPartialSign(
+ *   nonce,
+ *   privateKey,
+ *   ctx,
+ *   0,  // Alice is signer 0
+ *   aggNonce,
+ *   message
+ * )
+ * ```
+ */
 export declare function muSig2PartialSign(secretNonce: MuSig2Nonce, privateKey: PrivateKey, keyAggContext: MuSig2KeyAggContext, signerIndex: number, aggregatedNonce: MuSig2AggregatedNonce, message: Buffer, publicKeyForChallenge?: PublicKey): BN;
+/**
+ * Verify a partial signature
+ *
+ * Before aggregating partial signatures, each should be verified to ensure
+ * correctness and detect malicious signers.
+ *
+ * Verification equation:
+ * sᵢ·G = Rᵢ + e·aᵢ·Pᵢ
+ *
+ * @param partialSig - Partial signature to verify
+ * @param publicNonce - Signer's public nonce pair
+ * @param publicKey - Signer's public key
+ * @param keyAggContext - Key aggregation context
+ * @param signerIndex - Index of the signer
+ * @param aggregatedNonce - Aggregated nonces
+ * @param message - Message being signed
+ * @returns true if partial signature is valid
+ *
+ * @example
+ * ```typescript
+ * const valid = musigPartialSigVerify(
+ *   bobPartialSig,
+ *   bobNonce.publicNonces,
+ *   bob.publicKey,
+ *   ctx,
+ *   1,  // Bob is signer 1
+ *   aggNonce,
+ *   message
+ * )
+ * ```
+ */
 export declare function muSig2PartialSigVerify(partialSig: BN, publicNonce: [Point, Point], publicKey: PublicKey, keyAggContext: MuSig2KeyAggContext, signerIndex: number, aggregatedNonce: MuSig2AggregatedNonce, message: Buffer, publicKeyForChallenge?: PublicKey): boolean;
+/**
+ * Aggregate partial signatures into final Schnorr signature
+ *
+ * After collecting all partial signatures, the aggregator combines them
+ * into a standard 64-byte Schnorr signature that can be verified with
+ * the aggregated public key.
+ *
+ * Algorithm:
+ * 1. Compute b = H("MuSig/noncecoef", Q || R₁ || R₂ || m)
+ * 2. Compute R = R₁ + b·R₂
+ * 3. Compute s = Σ(sᵢ) mod n
+ * 4. Return signature (R.x, s)
+ *
+ * @param partialSigs - Array of partial signatures from all signers
+ * @param aggregatedNonce - Aggregated nonces
+ * @param message - Message that was signed
+ * @param aggregatedPubKey - Aggregated public key (for verification)
+ * @param sighashType - Optional sighash type to embed in signature (e.g., SIGHASH_ALL | SIGHASH_LOTUS)
+ * @returns Final 64-byte Schnorr signature with nhashtype set
+ *
+ * @example
+ * ```typescript
+ * const signature = musigSigAgg(
+ *   [alicePartialSig, bobPartialSig],
+ *   aggNonce,
+ *   message,
+ *   ctx.aggregatedPubKey
+ * )
+ *
+ * // Verify with standard Schnorr verification
+ * const valid = Schnorr.verify(
+ *   message,
+ *   signature,
+ *   ctx.aggregatedPubKey,
+ *   'big'
+ * )
+ * ```
+ */
 export declare function muSig2SigAgg(partialSigs: BN[], aggregatedNonce: MuSig2AggregatedNonce, message: Buffer, aggregatedPubKey: PublicKey, sighashType?: number, publicKeyForNonceCoef?: PublicKey): Signature;
 //# sourceMappingURL=musig2.d.ts.map

package/dist/types/lib/bitcore/crypto/musig2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"musig2.d.ts","sourceRoot":"","sources":["../../../../../lib/bitcore/crypto/musig2.ts"],"names":[],"mappings":"AA+BA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,EAAE,EAAE,MAAM,MAAM,CAAA;AAEzB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAYrC,MAAM,WAAW,mBAAmB;IAElC,OAAO,EAAE,SAAS,EAAE,CAAA;IAGpB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAG5B,gBAAgB,EAAE,SAAS,CAAA;CAC5B;AAOD,MAAM,WAAW,WAAW;IAE1B,YAAY,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;IAGtB,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;CAC7B;AAOD,MAAM,WAAW,qBAAqB;IAEpC,EAAE,EAAE,KAAK,CAAA;IAGT,EAAE,EAAE,KAAK,CAAA;CACV;AAOD,eAAO,MAAM,kBAAkB,gBAAgB,CAAA;AAG/C,eAAO,MAAM,uBAAuB,uBAAuB,CAAA;AAG3D,eAAO,MAAM,sBAAsB,oBAAoB,CAAA;AAGvD,eAAO,MAAM,cAAc,cAAc,CAAA;AAGzC,eAAO,MAAM,gBAAgB,gBAAgB,CAAA;AAiB7C,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIlE;AAmFD,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,mBAAmB,CAyEtE;AA2DD,wBAAgB,cAAc,CAC5B,UAAU,EAAE,UAAU,EACtB,gBAAgB,EAAE,SAAS,EAC3B,OAAO,CAAC,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,WAAW,CAwDb;AA4BD,wBAAgB,cAAc,CAC5B,YAAY,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,GAClC,qBAAqB,CAkCvB;AAyCD,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,WAAW,EACxB,UAAU,EAAE,UAAU,EACtB,aAAa,EAAE,mBAAmB,EAClC,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,qBAAqB,EACtC,OAAO,EAAE,MAAM,EACf,qBAAqB,CAAC,EAAE,SAAS,GAChC,EAAE,CAmDJ;AAqCD,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,EAAE,EACd,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,EAC3B,SAAS,EAAE,SAAS,EACpB,aAAa,EAAE,mBAAmB,EAClC,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,qBAAqB,EACtC,OAAO,EAAE,MAAM,EACf,qBAAqB,CAAC,EAAE,SAAS,GAChC,OAAO,CAsET;AA4CD,wBAAgB,YAAY,CAC1B,WAAW,EAAE,EAAE,EAAE,EACjB,eAAe,EAAE,qBAAqB,EACtC,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,SAAS,EAC3B,WAAW,CAAC,EAAE,MAAM,EACpB,qBAAqB,CAAC,EAAE,SAAS,GAChC,SAAS,CA0DX"}
+{"version":3,"file":"musig2.d.ts","sourceRoot":"","sources":["../../../../../lib/bitcore/crypto/musig2.ts"],"names":[],"mappings":"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"}

package/dist/types/lib/bitcore/crypto/point.d.ts

@@ -1,25 +1,112 @@
+/**
+ * Elliptic curve point operations for secp256k1
+ * Migrated from bitcore-lib-xpi with ESM support
+ */
 import { BN } from './bn';
 import type { Buffer } from 'buffer/';
+/** Prefix byte for compressed point with odd Y-coordinate */
 export declare const PREFIX_Y_ODD = 3;
+/** Prefix byte for compressed point with even Y-coordinate */
 export declare const PREFIX_Y_EVEN = 2;
 export declare class Point {
     private _point;
+    /** Buffer containing prefix byte for compressed point with odd Y-coordinate */
     static readonly PrefixOddY: Buffer;
+    /** Buffer containing prefix byte for compressed point with even Y-coordinate */
     static readonly PrefixEvenY: Buffer;
     constructor(x: BN | string, y: BN | string, isRed?: boolean);
+    /**
+     * Get the X coordinate of the point
+     */
     get x(): BN;
+    /**
+     * Get the Y coordinate of the point
+     */
     get y(): BN;
+    /**
+     * Instantiate a valid secp256k1 Point from only the X coordinate
+     *
+     * @param odd - If true, use the odd Y coordinate; if false, use the even Y coordinate
+     * @param x - The X coordinate as a BN or hex string
+     * @returns A Point instance on the secp256k1 curve
+     * @throws {Error} If the X coordinate does not correspond to a valid curve point
+     */
     static fromX(odd: boolean, x: BN | string): Point;
+    /**
+     * Will return a secp256k1 ECDSA base point
+     */
     static getG(): Point;
+    /**
+     * Will return the max of range of valid private keys as governed by the secp256k1 ECDSA standard
+     */
     static getN(): BN;
+    /**
+     * Will determine if the point is valid
+     */
     validate(): Point;
+    /**
+     * Check if point is at infinity
+     */
     isInfinity(): boolean;
+    /**
+     * Point addition
+     */
     add(other: Point): Point;
+    /**
+     * Point multiplication
+     */
     mul(scalar: BN): Point;
+    /**
+     * Point multiplication with addition
+     * Implemented using native BigInt instead of BN.js
+     */
     mulAdd(scalar1: BN, other: Point, scalar2: BN): Point;
+    /**
+     * Check if two points are equal
+     */
     eq(other: Point): boolean;
+    /**
+     * Convert point to compressed format (33 bytes)
+     *
+     * Compressed format consists of:
+     * - 1 byte prefix: 0x02 if Y is even, 0x03 if Y is odd
+     * - 32 bytes: X coordinate
+     *
+     * @param point - The point to compress
+     * @returns 33-byte buffer containing the compressed point
+     *
+     * @example
+     * ```typescript
+     * const compressed = Point.pointToCompressed(publicKeyPoint)
+     * // Returns Buffer of length 33
+     * ```
+     */
     static pointToCompressed(point: Point): Buffer;
+    /**
+     * Check if point has square root (Y coordinate is quadratic residue)
+     *
+     * In secp256k1, for any valid point on the curve, exactly one of Y or (p-Y)
+     * is a quadratic residue. The QR Y is the one computed by lift_x: c^((p+1)/4)
+     * where c = X³ + 7.
+     *
+     * IMPORTANT: This is NOT the same as checking if Y is even!
+     * The relationship between Y parity and quadratic residue depends on the specific
+     * X value, not just Y's parity.
+     *
+     * Efficient algorithm: Compute the canonical Y (lift_x result) and check if
+     * our Y matches it. If Y == canonical_Y, then Y is QR. If Y == p - canonical_Y,
+     * then Y is not QR.
+     *
+     * Reference: lotusd/src/secp256k1/src/field_impl.h secp256k1_fe_is_quad_var()
+     */
     hasSquare(): boolean;
+    /**
+     * Check if value is a square in the field
+     *
+     * @deprecated This function is slow (uses modPow).
+     * For checking if a point Y coordinate is a quadratic residue,
+     * use hasSquare() instead which is optimized for secp256k1.
+     */
     isSquare(x: BN): boolean;
 }
 //# sourceMappingURL=point.d.ts.map

package/dist/types/lib/bitcore/crypto/point.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"point.d.ts","sourceRoot":"","sources":["../../../../../lib/bitcore/crypto/point.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,EAAE,EAAE,MAAM,MAAM,CAAA;AAEzB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAOrC,eAAO,MAAM,YAAY,IAAO,CAAA;AAEhC,eAAO,MAAM,aAAa,IAAO,CAAA;AAEjC,qBAAa,KAAK;IAChB,OAAO,CAAC,MAAM,CAAsB;IAGpC,MAAM,CAAC,QAAQ,CAAC,UAAU,SAAkC;IAE5D,MAAM,CAAC,QAAQ,CAAC,WAAW,SAAmC;gBAElD,CAAC,EAAE,EAAE,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;IAe3D,IAAI,CAAC,IAAI,EAAE,CAGV;IAKD,IAAI,CAAC,IAAI,EAAE,CAGV;IAUD,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,GAAG,MAAM,GAAG,KAAK;IAsCjD,MAAM,CAAC,IAAI,IAAI,KAAK;IASpB,MAAM,CAAC,IAAI,IAAI,EAAE;IAOjB,QAAQ,IAAI,KAAK;IAgCjB,UAAU,IAAI,OAAO;IAOrB,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK;IASxB,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,KAAK;IAUtB,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,KAAK;IAYrD,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAoBzB,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IA2B9C,SAAS,IAAI,OAAO;IAkCpB,QAAQ,CAAC,CAAC,EAAE,EAAE,GAAG,OAAO;CAazB"}
+{"version":3,"file":"point.d.ts","sourceRoot":"","sources":["../../../../../lib/bitcore/crypto/point.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,EAAE,EAAE,MAAM,MAAM,CAAA;AAEzB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAgCrC,6DAA6D;AAC7D,eAAO,MAAM,YAAY,IAAO,CAAA;AAChC,8DAA8D;AAC9D,eAAO,MAAM,aAAa,IAAO,CAAA;AAEjC,qBAAa,KAAK;IAChB,OAAO,CAAC,MAAM,CAAsB;IAEpC,+EAA+E;IAC/E,MAAM,CAAC,QAAQ,CAAC,UAAU,SAAkC;IAC5D,gFAAgF;IAChF,MAAM,CAAC,QAAQ,CAAC,WAAW,SAAmC;gBAElD,CAAC,EAAE,EAAE,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;IAY3D;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,CAGV;IAED;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,CAGV;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,GAAG,MAAM,GAAG,KAAK;IAmCjD;;OAEG;IACH,MAAM,CAAC,IAAI,IAAI,KAAK;IAMpB;;OAEG;IACH,MAAM,CAAC,IAAI,IAAI,EAAE;IAIjB;;OAEG;IACH,QAAQ,IAAI,KAAK;IA6BjB;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK;IAMxB;;OAEG;IACH,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,KAAK;IAMtB;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,KAAK;IASrD;;OAEG;IACH,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAIzB;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAU9C;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,IAAI,OAAO;IA2BpB;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,EAAE,EAAE,GAAG,OAAO;CAazB"}

package/dist/types/lib/bitcore/crypto/random.d.ts

@@ -1,8 +1,56 @@
+/**
+ * Random number generation utilities
+ * Migrated from bitcore-lib-xpi with ESM support
+ *
+ * Uses @noble/hashes for browser compatibility
+ */
 import type { Buffer } from 'buffer/';
+/**
+ * Random number generation utilities for cryptographic operations
+ *
+ * This class provides secure random number generation that works in both
+ * Node.js and browser environments. It uses @noble/hashes which automatically
+ * detects the environment and uses the appropriate cryptographic random source:
+ * - Node.js: crypto.randomBytes
+ * - Browser: crypto.getRandomValues
+ *
+ * @example
+ * ```typescript
+ * // Generate 32 random bytes for a private key
+ * const randomBytes = Random.getRandomBuffer(32)
+ *
+ * // For non-critical uses where crypto may not be available
+ * const pseudoRandom = Random.getPseudoRandomBuffer(16)
+ * ```
+ */
 export declare class Random {
+    /**
+     * Secure random bytes - works in both Node.js and browser
+     * Uses @noble/hashes which automatically detects the environment
+     */
     static getRandomBuffer(size: number): Buffer;
+    /**
+     * Node.js implementation - now uses @noble/hashes
+     * @deprecated Use getRandomBuffer instead
+     */
     static getRandomBufferNode(size: number): Buffer;
+    /**
+     * Browser implementation - now uses @noble/hashes
+     * @deprecated Use getRandomBuffer instead
+     */
     static getRandomBufferBrowser(size: number): Buffer;
+    /**
+     * Insecure random bytes, but it never fails
+     *
+     * This method uses Math.random() which is NOT cryptographically secure.
+     * Only use this for non-security-critical purposes such as testing or
+     * when cryptographic random sources are unavailable.
+     *
+     * @param size - Number of random bytes to generate
+     * @returns Buffer containing pseudo-random bytes
+     *
+     * @warning Do NOT use for cryptographic keys, nonces, or any security-sensitive data
+     */
     static getPseudoRandomBuffer(size: number): Buffer;
 }
 //# sourceMappingURL=random.d.ts.map

package/dist/types/lib/bitcore/crypto/random.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"random.d.ts","sourceRoot":"","sources":["../../../../../lib/bitcore/crypto/random.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAoBrC,qBAAa,MAAM;IAKjB,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAQ5C,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAQhD,MAAM,CAAC,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAgBnD,MAAM,CAAC,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAmBnD"}
+{"version":3,"file":"random.d.ts","sourceRoot":"","sources":["../../../../../lib/bitcore/crypto/random.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAErC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,MAAM;IACjB;;;OAGG;IACH,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI5C;;;OAGG;IACH,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIhD;;;OAGG;IACH,MAAM,CAAC,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAInD;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAmBnD"}