@bsv/wallet-toolbox 1.6.32 → 1.6.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/wallet-toolbox",
-  "version": "1.6.32",
+  "version": "1.6.34",
   "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,26 @@ 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/WERR_errors.ts

@@ -54,6 +54,11 @@ export class WERR_INVALID_PARAMETER extends WalletError {
   ) {
     super('WERR_INVALID_PARAMETER', `The ${parameter} parameter must be ${mustBe ?? 'valid.'}`)
   }
+  override toJson(): string {
+    const obj = JSON.parse(super.toJson())
+    obj.parameter = this.parameter
+    return JSON.stringify(obj)
+  }
 }
 
 /**
@@ -65,6 +70,11 @@ export class WERR_MISSING_PARAMETER extends WalletError {
   constructor(public parameter: string) {
     super('WERR_MISSING_PARAMETER', `The required ${parameter} parameter is missing.`)
   }
+  override toJson(): string {
+    const obj = JSON.parse(super.toJson())
+    obj.parameter = this.parameter
+    return JSON.stringify(obj)
+  }
 }
 
 /**
@@ -127,6 +137,12 @@ export class WERR_INSUFFICIENT_FUNDS extends WalletError {
       `Insufficient funds in the available inputs to cover the cost of the required outputs and the transaction fee (${moreSatoshisNeeded} more satoshis are needed, for a total of ${totalSatoshisNeeded}), plus whatever would be required in order to pay the fee to unlock and spend the outputs used to provide the additional satoshis.`
     )
   }
+  override toJson(): string {
+    const obj = JSON.parse(super.toJson())
+    obj.totalSatoshisNeeded = this.totalSatoshisNeeded
+    obj.moreSatoshisNeeded = this.moreSatoshisNeeded
+    return JSON.stringify(obj)
+  }
 }
 
 export class WERR_INVALID_PUBLIC_KEY extends WalletError {
@@ -144,6 +160,11 @@ export class WERR_INVALID_PUBLIC_KEY extends WalletError {
         : `The provided public key is invalid or malformed.`
     super('WERR_INVALID_PUBLIC_KEY', message)
   }
+  protected override toJson(): string {
+    const obj = JSON.parse(super.toJson())
+    obj.key = this.key
+    return JSON.stringify(obj)
+  }
 }
 
 /**
@@ -166,4 +187,17 @@ export class WERR_REVIEW_ACTIONS extends WalletError {
   ) {
     super('WERR_REVIEW_ACTIONS', 'Undelayed createAction or signAction results require review.')
   }
+  override toJson(): string {
+    const obj = JSON.parse(super.toJson())
+    obj.reviewActionResults = this.reviewActionResults
+    obj.sendWithResults = this.sendWithResults
+    obj.txid = this.txid
+    obj.tx = this.tx
+    obj.noSendChange = this.noSendChange
+    return JSON.stringify(obj)
+  }
 }
+
+/**
+ * IF YOU ADD NEW ERRORS, ALSO UPDATE THE WalletError.fromJson METHOD IN src/sdk/WalletError.ts
+ */

package/src/sdk/WalletError.ts

