@bsv/sdk 1.7.7 → 1.8.1

package/docs/reference/script.md

@@ -218,21 +218,15 @@ export default class PushDrop implements ScriptTemplate {
         fields: number[][];
     } 
     constructor(wallet: WalletInterface, originator?: string) 
-    async lock(fields: number[][], protocolID: [
-        SecurityLevel,
-        string
-    ], keyID: string, counterparty: string, forSelf = false, includeSignature = true, lockPosition: "before" | "after" = "before"): Promise<LockingScript> 
-    unlock(protocolID: [
-        SecurityLevel,
-        string
-    ], keyID: string, counterparty: string, signOutputs: "all" | "none" | "single" = "all", anyoneCanPay = false, sourceSatoshis?: number, lockingScript?: LockingScript): {
+    async lock(fields: number[][], protocolID: WalletProtocol, keyID: string, counterparty: string, forSelf = false, includeSignature = true, lockPosition: "before" | "after" = "before"): Promise<LockingScript> 
+    unlock(protocolID: WalletProtocol, keyID: string, counterparty: string, signOutputs: "all" | "none" | "single" = "all", anyoneCanPay = false, sourceSatoshis?: number, lockingScript?: LockingScript): {
         sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>;
         estimateLength: () => Promise<73>;
     } 
 }
 ```
 
-See also: [LockingScript](./script.md#class-lockingscript), [PublicKey](./primitives.md#class-publickey), [ScriptTemplate](./script.md#interface-scripttemplate), [SecurityLevel](./wallet.md#type-securitylevel), [Transaction](./transaction.md#class-transaction), [UnlockingScript](./script.md#class-unlockingscript), [WalletInterface](./wallet.md#interface-walletinterface), [sign](./compat.md#variable-sign)
+See also: [LockingScript](./script.md#class-lockingscript), [PublicKey](./primitives.md#class-publickey), [ScriptTemplate](./script.md#interface-scripttemplate), [Transaction](./transaction.md#class-transaction), [UnlockingScript](./script.md#class-unlockingscript), [WalletInterface](./wallet.md#interface-walletinterface), [WalletProtocol](./wallet.md#type-walletprotocol), [sign](./compat.md#variable-sign)
 
 #### Constructor
 
@@ -277,12 +271,9 @@ Argument Details
 Creates a PushDrop locking script with arbitrary data fields and a public key lock.
 
 ```ts
-async lock(fields: number[][], protocolID: [
-    SecurityLevel,
-    string
-], keyID: string, counterparty: string, forSelf = false, includeSignature = true, lockPosition: "before" | "after" = "before"): Promise<LockingScript> 
+async lock(fields: number[][], protocolID: WalletProtocol, keyID: string, counterparty: string, forSelf = false, includeSignature = true, lockPosition: "before" | "after" = "before"): Promise<LockingScript> 
 ```
-See also: [LockingScript](./script.md#class-lockingscript), [SecurityLevel](./wallet.md#type-securitylevel)
+See also: [LockingScript](./script.md#class-lockingscript), [WalletProtocol](./wallet.md#type-walletprotocol)
 
 Returns
 
@@ -308,15 +299,12 @@ Argument Details
 Creates an unlocking script for spending a PushDrop token output.
 
 ```ts
