xpi-ts 0.2.22 → 0.2.24

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

@@ -1,40 +1,243 @@
+/**
+ * Schnorr signature implementation for Lotus
+ *
+ * This implements the custom Schnorr signature scheme used by Lotus (BCH-derived),
+ * which is different from BIP340 (Bitcoin Taproot).
+ *
+ * Reference: lotusd/src/secp256k1/src/modules/schnorr/schnorr_impl.h
+ *
+ * Key Differences from BIP340:
+ * - Uses compressed public key (33 bytes) instead of x-only (32 bytes)
+ * - Hash construction: e = Hash(R.x || compressed(P) || m) instead of Hash(R.x || P.x || m)
+ * - Verification equation: R = s*G - e*P (standard Schnorr)
+ * - Checks that R.y is a quadratic residue (Jacobi symbol = 1)
+ *
+ * Signature Format:
+ * - 64 bytes total: [R.x (32 bytes) || s (32 bytes)]
+ * - No sighash byte appended to raw signature
+ *
+ * Signing: s = k + e*x where e = Hash(R.x || compressed(P) || m) mod n
+ * Verification: Check that s*G - e*P has x-coordinate equal to r and y is quadratic residue
+ */
 import { BN } from './bn';
 import { Signature } from './signature';
 import { PrivateKey } from '../privatekey';
 import { PublicKey } from '../publickey';
 import type { Buffer } from 'buffer/';
+/**
+ * Data structure for initializing a Schnorr signature instance
+ */
 export interface SchnorrData {
+    /** 32-byte hash buffer to sign or verify */
     hashbuf?: Buffer;
+    /** Byte endianness for hash interpretation */
     endian?: 'little' | 'big';
+    /** Private key for signing operations */
     privkey?: PrivateKey;
+    /** Public key for verification */
     pubkey?: PublicKey;
+    /** Schnorr signature object */
     sig?: Signature;
+    /** Result of signature verification */
     verified?: boolean;
 }
