@bsv/wallet-toolbox 2.4.3 → 2.4.20

package/docs/monitor.md

@@ -87,12 +87,12 @@ export interface MonitorDaemonSetup {
     servicesOptions?: WalletServicesOptions;
     services?: Services;
     monitor?: Monitor;
-    chaintracks?: ChaintracksClientApi;
+    chaintracks?: Chaintracks;
     startupTaskMode?: MonitorStartupTaskMode;
 }
 ```
 
-See also: [Chain](./client.md#type-chain), [ChaintracksClientApi](./services.md#interface-chaintracksclientapi), [Monitor](./monitor.md#class-monitor), [MonitorStartupTaskMode](./monitor.md#type-monitorstartuptaskmode), [Services](./services.md#class-services), [StorageKnexOptions](./storage.md#interface-storageknexoptions), [StorageProvider](./storage.md#class-storageprovider), [WalletServicesOptions](./client.md#interface-walletservicesoptions), [WalletStorageManager](./storage.md#class-walletstoragemanager)
+See also: [Chain](./client.md#type-chain), [Chaintracks](./services.md#class-chaintracks), [Monitor](./monitor.md#class-monitor), [MonitorStartupTaskMode](./monitor.md#type-monitorstartuptaskmode), [Services](./services.md#class-services), [StorageKnexOptions](./storage.md#interface-storageknexoptions), [StorageProvider](./storage.md#class-storageprovider), [WalletServicesOptions](./client.md#interface-walletservicesoptions), [WalletStorageManager](./storage.md#class-walletstoragemanager)
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
@@ -105,14 +105,13 @@ export interface MonitorOptions {
     services: Services | WalletServices;
     storage: MonitorStorage;
     chaintracks: ChaintracksClientApi;
-    chaintracksWithEvents?: ChaintracksClientApi;
+    chaintracksWithEvents?: Chaintracks;
     startupTaskMode?: MonitorStartupTaskMode;
     msecsWaitPerMerkleProofServiceReq: number;
     taskRunWaitMsecs: number;
     abandonedMsecs: number;
     unprovenAttemptsLimitTest: number;
     unprovenAttemptsLimitMain: number;
-    maxRebroadcastAttempts: number;
     callbackToken?: string;
     loadLastSSEEventId?: () => Promise<string | undefined>;
     saveLastSSEEventId?: (lastEventId: string) => Promise<void>;
@@ -123,7 +122,7 @@ export interface MonitorOptions {
 }
 ```
 