-unlock(protocolID: [
-    SecurityLevel,
-    string
-], keyID: string, counterparty: string, signOutputs: "all" | "none" | "single" = "all", anyoneCanPay = false, sourceSatoshis?: number, lockingScript?: LockingScript): {
+unlock(protocolID: WalletProtocol, keyID: string, counterparty: string, signOutputs: "all" | "none" | "single" = "all", anyoneCanPay = false, sourceSatoshis?: number, lockingScript?: LockingScript): {
     sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>;
     estimateLength: () => Promise<73>;
 } 
 ```
-See also: [LockingScript](./script.md#class-lockingscript), [SecurityLevel](./wallet.md#type-securitylevel), [Transaction](./transaction.md#class-transaction), [UnlockingScript](./script.md#class-unlockingscript), [sign](./compat.md#variable-sign)
+See also: [LockingScript](./script.md#class-lockingscript), [Transaction](./transaction.md#class-transaction), [UnlockingScript](./script.md#class-unlockingscript), [WalletProtocol](./wallet.md#type-walletprotocol), [sign](./compat.md#variable-sign)
 
 Returns
 

package/docs/reference/transaction.md

@@ -456,6 +456,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | [BeefParty](#class-beefparty) |
 | [BeefTx](#class-beeftx) |
 | [FetchHttpClient](#class-fetchhttpclient) |
+| [LivePolicy](#class-livepolicy) |
 | [MerklePath](#class-merklepath) |
 | [NodejsHttpClient](#class-nodejshttpclient) |
 | [SatoshisPerKilobyte](#class-satoshisperkilobyte) |
@@ -1198,6 +1199,74 @@ See also: [Fetch](./transaction.md#type-fetch), [HttpClient](./transaction.md#in
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
+---
+### Class: LivePolicy
+
+Represents a live fee policy that fetches current rates from ARC GorillaPool.
+Extends SatoshisPerKilobyte to reuse transaction size calculation logic.
+
+```ts
+export default class LivePolicy extends SatoshisPerKilobyte {
+    constructor(cacheValidityMs: number = 5 * 60 * 1000) 
+    static getInstance(cacheValidityMs: number = 5 * 60 * 1000): LivePolicy 
+    async computeFee(tx: Transaction): Promise<number> 
+}
+```
+
+See also: [SatoshisPerKilobyte](./transaction.md#class-satoshisperkilobyte), [Transaction](./transaction.md#class-transaction)
+
+#### Constructor
+
+Constructs an instance of the live policy fee model.
+
+```ts
+constructor(cacheValidityMs: number = 5 * 60 * 1000) 
+```
+
+Argument Details
+
++ **cacheValidityMs**
+  + How long to cache the fee rate in milliseconds (default: 5 minutes)
+
+#### Method computeFee
+
+Computes the fee for a given transaction using the current live rate.
+Overrides the parent method to use dynamic rate fetching.
+
+```ts
+async computeFee(tx: Transaction): Promise<number> 
+```
+See also: [Transaction](./transaction.md#class-transaction)
+
+Returns
+
+The fee in satoshis for the transaction.
+
+Argument Details
+
++ **tx**
+  + The transaction for which a fee is to be computed.
+
+#### Method getInstance
+
+Gets the singleton instance of LivePolicy to ensure cache sharing across the application.
+
+```ts
+static getInstance(cacheValidityMs: number = 5 * 60 * 1000): LivePolicy 
+```
+See also: [LivePolicy](./transaction.md#class-livepolicy)
+
+Returns
+
+The singleton LivePolicy instance
+
+Argument Details
+
++ **cacheValidityMs**
+  + How long to cache the fee rate in milliseconds (default: 5 minutes)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
 ---
 ### Class: MerklePath
 
@@ -1520,7 +1589,7 @@ export default class Transaction {
     addOutput(output: TransactionOutput): void 
     addP2PKHOutput(address: number[] | string, satoshis?: number): void 
     updateMetadata(metadata: Record<string, any>): void 
-    async fee(modelOrFee: FeeModel | number = new SatoshisPerKilobyte(1), changeDistribution: "equal" | "random" = "equal"): Promise<void> 
+    async fee(modelOrFee: FeeModel | number = LivePolicy.getInstance(), changeDistribution: "equal" | "random" = "equal"): Promise<void> 
     getFee(): number 
     async sign(): Promise<void> 
     async broadcast(broadcaster: Broadcaster = defaultBroadcaster()): Promise<BroadcastResponse | BroadcastFailure> 
@@ -1540,7 +1609,7 @@ export default class Transaction {
 }
 ```
 
-See also: [BroadcastFailure](./transaction.md#interface-broadcastfailure), [BroadcastResponse](./transaction.md#interface-broadcastresponse), [Broadcaster](./transaction.md#interface-broadcaster), [ChainTracker](./transaction.md#interface-chaintracker), [FeeModel](./transaction.md#interface-feemodel), [MerklePath](./transaction.md#class-merklepath), [Reader](./primitives.md#class-reader), [SatoshisPerKilobyte](./transaction.md#class-satoshisperkilobyte), [TransactionInput](./transaction.md#interface-transactioninput), [TransactionOutput](./transaction.md#interface-transactionoutput), [defaultBroadcaster](./transaction.md#function-defaultbroadcaster), [defaultChainTracker](./transaction.md#function-defaultchaintracker), [sign](./compat.md#variable-sign), [toHex](./primitives.md#variable-tohex), [verify](./compat.md#variable-verify)
+See also: [BroadcastFailure](./transaction.md#interface-broadcastfailure), [BroadcastResponse](./transaction.md#interface-broadcastresponse), [Broadcaster](./transaction.md#interface-broadcaster), [ChainTracker](./transaction.md#interface-chaintracker), [FeeModel](./transaction.md#interface-feemodel), [LivePolicy](./transaction.md#class-livepolicy), [MerklePath](./transaction.md#class-merklepath), [Reader](./primitives.md#class-reader), [TransactionInput](./transaction.md#interface-transactioninput), [TransactionOutput](./transaction.md#interface-transactionoutput), [defaultBroadcaster](./transaction.md#function-defaultbroadcaster), [defaultChainTracker](./transaction.md#function-defaultchaintracker), [sign](./compat.md#variable-sign), [toHex](./primitives.md#variable-tohex), [verify](./compat.md#variable-verify)
 
 #### Method addInput
 
@@ -1610,13 +1679,13 @@ Argument Details
 #### Method fee
 
 Computes fees prior to signing.
-If no fee model is provided, uses a SatoshisPerKilobyte fee model that pays 1 sat/kb.
+If no fee model is provided, uses a LivePolicy fee model that fetches current rates from ARC.
 If fee is a number, the transaction uses that value as fee.
 
 ```ts
-async fee(modelOrFee: FeeModel | number = new SatoshisPerKilobyte(1), changeDistribution: "equal" | "random" = "equal"): Promise<void> 
+async fee(modelOrFee: FeeModel | number = LivePolicy.getInstance(), changeDistribution: "equal" | "random" = "equal"): Promise<void> 
 ```
-See also: [FeeModel](./transaction.md#interface-feemodel), [SatoshisPerKilobyte](./transaction.md#class-satoshisperkilobyte)
+See also: [FeeModel](./transaction.md#interface-feemodel), [LivePolicy](./transaction.md#class-livepolicy)
 
 Argument Details
 
@@ -2037,7 +2106,7 @@ Argument Details
 Example
 
 ```ts
-tx.verify(new WhatsOnChain(), new SatoshisPerKilobyte(1))
+tx.verify(new WhatsOnChain(), LivePolicy.getInstance())
 ```
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)

package/docs/reference/wallet.md

@@ -2629,7 +2629,7 @@ The SDK is how applications communicate with wallets over a communications subst
 export default class WalletClient implements WalletInterface {
     public substrate: "auto" | WalletInterface;
     originator?: OriginatorDomainNameStringUnder250Bytes;
-    constructor(substrate: "auto" | "Cicada" | "XDM" | "window.CWI" | "json-api" | "react-native" | WalletInterface = "auto", originator?: OriginatorDomainNameStringUnder250Bytes) 
+    constructor(substrate: "auto" | "Cicada" | "XDM" | "window.CWI" | "json-api" | "react-native" | "secure-json-api" | WalletInterface = "auto", originator?: OriginatorDomainNameStringUnder250Bytes) 
     async connectToSubstrate(): Promise<void> 
     async createAction(args: CreateActionArgs): Promise<CreateActionResult> 
     async signAction(args: SignActionArgs): Promise<SignActionResult> 

package/package.json

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

package/src/kvstore/GlobalKVStore.ts

@@ -0,0 +1,478 @@
+import Transaction from '../transaction/Transaction.js'
+import * as Utils from '../primitives/utils.js'
+import { TopicBroadcaster, LookupResolver } 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'
+import WalletClient from '../wallet/WalletClient.js'
+import { Beef } from '../transaction/Beef.js'
+import { Historian } from '../overlay-tools/Historian.js'
+import { KVContext, kvStoreInterpreter } from './kvStoreInterpreter.js'
+import { ProtoWallet } from '../wallet/ProtoWallet.js'
+import { kvProtocol, KVStoreConfig, KVStoreQuery, KVStoreEntry, KVStoreGetOptions, KVStoreSetOptions, KVStoreRemoveOptions } from './types.js'
+
+/**
+ * Default configuration values for GlobalKVStore operations.
+ * Provides sensible defaults for overlay connection and protocol settings.
+ */
+const DEFAULT_CONFIG: KVStoreConfig = {
+  protocolID: [1, 'kvstore'],
+  serviceName: 'ls_kvstore',
+  tokenAmount: 1,
+  topics: ['tm_kvstore'],
+  networkPreset: 'mainnet',
+  acceptDelayedBroadcast: false,
+  tokenSetDescription: '', // Will be set dynamically
+  tokenUpdateDescription: '', // Will be set dynamically
+  tokenRemovalDescription: '' // Will be set dynamically
+}
+
+/**
+ * Implements a global key-value storage system which uses an overlay service to track key-value pairs.
+ * Each key-value pair is represented by a PushDrop token output.
+ * Allows getting, setting, and removing key-value pairs with optional fetching by protocolID and history tracking.
+ */
+export class GlobalKVStore {
+  /**
+   * The wallet interface used to create transactions and perform cryptographic operations.
+   * @readonly
+   */
+  private readonly wallet: WalletInterface
+
+  /**
+   * Configuration for the KVStore instance containing all runtime options.
+   * @private
+   * @readonly
+   */
+  private readonly config: KVStoreConfig
+
+  /**
+   * Historian instance used to extract history from transaction outputs.
+   * @private
+   */
+  private readonly historian: Historian<string, KVContext>
+
+  /**
+   * Lookup resolver used to query the overlay for transaction outputs.
+   * @private
+   */
+  private readonly lookupResolver: LookupResolver
+
+  /**
+   * Topic broadcaster used to broadcast transactions to the overlay.
+   * @private
+   */
+  private readonly topicBroadcaster: TopicBroadcaster
+
+  /**
+   * A map to store locks for each key to ensure atomic updates.
+   * @private
+   */
+  private readonly keyLocks: Map<string, Array<(value: void | PromiseLike<void>) => void>> = new Map()
+
+  /**
+   * Cached user identity key
+   * @private
+   */
+  private cachedIdentityKey: PubKeyHex | null = null
+
+  /**
+   * Creates an instance of the GlobalKVStore.
+   *
+   * @param {KVStoreConfig} [config={}] - Configuration options for the KVStore. Defaults to empty object.
+   * @param {WalletInterface} [config.wallet] - Wallet to use for operations. Defaults to WalletClient.
+   * @throws {Error} If the configuration contains invalid parameters.
+   */
+  constructor (config: KVStoreConfig = {}) {
+    // Merge with defaults to create a fully resolved config
+    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
+    })
+    this.topicBroadcaster = new TopicBroadcaster(this.config.topics as string[], {
+      networkPreset: this.config.networkPreset
+    })
+  }
+
+  /**
+   * Retrieves data from the KVStore.
+   * Can query by key+controller (single result), protocolID, controller, or key (multiple results).
+   *
+   * @param {KVStoreQuery} query - Query parameters sent to overlay
+   * @param {KVStoreGetOptions} [options={}] - Configuration options for the get operation
+   * @returns {Promise<KVStoreEntry | KVStoreEntry[] | undefined>} Single entry for key+controller queries, array for all other queries
+   */
+  async get (query: KVStoreQuery, options: KVStoreGetOptions = {}): Promise<KVStoreEntry | KVStoreEntry[] | undefined> {
+    if (Object.keys(query).length === 0) {
+      throw new Error('Must specify either key, controller, or protocolID')
+    }
+    if (query.key != null && query.controller != null) {
+      // Specific key+controller query - return single entry
+      const entries = await this.queryOverlay(query, options)
+      return entries.length > 0 ? entries[0] : undefined
+    }
+    return await this.queryOverlay(query, options)
+  }
+
+  /**
+   * Sets a key-value pair. The current user (wallet identity) becomes the controller.
+   *
+   * @param {string} key - The key to set (user computes this however they want)
+   * @param {string} value - The value to store
+   * @param {KVStoreSetOptions} [options={}] - Configuration options for the set operation
+   * @returns {Promise<OutpointString>} The outpoint of the created token
+   */
+  async set (key: string, value: string, options: KVStoreSetOptions = {}): Promise<OutpointString> {
+    if (typeof key !== 'string' || key.length === 0) {
+      throw new Error('Key must be a non-empty string.')
+    }
+    if (typeof value !== 'string') {
+      throw new Error('Value must be a string.')
+    }
+
+    const controller = await this.getIdentityKey()
+    const lockQueue = await this.queueOperationOnKey(key)
+    const protocolID = options.protocolID ?? this.config.protocolID
+    const tokenSetDescription = (options.tokenSetDescription != null && options.tokenSetDescription !== '') ? options.tokenSetDescription : `Create KVStore value for ${key}`
+    const tokenUpdateDescription = (options.tokenUpdateDescription != null && options.tokenUpdateDescription !== '') ? options.tokenUpdateDescription : `Update KVStore value for ${key}`
+    const tokenAmount = options.tokenAmount ?? this.config.tokenAmount
+
+    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
+      const pushdrop = new PushDrop(this.wallet, this.config.originator)
+      const lockingScript = await pushdrop.lock(
+        [
+          Utils.toArray(JSON.stringify(protocolID), 'utf8'),
+          Utils.toArray(key, 'utf8'),
+          Utils.toArray(value, 'utf8'),
+          Utils.toArray(controller, 'hex')
+        ],
+        protocolID ?? this.config.protocolID as WalletProtocol,
+        Utils.toUTF8(Utils.toArray(key, 'utf8')),
+        'anyone',
+        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
+          }
+        }, 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 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
+          }
+        }, 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`
+      }
+    } finally {
+      if (lockQueue.length > 0) {
+        this.finishOperationOnKey(key, lockQueue)
+      }
+    }
+  }
+
+  /**
+   * Removes the key-value pair associated with the given key from the overlay service.
+   *
+   * @param {string} key - The key to remove.
+   * @param {CreateActionOutput[] | undefined} [outputs=undefined] - Additional outputs to include in the removal transaction.
+   * @param {KVStoreRemoveOptions} [options=undefined] - Optional parameters for the removal operation.
+   * @returns {Promise<HexString>} A promise that resolves to the txid of the removal transaction if successful.
+   * @throws {Error} If the key is invalid.
+   * @throws {Error} If the key does not exist in the store.
+   * @throws {Error} If the overlay service is unreachable or the transaction fails.
+   * @throws {Error} If there are existing tokens that cannot be unlocked.
+   */
+  async remove (key: string, outputs?: CreateActionOutput[], options: KVStoreRemoveOptions = {}): Promise<HexString> {
+    if (typeof key !== 'string' || key.length === 0) {
+      throw new Error('Key must be a non-empty string.')
+    }
+
+    const controller = await this.getIdentityKey()
+    const lockQueue = await this.queueOperationOnKey(key)
+
+    const protocolID = options.protocolID ?? this.config.protocolID
+    const tokenRemovalDescription = (options.tokenRemovalDescription != null && options.tokenRemovalDescription !== '') ? options.tokenRemovalDescription : `Remove KVStore value for ${key}`
+
+    try {
+      const existingEntries = await this.queryOverlay({ key, controller }, { includeToken: true })
+
+      if (existingEntries.length === 0 || existingEntries[0].token == null) {
+        throw new Error('The item did not exist, no item was deleted.')
+      }
+
+      const existingToken = existingEntries[0].token
+      const inputs: CreateActionInput[] = [{
+        outpoint: `${existingToken.txid}.${existingToken.outputIndex}`,
+        unlockingScriptLength: 74,
+        inputDescription: 'KVStore token to remove'
+      }]
+
+      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
+        }
+      }, 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: 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')
+      }
+
+      const transaction = Transaction.fromAtomicBEEF(finalTx)
+      await this.submitToOverlay(transaction)
+      return transaction.id('hex')
+    } finally {
+      if (lockQueue.length > 0) {
+        this.finishOperationOnKey(key, lockQueue)
+      }
+    }
+  }
+
+  /**
+   * Queues an operation on a specific key to ensure atomic updates.
+   * Prevents concurrent operations on the same key from interfering with each other.
+   *
+   * @param {string} key - The key to queue an operation for.
+   * @returns {Promise<Array<(value: void | PromiseLike<void>) => void>>} The lock queue for cleanup.
+   * @private
+   */
+  private async queueOperationOnKey (key: string): Promise<Array<(value: void | PromiseLike<void>) => void>> {
+    // Check if a lock exists for this key and wait for it to resolve
+    let lockQueue = this.keyLocks.get(key)
+    if (lockQueue == null) {
+      lockQueue = []
+      this.keyLocks.set(key, lockQueue)
+    }
+
+    let resolveNewLock: () => void = () => { }
+    const newLock = new Promise<void>((resolve) => {
+      resolveNewLock = resolve
+      if (lockQueue != null) { lockQueue.push(resolve) }
+    })
+
+    // If we are the only request, resolve the lock immediately, queue remains at 1 item until request ends.
+    if (lockQueue.length === 1) {
+      resolveNewLock()
+    }
+
+    await newLock
+    return lockQueue
+  }
+
+  /**
+   * Finishes an operation on a key and resolves the next waiting operation.
+   *
+   * @param {string} key - The key to finish the operation for.
+   * @param {Array<(value: void | PromiseLike<void>) => void>} lockQueue - The lock queue from queueOperationOnKey.
+   * @private
+   */
+  private finishOperationOnKey (key: string, lockQueue: Array<(value: void | PromiseLike<void>) => void>): void {
+    lockQueue.shift() // Remove the current lock from the queue
+    if (lockQueue.length > 0) {
+      // If there are more locks waiting, resolve the next one
+      lockQueue[0]()
+    } else {
+      // Clean up empty queue to prevent memory leak
+      this.keyLocks.delete(key)
+    }
+  }
+
+  /**
+   * Helper function to fetch and cache user identity key
+   *
+   * @returns {Promise<PubKeyHex>} The identity key of the current user
+   * @private
+   */
+  private async getIdentityKey (): Promise<PubKeyHex> {
+    if (this.cachedIdentityKey == null) {
+      this.cachedIdentityKey = (await this.wallet.getPublicKey({ identityKey: true }, this.config.originator)).publicKey
+    }
+    return this.cachedIdentityKey
+  }
+
+  /**
+   * Queries the overlay service for KV entries.
+   *
+   * @param {KVStoreQuery} query - Query parameters sent to overlay
+   * @param {KVStoreGetOptions} options - Configuration options for the query
+   * @returns {Promise<KVStoreEntry[]>} Array of matching KV entries
+   * @private
+   */
+  private async queryOverlay (query: KVStoreQuery, options: KVStoreGetOptions = {}): Promise<KVStoreEntry[]> {
+    const answer = await this.lookupResolver.query({
+      service: options.serviceName ?? this.config.serviceName as string,
+      query
+    })
+
+    if (answer.type !== 'output-list' || answer.outputs.length === 0) {
+      return []
+    }
+
+    const entries: KVStoreEntry[] = []
+
+    for (const result of answer.outputs) {
+      try {
+        const tx = Transaction.fromBEEF(result.beef)
+        const output = tx.outputs[result.outputIndex]
+        const decoded = PushDrop.decode(output.lockingScript)
+
+        if (decoded.fields.length !== 5) {
+          continue
+        }
+
+        // Verify signature
+        const anyoneWallet = new ProtoWallet('anyone')
+        const signature = decoded.fields.pop() as number[]
+        try {
+          await anyoneWallet.verifySignature({
+            data: decoded.fields.reduce((a, e) => [...a, ...e], []),
+            signature,
+            counterparty: Utils.toHex(decoded.fields[kvProtocol.controller]),
+            protocolID: JSON.parse(Utils.toUTF8(decoded.fields[kvProtocol.protocolID])),
+            keyID: Utils.toUTF8(decoded.fields[kvProtocol.key])
+          })
+        } catch (error) {
+          // Skip all outputs that fail signature verification
+          continue
+        }
+
+        const entry: KVStoreEntry = {
+          key: Utils.toUTF8(decoded.fields[kvProtocol.key]),
+          value: Utils.toUTF8(decoded.fields[kvProtocol.value]),
+          controller: Utils.toHex(decoded.fields[kvProtocol.controller]),
+          protocolID: JSON.parse(Utils.toUTF8(decoded.fields[kvProtocol.protocolID]))
+        }
+
+        if (options.includeToken === true) {
+          entry.token = {
+            txid: tx.id('hex'),
+            outputIndex: result.outputIndex,
+            beef: Beef.fromBinary(result.beef),
+            satoshis: output.satoshis ?? 1
+          }
+        }
+
+        if (options.history === true) {
+          entry.history = await this.historian.buildHistory(tx, {
+            key: entry.key,
+            protocolID: entry.protocolID
+          })
+        }
+
+        entries.push(entry)
+      } catch (error) {
+        continue
+      }
+    }
+
+    return entries
+  }
+
+  /**
+   * Submits a transaction to an overlay service using TopicBroadcaster.
+   * Broadcasts the transaction to the configured topics for network propagation.
+   *
+   * @param {Transaction} transaction - The transaction to broadcast.
+   * @returns {Promise<BroadcastResponse | BroadcastFailure>} The broadcast result.
+   * @throws {Error} If the broadcast fails or the network is unreachable.
+   * @private
+   */
+  private async submitToOverlay (transaction: Transaction): Promise<BroadcastResponse | BroadcastFailure> {
+    return await this.topicBroadcaster.broadcast(transaction)
+  }
+}
+
+export default GlobalKVStore