@bsv/sdk 1.8.10 → 1.8.11

package/docs/reference/wallet.md

@@ -3426,7 +3426,7 @@ static unknownToJson(error: any): string
 
 Returns
 
-stringified JSON representation of the error such that it can be desirialized to a WalletError.
+stringified JSON representation of the error such that it can be deserialized to a WalletError.
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
@@ -4562,17 +4562,17 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | | | |
 | --- | --- | --- |
-| [isHexString](#function-ishexstring) | [validateDiscoverByAttributesArgs](#function-validatediscoverbyattributesargs) | [validateOutpointString](#function-validateoutpointstring) |
-| [parseWalletOutpoint](#function-parsewalletoutpoint) | [validateDiscoverByIdentityKeyArgs](#function-validatediscoverbyidentitykeyargs) | [validatePositiveIntegerOrZero](#function-validatepositiveintegerorzero) |
-| [toOriginHeader](#function-tooriginheader) | [validateInteger](#function-validateinteger) | [validateProveCertificateArgs](#function-validateprovecertificateargs) |
-| [validateAbortActionArgs](#function-validateabortactionargs) | [validateInternalizeActionArgs](#function-validateinternalizeactionargs) | [validateRelinquishCertificateArgs](#function-validaterelinquishcertificateargs) |
-| [validateAcquireDirectCertificateArgs](#function-validateacquiredirectcertificateargs) | [validateInternalizeOutput](#function-validateinternalizeoutput) | [validateRelinquishOutputArgs](#function-validaterelinquishoutputargs) |
-| [validateAcquireIssuanceCertificateArgs](#function-validateacquireissuancecertificateargs) | [validateListActionsArgs](#function-validatelistactionsargs) | [validateSatoshis](#function-validatesatoshis) |
+| [isHexString](#function-ishexstring) | [validateCreateActionOutput](#function-validatecreateactionoutput) | [validateOriginator](#function-validateoriginator) |
+| [parseWalletOutpoint](#function-parsewalletoutpoint) | [validateDiscoverByAttributesArgs](#function-validatediscoverbyattributesargs) | [validateOutpointString](#function-validateoutpointstring) |
+| [toOriginHeader](#function-tooriginheader) | [validateDiscoverByIdentityKeyArgs](#function-validatediscoverbyidentitykeyargs) | [validatePositiveIntegerOrZero](#function-validatepositiveintegerorzero) |
+| [validateAbortActionArgs](#function-validateabortactionargs) | [validateInteger](#function-validateinteger) | [validateProveCertificateArgs](#function-validateprovecertificateargs) |
+| [validateAcquireDirectCertificateArgs](#function-validateacquiredirectcertificateargs) | [validateInternalizeActionArgs](#function-validateinternalizeactionargs) | [validateRelinquishCertificateArgs](#function-validaterelinquishcertificateargs) |
+| [validateAcquireIssuanceCertificateArgs](#function-validateacquireissuancecertificateargs) | [validateInternalizeOutput](#function-validateinternalizeoutput) | [validateRelinquishOutputArgs](#function-validaterelinquishoutputargs) |
+| [validateBase64String](#function-validatebase64string) | [validateListActionsArgs](#function-validatelistactionsargs) | [validateSatoshis](#function-validatesatoshis) |
 | [validateBasketInsertion](#function-validatebasketinsertion) | [validateListCertificatesArgs](#function-validatelistcertificatesargs) | [validateSignActionArgs](#function-validatesignactionargs) |
 | [validateCreateActionArgs](#function-validatecreateactionargs) | [validateListOutputsArgs](#function-validatelistoutputsargs) | [validateSignActionOptions](#function-validatesignactionoptions) |
 | [validateCreateActionInput](#function-validatecreateactioninput) | [validateOptionalInteger](#function-validateoptionalinteger) | [validateStringLength](#function-validatestringlength) |
 | [validateCreateActionOptions](#function-validatecreateactionoptions) | [validateOptionalOutpointString](#function-validateoptionaloutpointstring) | [validateWalletPayment](#function-validatewalletpayment) |
-| [validateCreateActionOutput](#function-validatecreateactionoutput) | [validateOriginator](#function-validateoriginator) |  |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
@@ -4692,6 +4692,36 @@ when args contain fields invalid for issuance
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
+---
+### Function: validateBase64String
+
+Validate a Base64 string (structure and decoded size).
+
+```ts
+export function validateBase64String(s: string, name: string, min?: number, max?: number): string 
+```
+
+Returns
+
+validated base64 string
+
+Argument Details
+
++ **s**
+  + base64 string
++ **name**
+  + parameter name used in error messages
++ **min**
+  + optional minimum decoded byte length
++ **max**
+  + optional maximum decoded byte length
+
+Throws
+
+WERR_INVALID_PARAMETER when invalid
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
 ---
 ### Function: validateBasketInsertion
 

package/package.json

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

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

@@ -7,7 +7,8 @@ import {
   fromBase58,
   toBase58,
   fromBase58Check,
-  toBase58Check
+  toBase58Check,
+  verifyNotNull
 } from '../../primitives/utils'
 
 describe('utils', () => {
@@ -207,3 +208,28 @@ describe('utils', () => {
     expect(toArray(input)).toEqual(expected)
   })
 })
+
+describe('verifyNotNull', () => {
+  it('should return the value if it is not null or undefined', () => {
+    expect(verifyNotNull(42)).toBe(42)
+    expect(verifyNotNull('hello')).toBe('hello')
+    expect(verifyNotNull({})).toEqual({})
+    expect(verifyNotNull([])).toEqual([])
+  })
+
+  it('should throw an error with default message if value is null', () => {
+    expect(() => verifyNotNull(null)).toThrow('Expected a valid value, but got undefined or null.')
+  })
+
+  it('should throw an error with default message if value is undefined', () => {
+    expect(() => verifyNotNull(undefined)).toThrow('Expected a valid value, but got undefined or null.')
+  })
+
+  it('should throw an error with custom message if value is null', () => {
+    expect(() => verifyNotNull(null, 'Custom error')).toThrow('Custom error')
+  })
+
+  it('should throw an error with custom message if value is undefined', () => {
+    expect(() => verifyNotNull(undefined, 'Another custom error')).toThrow('Another custom error')
+  })
+})

package/src/primitives/utils.ts

@@ -819,3 +819,20 @@ export const minimallyEncode = (buf: number[]): number[] => {
 
 const OverflowInt64 = new BigNumber(2).pow(new BigNumber(63))
 const OverflowUint64 = new BigNumber(2).pow(new BigNumber(64))
+
+/**
+ * Verifies that a value is not null or undefined, throwing an error if it is.
+ *
+ * @template T - The type of the value being verified
+ * @param {T | undefined | null} value - The value to verify
+ * @param {string} errorMessage - The error message to throw if the value is null or undefined
+ * @returns {T} - The verified value
+ * @throws {Error} - If the value is null or undefined
+ *
+ * @example
+ * const myValue = verifyNotNull(someValue, 'someValue must be defined')
+ */
+export function verifyNotNull<T> (value: T | undefined | null, errorMessage: string = 'Expected a valid value, but got undefined or null.'): T {
+  if (value == null) throw new Error(errorMessage)
+  return value
+}

package/src/script/__tests/Spend.test.ts

@@ -7,8 +7,30 @@ import RPuzzle from '../../script/templates/RPuzzle'
 import Transaction from '../../transaction/Transaction'
 import LockingScript from '../../script/LockingScript'
 import UnlockingScript from '../../script/UnlockingScript'
-
+import MerklePath from '../../transaction/MerklePath'
+import ChainTracker from '../../transaction/ChainTracker'
 import spendValid from './spend.valid.vectors'
+import Script from '../../script/Script'
+
+export class MockChain implements ChainTracker {
+  mock: { blockheaders: string[] }
+
+  constructor(mock: { blockheaders: string[] }) {
+    this.mock = mock
+  }
+
+  addBlock(merkleRoot: string) {
+    this.mock.blockheaders.push(merkleRoot)
+  }
+
+  async isValidRootForHeight(root: string, height: number): Promise<boolean> {
+    return this.mock.blockheaders[height] === root
+  }
+
+  async currentHeight(): Promise<number> {
+    return this.mock.blockheaders.length
+  }
+}
 
 describe('Spend', () => {
   it('Successfully validates a P2PKH spend', async () => {
@@ -368,4 +390,55 @@ describe('Spend', () => {
       expect(spend.validate()).toBe(true)
     })
   }
+
+  it('Successfully validates a spend where sequence is set to undefined', async () => {
+    const sourceTransaction = new Transaction(
+      1,
+      [{
+        sourceTXID: '0000000000000000000000000000000000000000000000000000000000000000',
+        sourceOutputIndex: 0,
+        unlockingScript: Script.fromASM('OP_TRUE'),
+        sequence: 0xffffffff
+      }],
+      [
+        {
+          lockingScript: Script.fromASM('OP_NOP'),
+          satoshis: 2
+        }
+      ],
+      0
+    )
+    const txid = sourceTransaction.id('hex')
+    sourceTransaction.merklePath = MerklePath.fromCoinbaseTxidAndHeight(txid, 0)
+    const chain = new MockChain({ blockheaders: [] })
+    chain.addBlock(txid)
+
+    const spendTx = new Transaction(
+      1,
+      [
+        {
+          unlockingScript: Script.fromASM('OP_TRUE'),
+          sourceTransaction,
+          sourceOutputIndex: 0
+        }
+      ],
+      [{
+          lockingScript: Script.fromASM('OP_NOP'),
+          satoshis: 1
+      }],
+      0
+    )
+
+    const valid = await spendTx.verify(chain)
+    
+    expect(valid).toBe(true)
+
+    const b = spendTx.toBinary()
+    const t = Transaction.fromBinary(b)
+    expect(t.inputs[0].sequence).toBe(0xffffffff)
+
+    const b2 = spendTx.toEF()
+    const t2 = Transaction.fromEF(b2)
+    expect(t2.inputs[0].sequence).toBe(0xffffffff)
+  })
 })

package/src/script/__tests/SpendComplex.test.ts

@@ -1,6 +1,7 @@
 import Script from '../../script/Script'
 import Spend from '../../script/Spend'
 import Transaction from '../../transaction/Transaction'
+import { verifyNotNull } from '../../primitives/utils'
 
 describe('SpendComplex', () => {
   it('complex unlock script validation', () => {
@@ -19,11 +20,6 @@ describe('SpendComplex', () => {
   })
 })
 
-function verifyTruthy<T> (v: T | undefined): T {
-  if (v == null) throw new Error('must have value')
-  return v
-}
-
 export function validateUnlockScript (
   spendingRawTx: string,
   vin: number,
@@ -34,16 +30,16 @@ export function validateUnlockScript (
   const ls = Script.fromHex(lockingScript)
 
   const spend = new Spend({
-    sourceTXID: verifyTruthy(spendingTx.inputs[vin].sourceTXID),
-    sourceOutputIndex: verifyTruthy(spendingTx.inputs[vin].sourceOutputIndex),
+    sourceTXID: verifyNotNull(spendingTx.inputs[vin].sourceTXID, 'sourceTXID must have value'),
+    sourceOutputIndex: verifyNotNull(spendingTx.inputs[vin].sourceOutputIndex, 'sourceOutputIndex must have value'),
     sourceSatoshis: amount,
     lockingScript: ls,
     transactionVersion: spendingTx.version,
     otherInputs: spendingTx.inputs.filter((v, i) => i !== vin),
     inputIndex: vin,
-    unlockingScript: verifyTruthy(spendingTx.inputs[vin].unlockingScript),
+    unlockingScript: verifyNotNull(spendingTx.inputs[vin].unlockingScript, 'unlockingScript must have value'),
     outputs: spendingTx.outputs,
-    inputSequence: verifyTruthy(spendingTx.inputs[vin].sequence),
+    inputSequence: verifyNotNull(spendingTx.inputs[vin].sequence, 'sequence must have value'),
     lockTime: spendingTx.lockTime
   })
 

package/src/script/templates/P2PKH.ts

@@ -1,6 +1,6 @@
 import OP from '../OP.js'
 import ScriptTemplate from '../ScriptTemplate.js'
-import { fromBase58Check } from '../../primitives/utils.js'
+import { fromBase58Check, verifyNotNull } from '../../primitives/utils.js'
 import LockingScript from '../LockingScript.js'
 import UnlockingScript from '../UnlockingScript.js'
 import Transaction from '../../transaction/Transaction.js'
@@ -9,11 +9,6 @@ import TransactionSignature from '../../primitives/TransactionSignature.js'
 import { sha256 } from '../../primitives/Hash.js'
 import Script from '../Script.js'
 
-function verifyTruthy<T>(v: T | undefined): T {
-  if (v == null) throw new Error('must have value')
-  return v
-}
-
 /**
  * P2PKH (Pay To Public Key Hash) class implementing ScriptTemplate.
  *
@@ -125,13 +120,13 @@ export default class P2PKH implements ScriptTemplate {
 
         const preimage = TransactionSignature.format({
           sourceTXID,
-          sourceOutputIndex: verifyTruthy(input.sourceOutputIndex),
+          sourceOutputIndex: verifyNotNull(input.sourceOutputIndex, 'input.sourceOutputIndex must have value'),
           sourceSatoshis,
           transactionVersion: tx.version,
           otherInputs,
           inputIndex,
           outputs: tx.outputs,
-          inputSequence: verifyTruthy(input.sequence),
+          inputSequence: verifyNotNull(input.sequence, 'input.sequence must have value'),
           subscript: lockingScript,
           lockTime: tx.lockTime,
           scope: signatureScope

package/src/script/templates/PushDrop.ts

@@ -9,11 +9,7 @@ import {
 import { WalletInterface } from '../../wallet/Wallet.interfaces.js'
 import { Transaction } from '../../transaction/index.js'
 import { WalletProtocol } from '../../wallet/Wallet.interfaces.js'
-
-function verifyTruthy<T>(v: T | undefined): T {
-  if (v == null) throw new Error('must have value')
-  return v
-}
+import { verifyNotNull } from '../../primitives/utils.js'
 
 /**
  * For a given piece of data to push onto the stack in script, creates the correct minimally-encoded script chunk,
@@ -71,7 +67,7 @@ export default class PushDrop implements ScriptTemplate {
     fields: number[][]
   } {
     const lockingPublicKey = PublicKey.fromString(
-      Utils.toHex(verifyTruthy(script.chunks[0].data)) // ✅ Ensure not undefined
+      Utils.toHex(verifyNotNull(script.chunks[0].data, 'script.chunks[0].data must have value'))
     )
 
     const fields: number[][] = []
@@ -249,7 +245,7 @@ export default class PushDrop implements ScriptTemplate {
 
         const preimage = TransactionSignature.format({
           sourceTXID,
-          sourceOutputIndex: verifyTruthy(input.sourceOutputIndex),
+          sourceOutputIndex: verifyNotNull(input.sourceOutputIndex, 'input.sourceOutputIndex must have value'),
           sourceSatoshis,
           transactionVersion: tx.version,
           otherInputs,

package/src/transaction/Beef.ts

@@ -2,14 +2,9 @@ import MerklePath from './MerklePath.js'
 import Transaction from './Transaction.js'
 import ChainTracker from './ChainTracker.js'
 import BeefTx from './BeefTx.js'
-import { Reader, Writer, toHex, toArray } from '../primitives/utils.js'
+import { Reader, Writer, toHex, toArray, verifyNotNull } from '../primitives/utils.js'
 import { hash256 } from '../primitives/Hash.js'
 
-function verifyTruthy<T> (v: T | undefined): T {
-  if (v == null) throw new Error('Expected a valid value, but got undefined.')
-  return v
-}
-
 export const BEEF_V1 = 4022206465 // 0100BEEF in LE order
 export const BEEF_V2 = 4022206466 // 0200BEEF in LE order
 export const ATOMIC_BEEF = 0x01010101 // 01010101
@@ -156,7 +151,7 @@ export class Beef {
 
     for (const i of beefTx.tx.inputs) {
       if (i.sourceTransaction == null) {
-        const itx = this.findTxid(verifyTruthy(i.sourceTXID)) // Ensure sourceTXID is valid
+        const itx = this.findTxid(verifyNotNull(i.sourceTXID, 'sourceTXID must be valid'))
         if (itx != null) {
           i.sourceTransaction = itx.tx
         }
@@ -185,7 +180,7 @@ export class Beef {
       } else {
         for (const i of tx.inputs) {
           if (i.sourceTransaction == null) {
-            const itx = beef.findTxid(verifyTruthy(i.sourceTXID)) // Ensure sourceTXID is valid
+            const itx = beef.findTxid(verifyNotNull(i.sourceTXID, 'sourceTXID must be valid'))
             if (itx != null) {
               i.sourceTransaction = itx.tx
             }

package/src/transaction/Transaction.ts

@@ -618,7 +618,7 @@ export default class Transaction {
       const scriptBin = i.unlockingScript.toBinary()
       writer.writeVarIntNum(scriptBin.length)
       writer.write(scriptBin)
-      writer.writeUInt32LE(i.sequence ?? 0)
+      writer.writeUInt32LE(i.sequence ?? 0xffffffff) // default to max sequence
     }
     writer.writeVarIntNum(this.outputs.length)
     for (const o of this.outputs) {
@@ -659,7 +659,7 @@ export default class Transaction {
       const scriptBin = i.unlockingScript.toBinary()
       writer.writeVarIntNum(scriptBin.length)
       writer.write(scriptBin)
-      writer.writeUInt32LE(i.sequence ?? 0)
+      writer.writeUInt32LE(i.sequence ?? 0xffffffff) // default to max sequence
       writer.writeUInt64LE(
         i.sourceTransaction.outputs[i.sourceOutputIndex].satoshis ?? 0
       )
@@ -866,7 +866,7 @@ export default class Transaction {
           transactionVersion: tx.version,
           otherInputs,
           unlockingScript: input.unlockingScript,
-          inputSequence: input.sequence ?? 0,
+          inputSequence: input.sequence ?? 0xffffffff, // default to max sequence
           inputIndex: i,
           outputs: tx.outputs,
           lockTime: tx.lockTime,