[BUG] Unusable funds after a reorg

[kuba-4chain]

Bug Description

After a reorg on chain, BEEFs fail validation because of invalid BUMPs, making funds unspendable and any affected UTXO unusable.

Steps to Reproduce

1. Run wallet-toolbox and fund it.
2. Simulate reorg on chain.
3. Try to spend funds.

Expected Behavior

BEEFs for affected UTXOs should be updated with the new block data and should pass validation.

Actual Behavior

UTXOs became unusable because of BEEF validation error.

Stack Traces or Screenshots

Environment

• OS: [MacOS]
• Node version: [v22.12.0]
• @bsv/sdk version: [v1.6.10]
• @bsv/wallet-toolbox version: [v1.5.6]

Additional Information

The method processReorg() in /src/monitor/Monitor.ts:336 is empty and is not called anywhere.

  /**
   * Process reorg event received from Chaintracks
   *
   * Reorgs can move recent transactions to new blocks at new index positions.
   * Affected transaction proofs become invalid and must be updated.
   *
   * It is possible for a transaction to become invalid.
   *
   * Coinbase transactions always become invalid.
   */
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
  processReorg(depth: number, oldTip: BlockHeader, newTip: BlockHeader): void {
    /* */
  }

Example query to BHS for a block height of 1691204 (testnet) returning 2 blocks, showing proof that there was a fork.

curl -X 'GET' \
  'https://bhs-testnet.ops.tokenovate.com/api/v1/chain/header/byHeight?height=1691204' \
  -H 'accept: application/json'

[
  {
    "hash": "0000000000f9da26cf80f2c664e7d35c1077572e6fbcf77240cfc1cd1060ed5c",
    "version": 536870912,
    "prevBlockHash": "000000000694bd959d09a5f5e115c218569bd71e6ed160785f3f37309241a3ec",
    "merkleRoot": "d45b7d1a2f1ca67c864ac670911afdaa0d6715a39c444f4d13912dd613203855",
    "creationTimestamp": 1756460161,
    "difficultyTarget": 473696877,
    "nonce": 1310892165,
    "work": "18312763791"
  },
  {
    "hash": "0000000021a63bd0434a31e3abc47a86fe7740a10a3007495477f0324a02573a",
    "version": 536870912,
    "prevBlockHash": "000000000694bd959d09a5f5e115c218569bd71e6ed160785f3f37309241a3ec",
    "merkleRoot": "99edabd8f545e37d570c0c713f19a29a86681df58806fe580c72ed4a0d57c441",
    "creationTimestamp": 1756460627,
    "difficultyTarget": 473696877,
    "nonce": 556043778,
    "work": "18312763791"
  }
]

[tonesnotes]

With the inclusion of open source chaintracks in wallet-toolbox 1.6 it is now possible to update Monitor to make use of it's ability to drive the processReorg event handler which in turn will review ProvenTx records that must have their merkle path's updated.

This will prevent generating new invlaid BEEFs.

There are two other paths that need completion work:

1. When internalizeAction is presented a BEEF the the chaintracker rejects, an attempt to "repair" the BEEF could be made, though this is problematic in public facing services as it could be abused with intentionally invalid BEEFs. When the chaintracker validates the BEEF, any conflict with existing merkle path's in ProvenTx table needs to be resolved. These are errors that accumulate when for whatever reason reorg notification failed to trigger an update.

2. When createAction/signAction generates a beef using data from ProvenTxs, a final confirmation of BEEF validity against the chaintracker is currently done, but the code to repair the BEEF before delivering it to the user is incomplete.

[tonesnotes]

Note that in general the wallet-toolbox is very hesitant to incorporate new block headers, waiting over a minute after the most recent block header notification before incorporating it (if it isn't replaced). With BEEF based SPV, there is little advantage to relying on very young block headers.

[rob-tkn]

Thanks for the pointers, @tonesnotes. Where's the best place to learn about chaintracks (open source version)? E.g. can we deploy it separately like we've done with block-headers-service and share it between wallet-toolbox instances? What's not included in the open source version? What's its API?

[tonesnotes]

Monitor update to use open source Chaintracks has been completed on branch chain3 which is not ready to merge yet.

It is not a solution to the problem reported above. My next step is to add code to implement #2 above.

The chaintracks API's are in src/services/chaintracker/chaintracks/Api/ChaintracksApi.ts.
The ChaintracksService and ChaintracksClient are one route to sharing a chaintracking instance among multiple processes.