@bsv/sdk 1.4.17 → 1.4.19

package/src/kvstore/LocalKVStore.ts

@@ -1,9 +1,10 @@
 import LockingScript from '../script/LockingScript.js'
 import PushDrop from '../script/templates/PushDrop.js'
 import * as Utils from '../primitives/utils.js'
-import { WalletInterface, OutpointString, CreateActionInput, SignActionSpend } from '../wallet/Wallet.interfaces.js'
+import { WalletInterface, OutpointString, CreateActionInput, SignActionSpend, WalletProtocol, ListOutputsResult, WalletOutput, AtomicBEEF } from '../wallet/Wallet.interfaces.js'
 import WalletClient from '../wallet/WalletClient.js'
 import Transaction from '../transaction/Transaction.js'
+import { Beef } from '../transaction/Beef.js'
 
 /**
  * Implements a key-value storage system backed by transaction outputs managed by a wallet.
@@ -41,14 +42,14 @@ export default class LocalKVStore {
    * Creates an instance of the localKVStore.
    *
    * @param {WalletInterface} [wallet=new WalletClient()] - The wallet interface to use. Defaults to a new WalletClient instance.
-   * @param {string} [context='kvstore-default'] - The context (basket) for namespacing keys. Defaults to 'kvstore-default'.
+   * @param {string} [context='kvstoredefault'] - The context (basket) for namespacing keys. Defaults to 'kvstore default'.
    * @param {boolean} [encrypt=true] - Whether to encrypt values. Defaults to true.
    * @param {string} [originator] — An originator to use with PushDrop and the wallet, if provided.
    * @throws {Error} If the context is missing or empty.
    */
   constructor (
     wallet: WalletInterface = new WalletClient(),
-    context = 'kvstore-default',
+    context = 'kvstore default',
     encrypt = true,
     originator?: string
   ) {
@@ -61,6 +62,21 @@ export default class LocalKVStore {
     this.originator = originator
   }
 
+  private getProtocol (key: string): { protocolID: WalletProtocol, keyID: string } {
+    return { protocolID: [2, this.context], keyID: key }
+  }
+
+  private async getOutputs (key: string, limit?: number): Promise<ListOutputsResult> {
+    const results = await this.wallet.listOutputs({
+      basket: this.context,
+      tags: [key],
+      tagQueryMode: 'all',
+      include: 'entire transactions',
+      limit
+    })
+    return results
+  }
+
   /**
    * Retrieves the value associated with a given key.
    *
@@ -68,43 +84,79 @@ export default class LocalKVStore {
    * @param {string | undefined} [defaultValue=undefined] - The value to return if the key is not found.
    * @returns {Promise<string | undefined>} A promise that resolves to the value as a string,
    *   the defaultValue if the key is not found, or undefined if no defaultValue is provided.
-   * @throws {Error} If multiple outputs are found for the key (ambiguous state).
+   * @throws {Error} If too many outputs are found for the key (ambiguous state).
    * @throws {Error} If the found output's locking script cannot be decoded or represents an invalid token format.
    */
   async get (key: string, defaultValue: string | undefined = undefined): Promise<string | undefined> {
-    const results = await this.wallet.listOutputs({
-      basket: this.context,
-      tags: [key],
-      include: 'locking scripts'
-    })
-    if (results.outputs.length === 0) {
-      return defaultValue
-    } else if (results.outputs.length > 1) {
-      throw new Error('Multiple tokens found for this key. You need to call set to collapse this ambiguous state before you can get this value again.')
+    const r = await this.lookupValue(key, defaultValue, 5)
+    return r.value
+  }
+
+  private getLockingScript (output: WalletOutput, beef: Beef): LockingScript {
+    const [txid, vout] = output.outpoint.split('.')
+    const tx = beef.findTxid(txid)?.tx
+    if (tx == null) { throw new Error(`beef must contain txid ${txid}`) }
+    const lockingScript = tx.outputs[Number(vout)].lockingScript
+    return lockingScript
+  }
+
+  private async lookupValue (key: string, defaultValue: string | undefined, limit?: number): Promise<LookupValueResult> {
+    const lor = await this.getOutputs(key, limit)
+    const r: LookupValueResult = { value: defaultValue, outpoint: undefined, lor }
+    const { outputs } = lor
+    if (outputs.length === 0) {
+      return r
     }
-    let fields: number[][]
+    const output = outputs.slice(-1)[0]
+    r.outpoint = output.outpoint
+    let field: number[]
     try {
-      if (typeof results.outputs[0].lockingScript !== 'string') {
-        throw new Error('No locking script')
-      }
-      const decoded = PushDrop.decode(LockingScript.fromHex(results.outputs[0].lockingScript))
-      if (decoded.fields.length !== 1) {
+      if (lor.BEEF === undefined) { throw new Error('entire transactions listOutputs option must return valid BEEF') }
+      const lockingScript = this.getLockingScript(output, Beef.fromBinary(lor.BEEF))
+      const decoded = PushDrop.decode(lockingScript)
+      if (decoded.fields.length < 1 || decoded.fields.length > 2) {
         throw new Error('Invalid token.')
       }
-      fields = decoded.fields
+      field = decoded.fields[0]
     } catch (_) {
-      throw new Error(`Invalid value found. You need to call set to collapse the corrupted state (or relinquish the corrupted ${results.outputs[0].outpoint} output from the ${this.context} basket) before you can get this value again.`)
+      throw new Error(`Invalid value found. You need to call set to collapse the corrupted state (or relinquish the corrupted ${outputs[0].outpoint} output from the ${this.context} basket) before you can get this value again.`)
     }
     if (!this.encrypt) {
-      return Utils.toUTF8(fields[0])
+      r.value = Utils.toUTF8(field)
     } else {
       const { plaintext } = await this.wallet.decrypt({
-        protocolID: [2, this.context],
-        keyID: key,
-        ciphertext: fields[0]
+        ...this.getProtocol(key),
+        ciphertext: field
+      })
+      r.value = Utils.toUTF8(plaintext)
+    }
+    return r
+  }
+
+  private getInputs (outputs: WalletOutput[]): CreateActionInput[] {
+    const inputs: CreateActionInput[] = []
+    for (let i = 0; i < outputs.length; i++) {
+      inputs.push({
+        outpoint: outputs[i].outpoint,
+        unlockingScriptLength: 74,
+        inputDescription: 'Previous key-value token'
       })
-      return Utils.toUTF8(plaintext)
     }
+    return inputs
+  }
+
+  private async getSpends (key: string, outputs: WalletOutput[], pushdrop: PushDrop, atomicBEEF: AtomicBEEF): Promise<Record<number, SignActionSpend>> {
+    const p = this.getProtocol(key)
+    const tx = Transaction.fromAtomicBEEF(atomicBEEF)
+    const spends: Record<number, SignActionSpend> = {}
+    for (let i = 0; i < outputs.length; i++) {
+      const unlocker = pushdrop.unlock(p.protocolID, p.keyID, 'self')
+      const unlockingScript = await unlocker.sign(tx, i)
+      spends[i] = {
+        unlockingScript: unlockingScript.toHex()
+      }
+    }
+    return spends
   }
 
   /**
@@ -121,95 +173,65 @@ export default class LocalKVStore {
    * @returns {Promise<OutpointString>} A promise that resolves to the outpoint string (txid.vout) of the new or updated token output.
    */
   async set (key: string, value: string): Promise<OutpointString> {
+    const current = await this.lookupValue(key, undefined, 10)
+    if (current.value === value) {
+      if (current.outpoint === undefined) { throw new Error('outpoint must be valid when value is valid and unchanged') }
+      // Don't create a new transaction if the value doesn't need to change...
+      return current.outpoint
+    }
+    const protocol = this.getProtocol(key)
     let valueAsArray = Utils.toArray(value, 'utf8')
     if (this.encrypt) {
       const { ciphertext } = await this.wallet.encrypt({
-        plaintext: valueAsArray,
-        protocolID: [2, this.context],
-        keyID: key
+        ...protocol,
+        plaintext: valueAsArray
       })
       valueAsArray = ciphertext
     }
     const pushdrop = new PushDrop(this.wallet, this.originator)
     const lockingScript = await pushdrop.lock(
       [valueAsArray],
-      [2, this.context],
-      key,
+      protocol.protocolID,
+      protocol.keyID,
       'self'
     )
-    const results = await this.wallet.listOutputs({
-      basket: this.context,
-      tags: [key],
-      include: 'entire transactions'
-    })
-    if (results.totalOutputs !== 0) {
-      try {
-        const inputs: CreateActionInput[] = []
-        for (let i = 0; i < results.outputs.length; i++) {
-          inputs.push({
-            outpoint: results.outputs[i].outpoint,
-            unlockingScriptLength: 74,
-            inputDescription: 'Previous key-value token'
-          })
-        }
-        const { signableTransaction } = await this.wallet.createAction({
-          description: `Update ${key} in ${this.context}`,
-          inputBEEF: results.BEEF,
-          inputs,
-          outputs: [{
-            lockingScript: lockingScript.toHex(),
-            satoshis: 1,
-            outputDescription: 'Key-value token'
-          }],
-          options: {
-            acceptDelayedBroadcast: false,
-            randomizeOutputs: false
-          }
-        })
-        if (typeof signableTransaction !== 'object') {
-          throw new Error('Wallet did not return a signable transaction when expected.')
-        }
-        const tx = Transaction.fromAtomicBEEF(signableTransaction.tx)
-        const spends: Record<number, SignActionSpend> = {}
-        for (let i = 0; i < results.outputs.length; i++) {
-          const unlocker = pushdrop.unlock(
-            [2, this.context],
-            key,
-            'self'
-          )
-          const unlockingScript = await unlocker.sign(tx, i)
-          spends[i] = {
-            unlockingScript: unlockingScript.toHex()
-          }
+    const { outputs, BEEF: inputBEEF } = current.lor
+    let outpoint: OutpointString
+    try {
+      const inputs = this.getInputs(outputs)
+      const { txid, signableTransaction } = await this.wallet.createAction({
+        description: `Update ${key} in ${this.context}`,
+        inputBEEF,
+        inputs,
+        outputs: [{
+          basket: this.context,
+          tags: [key],
+          lockingScript: lockingScript.toHex(),
+          satoshis: 1,
+          outputDescription: 'Key-value token'
+        }],
+        options: {
+          acceptDelayedBroadcast: false,
+          randomizeOutputs: false
         }
+      })
+      if (outputs.length > 0 && typeof signableTransaction !== 'object') {
+        throw new Error('Wallet did not return a signable transaction when expected.')
+      }
+      if (signableTransaction == null) {
+        outpoint = `${txid as string}.0`
+      } else {
+        const spends = await this.getSpends(key, outputs, pushdrop, signableTransaction.tx)
         const { txid } = await this.wallet.signAction({
           reference: signableTransaction.reference,
           spends
         })
-        return `${txid as string}.0`
-      } catch (_) {
-        // Signing failed, relinquish original outputs
-        for (let i = 0; i < results.outputs.length; i++) {
-          await this.wallet.relinquishOutput({
-            output: results.outputs[i].outpoint,
-            basket: this.context
-          })
-        }
+        outpoint = `${txid as string}.0`
       }
+    } catch (_) {
+      throw new Error(`There are ${outputs.length} outputs with tag ${key} that cannot be unlocked.`)
     }
-    const { txid } = await this.wallet.createAction({
-      description: `Set ${key} in ${this.context}`,
-      outputs: [{
-        lockingScript: lockingScript.toHex(),
-        satoshis: 1,
-        outputDescription: 'Key-value token'
-      }],
-      options: {
-        acceptDelayedBroadcast: false,
-        randomizeOutputs: false
-      }
-    })
-    return `${txid as string}.0`
+    return outpoint
   }
 
   /**
@@ -220,63 +242,46 @@ export default class LocalKVStore {
    * If signing the removal transaction fails, it relinquishes the original outputs instead of spending.
    *
    * @param {string} key - The key to remove.
-   * @returns {Promise<string | void>} A promise that resolves to the txid of the removal transaction if successful.
+   * @returns {Promise<string[]>} A promise that resolves to the txids of the removal transactions if successful.
    */
-  async remove (key: string): Promise<OutpointString | undefined> {
-    const results = await this.wallet.listOutputs({
-      basket: this.context,
-      tags: [key],
-      include: 'entire transactions'
-    })
-    if (results.totalOutputs === 0) {
-      return // Key not found, do nothing
-    }
-    const pushdrop = new PushDrop(this.wallet, this.originator)
-    try {
-      const inputs: CreateActionInput[] = []
-      for (let i = 0; i < results.outputs.length; i++) {
-        inputs.push({
-          outpoint: results.outputs[i].outpoint,
-          unlockingScriptLength: 74,
-          inputDescription: 'Previous key-value token'
-        })
-      }
-      const { signableTransaction } = await this.wallet.createAction({
-        description: `Remove ${key} in ${this.context}`,
-        inputBEEF: results.BEEF,
-        inputs,
-        options: {
-          acceptDelayedBroadcast: false
-        }
-      })
-      if (typeof signableTransaction !== 'object') {
-        throw new Error('Wallet did not return a signable transaction when expected.')
-      }
-      const tx = Transaction.fromAtomicBEEF(signableTransaction.tx)
-      const spends: Record<number, SignActionSpend> = {}
-      for (let i = 0; i < results.outputs.length; i++) {
-        const unlocker = pushdrop.unlock(
-          [2, this.context],
-          key,
-          'self'
-        )
-        const unlockingScript = await unlocker.sign(tx, i)
-        spends[i] = {
-          unlockingScript: unlockingScript.toHex()
+  async remove (key: string): Promise<string[]> {
+    const txids: string[] = []
+    for (; ;) {
+      const { outputs, BEEF: inputBEEF, totalOutputs } = await this.getOutputs(key)
+      if (outputs.length > 0) {
+        const pushdrop = new PushDrop(this.wallet, this.originator)
+        try {
+          const inputs = this.getInputs(outputs)
+          const { signableTransaction } = await this.wallet.createAction({
+            description: `Remove ${key} in ${this.context}`,
+            inputBEEF,
+            inputs,
+            options: {
+              acceptDelayedBroadcast: false
+            }
+          })
+          if (typeof signableTransaction !== 'object') {
+            throw new Error('Wallet did not return a signable transaction when expected.')
+          }
+          const spends = await this.getSpends(key, outputs, pushdrop, signableTransaction.tx)
+          const { txid } = await this.wallet.signAction({
+            reference: signableTransaction.reference,
+            spends
+          })
+          if (txid === undefined) { throw new Error('signAction must return a valid txid') }
+          txids.push(txid)
+        } catch (_) {
+          throw new Error(`There are ${totalOutputs} outputs with tag ${key} that cannot be unlocked.`)
         }
       }
-      const { txid } = await this.wallet.signAction({
-        reference: signableTransaction.reference,
-        spends
-      })
-      return txid
-    } catch (_) {
-      for (let i = 0; i < results.outputs.length; i++) {
-        await this.wallet.relinquishOutput({
-          output: results.outputs[i].outpoint,
-          basket: this.context
-        })
-      }
+      if (outputs.length === totalOutputs) { break }
     }
+    return txids
   }
 }
+
+interface LookupValueResult {
+  value: string | undefined
+  outpoint: OutpointString | undefined
+  lor: ListOutputsResult
+}