+/**
+ * Schnorr signature implementation for Lotus (BCH-derived)
+ *
+ * This class implements the custom Schnorr signature scheme used by Lotus,
+ * which is different from BIP340 (Bitcoin Taproot).
+ *
+ * Key Features:
+ * - Uses compressed public key (33 bytes) instead of x-only (32 bytes)
+ * - Hash construction: e = Hash(R.x || compressed(P) || m)
+ * - Verification equation: R = s*G - e*P
+ * - Checks that R.y is a quadratic residue (Jacobi symbol = 1)
+ *
+ * Signature Format:
+ * - 64 bytes total: [R.x (32 bytes) || s (32 bytes)]
+ * - No sighash byte appended to raw signature
+ *
+ * @example
+ * ```typescript
+ * // Sign a message hash
+ * const schnorr = new Schnorr({ privkey, hashbuf })
+ * schnorr.sign()
+ *
+ * // Verify a signature
+ * const isValid = Schnorr.verify(hashbuf, sig, pubkey)
+ *
+ * // Instance-based verification
+ * const schnorr = new Schnorr({ privkey, hashbuf })
+ * schnorr.set({ sig, pubkey }).verify().verified
+ * ```
+ */
 export declare class Schnorr {
+    /** 32-byte hash buffer to sign or verify */
     hashbuf: Buffer;
+    /** Byte endianness for hash interpretation ('little' or 'big') */
     endian: 'little' | 'big';
+    /** Private key for signing operations */
     privkey: PrivateKey;
+    /** Public key for verification (auto-derived from privkey if not set) */
     pubkey: PublicKey;
+    /** Schnorr signature object (generated by sign(), verified by verify()) */
     sig: Signature;
+    /** Result of signature verification (true if valid, false if invalid) */
     verified: boolean;
+    /**
+     * Creates a new Schnorr signature instance
+     *
+     * @param obj - Optional initialization data for the instance
+     * @example
+     * ```typescript
+     * const schnorr = new Schnorr({ hashbuf, privkey })
+     * ```
+     */
     constructor(obj?: SchnorrData);
+    /**
+     * Sets instance properties from a data object
+     *
+     * This method allows chaining by returning 'this'. It intelligently
+     * derives the public key from the private key if pubkey is not provided.
+     *
+     * @param obj - Data object containing properties to set
+     * @returns This Schnorr instance for method chaining
+     */
     set(obj: SchnorrData): Schnorr;
+    /**
+     * Derive public key from the instance's private key
+     *
+     * Computes the corresponding public key from the private key using
+     * elliptic curve point multiplication: P = d*G where d is private key
+     * and G is the generator point.
+     *
+     * @returns This Schnorr instance for method chaining
+     * @throws Error if privkey is not set
+     */
     privkey2pubkey(): Schnorr;
+    /**
+     * Get the public key from the instance's private key
+     *
+     * Convenience method that returns the public key without modifying
+     * the instance state.
+     *
+     * @returns The public key derived from the private key
+     * @throws Error if privkey is not set
+     */
     toPublicKey(): PublicKey;
+    /**
+     * Sign the hash using Schnorr signature algorithm
+     *
+     * Performs the complete Schnorr signing process:
+     * 1. Validates inputs (32-byte hash, valid private key)
+     * 2. Converts hash to big number
+     * 3. Generates signature components using _findSignature()
+     * 4. Creates Signature object with Schnorr flag set
+     *
+     * @returns This Schnorr instance with the 'sig' property set
+     * @throws Error if hashbuf is not 32 bytes or privkey is invalid
+     */
     sign(): Schnorr;
+    /**
+     * Find signature values using Lotus Schnorr algorithm
+     *
+     * Process:
+     * 1. Generate deterministic nonce k using RFC6979 with "Schnorr+SHA256  " seed
+     * 2. Compute R = k*G
+     * 3. If R.y is not a quadratic residue, use n-k instead (negate)
+     * 4. Compute e = Hash(R.x || compressed(P) || m) mod n
+     * 5. Compute s = k + e*d mod n
+     * 6. Return signature (r=R.x, s)
+     */
     _findSignature(d: BN, e: BN): {
         r: BN;
         s: BN;
         compressed?: boolean;
         isSchnorr?: boolean;
     };
+    /**
+     * Ensure r part of signature is at least 32 bytes
+     *
+     * The BN type naturally cuts off leading zeros, e.g.
+     * <BN: 4f92d8094f710bc11b93935ac157730dda26c5c2a856650dbd8ebcd730d2d4> 31 bytes
+     * Buffer <00 4f 92 d8 09 4f 71 0b c1 1b 93 93 5a c1 57 73 0d da 26 c5 c2 a8 56 65 0d bd 8e bc d7 30 d2 d4> 32 bytes
+     * Both types are equal, however Schnorr signatures must be a minimum of 64 bytes.
+     * This ensures the r component is always 32 bytes for proper signature formatting.
+     *
+     * @param r - The r value as BN
+     * @returns Buffer representation (at least 32 bytes, big-endian)
+     */
     private getrBuffer;
+    /**
+     * Check for signature errors (verification)
+     *
+     * Lotus Schnorr Verification:
+     * 1. Check signature length is 64 or 65 bytes (65 with sighash byte)
+     * 2. Check r < p (field prime) and s < n (curve order)
+     * 3. Compute e = Hash(r || compressed(P) || m) mod n
+     * 4. Compute R = s*G - e*P
+     * 5. Check R is not infinity
+     * 6. Check R.y is a quadratic residue
+     * 7. Check R.x == r
+     *
+     * @returns True if verification fails (signature is invalid), false if signature is valid
+     */
     sigError(): boolean;
+    /**
+     * Verify signature
+     *
+     * Performs Schnorr signature verification and stores the result
+     * in the 'verified' property. Uses sigError() internally.
+     *
+     * @returns This Schnorr instance with 'verified' property set to the verification result
+     * @example
+     * ```typescript
+     * const isValid = schnorr.set({ hashbuf, sig, pubkey }).verify().verified
+     * ```
+     */
     verify(): Schnorr;
+    /**
+     * RFC6979 deterministic nonce generation for Lotus Schnorr
+     *
+     * Uses HMAC-DRBG with SHA256 and Schnorr-specific domain separator.
+     *
+     * Key difference from standard RFC6979:
+     * - Uses "Schnorr+SHA256  " (with trailing spaces) as the algorithm identifier
+     * - This ensures different nonces than ECDSA for the same key and message
+     *
+     * Reference: lotusd/src/secp256k1/src/modules/schnorr/schnorr_impl.h
+     */
     nonceFunctionRFC6979(privkey: Buffer, msgbuf: Buffer): BN;
+    /**
+     * Static sign method
+     *
+     * @param hashbuf - 32-byte hash buffer to sign
+     * @param privkey - Private key for signing
+     * @param endian - Byte endianness ('little' or 'big')
+     * @returns Schnorr signature
+     */
     static sign(hashbuf: Buffer, privkey: PrivateKey, endian?: 'little' | 'big'): Signature;
+    /**
+     * Static verify method
+     *
+     * @param hashbuf - 32-byte hash buffer that was signed
+     * @param sig - Signature to verify
+     * @param pubkey - Public key to verify against
+     * @param endian - Byte endianness ('little' or 'big')
+     * @returns True if signature is valid, false otherwise
+     */
     static verify(hashbuf: Buffer, sig: Signature, pubkey: PublicKey, endian?: 'little' | 'big'): boolean;
+    /**
+     * Reverse buffer byte order
+     *
+     * Used for converting between little-endian and big-endian representations
+     * of hash values. This is needed when interpreting hashes with different
+     * endianness conventions.
+     *
+     * @param buf - Buffer to reverse
+     * @returns New buffer with bytes in reversed order
+     * @private
+     */
     private reverseBuffer;
 }
 //# sourceMappingURL=schnorr.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"schnorr.d.ts","sourceRoot":"","sources":["../../../../../lib/bitcore/crypto/schnorr.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,EAAE,EAAE,MAAM,MAAM,CAAA;AAEzB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAExC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAKrC,MAAM,WAAW,WAAW;IAE1B,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,MAAM,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;IAEzB,OAAO,CAAC,EAAE,UAAU,CAAA;IAEpB,MAAM,CAAC,EAAE,SAAS,CAAA;IAElB,GAAG,CAAC,EAAE,SAAS,CAAA;IAEf,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAgCD,qBAAa,OAAO;IAElB,OAAO,EAAG,MAAM,CAAA;IAEhB,MAAM,EAAG,QAAQ,GAAG,KAAK,CAAA;IAEzB,OAAO,EAAG,UAAU,CAAA;IAEpB,MAAM,EAAG,SAAS,CAAA;IAElB,GAAG,EAAG,SAAS,CAAA;IAEf,QAAQ,EAAG,OAAO,CAAA;gBAWN,GAAG,CAAC,EAAE,WAAW;IAe7B,GAAG,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO;IAqB9B,cAAc,IAAI,OAAO;IAczB,WAAW,IAAI,SAAS;IAgBxB,IAAI,IAAI,OAAO;IAkCf,cAAc,CACZ,CAAC,EAAE,EAAE,EACL,CAAC,EAAE,EAAE,GACJ;QAAE,CAAC,EAAE,EAAE,CAAC;QAAC,CAAC,EAAE,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE;IAiE9D,OAAO,CAAC,UAAU;IAmBlB,QAAQ,IAAI,OAAO;IA+DnB,MAAM,IAAI,OAAO;IAgBjB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,EAAE;IA0EzD,MAAM,CAAC,IAAI,CACT,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,MAAM,CAAC,EAAE,QAAQ,GAAG,KAAK,GACxB,SAAS;IAmBZ,MAAM,CAAC,MAAM,CACX,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,QAAQ,GAAG,KAAK,GACxB,OAAO;IAsBV,OAAO,CAAC,aAAa;CAOtB"}