@@ -56,7 +56,7 @@ export class WalletError extends Error implements WalletErrorObject {
   static fromUnknown(err: unknown): WalletError {
     if (err instanceof WalletError) return err
     let name = 'WERR_UNKNOWN'
-    let message = ''
+    let message = typeof err === 'string' ? err : typeof err === 'number' ? err.toString() : ''
     let stack: string | undefined
     const details: Record<string, string> = {}
     if (err !== null && typeof err === 'object') {
@@ -116,4 +116,45 @@ export class WalletError extends Error implements WalletErrorObject {
       description: this.message
     }
   }
+
+  /**
+   * Base class default JSON serialization.
+   * Captures just the name and message properties.
+   *
+   * Override this method to safely (avoid deep, large, circular issues) serialize
+   * derived class properties.
+   *
+   * @returns stringified JSON representation of the WalletError.
+   */
+  protected toJson(): string {
+    const e = new WalletError(this.name, this.message)
+    const json = JSON.stringify({
+      isError: true,
+      name: e.name,
+      message: e.message
+    })
+    return json
+  }
+
+  /**
+   * Safely serializes a WalletError derived, WERR_REVIEW_ACTIONS (special case), Error or unknown error to JSON.
+   *
+   * Safely means avoiding deep, large, circular issues.
+   *
+   * @param error
+   * @returns stringified JSON representation of the error such that it can be desirialized to a WalletError.
+   */
+  static unknownToJson(error: unknown | WalletError): string {
+    let json: string | undefined
+    let e: WalletError | undefined
+    if (error instanceof WalletError || (typeof error === 'object' && error?.constructor.name.startsWith('WERR_'))) {
+      e = error as WalletError
+    } else if (error instanceof Error) {
+      e = new WalletError(error.name, error.message)
+    } else {
+      e = new WalletError('WERR_UNKNOWN', String(error))
+    }
+    json = e.toJson()
+    return json
+  }
 }

package/src/sdk/WalletErrorFromJson.ts

@@ -0,0 +1,80 @@
+import { WalletError } from './WalletError'
+import {
+  WERR_BAD_REQUEST,
+  WERR_BROADCAST_UNAVAILABLE,
+  WERR_INSUFFICIENT_FUNDS,
+  WERR_INTERNAL,
+  WERR_INVALID_OPERATION,
+  WERR_INVALID_PARAMETER,
+  WERR_INVALID_PUBLIC_KEY,
+  WERR_MISSING_PARAMETER,
+  WERR_NETWORK_CHAIN,
+  WERR_NOT_ACTIVE,
+  WERR_NOT_IMPLEMENTED,
+  WERR_REVIEW_ACTIONS,
+  WERR_UNAUTHORIZED
+} from './WERR_errors'
+
+/**
+ * Reconstruct the correct derived WalletError from a JSON object created by `WalletError.unknownToJson`.
+ *
+ * This function is implemented as a separate function instead of a WalletError class static
+ * to avoid circular dependencies.
+ *
+ * @param json
+ * @returns a WalletError derived error object, typically for re-throw.
+ */
+export function WalletErrorFromJson(json: object): WalletError {
+  let e: WalletError
+  const obj = json as any
+  switch (obj.name) {
+    case 'WERR_NOT_IMPLEMENTED':
+      e = new WERR_NOT_IMPLEMENTED(obj.message)
+      break
+    case 'WERR_INTERNAL':
+      e = new WERR_INTERNAL(obj.message)
+      break
+    case 'WERR_INVALID_OPERATION':
+      e = new WERR_INVALID_OPERATION(obj.message)
+      break
+    case 'WERR_BROADCAST_UNAVAILABLE':
+      e = new WERR_BROADCAST_UNAVAILABLE(obj.message)
+      break
+    case 'WERR_INVALID_PARAMETER':
+      e = new WERR_INVALID_PARAMETER(obj.parameter)
+      e.message = obj.message
+      break
+    case 'WERR_MISSING_PARAMETER':
+      e = new WERR_MISSING_PARAMETER(obj.parameter)
+      e.message = obj.message
+      break
+    case 'WERR_BAD_REQUEST':
+      e = new WERR_BAD_REQUEST(obj.message)
+      break
+    case 'WERR_NETWORK_CHAIN':
+      e = new WERR_NETWORK_CHAIN(obj.message)
+      break
+    case 'WERR_UNAUTHORIZED':
+      e = new WERR_UNAUTHORIZED(obj.message)
+      break
+    case 'WERR_NOT_ACTIVE':
+      e = new WERR_NOT_ACTIVE(obj.message)
+      break
+    case 'WERR_INSUFFICIENT_FUNDS':
+      e = new WERR_INSUFFICIENT_FUNDS(obj.totalSatoshisNeeded, obj.moreSatoshisNeeded)
+      break
+    case 'WERR_INVALID_PUBLIC_KEY':
+      e = new WERR_INVALID_PUBLIC_KEY(obj.key, 'mainnet')
+      e.message = obj.message
+      break
+    case 'WERR_REVIEW_ACTIONS':
+      e = new WERR_REVIEW_ACTIONS(obj.reviewActionResults, obj.sendWithResults, obj.txid, obj.tx, obj.noSendChange)
+      break
+    default:
+      {
+        e = new WalletError(obj.name || 'WERR_UNKNOWN', obj.message || '')
+      }
+      break
+  }
+  return e
+}

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
+}