Merge pull request #381 from bsv-blockchain/feature/globalKVStore-withDoubleSpendRetry

Feature/global kv store with double spend retry

Author: BraydenLangley

CHANGELOG.md

@@ -5,6 +5,7 @@ All notable changes to this project will be documented in this file. The format
 ## Table of Contents
 
 - [Unreleased](#unreleased)
+- [1.9.3 - 2025-11-11](#193---2025-11-11)
 - [1.9.2 - 2025-11-11](#192---2025-11-11)
 - [1.9.1 - 2025-11-10](#191---2025-11-10)
 - [1.9.0 - 2025-11-09](#190---2025-11-09)
@@ -176,6 +177,15 @@ All notable changes to this project will be documented in this file. The format
 
 ---
 
+### [1.9.3] - 2025-11-11
+
+### Added
+
+- Added `withDoubleSpendRetry` overlay tool to retry broadcast with resolved competing transactions.
+- Updated GlobalKVStore to use `withDoubleSpendRetry` in set/remove operations.
+
+---
+
 ### [1.9.2] - 2025-11-11
 
 ### Fixed

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

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-lock.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",