@bsv/sdk 2.1.3 → 2.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",
@@ -237,23 +237,23 @@
   },
   "homepage": "https://github.com/bsv-blockchain/ts-stack/tree/main/packages/sdk#readme",
   "devDependencies": {
-    "@eslint/js": "^9.39.1",
-    "@jest/globals": "^30.3.0",
-    "@rspack/cli": "^2.0.0",
-    "@rspack/core": "^1.6.1",
+    "@eslint/js": "^10.0.1",
+    "@jest/globals": "^30.4.1",
+    "@rspack/cli": "^2.0.8",
+    "@rspack/core": "^2.0.8",
     "@types/jest": "^30.0.0",
-    "@types/node": "^24.10.1",
-    "eslint": "^9.39.1",
-    "globals": "^16.5.0",
-    "jest": "^30.3.0",
-    "jest-environment-jsdom": "^30.3.0",
-    "ts-jest": "^29.4.9",
-    "ts-loader": "^9.5.4",
+    "@types/node": "^25.9.3",
+    "eslint": "^10.5.0",
+    "globals": "^17.6.0",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
+    "ts-jest": "^29.4.11",
+    "ts-loader": "^9.6.0",
     "ts-standard": "^12.0.2",
     "ts2md": "^0.2.8",
     "tsconfig-to-dual-package": "^1.2.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.46.4"
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.61.0"
   },
   "ts-standard": {
     "project": "tsconfig.eslint.json",

package/src/compat/Mnemonic.ts

@@ -125,9 +125,22 @@ export default class Mnemonic {
    * Sets the mnemonic for the instance from a string.
    * @param {string} mnemonic - The mnemonic phrase as a string.
    * @returns {this} The Mnemonic instance with the set mnemonic.
+   * @throws {Error} If the mnemonic does not pass BIP-39 validation
+   * (unknown words, invalid length, or bad checksum).
    */
   public fromString (mnemonic: string): this {
     this.mnemonic = mnemonic
+    let valid = false
+    try {
+      valid = this.check()
+    } catch {
+      valid = false
+    }
+    if (!valid) {
+      throw new Error(
+        'Mnemonic does not pass the check - was the mnemonic typed incorrectly? Are there extra spaces?'
+      )
+    }
     return this
   }
 

package/src/compat/__tests/Mnemonic.test.ts

@@ -49,15 +49,21 @@ describe('Mnemonic', function () {
     mnemonic = m.mnemonic
 
     // mnemonics with extra whitespace do not pass the check
-    m = new Mnemonic().fromString(mnemonic + ' ')
-    expect(m.check()).toEqual(false)
+    const trailingSpace = mnemonic + ' '
+    const trailing = new Mnemonic()
+    trailing.mnemonic = trailingSpace
+    expect(trailing.check()).toEqual(false)
+    expect(() => new Mnemonic().fromString(trailingSpace)).toThrow()
 
     // mnemonics with a word replaced do not pass the check
     const words = mnemonic.split(' ')
     expect(words[words.length - 1]).not.toEqual('zoo')
     words[words.length - 1] = 'zoo'
-    mnemonic = words.join(' ')
-    expect(new Mnemonic().fromString(mnemonic).check()).toEqual(false)
+    const badWord = words.join(' ')
+    const replaced = new Mnemonic()
+    replaced.mnemonic = badWord
+    expect(replaced.check()).toEqual(false)
+    expect(() => new Mnemonic().fromString(badWord)).toThrow()
   })
 
   describe('#toBinary', () => {
@@ -132,13 +138,51 @@ describe('Mnemonic', function () {
   })
 
   describe('#fromString', () => {
-    it('should throw an error in invalid mnemonic', () => {
+    it('should throw an error on invalid mnemonic when toSeed is called', () => {
       expect(() => {
         new Mnemonic().fromString('invalid mnemonic').toSeed()
       }).toThrow(
         'Mnemonic does not pass the check - was the mnemonic typed incorrectly? Are there extra spaces?'
       )
     })
+
+    it('should throw immediately on nonsense input', () => {
+      expect(() => {
+        Mnemonic.fromString('this is not a real bip39 mnemonic phrase at all')
+      }).toThrow(
+        'Mnemonic does not pass the check - was the mnemonic typed incorrectly? Are there extra spaces?'
+      )
+    })
+
+    it('should throw on garbage string', () => {
+      expect(() => {
+        Mnemonic.fromString('asdfghjkl qwertyuiop zxcvbnm')
+      }).toThrow()
+    })
+
+    it('should throw on empty string', () => {
+      expect(() => {
+        Mnemonic.fromString('')
+      }).toThrow()
+    })
+
+    it('should throw on valid words but wrong checksum', () => {
+      // 12 valid wordlist entries but checksum will not match
+      expect(() => {
+        Mnemonic.fromString(
+          'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon'
+        )
+      }).toThrow()
+    })
+
+    it('should accept a known-valid BIP-39 phrase', () => {
+      const m = Mnemonic.fromString(
+        'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'
+      )
+      expect(m.mnemonic).toEqual(
+        'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'
+      )
+    })
   })
 
   describe('@isValid', () => {

package/src/kvstore/GlobalKVStore.ts

@@ -89,11 +89,26 @@ export class GlobalKVStore {
     this.config = { ...DEFAULT_CONFIG, ...config }
     this.wallet = config.wallet ?? new WalletClient()
     this.historian = new Historian<string, KVContext>(kvStoreInterpreter)
-    this.lookupResolver = new LookupResolver({
-      networkPreset: this.config.networkPreset
+    // Resolve overlay hosts via, in order of precedence: an injected resolver,
+    // otherwise a default resolver built from `networkPreset` plus any
+    // `hostOverrides` / `slapTrackers`. The same resolver is shared with the
+    // topic broadcaster so read lookups and the broadcaster's SHIP host
+    // discovery both go through it. Note this shares the *lookup* path, not the
+    // broadcast target: writes still go to whatever hosts the `ls_ship` SHIP
+    // lookup returns, so pinning the broadcast backend requires that lookup to
+    // return the desired host (a host override alone does not force it). With no
+    // overrides this is behaviourally identical to the previous
+    // networkPreset-only construction.
+    // `hostOverrides` / `slapTrackers` are passed straight through; LookupResolver
+    // already falls back to its defaults when they're undefined.
+    this.lookupResolver = this.config.lookupResolver ?? new LookupResolver({
+      networkPreset: this.config.networkPreset,
+      hostOverrides: this.config.hostOverrides,
+      slapTrackers: this.config.slapTrackers
     })
     this.topicBroadcaster = new TopicBroadcaster(this.config.topics as string[], {
-      networkPreset: this.config.networkPreset
+      networkPreset: this.config.networkPreset,
+      resolver: this.lookupResolver
     })
   }
 

package/src/kvstore/__tests/GlobalKVStore.test.ts

@@ -264,6 +264,42 @@ describe('GlobalKVStore', () => {
     it('initializes Historian with kvStoreInterpreter', () => {
       expect(MockHistorian).toHaveBeenCalledWith(kvStoreInterpreter)
     })
+
+    it('builds a default resolver from networkPreset and shares it with the broadcaster', () => {
+      MockLookupResolver.mockClear()
+      MockTopicBroadcaster.mockClear()
+      const store = new GlobalKVStore({ wallet: mockWallet, networkPreset: 'testnet' })
+      expect(store).toBeInstanceOf(GlobalKVStore)
+      expect(MockLookupResolver).toHaveBeenCalledWith({ networkPreset: 'testnet' })
+      // The broadcaster must reuse the same resolver so read lookups and the
+      // broadcaster's SHIP host discovery share one lookup path.
+      const broadcasterConfig = MockTopicBroadcaster.mock.calls[0][1] as { resolver?: unknown }
+      expect(broadcasterConfig.resolver).toBe(mockResolver)
+    })
+
+    it('passes hostOverrides and slapTrackers into the default resolver', () => {
+      MockLookupResolver.mockClear()
+      const hostOverrides = { ls_kvstore: ['https://host.example'] }
+      const slapTrackers = ['https://slap.example']
+      const store = new GlobalKVStore({ wallet: mockWallet, hostOverrides, slapTrackers })
+      expect(store).toBeInstanceOf(GlobalKVStore)
+      expect(MockLookupResolver).toHaveBeenCalledWith({
+        networkPreset: 'mainnet',
+        hostOverrides,
+        slapTrackers,
+      })
+    })
+
+    it('uses an injected lookupResolver verbatim and does not build a default one', () => {
+      MockLookupResolver.mockClear()
+      MockTopicBroadcaster.mockClear()
+      const injected = { query: jest.fn() } as unknown as InstanceType<typeof LookupResolver>
+      const store = new GlobalKVStore({ wallet: mockWallet, lookupResolver: injected })
+      expect(store).toBeInstanceOf(GlobalKVStore)
+      expect(MockLookupResolver).not.toHaveBeenCalled()
+      const broadcasterConfig = MockTopicBroadcaster.mock.calls[0][1] as { resolver?: unknown }
+      expect(broadcasterConfig.resolver).toBe(injected)
+    })
   })
 
   // --------------------------------------------------------------------------

package/src/kvstore/types.ts

@@ -1,6 +1,8 @@
 import { Beef } from '../transaction/Beef.js'
 import { PubKeyHex, WalletProtocol } from '../wallet/Wallet.interfaces.js'
 import { WalletInterface } from '../wallet/index.js'
+// Type-only import — erased at runtime, so it introduces no module cycle with overlay-tools.
+import type { LookupResolver } from '../overlay-tools/index.js'
 
 /**
  * Configuration interface for GlobalKVStore operations.
@@ -23,6 +25,32 @@ export interface KVStoreConfig {
   wallet?: WalletInterface
   /** Network preset for overlay services */
   networkPreset?: 'mainnet' | 'testnet' | 'local'
+  /**
+   * A pre-built lookup resolver to use for all overlay queries — both reads and
+   * write-host (SHIP) discovery. When provided, it takes precedence and
+   * `hostOverrides` / `slapTrackers` are ignored for resolver construction.
+   * Use this to fully control overlay host resolution.
+   */
+  lookupResolver?: LookupResolver
+  /**
+   * Per-service overlay host overrides (`serviceName -> hosts`), applied when
+   * the store builds its default lookup resolver. This pins which hosts answer
+   * *lookup* queries for a given service (e.g. read lookups via `ls_kvstore`),
+   * instead of discovering them via SLAP.
+   *
+   * Note this does not by itself pin the *broadcast* target: writes are
+   * submitted to the hosts that the `ls_ship` SHIP lookup returns, so an
+   * `ls_ship` override only changes which tracker answers — the broadcast host
+   * is whatever advertisements that lookup names. To force writes to a specific
+   * backend, use a resolver / SHIP setup whose `ls_ship` results return the
+   * desired host. Ignored when `lookupResolver` is supplied.
+   */
+  hostOverrides?: Record<string, string[]>
+  /**
+   * Override the SLAP trackers used by the default lookup resolver. Ignored when
+   * `lookupResolver` is supplied.
+   */
+  slapTrackers?: string[]
   /** Whether to accept delayed broadcast */
   acceptDelayedBroadcast?: boolean
   /** Whether to let overlay handle broadcasting (prevents UTXO spending on rejection) */

package/src/script/Spend.ts

@@ -1213,7 +1213,14 @@ export default class Spend {
               sig = this.parseChecksigSignature(bufSig)
 
               const scriptForChecksig: Script = this.context === 'UnlockingScript' ? this.unlockingScript : this.lockingScript
-              const scriptCodeChunks = scriptForChecksig.chunks.slice(this.lastCodeSeparator === null ? 0 : this.lastCodeSeparator + 1)
+              let scriptCodeChunks = scriptForChecksig.chunks.slice(this.lastCodeSeparator === null ? 0 : this.lastCodeSeparator + 1)
+              // When an OP_CODESEPARATOR appears in the unlocking script, the CHECKSIG subscript
+              // continues across the unlock/lock boundary into the full locking script (legacy
+              // combined-script semantics; matches BSV node consensus). Without this, signatures
+              // taken over such a subscript (e.g. OP_PUSH_TX-style contracts) are wrongly rejected.
+              if (this.context === 'UnlockingScript') {
+                scriptCodeChunks = scriptCodeChunks.concat(this.lockingScript.chunks)
+              }
               subscript = new Script(scriptCodeChunks)
               subscript.findAndDelete(new Script().writeBin(bufSig))
 

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

@@ -0,0 +1,88 @@
+import PrivateKey from '../../primitives/PrivateKey'
+import { sha256 } from '../../primitives/Hash'
+import Spend from '../../script/Spend'
+import Transaction from '../../transaction/Transaction'
+import TransactionSignature from '../../primitives/TransactionSignature'
+import LockingScript from '../../script/LockingScript'
+import UnlockingScript from '../../script/UnlockingScript'
+import Script from '../../script/Script'
+import OP from '../../script/OP'
+
+/**
+ * Regression test for the CHECKSIG subscript across an OP_CODESEPARATOR in the unlocking script.
+ *
+ * When an OP_CODESEPARATOR is executed in the *unlocking* script and an OP_CHECKSIG then runs
+ * (still in unlocking-script context), the signature's subscript must span from after that
+ * separator across the unlock/lock boundary into the FULL locking script (legacy combined-script
+ * semantics, which BSV nodes enforce). This is the basis of OP_PUSH_TX-style contracts.
+ *
+ * Before the fix, Spend built the subscript from the unlocking script alone, so a signature taken
+ * over <unlock-tail> ++ <locking-script> was rejected ("OP_CHECKSIGVERIFY requires a valid
+ * signature"), even though BSV consensus accepts the transaction.
+ */
+describe('Spend — CHECKSIG subscript across OP_CODESEPARATOR in the unlocking script', () => {
+  it('validates a signature whose subscript spans into the locking script', () => {
+    const priv = new PrivateKey(42)
+    const pub = priv.toPublicKey()
+    const pubEnc = pub.encode(true) as number[]
+    const satoshis = 1000
+    const scope = TransactionSignature.SIGHASH_ALL | TransactionSignature.SIGHASH_FORKID
+
+    // Non-empty locking-script tail that MUST be part of the subscript (proves the concat).
+    const lockingScript = new LockingScript([{ op: OP.OP_NOP }, { op: OP.OP_NOP }])
+
+    // Version 2 -> "relaxed" rules (post-Genesis/Chronicle), so the non-push unlocking script
+    // below is permitted (push-only is only enforced for legacy v1 transactions).
+    const sourceTx = new Transaction(2, [], [{ lockingScript, satoshis }], 0)
+
+    // The subscript the interpreter derives (after findAndDelete removes the signature push):
+    //   <unlock-after-codesep without the sig> ++ <locking script>
+    //   = [ <pubkey> OP_CHECKSIG ] ++ [ OP_NOP OP_NOP ]
+    const subscript = new Script([
+      { op: pubEnc.length, data: pubEnc },
+      { op: OP.OP_CHECKSIG },
+      ...lockingScript.chunks
+    ])
+
+    const preimage = TransactionSignature.formatBytes({
+      sourceTXID: sourceTx.id('hex'),
+      sourceOutputIndex: 0,
+      sourceSatoshis: satoshis,
+      transactionVersion: 2,
+      otherInputs: [],
+      outputs: [],
+      inputIndex: 0,
+      subscript,
+      inputSequence: 0xffffffff,
+      lockTime: 0,
+      scope
+    })
+    const raw = priv.sign(sha256(preimage))
+    const sig = new TransactionSignature(raw.r, raw.s, scope)
+    const sigForScript = sig.toChecksigFormat()
+
+    // Unlocking script: OP_CODESEPARATOR then <sig> <pubkey> OP_CHECKSIG (checksig runs here).
+    const unlockingScript = new UnlockingScript([
+      { op: OP.OP_CODESEPARATOR },
+      { op: sigForScript.length, data: sigForScript },
+      { op: pubEnc.length, data: pubEnc },
+      { op: OP.OP_CHECKSIG }
+    ])
+
+    const spend = new Spend({
+      sourceTXID: sourceTx.id('hex'),
+      sourceOutputIndex: 0,
+      sourceSatoshis: satoshis,
+      lockingScript,
+      transactionVersion: 2,
+      otherInputs: [],
+      inputIndex: 0,
+      unlockingScript,
+      outputs: [],
+      inputSequence: 0xffffffff,
+      lockTime: 0
+    })
+
+    expect(spend.validate()).toBe(true)
+  })
+})

package/src/transaction/BdkVerifierInterface.ts

@@ -0,0 +1,22 @@
+import type Transaction from './Transaction.js'
+
+/**
+ * A pluggable backend that verifies ALL input scripts of a single transaction.
+ *
+ * Implementations (e.g. @bsv/verifast's BdkVerifier) typically delegate to a
+ * native/WASM engine. The backend operates at whole-transaction granularity,
+ * not per input.
+ */
+export default interface BdkVerifierInterface {
+  /**
+   * Verify all input scripts of `params.tx`.
+   * @returns Promise resolving true if every input script is valid, false otherwise.
+   * @throws If the backend itself fails (load error, marshalling error, unavailable).
+   */
+  verifyScripts: (params: {
+    tx: Transaction
+    blockHeight: number
+    consensus: boolean
+    verifyFlags?: string | string[]
+  }) => Promise<boolean>
+}

package/src/transaction/Transaction.ts

@@ -18,6 +18,10 @@ import P2PKH from '../script/templates/P2PKH.js'
 import type { WalletInterface, DescriptionString5to50Bytes, CreateActionOptions } from '../wallet/Wallet.interfaces.js'
 import TransactionSignature from '../primitives/TransactionSignature.js'
 import Random from '../primitives/Random.js'
+import type BdkVerifierInterface from './BdkVerifierInterface.js'
+
+/** Post-Chronicle height used when an input's source UTXO mined-height is unobtainable. */
+const POST_CHRONICLE_HEIGHT_FALLBACK = 943816
 
 /**
  * Represents a complete Bitcoin transaction. This class encapsulates all the details
@@ -833,7 +837,8 @@ export default class Transaction {
   async verify (
     chainTracker: ChainTracker | 'scripts only' = defaultChainTracker(),
     feeModel?: FeeModel,
-    memoryLimit?: number
+    memoryLimit?: number,
+    verifier?: BdkVerifierInterface
   ): Promise<boolean> {
     const verifiedTxids = new Set<string>()
     const txQueue: Transaction[] = [this]
@@ -910,23 +915,41 @@ export default class Transaction {
         const otherInputs = tx.inputs.filter((_, idx) => idx !== i)
         input.sourceTXID ??= sourceTxid
 
-        const spend = new Spend({
-          sourceTXID: input.sourceTXID,
-          sourceOutputIndex: input.sourceOutputIndex,
-          lockingScript: sourceOutput.lockingScript,
-          sourceSatoshis: sourceOutput.satoshis ?? 0,
-          transactionVersion: tx.version,
-          otherInputs,
-          unlockingScript: input.unlockingScript,
-          inputSequence: input.sequence ?? 0xffffffff, // default to max sequence
-          inputIndex: i,
-          outputs: tx.outputs,
-          lockTime: tx.lockTime,
-          memoryLimit
-        })
-        const spendValid = spend.validate()
+        if (verifier === undefined) {
+          const spend = new Spend({
+            sourceTXID: input.sourceTXID,
+            sourceOutputIndex: input.sourceOutputIndex,
+            lockingScript: sourceOutput.lockingScript,
+            sourceSatoshis: sourceOutput.satoshis ?? 0,
+            transactionVersion: tx.version,
+            otherInputs,
+            unlockingScript: input.unlockingScript,
+            inputSequence: input.sequence ?? 0xffffffff, // default to max sequence
+            inputIndex: i,
+            outputs: tx.outputs,
+            lockTime: tx.lockTime,
+            memoryLimit
+          })
+          const spendValid = spend.validate()
+
+          if (!spendValid) {
+            return false
+          }
+        }
+      }
 
-        if (!spendValid) {
+      // When a pluggable verifier is configured, hand the whole transaction to it
+      // once (BDK operates at whole-tx granularity). Strict: its verdict is
+      // authoritative and any thrown error propagates (no JS fallback).
+      if (verifier !== undefined) {
+        // A tx reaching here has no merkle proof (mined txs short-circuit above),
+        // so its source UTXO mined-height is unobtainable -> post-Chronicle fallback.
+        const scriptsValid = await verifier.verifyScripts({
+          tx,
+          blockHeight: POST_CHRONICLE_HEIGHT_FALLBACK,
+          consensus: true
+        })
+        if (!scriptsValid) {
           return false
         }
       }

package/src/transaction/__tests/Transaction.verifier.test.ts

@@ -0,0 +1,72 @@
+import Transaction from '../Transaction'
+import Script from '../../script/Script'
+import P2PKH from '../../script/templates/P2PKH'
+import PrivateKey from '../../primitives/PrivateKey'
+import MerklePath from '../MerklePath'
+import type BdkVerifierInterface from '../BdkVerifierInterface'
+
+// Build a tx whose single P2PKH input is genuinely valid under the pure-JS interpreter.
+async function buildValidTx (): Promise<Transaction> {
+  const key = PrivateKey.fromRandom()
+  const source = new Transaction()
+  source.addInput({
+    sourceTXID: '00'.repeat(32),
+    sourceOutputIndex: 0,
+    unlockingScript: Script.fromASM('OP_TRUE')
+  })
+  source.addOutput({ satoshis: 2, lockingScript: new P2PKH().lock(key.toAddress()) })
+  await source.sign()
+  source.merklePath = new MerklePath(1000, [
+    [{ offset: 0, hash: source.id('hex'), txid: true }, { offset: 1, duplicate: true }]
+  ])
+
+  const tx = new Transaction()
+  tx.addInput({
+    sourceTransaction: source,
+    sourceOutputIndex: 0,
+    unlockingScriptTemplate: new P2PKH().unlock(key)
+  })
+  tx.addOutput({ satoshis: 1, lockingScript: new P2PKH().lock(key.toAddress()) })
+  await tx.sign()
+  return tx
+}
+
+describe('Transaction.verify with a pluggable verifier', () => {
+  it('routes to the verifier and returns its false result, bypassing Spend', async () => {
+    const tx = await buildValidTx()
+    let called = 0
+    const verifier: BdkVerifierInterface = {
+      verifyScripts: async () => { called++; return false }
+    }
+    // Pure-JS would return true; verifier says false -> proves bypass + routing.
+    const result = await tx.verify('scripts only', undefined, undefined, verifier)
+    expect(called).toBe(1)
+    expect(result).toBe(false)
+  })
+
+  it('returns true when the verifier approves', async () => {
+    const tx = await buildValidTx()
+    const verifier: BdkVerifierInterface = { verifyScripts: async () => true }
+    const result = await tx.verify('scripts only', undefined, undefined, verifier)
+    expect(result).toBe(true)
+  })
+
+  it('propagates a verifier throw (strict, no fallback)', async () => {
+    const tx = await buildValidTx()
+    const verifier: BdkVerifierInterface = {
+      verifyScripts: async () => { throw new Error('wasm unavailable') }
+    }
+    await expect(tx.verify('scripts only', undefined, undefined, verifier))
+      .rejects.toThrow('wasm unavailable')
+  })
+
+  it('passes the post-Chronicle fallback blockHeight (943816) to the verifier', async () => {
+    const tx = await buildValidTx() // unmined tx -> no merkle proof -> fallback height
+    let seenHeight = -1
+    const verifier: BdkVerifierInterface = {
+      verifyScripts: async ({ blockHeight }) => { seenHeight = blockHeight; return true }
+    }
+    await tx.verify('scripts only', undefined, undefined, verifier)
+    expect(seenHeight).toBe(943816)
+  })
+})

package/src/transaction/index.ts

@@ -1,4 +1,5 @@
 export { default as Transaction } from './Transaction.js'
+export type { default as BdkVerifierInterface } from './BdkVerifierInterface.js'
 export { default as MerklePath } from './MerklePath.js'
 export type { default as TransactionInput } from './TransactionInput.js'
 export type { default as TransactionOutput } from './TransactionOutput.js'