@bsv/wallet-toolbox 2.1.27 → 2.1.28

package/docs/monitor.md

@@ -542,7 +542,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ---
 ##### Class: TaskCheckNoSends
 
-`TaskCheckNoSends` is a WalletMonitor task that retreives merkle proofs for
+`TaskCheckNoSends` is a WalletMonitor task that retrieves merkle proofs for
 'nosend' transactions that MAY have been shared externally.
 
 Unlike intentionally processed transactions, 'nosend' transactions are fully valid
@@ -554,10 +554,54 @@ 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 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;
@@ -577,6 +621,30 @@ 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

package/docs/storage.md

@@ -22,25 +22,25 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | | | |
 | --- | --- | --- |
-| [AdminStatsResult](#interface-adminstatsresult) | [PostReqsToNetworkResult](#interface-postreqstonetworkresult) | [TableOutput](#interface-tableoutput) |
-| [AggregatePostBeefTxResult](#interface-aggregatepostbeeftxresult) | [ProvenTxFromTxidResult](#interface-proventxfromtxidresult) | [TableOutputBasket](#interface-tableoutputbasket) |
-| [CommitNewTxResults](#interface-commitnewtxresults) | [ProvenTxReqHistory](#interface-proventxreqhistory) | [TableOutputTag](#interface-tableoutputtag) |
-| [EntitySyncMap](#interface-entitysyncmap) | [ProvenTxReqHistorySummaryApi](#interface-proventxreqhistorysummaryapi) | [TableOutputTagMap](#interface-tableoutputtagmap) |
-| [GenerateChangeSdkChangeInput](#interface-generatechangesdkchangeinput) | [ProvenTxReqNotify](#interface-proventxreqnotify) | [TableOutputX](#interface-tableoutputx) |
-| [GenerateChangeSdkChangeOutput](#interface-generatechangesdkchangeoutput) | [StorageAdminStats](#interface-storageadminstats) | [TableProvenTx](#interface-tableproventx) |
-| [GenerateChangeSdkInput](#interface-generatechangesdkinput) | [StorageIdbOptions](#interface-storageidboptions) | [TableProvenTxReq](#interface-tableproventxreq) |
-| [GenerateChangeSdkOutput](#interface-generatechangesdkoutput) | [StorageIdbSchema](#interface-storageidbschema) | [TableProvenTxReqDynamics](#interface-tableproventxreqdynamics) |
-| [GenerateChangeSdkParams](#interface-generatechangesdkparams) | [StorageKnexOptions](#interface-storageknexoptions) | [TableSettings](#interface-tablesettings) |
-| [GenerateChangeSdkResult](#interface-generatechangesdkresult) | [StorageProviderOptions](#interface-storageprovideroptions) | [TableSyncState](#interface-tablesyncstate) |
-| [GenerateChangeSdkStorageChange](#interface-generatechangesdkstoragechange) | [StorageReaderOptions](#interface-storagereaderoptions) | [TableTransaction](#interface-tabletransaction) |
-| [GetReqsAndBeefDetail](#interface-getreqsandbeefdetail) | [StorageReaderWriterOptions](#interface-storagereaderwriteroptions) | [TableTxLabel](#interface-tabletxlabel) |
-| [GetReqsAndBeefResult](#interface-getreqsandbeefresult) | [SyncError](#interface-syncerror) | [TableTxLabelMap](#interface-tabletxlabelmap) |
-| [ListActionsSpecOp](#interface-listactionsspecop) | [SyncMap](#interface-syncmap) | [TableUser](#interface-tableuser) |
-| [ListOutputsSpecOp](#interface-listoutputsspecop) | [TableCertificate](#interface-tablecertificate) | [ValidateGenerateChangeSdkParamsResult](#interface-validategeneratechangesdkparamsresult) |
-| [MonitorAdminContext](#interface-monitoradmincontext) | [TableCertificateField](#interface-tablecertificatefield) | [VerifyAndRepairBeefResult](#interface-verifyandrepairbeefresult) |
-| [MonitorAdminContextConfig](#interface-monitoradmincontextconfig) | [TableCertificateX](#interface-tablecertificatex) | [WalletStorageServerOptions](#interface-walletstorageserveroptions) |
-| [PostBeefResultForTxidApi](#interface-postbeefresultfortxidapi) | [TableCommission](#interface-tablecommission) | [XValidCreateActionOutput](#interface-xvalidcreateactionoutput) |
-| [PostReqsToNetworkDetails](#interface-postreqstonetworkdetails) | [TableMonitorEvent](#interface-tablemonitorevent) |  |
+| [AdminStatsResult](#interface-adminstatsresult) | [PostReqsToNetworkResult](#interface-postreqstonetworkresult) | [TableMonitorEvent](#interface-tablemonitorevent) |
+| [AggregatePostBeefTxResult](#interface-aggregatepostbeeftxresult) | [ProvenTxFromTxidResult](#interface-proventxfromtxidresult) | [TableOutput](#interface-tableoutput) |
+| [CommitNewTxResults](#interface-commitnewtxresults) | [ProvenTxReqHistory](#interface-proventxreqhistory) | [TableOutputBasket](#interface-tableoutputbasket) |
+| [EntitySyncMap](#interface-entitysyncmap) | [ProvenTxReqHistorySummaryApi](#interface-proventxreqhistorysummaryapi) | [TableOutputTag](#interface-tableoutputtag) |
+| [GenerateChangeSdkChangeInput](#interface-generatechangesdkchangeinput) | [ProvenTxReqNotify](#interface-proventxreqnotify) | [TableOutputTagMap](#interface-tableoutputtagmap) |
+| [GenerateChangeSdkChangeOutput](#interface-generatechangesdkchangeoutput) | [SpentInputTransition](#interface-spentinputtransition) | [TableOutputX](#interface-tableoutputx) |
+| [GenerateChangeSdkInput](#interface-generatechangesdkinput) | [StorageAdminStats](#interface-storageadminstats) | [TableProvenTx](#interface-tableproventx) |
+| [GenerateChangeSdkOutput](#interface-generatechangesdkoutput) | [StorageIdbOptions](#interface-storageidboptions) | [TableProvenTxReq](#interface-tableproventxreq) |
+| [GenerateChangeSdkParams](#interface-generatechangesdkparams) | [StorageIdbSchema](#interface-storageidbschema) | [TableProvenTxReqDynamics](#interface-tableproventxreqdynamics) |
+| [GenerateChangeSdkResult](#interface-generatechangesdkresult) | [StorageKnexOptions](#interface-storageknexoptions) | [TableSettings](#interface-tablesettings) |
+| [GenerateChangeSdkStorageChange](#interface-generatechangesdkstoragechange) | [StorageProviderOptions](#interface-storageprovideroptions) | [TableSyncState](#interface-tablesyncstate) |
+| [GetReqsAndBeefDetail](#interface-getreqsandbeefdetail) | [StorageReaderOptions](#interface-storagereaderoptions) | [TableTransaction](#interface-tabletransaction) |
+| [GetReqsAndBeefResult](#interface-getreqsandbeefresult) | [StorageReaderWriterOptions](#interface-storagereaderwriteroptions) | [TableTxLabel](#interface-tabletxlabel) |
+| [ListActionsSpecOp](#interface-listactionsspecop) | [SyncError](#interface-syncerror) | [TableTxLabelMap](#interface-tabletxlabelmap) |
+| [ListOutputsSpecOp](#interface-listoutputsspecop) | [SyncMap](#interface-syncmap) | [TableUser](#interface-tableuser) |
+| [MonitorAdminContext](#interface-monitoradmincontext) | [TableCertificate](#interface-tablecertificate) | [ValidateGenerateChangeSdkParamsResult](#interface-validategeneratechangesdkparamsresult) |
+| [MonitorAdminContextConfig](#interface-monitoradmincontextconfig) | [TableCertificateField](#interface-tablecertificatefield) | [VerifyAndRepairBeefResult](#interface-verifyandrepairbeefresult) |
+| [PostBeefResultForTxidApi](#interface-postbeefresultfortxidapi) | [TableCertificateX](#interface-tablecertificatex) | [WalletStorageServerOptions](#interface-walletstorageserveroptions) |
+| [PostReqsToNetworkDetails](#interface-postreqstonetworkdetails) | [TableCommission](#interface-tablecommission) | [XValidCreateActionOutput](#interface-xvalidcreateactionoutput) |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
@@ -588,6 +588,26 @@ export interface ProvenTxReqNotify {
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Interface: SpentInputTransition
+
+```ts
+export interface SpentInputTransition {
+    outputId: number;
+    setSpentBy: boolean;
+}
+```
+
+###### Property setSpentBy
+
+true if the call set spentBy; false if only spendable was flipped.
+
+```ts
+setSpentBy: boolean
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Interface: StorageAdminStats
 
@@ -4712,12 +4732,13 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | [listOutputs](#function-listoutputs) | [purgeDataIdb](#function-purgedataidb) | [upgradeUsers](#function-upgradeusers) |
 | [listOutputsIdb](#function-listoutputsidb) | [redeemServiceCharges](#function-redeemservicecharges) | [validateDate](#function-validatedate) |
 | [lockScriptWithKeyOffsetFromPubKey](#function-lockscriptwithkeyoffsetfrompubkey) | [renderAdminPage](#function-renderadminpage) | [validateEntities](#function-validateentities) |
-| [markStaleInputsAsSpent](#function-markstaleinputsasspent) | [reviewStatus](#function-reviewstatus) | [validateEntity](#function-validateentity) |
-| [matchesCertificateFieldPartial](#function-matchescertificatefieldpartial) | [reviewStatusIdb](#function-reviewstatusidb) | [validateGenerateChangeSdkParams](#function-validategeneratechangesdkparams) |
-| [matchesCertificatePartial](#function-matchescertificatepartial) | [setDisableDoubleSpendCheckForTest](#function-setdisabledoublespendcheckfortest) | [validateGenerateChangeSdkResult](#function-validategeneratechangesdkresult) |
-| [matchesCommissionPartial](#function-matchescommissionpartial) | [shareReqsWithWorld](#function-sharereqswithworld) | [validateStorageFeeModel](#function-validatestoragefeemodel) |
-| [matchesMonitorEventPartial](#function-matchesmonitoreventpartial) | [transactionInputSize](#function-transactioninputsize) | [validateSyncChunkEntities](#function-validatesyncchunkentities) |
-| [matchesOutputBasketPartial](#function-matchesoutputbasketpartial) | [transactionOutputSize](#function-transactionoutputsize) | [varUintSize](#function-varuintsize) |
+| [markStaleInputsAsSpent](#function-markstaleinputsasspent) | [restoreInputsToSpendable](#function-restoreinputstospendable) | [validateEntity](#function-validateentity) |
+| [markUserInputsSpent](#function-markuserinputsspent) | [reviewStatus](#function-reviewstatus) | [validateGenerateChangeSdkParams](#function-validategeneratechangesdkparams) |
+| [matchesCertificateFieldPartial](#function-matchescertificatefieldpartial) | [reviewStatusIdb](#function-reviewstatusidb) | [validateGenerateChangeSdkResult](#function-validategeneratechangesdkresult) |
+| [matchesCertificatePartial](#function-matchescertificatepartial) | [setDisableDoubleSpendCheckForTest](#function-setdisabledoublespendcheckfortest) | [validateStorageFeeModel](#function-validatestoragefeemodel) |
+| [matchesCommissionPartial](#function-matchescommissionpartial) | [shareReqsWithWorld](#function-sharereqswithworld) | [validateSyncChunkEntities](#function-validatesyncchunkentities) |
+| [matchesMonitorEventPartial](#function-matchesmonitoreventpartial) | [transactionInputSize](#function-transactioninputsize) | [varUintSize](#function-varuintsize) |
+| [matchesOutputBasketPartial](#function-matchesoutputbasketpartial) | [transactionOutputSize](#function-transactionoutputsize) |  |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
@@ -4916,7 +4937,17 @@ A "wallet payment" adds an outputs value to the wallet's change "balance". These
 Processing starts with simple validation and then checks for a pre-existing transaction.
 If the transaction is already known to the user, then the outputs are reviewed against the existing outputs treatment,
 and merge rules are added to the arguments passed to the storage layer.
-The existing transaction must be in the 'unproven' or 'completed' status. Any other status is an error.
+
+The existing transaction's `status` determines what the merge path does next:
+ - `'unproven'` or `'completed'`: outputs are merged into the existing record. The transaction status is left as-is.
+ - `'nosend'`: an ambiguous case. The transaction was created with `noSend: true` and may have been externally
+   broadcast, may be sitting in a sendWith chain, or may be stuck mid-flight. The merge path treats the
+   `internalizeAction` call as explicit authorization to advance the lifecycle. Specifically: `transactions.status`
+   is promoted to `'completed'` (when a BUMP is included in the BEEF) or `'unproven'` (otherwise), and the
+   `proven_tx_req` is moved out of `'nosend'` so Monitor's standard proof-fetching flow can finalize it.
+   This makes the `internalizeAction` semantics consistent regardless of whether the originator shares the
+   same storage as the internalizer or not.
+ - Any other status: an error.
 
 When the transaction already exists, the description is updated. The isOutgoing sense is not changed.
 
@@ -5070,6 +5101,17 @@ See also: [AggregatePostBeefTxResult](./storage.md#interface-aggregatepostbeeftx
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Function: markUserInputsSpent
+
+```ts
+export async function markUserInputsSpent(storage: StorageProvider, userId: number, tx: BsvTransaction, transactionId: number): Promise<SpentInputTransition[]> 
+```
+
+See also: [SpentInputTransition](./storage.md#interface-spentinputtransition), [StorageProvider](./storage.md#class-storageprovider)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Function: matchesCertificateFieldPartial
 
@@ -5366,6 +5408,17 @@ export function renderAdminPage(): string
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+##### Function: restoreInputsToSpendable
+
+```ts
+export async function restoreInputsToSpendable(storage: StorageProvider, transitions: SpentInputTransition[]): Promise<void> 
+```
+
+See also: [SpentInputTransition](./storage.md#interface-spentinputtransition), [StorageProvider](./storage.md#class-storageprovider)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ##### Function: reviewStatus
 
@@ -5900,13 +5953,36 @@ getLabelToSpecOp: () => Record<string, ListActionsSpecOp> = () => {
             labelsToIntercept: ["abort"],
             setStatusFilter: () => ["nosend"],
             postProcess: async (s: StorageProvider, auth: AuthId, vargs: Validation.ValidListActionsArgs, specOpLabels: string[], txs: Array<Partial<TableTransaction>>): Promise<void> => {
-                if (specOpLabels.includes("abort")) {
-                    for (const tx of txs) {
-                        if (tx.status === "nosend") {
-                            await s.abortAction(auth, { reference: tx.reference! });
-                            tx.status = "failed";
+                if (!specOpLabels.includes("abort"))
+                    return;
+                const candidates = txs.filter(tx => tx.status === "nosend" && !!tx.txid);
+                const candidateTxids = candidates.map(tx => tx.txid as string);
+                const protectedTxids = new Set<string>();
+                if (candidateTxids.length > 0) {
+                    const services = s.getServices();
+                    try {
+                        const r = await services.getStatusForTxids(candidateTxids);
+                        if (r.status === "success") {
+                            for (const result of r.results) {
+                                if (result.status === "mined" || result.status === "known") {
+                                    protectedTxids.add(result.txid);
+                                }
+                            }
                         }
                     }
+                    catch {
+                    }
+                }
+                for (const tx of txs) {
+                    if (tx.status !== "nosend")
+                        continue;
+                    if (tx.txid && protectedTxids.has(tx.txid)) {
+                        continue;
+                    }
+                    const result = await s.abortAction(auth, { reference: tx.reference! });
+                    if (result.aborted) {
+                        tx.status = "failed";
+                    }
                 }
             }
         },