@bsv/sdk 1.9.2 → 1.9.3

package/docs/reference/kvstore.md

@@ -50,6 +50,7 @@ export interface KVStoreConfig {
     wallet?: WalletInterface;
     networkPreset?: "mainnet" | "testnet" | "local";
     acceptDelayedBroadcast?: boolean;
+    overlayBroadcast?: boolean;
     tokenSetDescription?: string;
     tokenUpdateDescription?: string;
     tokenRemovalDescription?: string;
@@ -82,6 +83,14 @@ Originator
 originator?: string
 ```
 
+#### Property overlayBroadcast
+
+Whether to let overlay handle broadcasting (prevents UTXO spending on rejection)
+
+```ts
+overlayBroadcast?: boolean
+```
+
 #### Property overlayHost
 
 The overlay service host URL

package/docs/reference/overlay-tools.md

@@ -564,6 +564,38 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ---
 ## Functions
 
+### Function: withDoubleSpendRetry
+
+Executes an operation with automatic retry logic for double-spend errors.
+When a double-spend is detected, broadcasts the competing transaction to
+update the overlay with missing state, then retries the operation.
+
+```ts
+export async function withDoubleSpendRetry<T>(operation: () => Promise<T>, broadcaster: TopicBroadcaster, maxRetries: number = MAX_DOUBLE_SPEND_RETRIES): Promise<T> 
+```
+
+See also: [TopicBroadcaster](./overlay-tools.md#class-topicbroadcaster)
+
+Returns
+
+The result of the successful operation
+
+Argument Details
+
++ **operation**
+  + The async operation to execute (e.g., createAction + signAction)
++ **broadcaster**
+  + The TopicBroadcaster to use for syncing missing state
++ **maxRetries**
+  + Maximum number of retry attempts (default: MAX_DOUBLE_SPEND_RETRIES)
+
+Throws
+
+If max retries exceeded or non-double-spend error occurs
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
 ## Types
 
 | |

package/package.json

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

package/src/kvstore/GlobalKVStore.ts

@@ -1,6 +1,6 @@
 import Transaction from '../transaction/Transaction.js'
 import * as Utils from '../primitives/utils.js'
-import { TopicBroadcaster, LookupResolver } from '../overlay-tools/index.js'
+import { TopicBroadcaster, LookupResolver, withDoubleSpendRetry } from '../overlay-tools/index.js'
 import { BroadcastResponse, BroadcastFailure } from '../transaction/Broadcaster.js'
 import { WalletInterface, WalletProtocol, CreateActionInput, OutpointString, PubKeyHex, CreateActionOutput, HexString } from '../wallet/Wallet.interfaces.js'
 import { PushDrop } from '../script/index.js'
@@ -22,6 +22,7 @@ const DEFAULT_CONFIG: KVStoreConfig = {
   topics: ['tm_kvstore'],
   networkPreset: 'mainnet',
   acceptDelayedBroadcast: false,
+  overlayBroadcast: false, // Use overlay broadcasting to prevent UTXO spending on broadcast rejection.
   tokenSetDescription: '', // Will be set dynamically
   tokenUpdateDescription: '', // Will be set dynamically
   tokenRemovalDescription: '' // Will be set dynamically
@@ -141,11 +142,7 @@ export class GlobalKVStore {
     const tags = options.tags ?? []
 
     try {
-      // Check for existing token to spend
-      const existingEntries = await this.queryOverlay({ key, controller }, { includeToken: true })
-      const existingToken = existingEntries.length > 0 ? existingEntries[0].token : undefined
-
-      // Create PushDrop locking script
+      // Create PushDrop locking script (reusable across retries)
       const pushdrop = new PushDrop(this.wallet, this.config.originator)
       const lockingScriptFields = [
         Utils.toArray(JSON.stringify(protocolID), 'utf8'),
@@ -167,82 +164,92 @@ export class GlobalKVStore {
         true
       )
 
-      let inputs: CreateActionInput[] = []
-      let inputBEEF: Beef | undefined
-
-      if (existingToken != null) {
-        inputs = [{
-          outpoint: `${existingToken.txid}.${existingToken.outputIndex}`,
-          unlockingScriptLength: 74,
-          inputDescription: 'Previous KVStore token'
-        }]
-        inputBEEF = existingToken.beef
-      }
-
-      if (inputs.length > 0) {
-        // Update existing token
-        const { signableTransaction } = await this.wallet.createAction({
-          description: tokenUpdateDescription,
-          inputBEEF: inputBEEF?.toBinary(),
-          inputs,
-          outputs: [{
-            satoshis: tokenAmount ?? this.config.tokenAmount as number,
-            lockingScript: lockingScript.toHex(),
-            outputDescription: 'KVStore token'
-          }],
-          options: {
-            acceptDelayedBroadcast: this.config.acceptDelayedBroadcast,
-            randomizeOutputs: false
+      // Wrap entire operation in double-spend retry, including overlay query
+      const outpoint = await withDoubleSpendRetry(async () => {
+        // Re-query overlay on each attempt to get fresh token state
+        const existingEntries = await this.queryOverlay({ key, controller }, { includeToken: true })
+        const existingToken = existingEntries.length > 0 ? existingEntries[0].token : undefined
+
+        if (existingToken != null) {
+          // Update existing token
+          const inputs: CreateActionInput[] = [{
+            outpoint: `${existingToken.txid}.${existingToken.outputIndex}`,
+            unlockingScriptLength: 74,
+            inputDescription: 'Previous KVStore token'
+          }]
+          const inputBEEF = existingToken.beef
+
+          const { signableTransaction } = await this.wallet.createAction({
+            description: tokenUpdateDescription,
+            inputBEEF: inputBEEF.toBinary(),
+            inputs,
+            outputs: [{
+              satoshis: tokenAmount ?? this.config.tokenAmount as number,
+              lockingScript: lockingScript.toHex(),
+              outputDescription: 'KVStore token'
+            }],
+            options: {
+              acceptDelayedBroadcast: this.config.acceptDelayedBroadcast,
+              noSend: this.config.overlayBroadcast,
+              randomizeOutputs: false
+            }
+          }, this.config.originator)
+
+          if (signableTransaction == null) {
+            throw new Error('Unable to create update transaction')
           }
-        }, this.config.originator)
-
-        if (signableTransaction == null) {
-          throw new Error('Unable to create update transaction')
-        }
-
-        const tx = Transaction.fromAtomicBEEF(signableTransaction.tx)
-        const unlocker = pushdrop.unlock(
-          this.config.protocolID as WalletProtocol,
-          key,
-          'anyone'
-        )
-        const unlockingScript = await unlocker.sign(tx, 0)
 
-        const { tx: finalTx } = await this.wallet.signAction({
-          reference: signableTransaction.reference,
-          spends: { 0: { unlockingScript: unlockingScript.toHex() } }
-        }, this.config.originator)
-
-        if (finalTx == null) {
-          throw new Error('Unable to finalize update transaction')
-        }
+          const tx = Transaction.fromAtomicBEEF(signableTransaction.tx)
+          const unlocker = pushdrop.unlock(
+            this.config.protocolID as WalletProtocol,
+            key,
+            'anyone'
+          )
+          const unlockingScript = await unlocker.sign(tx, 0)
+
+          const { tx: finalTx } = await this.wallet.signAction({
+            reference: signableTransaction.reference,
+            spends: { 0: { unlockingScript: unlockingScript.toHex() } },
+            options: {
+              acceptDelayedBroadcast: this.config.acceptDelayedBroadcast,
+              noSend: this.config.overlayBroadcast
+            }
+          }, this.config.originator)
+
+          if (finalTx == null) {
+            throw new Error('Unable to finalize update transaction')
+          }
 
-        const transaction = Transaction.fromAtomicBEEF(finalTx)
-        await this.submitToOverlay(transaction)
-        return `${transaction.id('hex')}.0`
-      } else {
-        // Create new token
-        const { tx } = await this.wallet.createAction({
-          description: tokenSetDescription,
-          outputs: [{
-            satoshis: tokenAmount ?? this.config.tokenAmount as number,
-            lockingScript: lockingScript.toHex(),
-            outputDescription: 'KVStore token'
-          }],
-          options: {
-            acceptDelayedBroadcast: this.config.acceptDelayedBroadcast,
-            randomizeOutputs: false
+          const transaction = Transaction.fromAtomicBEEF(finalTx)
+          await this.submitToOverlay(transaction)
+          return `${transaction.id('hex')}.0`
+        } else {
+          // Create new token
+          const { tx } = await this.wallet.createAction({
+            description: tokenSetDescription,
+            outputs: [{
+              satoshis: tokenAmount ?? this.config.tokenAmount as number,
+              lockingScript: lockingScript.toHex(),
+              outputDescription: 'KVStore token'
+            }],
+            options: {
+              acceptDelayedBroadcast: this.config.acceptDelayedBroadcast,
+              noSend: this.config.overlayBroadcast,
+              randomizeOutputs: false
+            }
+          }, this.config.originator)
+
+          if (tx == null) {
+            throw new Error('Failed to create transaction')
           }
-        }, this.config.originator)
 
-        if (tx == null) {
-          throw new Error('Failed to create transaction')
+          const transaction = Transaction.fromAtomicBEEF(tx)
+          await this.submitToOverlay(transaction)
+          return `${transaction.id('hex')}.0`
         }
+      }, this.topicBroadcaster)
 
-        const transaction = Transaction.fromAtomicBEEF(tx)
-        await this.submitToOverlay(transaction)
-        return `${transaction.id('hex')}.0`
-      }
+      return outpoint
     } finally {
       if (lockQueue.length > 0) {
         this.finishOperationOnKey(key, lockQueue)
@@ -274,54 +281,67 @@ export class GlobalKVStore {
     const tokenRemovalDescription = (options.tokenRemovalDescription != null && options.tokenRemovalDescription !== '') ? options.tokenRemovalDescription : `Remove KVStore value for ${key}`
 
     try {
-      const existingEntries = await this.queryOverlay({ key, controller }, { includeToken: true })
+      const pushdrop = new PushDrop(this.wallet, this.config.originator)
 
-      if (existingEntries.length === 0 || existingEntries[0].token == null) {
-        throw new Error('The item did not exist, no item was deleted.')
-      }
+      // Remove token with double-spend retry
+      const txid = await withDoubleSpendRetry(async () => {
+        // Re-query overlay on each attempt to get fresh token state
+        const existingEntries = await this.queryOverlay({ key, controller }, { includeToken: true })
 
-      const existingToken = existingEntries[0].token
-      const inputs: CreateActionInput[] = [{
-        outpoint: `${existingToken.txid}.${existingToken.outputIndex}`,
-        unlockingScriptLength: 74,
-        inputDescription: 'KVStore token to remove'
-      }]
+        if (existingEntries.length === 0 || existingEntries[0].token == null) {
+          throw new Error('The item did not exist, no item was deleted.')
+        }
 
-      const pushdrop = new PushDrop(this.wallet, this.config.originator)
-      const { signableTransaction } = await this.wallet.createAction({
-        description: tokenRemovalDescription,
-        inputBEEF: existingToken.beef.toBinary(),
-        inputs,
-        outputs,
-        options: {
-          acceptDelayedBroadcast: this.config.acceptDelayedBroadcast
+        const existingToken = existingEntries[0].token
+        const inputs: CreateActionInput[] = [{
+          outpoint: `${existingToken.txid}.${existingToken.outputIndex}`,
+          unlockingScriptLength: 74,
+          inputDescription: 'KVStore token to remove'
+        }]
+
+        const { signableTransaction } = await this.wallet.createAction({
+          description: tokenRemovalDescription,
+          inputBEEF: existingToken.beef.toBinary(),
+          inputs,
+          outputs,
+          options: {
+            acceptDelayedBroadcast: this.config.acceptDelayedBroadcast,
+            randomizeOutputs: false,
+            noSend: this.config.overlayBroadcast
+          }
+        }, this.config.originator)
+
+        if (signableTransaction == null) {
+          throw new Error('Unable to create removal transaction')
         }
-      }, this.config.originator)
 
-      if (signableTransaction == null) {
-        throw new Error('Unable to create removal transaction')
-      }
+        const tx = Transaction.fromAtomicBEEF(signableTransaction.tx)
+        const unlocker = pushdrop.unlock(
+          protocolID ?? this.config.protocolID as WalletProtocol,
+          key,
+          'anyone'
+        )
+        const unlockingScript = await unlocker.sign(tx, 0)
 
-      const tx = Transaction.fromAtomicBEEF(signableTransaction.tx)
-      const unlocker = pushdrop.unlock(
-        protocolID ?? this.config.protocolID as WalletProtocol,
-        key,
-        'anyone'
-      )
-      const unlockingScript = await unlocker.sign(tx, 0)
+        const { tx: finalTx } = await this.wallet.signAction({
+          reference: signableTransaction.reference,
+          spends: { 0: { unlockingScript: unlockingScript.toHex() } },
+          options: {
+            acceptDelayedBroadcast: this.config.acceptDelayedBroadcast,
+            noSend: this.config.overlayBroadcast
+          }
+        }, this.config.originator)
 
-      const { tx: finalTx } = await this.wallet.signAction({
-        reference: signableTransaction.reference,
-        spends: { 0: { unlockingScript: unlockingScript.toHex() } }
-      }, this.config.originator)
+        if (finalTx == null) {
+          throw new Error('Unable to finalize removal transaction')
+        }
 
-      if (finalTx == null) {
-        throw new Error('Unable to finalize removal transaction')
-      }
+        const transaction = Transaction.fromAtomicBEEF(finalTx)
+        await this.submitToOverlay(transaction)
+        return transaction.id('hex')
+      }, this.topicBroadcaster)
 
-      const transaction = Transaction.fromAtomicBEEF(finalTx)
-      await this.submitToOverlay(transaction)
-      return transaction.id('hex')
+      return txid
     } finally {
       if (lockQueue.length > 0) {
         this.finishOperationOnKey(key, lockQueue)

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

@@ -18,7 +18,17 @@ jest.mock('../../overlay-tools/Historian.js')
 jest.mock('../kvStoreInterpreter.js')
 jest.mock('../../script/index.js')
 jest.mock('../../primitives/utils.js')
-jest.mock('../../overlay-tools/index.js')
+jest.mock('../../overlay-tools/index.js', () => {
+  const actual = jest.requireActual('../../overlay-tools/index.js')
+  return {
+    ...actual,
+    // Keep withDoubleSpendRetry as the real implementation
+    withDoubleSpendRetry: actual.withDoubleSpendRetry,
+    // Mock the classes
+    TopicBroadcaster: jest.fn(),
+    LookupResolver: jest.fn()
+  }
+})
 jest.mock('../../wallet/ProtoWallet.js')
 jest.mock('../../wallet/WalletClient.js')
 

package/src/kvstore/types.ts

@@ -25,6 +25,8 @@ export interface KVStoreConfig {
   networkPreset?: 'mainnet' | 'testnet' | 'local'
   /** Whether to accept delayed broadcast */
   acceptDelayedBroadcast?: boolean
+  /** Whether to let overlay handle broadcasting (prevents UTXO spending on rejection) */
+  overlayBroadcast?: boolean
   /** Description for token set */
   tokenSetDescription?: string
   /** Description for token update */

package/src/overlay-tools/index.ts

@@ -1,5 +1,6 @@
 export * from './LookupResolver.js'
 export * from './SHIPBroadcaster.js'
+export * from './withDoubleSpendRetry.js'
 export { default as OverlayAdminTokenTemplate } from './OverlayAdminTokenTemplate.js'
 export { default as LookupResolver } from './LookupResolver.js'
 

package/src/overlay-tools/withDoubleSpendRetry.ts

@@ -0,0 +1,71 @@
+import Transaction from '../transaction/Transaction.js'
+import { WERR_REVIEW_ACTIONS } from '../wallet/WERR_REVIEW_ACTIONS.js'
+import { ReviewActionResult } from '../wallet/Wallet.interfaces.js'
+import TopicBroadcaster from './SHIPBroadcaster.js'
+
+/**
+ * Maximum number of retry attempts for double-spend resolution
+ */
+const MAX_DOUBLE_SPEND_RETRIES = 5
+
+/**
+ * Executes an operation with automatic retry logic for double-spend errors.
+ * When a double-spend is detected, broadcasts the competing transaction to
+ * update the overlay with missing state, then retries the operation.
+ *
+ * @param operation - The async operation to execute (e.g., createAction + signAction)
+ * @param broadcaster - The TopicBroadcaster to use for syncing missing state
+ * @param maxRetries - Maximum number of retry attempts (default: MAX_DOUBLE_SPEND_RETRIES)
+ * @returns The result of the successful operation
+ * @throws If max retries exceeded or non-double-spend error occurs
+ */
+export async function withDoubleSpendRetry<T> (
+  operation: () => Promise<T>,
+  broadcaster: TopicBroadcaster,
+  maxRetries: number = MAX_DOUBLE_SPEND_RETRIES
+): Promise<T> {
+  let attempts = 0
+
+  while (attempts < maxRetries) {
+    attempts++
+
+    try {
+      return await operation()
+    } catch (error) {
+      // Only handle double-spend errors on non-final attempts
+      if (attempts < maxRetries && error.name === 'WERR_REVIEW_ACTIONS') {
+        const reviewError = error as WERR_REVIEW_ACTIONS
+
+        // Check if any action in the batch has a double-spend
+        const doubleSpendResult = reviewError.reviewActionResults.find(
+          (result: ReviewActionResult) => result.status === 'doubleSpend'
+        )
+
+        if (doubleSpendResult?.competingBeef != null &&
+          doubleSpendResult?.competingTxs != null &&
+          doubleSpendResult?.competingTxs.length > 0) {
+          const competingTx = Transaction.fromBEEF(
+            doubleSpendResult.competingBeef,
+            doubleSpendResult.competingTxs[0]
+          )
+
+          // Recursively handle double-spend errors during broadcast
+          // The broadcast itself might fail if the competing tx depends on another missing tx
+          await withDoubleSpendRetry(
+            async () => await broadcaster.broadcast(competingTx),
+            broadcaster,
+            maxRetries - attempts // Reduce max retries based on attempts already used
+          )
+
+          continue
+        }
+      }
+
+      // Non-double-spend error or max retries exceeded - rethrow
+      throw error
+    }
+  }
+
+  // This should never be reached, but TypeScript requires it
+  throw new Error('Unexpected end of retry loop')
+}