@bsv/sdk 1.2.9 → 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/docs/transaction.md

@@ -592,6 +592,7 @@ export class Beef {
     constructor(version?: BeefVersion) 
     get magic(): number 
     findTxid(txid: string): BeefTx | undefined 
+    makeTxidOnly(txid: string): BeefTx | undefined 
     findBump(txid: string): MerklePath | undefined 
     findTransactionForSigning(txid: string): Transaction | undefined 
     findAtomicTransaction(txid: string): Transaction | undefined 
@@ -779,6 +780,23 @@ Argument Details
 + **allowTxidOnly**
   + optional. If true, transaction txid only is assumed valid
 
+#### Method makeTxidOnly
+
+Replaces `BeefTx` for this txid with txidOnly.
+
+Replacement is done so that a `clone()` can be
+updated by this method without affecting the
+original.
+
+```ts
+makeTxidOnly(txid: string): BeefTx | undefined 
+```
+See also: [BeefTx](#class-beeftx)
+
+Returns
+
+undefined if txid is unknown.
+
 #### Method mergeBump
 
 Merge a MerklePath that is assumed to be fully valid.
@@ -847,7 +865,7 @@ Argument Details
 #### Method sortTxs
 
 Sort the `txs` by input txid dependency order:
-- Oldest Tx Anchored by Path
+- Oldest Tx Anchored by Path or txid only
 - Newer Txs depending on Older parents
 - Newest Tx
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.2.9",
+  "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)
+      }
+    })
   })
 })

package/src/transaction/Beef.ts

@@ -98,6 +98,26 @@ export class Beef {
     return this.txs.find(tx => tx.txid === txid)
   }
 
+  /**
+   * Replaces `BeefTx` for this txid with txidOnly.
+   *
+   * Replacement is done so that a `clone()` can be
+   * updated by this method without affecting the
+   * original.
+   *
+   * @param txid
+   * @returns undefined if txid is unknown.
+   */
+  makeTxidOnly (txid: string): BeefTx | undefined {
+    const i = this.txs.findIndex(tx => tx.txid === txid)
+    if (i === -1) return undefined
+    let btx = this.txs[i]
+    if (btx.isTxidOnly) { return btx }
+    this.txs.slice(i, i + 1)
+    btx = this.mergeTxidOnly(txid)
+    return btx
+  }
+
   /**
    * @returns `MerklePath` with level zero hash equal to txid or undefined.
    */
@@ -518,7 +538,7 @@ export class Beef {
 
   /**
      * Sort the `txs` by input txid dependency order:
-     * - Oldest Tx Anchored by Path
+     * - Oldest Tx Anchored by Path or txid only
      * - Newer Txs depending on Older parents
      * - Newest Tx
      *
@@ -553,7 +573,10 @@ export class Beef {
       if (tx.isValid) {
         validTxids[tx.txid] = true
         result.push(tx)
-      } else if (tx.isTxidOnly) { txidOnly.push(tx) } else { queue.push(tx) }
+      } else if (tx.isTxidOnly && tx.inputTxids.length === 0) {
+        validTxids[tx.txid] = true
+        txidOnly.push(tx)
+      } else { queue.push(tx) }
     }
 
     // Hashtable of unknown input txids used to fund transactions without their own proof.
@@ -564,17 +587,18 @@ export class Beef {
     const possiblyMissingInputs = queue
     queue = []
 
+    // all tx are isValid false, hasProof false.
+    // if isTxidOnly then has inputTxids
     for (const tx of possiblyMissingInputs) {
       let hasMissingInput = false
-      if (!tx.isValid) {
-        // For all the unproven transactions,
-        // link their inputs that exist in this beef,
-        // make a note of missing inputs.
-        for (const inputTxid of tx.inputTxids) {
-          if (!txidToTx[inputTxid]) {
-            missingInputs[inputTxid] = true
-            hasMissingInput = true
-          }
+
+      // For all the unproven transactions,
+      // link their inputs that exist in this beef,
+      // make a note of missing inputs.
+      for (const inputTxid of tx.inputTxids) {
+        if (!txidToTx[inputTxid]) {
+          missingInputs[inputTxid] = true
+          hasMissingInput = true
         }
       }
       if (hasMissingInput) { txsMissingInputs.push(tx) } else { queue.push(tx) }
@@ -584,6 +608,8 @@ export class Beef {
     while (queue.length > 0) {
       const oldQueue = queue
       queue = []
+      // all tx are isValid false, hasProof false.
+      // if isTxidOnly then has inputTxids
       for (const tx of oldQueue) {
         if (tx.inputTxids.every(txid => validTxids[txid])) {
           validTxids[tx.txid] = true
@@ -596,8 +622,8 @@ export class Beef {
     // transactions that don't have proofs and don't chain to proofs
     const txsNotValid = queue
 
-    // New order of txs is sorted, unsortable, txidOnly (no raw transaction)
-    this.txs = result.concat(queue).concat(txidOnly).concat(txsMissingInputs)
+    // New order of txs is unsortable (missing inputs or depends on missing inputs), txidOnly, sorted (so newest sorted is last)
+    this.txs = txsMissingInputs.concat(txsNotValid).concat(txidOnly).concat(result)
 
     return {
       missingInputs: Object.keys(missingInputs),

package/src/transaction/__tests/Beef.test.ts

@@ -305,6 +305,24 @@ describe('Beef tests', () => {
         expect(atomic).toEqual(beef2)
       }
     })
+    test('9_sortTxs', async () => {
+      {
+        const beef = new Beef()
+        beef.mergeTxidOnly('a')
+        const btx = beef.mergeTxidOnly('b')
+        btx.inputTxids = ['a']
+        beef.sortTxs()
+        expect(beef.txs[1].txid).toBe('b')
+      }
+      {
+        const beef = new Beef()
+        const atx = beef.mergeTxidOnly('a')
+        const btx = beef.mergeTxidOnly('b')
+        atx.inputTxids = ['b']
+        beef.sortTxs()
+        expect(beef.txs[1].txid).toBe('a')
+      }
+    })
 })
 
 const txs: string[] = [