@bsv/sdk 1.2.10 → 1.2.11

package/docs/primitives.md

@@ -5254,7 +5254,8 @@ create a corresponding public key and derive a shared secret from a public key.
 ```ts
 export default class PrivateKey extends BigNumber {
     static fromRandom(): PrivateKey 
-    static fromString(str: string, base: number | "hex"): PrivateKey 
+    static fromString(str: string, base: number | "hex" = "hex"): PrivateKey 
+    static fromHex(str: string): PrivateKey 
     static fromWif(wif: string, prefixLength: number = 1): PrivateKey 
     constructor(number: BigNumber | number | string | number[] = 0, base: number | "be" | "le" | "hex" = 10, endian: "be" | "le" = "be", modN: "apply" | "nocheck" | "error" = "apply") 
     checkInField(): {
@@ -5267,6 +5268,8 @@ export default class PrivateKey extends BigNumber {
     toPublicKey(): PublicKey 
     toWif(prefix: number[] = [128]): string 
     toAddress(prefix: number[] | string = [0]): string 
+    toHex(): string 
+    toString(base: number | "hex" = "hex", padding: number = 64): string 
     deriveSharedSecret(key: PublicKey): Point 
     deriveChild(publicKey: PublicKey, invoiceNumber: string): PrivateKey 
     toKeyShares(threshold: number, totalShares: number): KeyShares 
@@ -5276,7 +5279,7 @@ export default class PrivateKey extends BigNumber {
 }
 ```
 
