@bsv/sdk 1.9.2 → 1.9.4

package/docs/index.md

@@ -2,71 +2,76 @@
 
 ## SDK Overview
 
-The BSV TypeScript SDK is designed to provide an updated and unified layer for developing scalable applications on the BSV Blockchain. It addresses the limitations of previous tools by offering a fresh, peer-to-peer approach, adhering to SPV principles, and ensuring privacy and scalability.
+The BSV TypeScript SDK is designed to provide an updated and unified layer for developing scalable applications on the BSV Blockchain. It addresses the limitations of previous tools by offering a Direct Instant Payments (DIP) approach, ensuring privacy and scalability.
 
-This documentation is organized to help you learn, solve problems, understand concepts, and find technical references.
+## Installation
 
-## Documentation Categories
+To install the SDK, run:
 
-### [🚀 Tutorials](./tutorials/index.md)
+```bash
+npm install @bsv/sdk
+```
 
-Learn step-by-step with practical, guided examples:
+You can then import modules from the SDK as follows:
 
-- [Your First BSV Transaction](./tutorials/first-transaction.md)
-- [Key Management and Cryptography](./tutorials/key-management.md)
-- [Transaction Broadcasting and ARC](./tutorials/transaction-broadcasting.md)
-- [View all tutorials →](./tutorials/index.md)
+```ts
+import { WalletClient, PrivateKey, Transaction } from "@bsv/sdk";
+```
 
-### [🔧 How-To Guides](./guides/index.md)
+Or using require syntax:
 
-Problem-oriented guides for specific tasks:
+```js
+const { WalletClient, PrivateKey, Transaction } = require("@bsv/sdk");
+```
 
-- [Creating Multi-signature Transactions](./guides/multisig-transactions.md)
-- [Implementing Transaction Batching](./guides/transaction-batching.md)
-- [Configuring Custom ARC Endpoints](./guides/custom-arc-endpoints.md)
-- [View all guides →](./guides/index.md)
 
-### [📚 Reference](./reference/index.md)
+## BRC-100 Application to Wallet Interface
 
-Complete technical specifications and API documentation:
+This interface is what most application developers will use to interact with the BSV blockchain.
 
-- [BRC-100 Wallet Interface (Swagger)](./reference/brc-100.md)
-- [Primitives](./reference/primitives.md)
-- [Script](./reference/script.md)
-- [Transaction](./reference/transaction.md)
-- [View all references →](./reference/index.md)
+🚀 **[WalletClient Quickstart](https://fast.brc.dev/)**
 
-### [🏗️ Concepts & Explanations](./concepts/index.md)
+- Run SDK code examples without any setup
+- Experiment with transactions, keys, and scripts in real-time  
+- Learn by doing with immediate feedback
+- Test concepts from our tutorials interactively
 
-Understanding the architecture and design principles:
+[![alt text](fast-docs.png)](https://fast.brc.dev/)
 
-- [SDK Design Philosophy](./concepts/sdk-philosophy.md)
-- [Transaction Structure](./concepts/transaction-structure.md)
-- [SPV Verification](./concepts/spv-verification.md)
-- [BEEF Format](./concepts/beef.md)
-- [View all concepts →](./concepts/index.md)
+Perfect for getting started quickly or experimenting with new ideas.
 
-## Getting Started
+Another way to familiarize yourself with the Application to Wallet Interface is to checkout this Swagger UI.
 
-If you're new to the BSV TypeScript SDK, we recommend starting with our [Getting Started Tutorial](./tutorials/first-transaction.md).
+[![Swagger](swagger.png)](./swagger/index.html)
 
-## Try It Interactive
+Finally, you can deep dive into the details of the interface and types in the reference material below.
 
-🚀 **[Interactive BSV Coding Environment](https://fast.brc.dev/)**
+## Reference Material
 
-Experience the BSV TypeScript SDK directly in your browser! Our interactive coding environment lets you:
+- [Wallet](./reference/wallet.md)
+- [Primitives](./reference/primitives.md)
+- [Script](./reference/script.md)
+- [Transaction](./reference/transaction.md)
+- [Mutual Authenitcation](./reference/auth.md)
+- [Identity](./reference/identity.md)
+- [Overlay Tools](./reference/overlay-tools.md)
+- [Registry](./reference/registry.md)
+- [Storage](./reference/storage.md)
+- [KV Store](./reference/kvstore.md)
+- [Messages](./reference/messages.md)
+- [TOTP](./reference/totp.md)
+- [Compatibility](./reference/compat.md)
 
-- Run SDK code examples without any setup
-- Experiment with transactions, keys, and scripts in real-time  
-- Learn by doing with immediate feedback
-- Test concepts from our tutorials interactively
 
-Perfect for getting started quickly or experimenting with new ideas.
+## Coming Soon™
 
-## Installation
+- [Manual Transaction Creation](#manual-transaction-creation)
+- [Broadcasting Transactions](#broadcasting-transactions)
+- [Deriving Keys](#deriving-keys)
+- [Overlays](#overlays)
+- [MessageBox](#message-box)
 
-To install the SDK, run:
 
-```bash
-npm install @bsv/sdk
-```
+## Performance Reports
+
+- [Benchmarks](./performance.md)

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.4",
   "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')
+}