@bsv/wallet-toolbox 1.6.32 → 1.6.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/wallet-toolbox",
-  "version": "1.6.32",
+  "version": "1.6.33",
   "description": "BRC100 conforming wallet, wallet storage and wallet signer components",
   "main": "./out/src/index.js",
   "types": "./out/src/index.d.ts",

package/src/monitor/Monitor.ts

@@ -383,6 +383,14 @@ export class Monitor {
     }
   }
 
+  /**
+   * Handler for new header events from Chaintracks.
+   *
+   * To minimize reorg processing, new headers are aged before processing via TaskNewHeader.
+   * Therefore this handler is intentionally a no-op.
+   *
+   * @param header
+   */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   processHeader(header: BlockHeader): void {}
 }

package/src/monitor/tasks/TaskReorg.ts

@@ -14,7 +14,7 @@ import { WalletMonitorTask } from './WalletMonitorTask'
  * The current implementation ages deactivation notifications by 10 minutes with each retry.
  * If a successful proof update confirms original proof data after 3 retries, the original is retained.
  *
- * In normal operation there should never be any work for this task to perform.
+ * In normal operation there should rarely be any work for this task to perform.
  * The most common result is that there are no matching proven_txs records because
  * generating new proven_txs records intentionally lags new block generation to
  * minimize this disruption.
@@ -24,17 +24,8 @@ import { WalletMonitorTask } from './WalletMonitorTask'
  * - Generated beefs are impacted.
  * - Updated proof data may be unavailable at the time a reorg is first reported.
  *