-See also: [Chain](./client.md#type-chain), [ChaintracksClientApi](./services.md#interface-chaintracksclientapi), [MonitorStartupTaskMode](./monitor.md#type-monitorstartuptaskmode), [MonitorStorage](./monitor.md#type-monitorstorage), [ProvenTransactionStatus](./client.md#interface-proventransactionstatus), [ReviewActionResult](./client.md#interface-reviewactionresult), [Services](./services.md#class-services), [WalletServices](./client.md#interface-walletservices)
+See also: [Chain](./client.md#type-chain), [Chaintracks](./services.md#class-chaintracks), [ChaintracksClientApi](./services.md#interface-chaintracksclientapi), [MonitorStartupTaskMode](./monitor.md#type-monitorstartuptaskmode), [MonitorStorage](./monitor.md#type-monitorstorage), [ProvenTransactionStatus](./client.md#interface-proventransactionstatus), [ReviewActionResult](./client.md#interface-reviewactionresult), [Services](./services.md#class-services), [WalletServices](./client.md#interface-walletservices)
 
 ###### Property EventSourceClass
 
@@ -152,19 +151,6 @@ Load persisted SSE lastEventId (e.g. from SQLite) for catchup on startup
 loadLastSSEEventId?: () => Promise<string | undefined>
 ```
 
-###### Property maxRebroadcastAttempts
-
-Maximum number of times a broadcast transaction may be reset to 'unsent' for
-rebroadcast after proof check timeout (circuit breaker).
-
-Default 0 means unlimited — the tx is rebroadcast indefinitely until a proof
-is found. Set to a positive integer to cap rebroadcast cycles; once the limit
-is reached the req is marked 'invalid'.
-
-```ts
-maxRebroadcastAttempts: number
-```
-
 ###### Property msecsWaitPerMerkleProofServiceReq
 
 How many msecs to wait after each getMerkleProof service request.
@@ -270,19 +256,18 @@ and potentially that reorgs update proofs that were already received.
 
 ```ts
 export class Monitor {
-    static createDefaultWalletMonitorOptions(chain: Chain, storage: MonitorStorage, services?: Services, chaintracks?: ChaintracksClientApi, startupTaskMode: MonitorStartupTaskMode = "none"): MonitorOptions 
+    static createDefaultWalletMonitorOptions(chain: Chain, storage: MonitorStorage, services?: Services, chaintracks?: Chaintracks, startupTaskMode: MonitorStartupTaskMode = "none"): MonitorOptions 
     options: MonitorOptions;
     services: Services | WalletServices;
     chain: Chain;
     storage: MonitorStorage;
     chaintracks: ChaintracksClientApi;
-    chaintracksWithEvents?: ChaintracksClientApi;
+    chaintracksWithEvents?: Chaintracks;
     reorgSubscriptionPromise?: Promise<string>;
     headersSubscriptionPromise?: Promise<string>;
     onTransactionBroadcasted?: (broadcastResult: ReviewActionResult) => Promise<void>;
     onTransactionProven?: (txStatus: ProvenTransactionStatus) => Promise<void>;
     onTransactionStatusChanged?: (txid: string, newStatus: string) => Promise<void>;
-    get ready(): Promise<void> 
     constructor(options: MonitorOptions) 
     async destroy(): Promise<void> 
     static readonly oneSecond = 1000;
@@ -327,7 +312,7 @@ export class Monitor {
 }
 ```
 
-See also: [BlockHeader](./client.md#interface-blockheader), [Chain](./client.md#type-chain), [ChaintracksClientApi](./services.md#interface-chaintracksclientapi), [DeactivedHeader](./monitor.md#interface-deactivedheader), [MonitorOptions](./monitor.md#interface-monitoroptions), [MonitorStartupTaskMode](./monitor.md#type-monitorstartuptaskmode), [MonitorStorage](./monitor.md#type-monitorstorage), [ProvenTransactionStatus](./client.md#interface-proventransactionstatus), [ReviewActionResult](./client.md#interface-reviewactionresult), [Services](./services.md#class-services), [TaskPurgeParams](./monitor.md#interface-taskpurgeparams), [WalletMonitorTask](./monitor.md#class-walletmonitortask), [WalletServices](./client.md#interface-walletservices)
+See also: [BlockHeader](./client.md#interface-blockheader), [Chain](./client.md#type-chain), [Chaintracks](./services.md#class-chaintracks), [ChaintracksClientApi](./services.md#interface-chaintracksclientapi), [DeactivedHeader](./monitor.md#interface-deactivedheader), [MonitorOptions](./monitor.md#interface-monitoroptions), [MonitorStartupTaskMode](./monitor.md#type-monitorstartuptaskmode), [MonitorStorage](./monitor.md#type-monitorstorage), [ProvenTransactionStatus](./client.md#interface-proventransactionstatus), [ReviewActionResult](./client.md#interface-reviewactionresult), [Services](./services.md#class-services), [TaskPurgeParams](./monitor.md#interface-taskpurgeparams), [WalletMonitorTask](./monitor.md#class-walletmonitortask), [WalletServices](./client.md#interface-walletservices)
 
 ###### Property _otherTasks
 
@@ -474,7 +459,7 @@ when transactions are MINED.
 
 ```ts
 export class TaskArcadeSSE extends WalletMonitorTask {
-    static readonly taskName = "ArcadeSSE";
+    static taskName = "ArcadeSSE";
     sseClient: ArcSSEClient | null = null;
     constructor(monitor: Monitor) 
     override async asyncSetup(): Promise<void> 
@@ -506,7 +491,7 @@ the original ProvenTxReq status is advanced to 'notifying'.
 
 ```ts
 export class TaskCheckForProofs extends WalletMonitorTask {
-    static readonly taskName = "CheckForProofs";
+    static taskName = "CheckForProofs";
     static checkNow = false;
     constructor(monitor: Monitor, public triggerMsecs = 0) 
     trigger(nowMsecsSinceEpoch: number): {
@@ -542,7 +527,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ---
 ##### Class: TaskCheckNoSends
 
-`TaskCheckNoSends` is a WalletMonitor task that retrieves merkle proofs for
+`TaskCheckNoSends` is a WalletMonitor task that retreives merkle proofs for
 'nosend' transactions that MAY have been shared externally.
 
 Unlike intentionally processed transactions, 'nosend' transactions are fully valid
@@ -554,54 +539,10 @@ managed to get mined by some external process.
 If a proof is obtained and validated, a new ProvenTx record is created and
 the original ProvenTxReq status is advanced to 'notifying'.
 
-# Aging schedule on the checkNow path
-
-When this task is triggered by a new block header (`checkNow = true`, wired in
-`Monitor.processNewBlockHeader`), it does NOT scan every `nosend` row on every
-block. The set of `nosend` rows can grow large over a wallet's lifetime
-(txs sitting in escrow, un-aborted tests, abandoned batches), and a fast,
-unfiltered scan on every block would do an unbounded number of external
-`getMerklePath` lookups per block.
-
-Instead, the row's age (now - `created_at`) determines how often it is
-eligible for a checkNow-triggered chain check. The schedule starts at "skip
-entirely" for very fresh rows (to protect in-flight batched-tx workflows
-where chained `createAction({ noSend: true, sendWith: [...] })` builds
-deliberately keep rows in `nosend` until a single terminator broadcasts the
-whole BEEF), then progresses to "every block", "hourly", "daily", and
-"weekly" as rows age:
-
-  age < 5 min                 → skip (in-flight batch protection)
-  5 min ≤ age < 1 hr          → check on every checkNow trigger
-  1 hr   ≤ age < 24 hr        → check on ~hourly cadence (block-height % 6)
-  24 hr  ≤ age < 7 days       → check on ~daily cadence  (block-height % 144)
-  age ≥ 7 days                → check on ~weekly cadence (block-height % 1008)
-
-Block-height modulo gives a deterministic, stateless way to schedule
-checks for older rows; no per-row "last checked" persistence is required.
-Each row's modulo offset is keyed by its `provenTxReqId` so that rows in
-the same age tier are staggered across the modulo cycle rather than all
-firing on the same block — `(blockHeight + provenTxReqId) % tierInterval`.
-For a wallet with N rows in tier T and tier interval K, this gives
-roughly N/K rows fired per block instead of N rows fired every K blocks.
-
-The scheduled daily cadence (no `checkNow`) is unaffected — it still scans
-every row regardless of age. That path is the once-per-day fallback that
-guarantees externally-broadcast `nosend` txs are eventually recognized
-even if the aging schedule on the checkNow path defers them.
-
 ```ts
 export class TaskCheckNoSends extends WalletMonitorTask {
-    static readonly taskName = "CheckNoSends";
+    static taskName = "CheckNoSends";
     static checkNow = false;
-    static readonly tier0FreshSkipMsecs = 5 * 60 * 1000;
-    static readonly tier1EveryBlockMsecs = 60 * 60 * 1000;
-    static readonly tier2HourlyMsecs = 24 * 60 * 60 * 1000;
-    static readonly tier3DailyMsecs = 7 * 24 * 60 * 60 * 1000;
-    static readonly tier2BlockInterval = 6;
-    static readonly tier3BlockInterval = 144;
-    static readonly tier4BlockInterval = 1008;
-    static shouldCheckOnCheckNow(createdAt: Date, nowMs: number, currentBlockHeight: number, provenTxReqId: number): boolean 
     constructor(monitor: Monitor, public triggerMsecs = Monitor.oneDay * 1) 
     trigger(nowMsecsSinceEpoch: number): {
         run: boolean;
@@ -621,30 +562,6 @@ listener can set this true to cause
 static checkNow = false
 ```
 
-###### Property tier0FreshSkipMsecs
-
-Aging-schedule constants for the `checkNow` path. Rows below `tier0FreshSkipMsecs`
-are never checked via checkNow (batched-tx protection). Rows from tier 0 up
-to `tier1EveryBlockMsecs` are checked on every checkNow trigger. Beyond that,
-checks happen on `block-height % tierNBlockInterval === 0` cadences with
-growing intervals. The scheduled daily cadence (no checkNow) is unaffected.
-
-```ts
-static readonly tier0FreshSkipMsecs = 5 * 60 * 1000
-```
-
-###### Method shouldCheckOnCheckNow
-
-Decide whether a single `nosend` row should be chain-checked on the
-current `checkNow` trigger, based on its age, the current block
-height, and its `provenTxReqId` (used to stagger same-tier rows
-across the modulo cycle). See class docstring for the full schedule
-and staggering rationale.
-
-```ts
-static shouldCheckOnCheckNow(createdAt: Date, nowMs: number, currentBlockHeight: number, provenTxReqId: number): boolean 
-```
-
 ###### Method trigger
 
 Normally triggered by checkNow getting set by new block header found event from chaintracks
@@ -662,7 +579,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ```ts
 export class TaskClock extends WalletMonitorTask {
-    static readonly taskName = "Clock";
+    static taskName = "Clock";
     nextMinute: number;
     constructor(monitor: Monitor, public triggerMsecs = 1 * Monitor.oneSecond) 
     trigger(nowMsecsSinceEpoch: number): {
@@ -689,7 +606,7 @@ outputs are not spendable.
 
 ```ts
 export class TaskFailAbandoned extends WalletMonitorTask {
-    static readonly taskName = "FailAbandoned";
+    static taskName = "FailAbandoned";
     constructor(monitor: Monitor, public triggerMsecs = 1000 * 60 * 5) 
     trigger(nowMsecsSinceEpoch: number): {
         run: boolean;
@@ -707,7 +624,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ```ts
 export class TaskMineBlock extends WalletMonitorTask {
-    static readonly taskName = "MineBlock";
+    static taskName = "MineBlock";
     static mineNow = false;
     constructor(monitor: Monitor, public triggerMsecs = 10 * Monitor.oneMinute) 
     trigger(nowMsecsSinceEpoch: number): {
@@ -726,7 +643,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ```ts
 export class TaskMonitorCallHistory extends WalletMonitorTask {
-    static readonly taskName = "MonitorCallHistory";
+    static taskName = "MonitorCallHistory";
     constructor(monitor: Monitor, public triggerMsecs = Monitor.oneMinute * 12) 
     trigger(nowMsecsSinceEpoch: number): {
         run: boolean;
@@ -755,7 +672,7 @@ with that header height as the limit for which proofs are accepted.
 
 ```ts
 export class TaskNewHeader extends WalletMonitorTask {
-    static readonly taskName = "NewHeader";
+    static taskName = "NewHeader";
     header?: BlockHeader;
     queuedHeader?: BlockHeader;
     queuedHeaderWhen?: Date;
@@ -792,8 +709,9 @@ See also: [BlockHeader](./client.md#interface-blockheader)
 
 ###### Method asyncSetup
 
-This is a temporary incomplete solution for which a full chaintracker
-with new header and reorg event notification is required.
+This task intentionally polls for new headers. Reorganization notification is
+outside this task's current contract and requires a chaintracker event source
+before it can be added without changing monitor behavior.
 
 New header events drive retrieving merklePaths for newly mined transactions.
 This implementation performs this function.
@@ -815,7 +733,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ```ts
 export class TaskPurge extends WalletMonitorTask {
-    static readonly taskName = "Purge";
+    static taskName = "Purge";
     static checkNow = false;
     constructor(monitor: Monitor, public params: TaskPurgeParams, public triggerMsecs = 0) 
     trigger(nowMsecsSinceEpoch: number): {
@@ -865,7 +783,7 @@ createAction fails to verify a generated beef against the chaintracker.
 
 ```ts
 export class TaskReorg extends WalletMonitorTask {
-    static readonly taskName = "Reorg";
+    static taskName = "Reorg";
     process: DeactivedHeader[] = [];
     constructor(monitor: Monitor, public agedMsecs = Monitor.oneMinute * 10, public maxRetries = 3) 
     trigger(nowMsecsSinceEpoch: number): {
@@ -906,7 +824,7 @@ back to 'unfail' so existing recovery handling can re-process them.
 
 ```ts
 export class TaskReviewDoubleSpends extends WalletMonitorTask {
-    static readonly taskName = "ReviewDoubleSpends";
+    static taskName = "ReviewDoubleSpends";
     static checkNow = false;
     triggerNextMsecs: number;
     constructor(monitor: Monitor, public triggerMsecs = Monitor.oneMinute * 12, public reviewLimit = 100, public minAgeMinutes = 60, public triggerQuickMsecs = Monitor.oneMinute * 1) 
@@ -936,7 +854,7 @@ the currently canonical merkleRoot at a height no longer matches stored proven_t
 
 ```ts
 export class TaskReviewProvenTxs extends WalletMonitorTask {
-    static readonly taskName = "ReviewProvenTxs";
+    static taskName = "ReviewProvenTxs";
     static checkNow = false;
     triggerNextMsecs: number;
     constructor(monitor: Monitor, public triggerMsecs = Monitor.oneMinute * 10, public maxHeightsPerRun = 100, public minBlockAge = 100, public triggerQuickMsecs = Monitor.oneMinute * 1) 
@@ -966,7 +884,7 @@ Looks for reqs with 'invalid' status that have corresonding transactions with st
 
 ```ts
 export class TaskReviewStatus extends WalletMonitorTask {
-    static readonly taskName = "ReviewStatus";
+    static taskName = "ReviewStatus";
     static checkNow = false;
     constructor(monitor: Monitor, public triggerMsecs = 1000 * 60 * 15, public agedMsecs = 1000 * 60 * 5) 
     trigger(nowMsecsSinceEpoch: number): {
@@ -997,7 +915,7 @@ The task itself is disabled and will not run on a schedule; review must be trigg
 
 ```ts
 export class TaskReviewUtxos extends WalletMonitorTask {
-    static readonly taskName = "ReviewUtxos";
+    static taskName = "ReviewUtxos";
     static checkNow = false;
     constructor(monitor: Monitor, public triggerMsecs = 0, public userLimit = 10, public userOffset = 0, public tags: string[] = ["release", "all"]) 
     trigger(_nowMsecsSinceEpoch: number): {
@@ -1017,7 +935,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ```ts
 export class TaskSendWaiting extends WalletMonitorTask {
-    static readonly taskName = "SendWaiting";
+    static taskName = "SendWaiting";
     lastSendingRunMsecsSinceEpoch: number | undefined;
     includeSending: boolean = true;
     triggerNextMsecs: number;
@@ -1082,7 +1000,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ```ts
 export class TaskSyncWhenIdle extends WalletMonitorTask {
-    static readonly taskName = "SyncWhenIdle";
+    static taskName = "SyncWhenIdle";
     constructor(monitor: Monitor, public triggerMsecs = 1000 * 60 * 1) 
     trigger(nowMsecsSinceEpoch: number): {
         run: boolean;
@@ -1109,7 +1027,7 @@ If it fails (to find a merklePath), returns the req status to 'invalid'.
 
 ```ts
 export class TaskUnFail extends WalletMonitorTask {
-    static readonly taskName = "UnFail";
+    static taskName = "UnFail";
     static checkNow = false;
     constructor(monitor: Monitor, public triggerMsecs = Monitor.oneMinute * 10) 
     trigger(nowMsecsSinceEpoch: number): {
@@ -1225,7 +1143,7 @@ depending on chaintracks succeeding on proof verification.
 Increments attempts if proofs where requested.
 
 ```ts
-export async function getProofs(task: WalletMonitorTask, reqs: TableProvenTxReq[], maxAcceptableHeight: number, indent = 0, countsAsAttempt = false, ignoreStatus = false): Promise<{
+export async function getProofs(task: WalletMonitorTask, reqs: TableProvenTxReq[], indent = 0, countsAsAttempt = false, ignoreStatus = false, maxAcceptableHeight: number): Promise<{
     proven: TableProvenTxReq[];
     invalid: TableProvenTxReq[];
     log: string;