@bsv/wallet-toolbox 1.6.33 → 1.6.34

package/docs/monitor.md

@@ -309,6 +309,18 @@ callOnProvenTransaction(txStatus: ProvenTransactionStatus): void
 ```
 See also: [ProvenTransactionStatus](./client.md#interface-proventransactionstatus)
 
+###### Method processHeader
+
+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.
+
+```ts
+processHeader(header: BlockHeader): void 
+```
+See also: [BlockHeader](./client.md#interface-blockheader)
+
 ###### Method processNewBlockHeader
 
 Process new chain header event received from Chaintracks
@@ -633,7 +645,7 @@ They must be shifted out as they are processed.
 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.
@@ -643,17 +655,8 @@ It is very disruptive to update a proven_txs record because:
 - 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.
 
 ```ts
 export class TaskReorg extends WalletMonitorTask {
@@ -669,6 +672,25 @@ export class TaskReorg extends WalletMonitorTask {
 
 See also: [DeactivedHeader](./monitor.md#interface-deactivedheader), [Monitor](./monitor.md#class-monitor), [WalletMonitorTask](./monitor.md#class-walletmonitortask)
 
+###### Method trigger
+
+Shift aged deactivated headers onto `process` array.
+
+```ts
+trigger(nowMsecsSinceEpoch: number): {
+    run: boolean;
+} 
+```
+
+Returns
+
+`run` true iff there are aged deactivated headers to process.
+
+Argument Details
+
++ **nowMsecsSinceEpoch**
+  + current time in milliseconds since epoch.
+
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---

package/docs/storage.md

@@ -4335,6 +4335,9 @@ export class WalletStorageManager implements sdk.WalletStorage {
     async findOutputBaskets(args: sdk.FindOutputBasketsArgs): Promise<TableOutputBasket[]> 
     async findOutputs(args: sdk.FindOutputsArgs): Promise<TableOutput[]> 
     async findProvenTxReqs(args: sdk.FindProvenTxReqsArgs): Promise<TableProvenTxReq[]> 
+    async reproveHeader(deactivatedHash: string): Promise<sdk.ReproveHeaderResult> 
+    async verifyAndRepairBeef(beef: Beef, allowTxidOnly?: boolean): Promise<boolean> 
+    async reproveProven(ptx: TableProvenTx, noUpdate?: boolean): Promise<sdk.ReproveProvenResult> 
     async syncFromReader(identityKey: string, reader: sdk.WalletStorageSyncReader, activeSync?: sdk.WalletStorageSync, log: string = ""): Promise<{
         inserts: number;
         updates: number;
@@ -4352,7 +4355,7 @@ export class WalletStorageManager implements sdk.WalletStorage {
 }
 ```
 
-See also: [AuthId](./client.md#interface-authid), [FindCertificatesArgs](./client.md#interface-findcertificatesargs), [FindOutputBasketsArgs](./client.md#interface-findoutputbasketsargs), [FindOutputsArgs](./client.md#interface-findoutputsargs), [FindProvenTxReqsArgs](./client.md#interface-findproventxreqsargs), [StorageCreateActionResult](./client.md#interface-storagecreateactionresult), [StorageInternalizeActionResult](./client.md#interface-storageinternalizeactionresult), [StorageProcessActionArgs](./client.md#interface-storageprocessactionargs), [StorageProcessActionResults](./client.md#interface-storageprocessactionresults), [StorageProvider](./storage.md#class-storageprovider), [TableCertificate](./storage.md#interface-tablecertificate), [TableCertificateX](./storage.md#interface-tablecertificatex), [TableOutput](./storage.md#interface-tableoutput), [TableOutputBasket](./storage.md#interface-tableoutputbasket), [TableProvenTxReq](./storage.md#interface-tableproventxreq), [TableSettings](./storage.md#interface-tablesettings), [TableUser](./storage.md#interface-tableuser), [ValidCreateActionArgs](./client.md#interface-validcreateactionargs), [ValidListActionsArgs](./client.md#interface-validlistactionsargs), [ValidListCertificatesArgs](./client.md#interface-validlistcertificatesargs), [ValidListOutputsArgs](./client.md#interface-validlistoutputsargs), [WalletServices](./client.md#interface-walletservices), [WalletStorage](./client.md#interface-walletstorage), [WalletStorageInfo](./client.md#interface-walletstorageinfo), [WalletStorageProvider](./client.md#interface-walletstorageprovider), [WalletStorageReader](./client.md#interface-walletstoragereader), [WalletStorageSync](./client.md#interface-walletstoragesync), [WalletStorageSyncReader](./client.md#interface-walletstoragesyncreader), [WalletStorageWriter](./client.md#interface-walletstoragewriter), [createAction](./storage.md#function-createaction), [internalizeAction](./storage.md#function-internalizeaction), [listActions](./storage.md#function-listactions), [listCertificates](./storage.md#function-listcertificates), [listOutputs](./storage.md#function-listoutputs), [processAction](./storage.md#function-processaction)
+See also: [AuthId](./client.md#interface-authid), [FindCertificatesArgs](./client.md#interface-findcertificatesargs), [FindOutputBasketsArgs](./client.md#interface-findoutputbasketsargs), [FindOutputsArgs](./client.md#interface-findoutputsargs), [FindProvenTxReqsArgs](./client.md#interface-findproventxreqsargs), [ReproveHeaderResult](./client.md#interface-reproveheaderresult), [ReproveProvenResult](./client.md#interface-reproveprovenresult), [StorageCreateActionResult](./client.md#interface-storagecreateactionresult), [StorageInternalizeActionResult](./client.md#interface-storageinternalizeactionresult), [StorageProcessActionArgs](./client.md#interface-storageprocessactionargs), [StorageProcessActionResults](./client.md#interface-storageprocessactionresults), [StorageProvider](./storage.md#class-storageprovider), [TableCertificate](./storage.md#interface-tablecertificate), [TableCertificateX](./storage.md#interface-tablecertificatex), [TableOutput](./storage.md#interface-tableoutput), [TableOutputBasket](./storage.md#interface-tableoutputbasket), [TableProvenTx](./storage.md#interface-tableproventx), [TableProvenTxReq](./storage.md#interface-tableproventxreq), [TableSettings](./storage.md#interface-tablesettings), [TableUser](./storage.md#interface-tableuser), [ValidCreateActionArgs](./client.md#interface-validcreateactionargs), [ValidListActionsArgs](./client.md#interface-validlistactionsargs), [ValidListCertificatesArgs](./client.md#interface-validlistcertificatesargs), [ValidListOutputsArgs](./client.md#interface-validlistoutputsargs), [WalletServices](./client.md#interface-walletservices), [WalletStorage](./client.md#interface-walletstorage), [WalletStorageInfo](./client.md#interface-walletstorageinfo), [WalletStorageProvider](./client.md#interface-walletstorageprovider), [WalletStorageReader](./client.md#interface-walletstoragereader), [WalletStorageSync](./client.md#interface-walletstoragesync), [WalletStorageSyncReader](./client.md#interface-walletstoragesyncreader), [WalletStorageWriter](./client.md#interface-walletstoragewriter), [createAction](./storage.md#function-createaction), [internalizeAction](./storage.md#function-internalizeaction), [listActions](./storage.md#function-listactions), [listCertificates](./storage.md#function-listcertificates), [listOutputs](./storage.md#function-listoutputs), [processAction](./storage.md#function-processaction)
 
 ###### Constructor
 
@@ -4470,6 +4473,39 @@ Throws
 
 WERR_INVALID_PARAMETER if canMakeAvailable returns false.
 
+###### Method reproveHeader
+
+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.
+
+```ts
+async reproveHeader(deactivatedHash: string): Promise<sdk.ReproveHeaderResult> 
+```
+See also: [ReproveHeaderResult](./client.md#interface-reproveheaderresult)
+
+Argument Details
+
++ **deactivatedHash**
+  + An orphaned header than may have served as a proof source for proven_txs records.
+
+###### Method reproveProven
+
+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.
+
+```ts
+async reproveProven(ptx: TableProvenTx, noUpdate?: boolean): Promise<sdk.ReproveProvenResult> 
+```
+See also: [ReproveProvenResult](./client.md#interface-reproveprovenresult), [TableProvenTx](./storage.md#interface-tableproventx)
+
+Argument Details
+
++ **ptx**
+  + proven_txs record to reprove
+
 ###### Method runAsSync
 
 ```ts
@@ -4499,6 +4535,18 @@ Argument Details
 + **storageIdentityKey**
   + of current backup storage provider that is to become the new active provider.
 
+###### Method verifyAndRepairBeef
+
+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.
+
+```ts
+async verifyAndRepairBeef(beef: Beef, allowTxidOnly?: boolean): Promise<boolean> 
+```
+
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---