-See also: [BigNumber](#class-bignumber), [KeyShares](#class-keyshares), [Point](#class-point), [PublicKey](#class-publickey), [Signature](#class-signature), [sign](#variable-sign), [verify](#variable-verify)
+See also: [BigNumber](#class-bignumber), [KeyShares](#class-keyshares), [Point](#class-point), [PublicKey](#class-publickey), [Signature](#class-signature), [sign](#variable-sign), [toHex](#variable-tohex), [verify](#variable-verify)
 
 <details>
 
@@ -5394,6 +5397,28 @@ const share2 = 'Cm5fuUc39X5xgdedao8Pr1kvCSm8Gk7Cfenc7xUKcfLX.2juyK9BxCWn2DiY5JUA
 const recoveredKey = PrivateKey.fromBackupShares([share1, share2])
 ```
 
+#### Method fromHex
+
+Generates a private key from a hexadecimal string.
+
+```ts
+static fromHex(str: string): PrivateKey 
+```
+See also: [PrivateKey](#class-privatekey)
+
+Returns
+
+The generated Private Key instance.
+
+Argument Details
+
++ **str**
+  + The hexadecimal string representing the private key. The string must represent a valid private key in big-endian format.
+
+Throws
+
+If the string is not a valid hexadecimal or represents an invalid private key.
+
 #### Method fromKeyShares
 
 Combines shares to reconstruct the private key.
@@ -5438,7 +5463,7 @@ const privateKey = PrivateKey.fromRandom();
 Generates a private key from a string.
 
 ```ts
-static fromString(str: string, base: number | "hex"): PrivateKey 
+static fromString(str: string, base: number | "hex" = "hex"): PrivateKey 
 ```
 See also: [PrivateKey](#class-privatekey)
 
@@ -5562,6 +5587,30 @@ Argument Details
 + **totalShares**
   + The number of shares to generate for distribution.
 
+#### Method toHex
+
+Converts this PrivateKey to a hexadecimal string.
+
+```ts
+toHex(): string 
+```
+
+Returns
+
+Returns a string representing the hexadecimal value of this BigNumber.
+
+Argument Details
+
++ **length**
+  + The minimum length of the hex string
+
+Example
+
+```ts
+const bigNumber = new BigNumber(255);
+const hex = bigNumber.toHex();
+```
+
 #### Method toKeyShares
 
 Splits the private key into shares using Shamir's Secret Sharing Scheme.
@@ -5613,6 +5662,27 @@ const privateKey = PrivateKey.fromRandom();
 const publicKey = privateKey.toPublicKey();
 ```
 
+#### Method toString
+
+function toString() { [native code] }
+
+Converts this PrivateKey to a string representation.
+
+```ts
+toString(base: number | "hex" = "hex", padding: number = 64): string 
+```
+
+Returns
+
+A string representation of the PrivateKey in the specified base, padded to the specified length.
+
+Argument Details
+
++ **base**
+  + The base for representing the number. Default is hexadecimal ('hex').
++ **padding**
+  + The minimum number of digits for the output string. Default is 64, ensuring a 256-bit representation in hexadecimal.
+
 #### Method toWif
 
 Converts the private key to a Wallet Import Format (WIF) string.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.2.10",
+  "version": "1.2.11",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/primitives/PrivateKey.ts

@@ -93,8 +93,21 @@ export default class PrivateKey extends BigNumber {
    * @returns The generated Private Key.
    * @throws Will throw an error if the string is not valid.
    **/
-  static fromString (str: string, base: number | 'hex'): PrivateKey {
-    return new PrivateKey(BigNumber.fromString(str, base).toArray())
+  static fromString (str: string, base: number | 'hex' = 'hex'): PrivateKey {
+    return new PrivateKey(super.fromString(str, base).toArray())
+  }
+
+  /**
+   * Generates a private key from a hexadecimal string.
+   *
+   * @method fromHex
+   * @static
+   * @param {string} str - The hexadecimal string representing the private key. The string must represent a valid private key in big-endian format.
+   * @returns {PrivateKey} The generated Private Key instance.
+   * @throws {Error} If the string is not a valid hexadecimal or represents an invalid private key.
+   **/
+  static fromHex (str: string): PrivateKey {
+    return new PrivateKey(super.fromHex(str, 'big'))
   }
 
   /**
@@ -274,6 +287,34 @@ export default class PrivateKey extends BigNumber {
     return this.toPublicKey().toAddress(prefix)
   }
 
+  /**
+   * Converts this PrivateKey to a hexadecimal string.
+   *
+   * @method toHex
+   * @param length - The minimum length of the hex string
+   * @returns Returns a string representing the hexadecimal value of this BigNumber.
+   *
+   * @example
+   * const bigNumber = new BigNumber(255);
+   * const hex = bigNumber.toHex();
+   */
+  toHex (): string {
+    return super.toHex(32)
+  }
+
+  /**
+   * Converts this PrivateKey to a string representation.
+   *
+   * @method toString
+   * @param {number | 'hex'} [base='hex'] - The base for representing the number. Default is hexadecimal ('hex').
+   * @param {number} [padding=64] - The minimum number of digits for the output string. Default is 64, ensuring a 256-bit representation in hexadecimal.
+   * @returns {string} A string representation of the PrivateKey in the specified base, padded to the specified length.
+   *
+   **/
+  toString (base: number | 'hex' = 'hex', padding: number = 64): string {
+    return super.toString(base, padding)
+  }
+
   /**
    * Derives a shared secret from the public key.
    *

package/src/primitives/__tests/PrivateKey.test.ts

@@ -1,17 +1,97 @@
 import PublicKey from '../../../dist/cjs/src/primitives/PublicKey'
 import PrivateKey from '../../../dist/cjs/src/primitives/PrivateKey'
 import BRC42Private from './BRC42.private.vectors'
+import Curve from '../../../dist/cjs/src/primitives/Curve'
+import BigNumber from '../../../dist/cjs/src/primitives/BigNumber'
 
 describe('PrivateKey', () => {
   describe('BRC42 vectors', () => {
-    for (let i = 0; i < BRC42Private.length; i++) {
-      it(`Passes BRC42 private vector #${i + 1}`, () => {
-        const v = BRC42Private[i]
-        const publicKey = PublicKey.fromString(v.senderPublicKey)
-        const privateKey = PrivateKey.fromString(v.recipientPrivateKey, 16)
-        const derived = privateKey.deriveChild(publicKey, v.invoiceNumber)
-        expect(derived.toHex(32)).toEqual(v.privateKey)
+    const curve = new Curve()
+
+    BRC42Private.forEach((vector, index) => {
+      it(`Passes BRC42 private vector #${index + 1}`, () => {
+        const publicKey = PublicKey.fromString(vector.senderPublicKey)
+        const privateKey = PrivateKey.fromString(vector.recipientPrivateKey, 16)
+        const derived = privateKey.deriveChild(publicKey, vector.invoiceNumber)
+        expect(derived.toHex(32)).toEqual(vector.privateKey)
       })
+    })
+  })
+
+  describe('PrivateKey Validation and Conversion', () => {
+    const curve = new Curve()
+
+    const isValidPrivateKey = (key) => {
+      try {
+        const keyAsNumber = new BigNumber(key, 16)
+        return (
+          !keyAsNumber.isZero() &&
+          keyAsNumber.cmp(curve.n) < 0 &&
+          key.length === 64
+        )
+      } catch (e) {
+        return false
+      }
     }
+
+    it('Validates and converts valid private keys between hex and string', () => {
+      const validKeys = [
+        '0000000000000000000000000000000000000000000000000000000000000001',
+        'fffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364140',
+        '8a2f85e08360a04c8a36b7c22c5e9e9a0d3bcf2f95c97db2b8bd90fc5f5ff66a',
+        '1b5a8f2392e6959a7de2b0a58f8a64cc528c9bfc1788ee0d32e1455063e71545'
+      ]
+
+      validKeys.forEach((key, index) => {
+        const privateKeyFromHex = PrivateKey.fromHex(key)
+        const privateKeyFromString = PrivateKey.fromString(key, 'hex')
+        const privateKeyToHex = privateKeyFromHex.toHex()
+        const privateKeyToString = privateKeyFromString.toString('hex')
+        expect(isValidPrivateKey(privateKeyToHex)).toBe(true)
+        expect(isValidPrivateKey(privateKeyToString)).toBe(true)
+
+        // Round-trip conversion checks
+        expect(privateKeyToHex).toEqual(key)
+        expect(privateKeyToString).toEqual(key)
+      })
+    })
+
+    // it('Rejects invalid private keys during validation and conversion', () => {
+    //   const invalidKeys = [
+    //     '0000000000000000000000000000000000000000000000000000000000000000',
+    //     'fffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141',
+    //     'ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff',
+    //     'fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe',
+    //     '1234567890abcdef',
+    //     'fffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd03641',
+    //     'fffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364',
+    //   ]
+
+    //   invalidKeys.forEach((key, index) => {
+    //     const isValid = isValidPrivateKey(key)
+    //     expect(isValid).toBe(false)
+    //     // Ensure invalid keys throw an error during conversion
+    //     expect(() => PrivateKey.fromHex(key)).toThrow()
+    //     expect(() => PrivateKey.fromString(key, 'hex')).toThrow()
+    //   })
+    // })
+
+    it('Tests 10,000 random private keys for valid conversions', () => {
+      for (let i = 0; i < 10000; i++) {
+        const privateKey = PrivateKey.fromRandom()
+        const privateKeyHex = privateKey.toHex()
+        const privateKeyString = privateKey.toString('hex')
+
+        // Validate the random key's format
+        expect(isValidPrivateKey(privateKeyHex)).toBe(true)
+        expect(isValidPrivateKey(privateKeyString)).toBe(true)
+
+        // Round-trip conversion checks
+        const roundTripHex = PrivateKey.fromHex(privateKeyHex).toHex()
+        const roundTripString = PrivateKey.fromString(privateKeyString, 'hex').toString('hex')
+        expect(roundTripHex).toEqual(privateKeyHex)
+        expect(roundTripString).toEqual(privateKeyString)
+      }
+    })
   })
 })