+{"version":3,"file":"schnorr.d.ts","sourceRoot":"","sources":["../../../../../lib/bitcore/crypto/schnorr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,EAAE,EAAE,MAAM,MAAM,CAAA;AAEzB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAExC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAErC;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;IACzB,yCAAyC;IACzC,OAAO,CAAC,EAAE,UAAU,CAAA;IACpB,kCAAkC;IAClC,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,+BAA+B;IAC/B,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,OAAO;IAClB,4CAA4C;IAC5C,OAAO,EAAG,MAAM,CAAA;IAChB,kEAAkE;IAClE,MAAM,EAAG,QAAQ,GAAG,KAAK,CAAA;IACzB,yCAAyC;IACzC,OAAO,EAAG,UAAU,CAAA;IACpB,yEAAyE;IACzE,MAAM,EAAG,SAAS,CAAA;IAClB,2EAA2E;IAC3E,GAAG,EAAG,SAAS,CAAA;IACf,yEAAyE;IACzE,QAAQ,EAAG,OAAO,CAAA;IAElB;;;;;;;;OAQG;gBACS,GAAG,CAAC,EAAE,WAAW;IAM7B;;;;;;;;OAQG;IACH,GAAG,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO;IAW9B;;;;;;;;;OASG;IACH,cAAc,IAAI,OAAO;IAKzB;;;;;;;;OAQG;IACH,WAAW,IAAI,SAAS;IAIxB;;;;;;;;;;;OAWG;IACH,IAAI,IAAI,OAAO;IAuBf;;;;;;;;;;OAUG;IACH,cAAc,CACZ,CAAC,EAAE,EAAE,EACL,CAAC,EAAE,EAAE,GACJ;QAAE,CAAC,EAAE,EAAE,CAAC;QAAC,CAAC,EAAE,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE;IAqD9D;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,UAAU;IAKlB;;;;;;;;;;;;;OAaG;IACH,QAAQ,IAAI,OAAO;IAmDnB;;;;;;;;;;;OAWG;IACH,MAAM,IAAI,OAAO;IAKjB;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,EAAE;IAkEzD;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,CACT,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,MAAM,CAAC,EAAE,QAAQ,GAAG,KAAK,GACxB,SAAS;IAUZ;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,CACX,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,QAAQ,GAAG,KAAK,GACxB,OAAO;IAWV;;;;;;;;;;OAUG;IACH,OAAO,CAAC,aAAa;CAOtB"}