- * Instead of reorg notification derived from new header notification, reorg repair to
- * the proven_txs table is more effectively driven by noticing that a beef generated for a new
- * createAction fails to verify against the chaintracker.
- *
- * An alternate approach to processing these events is to revert the proven_txs record to a proven_tx_reqs record.
- * Pros:
- * - The same multiple attempt logic that already exists is reused.
- * - Failing to obtain a new proof already has transaction failure handling in place.
- * - Generated beefs automatically become one generation deeper, potentially allowing transaction outputs to be spent.
- * Cons:
- * - Transactions must revert to un-proven / un-mined.
+ * Proper reorg handling also requires repairing invalid beefs for new transactions when
+ * createAction fails to verify a generated beef against the chaintracker.
  */
 export class TaskReorg extends WalletMonitorTask {
   static taskName = 'Reorg'
@@ -49,6 +40,11 @@ export class TaskReorg extends WalletMonitorTask {
     super(monitor, TaskReorg.taskName)
   }
 
+  /**
+   * Shift aged deactivated headers onto `process` array.
+   * @param nowMsecsSinceEpoch current time in milliseconds since epoch.
+   * @returns `run` true iff there are aged deactivated headers to process.
+   */
   trigger(nowMsecsSinceEpoch: number): { run: boolean } {
     const cutoff = nowMsecsSinceEpoch - this.agedMsecs
     const q = this.monitor.deactivatedHeaders
@@ -66,72 +62,22 @@ export class TaskReorg extends WalletMonitorTask {
     let log = ''
 
     for (;;) {
+      // Loop over deactivated headers to process
       const header = this.process.shift()
       if (!header) break
 
-      let ptxs: TableProvenTx[] = []
-
-      await this.storage.runAsStorageProvider(async sp => {
-        // Lookup all the proven_txs records matching the deactivated headers
-        ptxs = await sp.findProvenTxs({ partial: { blockHash: header.header.hash } })
-      })
+      const r = await this.storage.reproveHeader(header.header.hash)
 
-      log += `  block ${header.header.hash} orphaned with ${ptxs.length} impacted transactions\n`
+      log += r.log
 
-      let retry = false
-      for (const ptx of ptxs) {
-        const mpr = await this.monitor.services.getMerklePath(ptx.txid)
-        if (mpr.merklePath && mpr.header) {
-          const mp = mpr.merklePath
-          const h = mpr.header
-          const leaf = mp.path[0].find(leaf => leaf.txid === true && leaf.hash === ptx.txid)
-          if (leaf) {
-            const update: Partial<TableProvenTx> = {
-              height: mp.blockHeight,
-              index: leaf.offset,
-              merklePath: mp.toBinary(),
-              merkleRoot: h.merkleRoot,
-              blockHash: h.hash
-            }
-            if (update.blockHash === ptx.blockHash) {
-              log += `    txid ${ptx.txid} merkle path update still based on deactivated header ${ptx.blockHash}\n`
-              if (header.tries + 1 >= this.maxRetries) {
-                log += `      maximum retries ${this.maxRetries} exceeded\n`
-              } else {
-                retry = true
-              }
-            } else {
-              // Verify the new proof's validity.
-              const merkleRoot = mp.computeRoot(ptx.txid)
-              const chaintracker = await this.monitor.services.getChainTracker()
-              const isValid = await chaintracker.isValidRootForHeight(merkleRoot, update.height!)
-              const logUpdate = `      height ${ptx.height} ${ptx.height === update.height ? 'unchanged' : `-> ${update.height}`}\n`
-              log += `      blockHash ${ptx.blockHash} -> ${update.blockHash}\n`
-              log += `      merkleRoot ${ptx.merkleRoot} -> ${update.merkleRoot}\n`
-              log += `      index ${ptx.index} -> ${update.index}\n`
-              if (!isValid) {
-                log +=
-                  `    txid ${ptx.txid} chaintracker fails to confirm updated merkle path update invalid\n` + logUpdate
-              } else {
-                await this.storage.runAsStorageProvider(async sp => {
-                  await sp.updateProvenTx(ptx.provenTxId, update)
-                })
-                log += `    txid ${ptx.txid} proof data updated\n` + logUpdate
-              }
-            }
-          } else {
-            log += `    txid ${ptx.txid} merkle path update doesn't include txid\n`
-            retry = true
-          }
+      if (r.unavailable.length > 0 || r.unchanged.length > 0) {
+        if (header.tries + 1 >= this.maxRetries) {
+          log += `      maximum retries ${this.maxRetries} exceeded\n`
         } else {
-          log += `    txid ${ptx.txid} merkle path update unavailable\n`
-          retry = true
+          log += `    retrying...\n`
+          this.monitor.deactivatedHeaders.push({ header: header.header, whenMsecs: Date.now(), tries: header.tries + 1 })
         }
       }
-      if (retry) {
-        log += `    retrying...\n`
-        this.monitor.deactivatedHeaders.push({ header: header.header, whenMsecs: Date.now(), tries: header.tries + 1 })
-      }
     }
 
     return log

package/src/sdk/WalletStorage.interfaces.ts

@@ -560,3 +560,47 @@ export interface ProcessSyncChunkResult {
   inserts: number
   error?: WalletError
 }
+
+/**
+ * Returned results from WalletStorageManager reproveHeader method.
+ */
+export interface ReproveHeaderResult {
+  /**
+   * Human readable log of the reproveHeader process.
+   */
+  log: string
+  /**
+   * List of proven_txs records that were updated with new proof data.
+   */
+  updated: { was: TableProvenTx; update: Partial<TableProvenTx>, logUpdate: string }[]
+  /**
+   * List of proven_txs records that were checked but currently available proof is unchanged.
+   */
+  unchanged: TableProvenTx[]
+  /**
+   * List of proven_txs records that were checked but currently proof data is unavailable.
+   */
+  unavailable: TableProvenTx[]
+}
+
+/**
+ * Returned results from WalletStorageManager reproveProven method.
+ */
+export interface ReproveProvenResult {
+  /**
+   * Human readable log of the reproveProven process.
+   */
+  log: string
+  /**
+   * Valid if proof data for proven_txs record is available and has changed.
+   */
+  updated?: { update: Partial<TableProvenTx>, logUpdate: string }
+  /**
+   * True if proof data for proven_txs record was found to be unchanged.
+   */
+  unchanged: boolean
+  /**
+   * True if proof data for proven_txs record is currently unavailable.
+   */
+  unavailable: boolean
+}

package/src/services/__tests/verifyBeef.test.ts

@@ -1,4 +1,4 @@
-import { Beef } from '@bsv/sdk'
+import { Beef, Utils } from '@bsv/sdk'
 import { Services } from '../Services'
 import { _tu, logger } from '../../../test/utils/TestUtilsWalletStorage'
 import { verifyTruthy } from '../../utility/utilityHelpers'
@@ -38,4 +38,14 @@ describe('verifyBeef tests', () => {
       expect(ok).toBe(true)
     }
   })
+
+  test.skip('2_ review beef verify root', async () => {
+    const bhex =
+      '0200beef01fe7c830d000a02a0021d4ca6c031db7f6334c08ddfda43cbde3800c7fa27892f8e80a5218ca8493918a10081788ac8d8267d409b6258a6a6f5d28317ee65b5b25892def4f6cbf44f92571d01510027c2382032711033d0a1e2724b9eefcf257e27bce28e37b7472877860570ee6e0129008e15879954392f322efdd32376077a3323db02501926a697f5db6b68862f67ce01150061dcb195186d564d754a056d9ad90d65ece5bfa5ddccebd24b64d25df3780b15010b00bcd8f2c9c62b4fbbefad9640f9f6dccf21246fa08a6e1cab2c052666dee4182001040018ad6a5739749e27c191a5ef7442d861e5b8d204d36c91e08bf8015811851dbe010300f47047d1c4582eb02349eabcdafc7f4573e93ed687718275475d6f528783d16201000039a5fa5dbbbcd4a1754c250a7879ae1ad2eeb189d87d3614c2a2d9519a7a47af0101001670fc6a8d40adbd3f8a84ae35f0a702695f19f19a8feddcfd1de6249cc164e901010092a689a4cda27aea3552a98a7441ffbaed8566ae31e0a1a67e67647e2f3b8fda05025a8b77e1c82cfcfda197fec3f805a6b7000737a583e45833df6721975fe8bad102448f38860c45d33c87041c0fda51befb1c90853d3141a0df3ac737ccb9b5e61b01000100000001f7ddf439a165bf63a7d6c144b4bd8882ff45dc35a3ca3e75517fa56482fed6bd000000006b4830450221008106bc7164333415bc485ae1d12acd72bbc536f1f03b25aa42d92971565b329902202d484d09935be7fa49bbd5806148dbfdb90cc86516537351acf20655c03fa656412102b53b5339d6241c4271a07e7b09035966defe37c1a3edd60b8a427d5a5b488cb5ffffffff021d00000000000000c421029664d9baa433b4ded47ce151d348fda7ed30df597b93bf5f321ec2fe742b0faaac2131546f446f44744b7265457a6248594b466a6d6f42756475466d53585855475a4734aba7171082ff009628f6d1abea57bc1ffcdb6c2b45a5e17219eaf6bc6b6e093b5243036565505084548f9715a440b6c03e73427d4730450221008e4964dc5e8f3cc6f41da7508cba05babb2ce211fa47fe91ae9c06903d95fde902206cb21d6c188f302fccedbbcd80459561dbabcabe3da16853371fede9f5d027d06d75c8030000000000001976a914f8a84c2bef6eed4eb3270c8605a8063202ed25cb88ac000000000001000000015a8b77e1c82cfcfda197fec3f805a6b7000737a583e45833df6721975fe8bad1010000006b483045022100fb62de36ac2930029b1397931c3f30bf6df5166f2e82bed6b2ef1d23491f8e450220730105461dc12236439ee568709ee72c345bb6748efe8656a0e96e4cc5eaecfb412102c6b33e96f3b635ebd71bcedd9bcb90b4c098b9b38730f58984e23615e0864833ffffffff042800000000000000c521029664d9baa433b4ded47ce151d348fda7ed30df597b93bf5f321ec2fe742b0faaac2131546f446f44744b7265457a6248594b466a6d6f42756475466d53585855475a47361c08d47822cb0806cd17af298948641db6bd36440da9a988af0f6600cba6dabfcfe5c7fe086b7a08e8feef3a9d21d8b0126c2f4a260b46304402204f418ece238fb0587f887c1e0ea6beb4ebcefa6749d1b523195bd65dc9971374022009d0b21c669a72a8a01808d394c55de730a3a4d287b3bb209697b2e79a9787ce6d7516050000000000001976a914803a2e1d2ca2373c21129a7075f1a42587f16c8188acec030000000000001976a91441cb6381a584c464df4b6dd75b91fb0ab6c4b7a688acd0040000000000001976a914e08fbd92ba37c1d84bba8439c55793ea60c0dd6b88ac00000000000100000001448f38860c45d33c87041c0fda51befb1c90853d3141a0df3ac737ccb9b5e61b020000006a4730440220411ab1f23f747899bf71185fbb4ab03defc6e215fb1ee3d24060b14256d2dc40022035669cd13b5c5fd399a402862b4e6bc001d0cbf56660bac37b1563eeaf49a700412103b20f91159733fd69817cc4d4f9ed0cf4340f63b482e0a0a7f233885c61d1b044ffffffff020a00000000000000c421029664d9baa433b4ded47ce151d348fda7ed30df597b93bf5f321ec2fe742b0faaac2131546f446f44744b7265457a6248594b466a6d6f42756475466d53585855475a47343c32fe905bb02e70c0a9779048c921b1e26a2684c498ab44759ac25bcdfafa95309c59d1c3ac12f056ad8d10dabe777d1d57dd934730450221009a64cdc81a0ada12d329463db24260a15ad56bdc3523613c0fae2fb64762d20e022021b942e859749fc23585fdb0395585d6ea52dcf0a310cc989a38ff0483c8717e6d75b7150000000000001976a91468cce1214ccbd14d9dfd813d8490daadaa96b39288ac00000000'
+    const beef = Beef.fromString(bhex)
+    logger(beef.toLogString())
+    logger(Utils.toHex(beef.txs[1].rawTx!))
+    logger(beef.bumps[0].computeRoot('e47df21819ed320a78392e62e963ddd77143c3c52ad5255a07ff55ba507df71d'))
+  })
+
 })

package/src/storage/StorageProvider.ts

@@ -230,7 +230,11 @@ export abstract class StorageProvider extends StorageReaderWriter implements Wal
     for (const txid of txids) {
       const d: GetReqsAndBeefDetail = {
         txid,
+        // status: 'readyToSend' | 'alreadySent' | 'error' | 'unknown'
         status: 'unknown'
+        // req?: TableProvenTxReq
+        // proven?: TableProvenTx
+        // error?: string
       }
       r.details.push(d)
       try {

package/src/storage/WalletStorageManager.ts

@@ -1,6 +1,7 @@
 import {
   AbortActionArgs,
   AbortActionResult,
+  Beef,
   InternalizeActionArgs,
   InternalizeActionResult,
   ListActionsResult,
@@ -16,6 +17,7 @@ import {
   TableCertificateX,
   TableOutput,
   TableOutputBasket,
+  TableProvenTx,
   TableProvenTxReq,
   TableSettings,
   TableUser
@@ -519,6 +521,165 @@ export class WalletStorageManager implements sdk.WalletStorage {
     })
   }
 
+  /**
+   * For each proven_txs record currently sourcing its transaction merkle proof from the given deactivated header,
+   * attempt to reprove the transaction against the current chain,
+   * updating the proven_txs record if a new valid proof is found.
+   * 
+   * @param deactivatedHash An orphaned header than may have served as a proof source for proven_txs records.
+   * @returns 
+   */
+  async reproveHeader(deactivatedHash: string): Promise<sdk.ReproveHeaderResult> {
+    const r: sdk.ReproveHeaderResult = { log: '', updated: [], unchanged: [], unavailable: [] }
+    const services = this.getServices()
+    const chaintracker = await services.getChainTracker()
+
+    // Lookup all the proven_txs records matching the deactivated headers
+    let ptxs: TableProvenTx[] = []
+    await this.runAsStorageProvider(async sp => {
+      ptxs = await sp.findProvenTxs({ partial: { blockHash: deactivatedHash } })
+    })
+
+    r.log += `  block ${deactivatedHash} orphaned with ${ptxs.length} impacted transactions\n`
+
+    for (const ptx of ptxs) {
+      // Loop over proven_txs records matching the deactivated header
+      const rp = await this.reproveProven(ptx, true)
+
+      r.log += rp.log
+      if (rp.unavailable) r.unavailable.push(ptx);
+      if (rp.unchanged) r.unchanged.push(ptx);
+      if (rp.updated) r.updated.push({ was: ptx, update: rp.updated.update, logUpdate: rp.updated.logUpdate })
+    }
+
+    if (r.updated.length > 0) {
+      await this.runAsStorageProvider(async sp => {
+        for (const u of r.updated) {
+          await sp.updateProvenTx(u.was.provenTxId, u.update)
+          r.log += `    txid ${u.was.txid} proof data updated\n` + u.logUpdate
+        }
+      })
+    }
+
+    return r
+  }
+
+  /**
+   * Extends the Beef `verify` function to handle BUMPs that have become invalid due to a chain reorg.
+   * 
+   * Any merkle root that fails `isValidRootForHeight` triggers a reprove attempt for that block header.
+   * This results in proven_txs with invalid proofs being updated with new valid proofs where possible.
+   * Finally, a new beef is generated and verified against the chaintracker.
+   * 
+   * @param beef 
+   * @param allowTxidOnly 
+   * @returns 
+   */
+  async verifyAndRepairBeef(beef: Beef, allowTxidOnly?: boolean): Promise<boolean> {
+    throw new sdk.WERR_NOT_IMPLEMENTED()
+
+    const services = this.getServices()
+    const chaintracker = await services.getChainTracker()
+    const verified = await beef.verify(chaintracker)
+
+    const r = beef.verifyValid(allowTxidOnly)
+    if (!r.valid) return false
+
+    const invalidRoots: Record<number, string> = {}
+    for (const height of Object.keys(r.roots)) {
+      const isValid = await chaintracker.isValidRootForHeight(
+        r.roots[height],
+        Number(height)
+      )
+      if (!isValid) {
+        invalidRoots[height] = r.roots[height]
+      }
+    }
+
+    if (Object.keys(invalidRoots).length === 0) {
+      // There are no invalid merkle roots and the beef is structurally valid,
+      // the beef is fully verified.
+      return true
+    }
+
+    for (const heightStr of Object.keys(invalidRoots)) {
+      const hash = invalidRoots[Number(heightStr)]
+      const r = await this.reproveHeader(hash)
+    }
+
+    // All invalid BUMPs must be removed from the beef
+    // and all txid's that were proven by those BUMPs need
+    // new beefs merged into the beef.
+    // In most cases, this will be a replacement BUMP,
+    // but it may also require a deeper proof.
+  }
+
+  /**
+   * Attempt to reprove the transaction against the current chain,
+   * If a new valid proof is found and noUpdate is not true,
+   * update the proven_txs record with new block and merkle proof data.
+   * If noUpdate is true, the update to be applied is available in the returned result.
+   * 
+   * @param ptx proven_txs record to reprove
+   * @param noUpdate 
+   * @returns 
+   */
+  async reproveProven(ptx: TableProvenTx, noUpdate?: boolean): Promise<sdk.ReproveProvenResult> {
+    const r: sdk.ReproveProvenResult = { log: '', updated: undefined, unchanged: false, unavailable: false }
+    const services = this.getServices()
+    const chaintracker = await services.getChainTracker()
+
+    const mpr = await services.getMerklePath(ptx.txid)
+    if (mpr.merklePath && mpr.header) {
+      const mp = mpr.merklePath
+      const h = mpr.header
+      const leaf = mp.path[0].find(leaf => leaf.txid === true && leaf.hash === ptx.txid)
+      if (leaf) {
+        const update: Partial<TableProvenTx> = {
+          height: mp.blockHeight,
+          index: leaf.offset,
+          merklePath: mp.toBinary(),
+          merkleRoot: h.merkleRoot,
+          blockHash: h.hash
+        }
+        if (update.blockHash === ptx.blockHash) {
+          r.log += `    txid ${ptx.txid} merkle path update still based on deactivated header ${ptx.blockHash}\n`
+          r.unchanged = true
+        } else {
+          // Verify the new proof's validity.
+          const merkleRoot = mp.computeRoot(ptx.txid)
+          const isValid = await chaintracker.isValidRootForHeight(merkleRoot, update.height!)
+          const logUpdate = `      height ${ptx.height} ${ptx.height === update.height ? 'unchanged' : `-> ${update.height}`}\n`
+          r.log += `      blockHash ${ptx.blockHash} -> ${update.blockHash}\n`
+          r.log += `      merkleRoot ${ptx.merkleRoot} -> ${update.merkleRoot}\n`
+          r.log += `      index ${ptx.index} -> ${update.index}\n`
+          if (isValid) {
+            r.updated = { update, logUpdate }
+          } else {
+            r.log +=
+              `    txid ${ptx.txid} chaintracker fails to confirm updated merkle path update invalid\n` + logUpdate
+            r.unavailable = true
+          }
+        }
+      } else {
+        r.log += `    txid ${ptx.txid} merkle path update doesn't include txid\n`
+        r.unavailable = true
+      }
+    } else {
+      r.log += `    txid ${ptx.txid} merkle path update unavailable\n`
+      r.unavailable = true
+    }
+
+    if (r.updated && !noUpdate) {
+      await this.runAsStorageProvider(async sp => {
+          await sp.updateProvenTx(ptx.provenTxId, r.updated!.update)
+          r.log += `    txid ${ptx.txid} proof data updated\n` + r.updated!.logUpdate
+      })
+    }
+
+    return r
+  }
+
   async syncFromReader(
     identityKey: string,
     reader: sdk.WalletStorageSyncReader,
@@ -763,4 +924,4 @@ export class WalletStorageManager implements sdk.WalletStorage {
     }
     return stores
   }
-}
+}

package/src/storage/__test/getBeefForTransaction.test.ts

@@ -1,5 +1,4 @@
-import { Beef, ListActionsResult, ListOutputsResult } from '@bsv/sdk'
-import { WalletError } from '../../sdk/WalletError'
+import { Beef, ListActionsResult, ListOutputsResult, Utils } from '@bsv/sdk'
 import { StorageAdminStats, StorageProvider } from '../StorageProvider'
 import { Chain } from '../../sdk/types'
 import { Services } from '../../services/Services'
@@ -60,6 +59,16 @@ describe('getBeefForTransaction tests', () => {
       expect(beef.bumps.length > 0)
     }
   })
+
+  test.skip('1 obtain atomic beef hex for txid', async () => {
+    const ps = new ProtoStorage('main')
+    const txid = '4cefbe79926d6ef2cc727d8faccac186d9bb141f170411dd75bc6329f428f5a4'
+    const beef = await ps.getBeefForTxid(txid)
+    expect(beef.bumps.length > 0)
+    console.log(beef.toLogString())
+    const hex = Utils.toHex(beef.toBinaryAtomic(txid))
+    console.log(hex)
+  })
 })
 
 class ProtoStorage extends StorageProvider {

package/src/storage/methods/internalizeAction.ts

@@ -18,7 +18,7 @@ import { randomBytesBase64, verifyId, verifyOne, verifyOneOrNone } from '../../u
 import { TransactionStatus } from '../../sdk/types'
 import { EntityProvenTxReq } from '../schema/entities/EntityProvenTxReq'
 import { blockHash } from '../../services/chaintracker/chaintracks/util/blockHeaderUtilities'
-import { TableProvenTx } from '../index.client'
+import { TableProvenTx } from '../schema/tables/TableProvenTx'
 
 /**
  * Internalize Action allows a wallet to take ownership of outputs in a pre-existing transaction.
@@ -559,4 +559,4 @@ class InternalizeActionContext {
 
     basket.eo = txOut
   }
-}
+}

package/src/storage/schema/KnexMigrations.ts

@@ -73,6 +73,19 @@ export class KnexMigrations implements MigrationSource<string> {
       }
     }
 
+    migrations['2025-10-13-001 add outputs spendable index'] = {
+      async up(knex) {
+        await knex.schema.alterTable('outputs', table => {
+          table.index('spendable')
+        })
+      },
+      async down(knex) {
+        await knex.schema.alterTable('outputs', table => {
+          table.dropIndex('spendable')
+        })
+      }
+    }
+
     migrations['2025-10-18-002 add proven_tx_reqs txid index'] = {
       async up(knex) {
         await knex.schema.alterTable('proven_tx_reqs', table => {