Allow setting custom threshold when running `VtxoManager.renewVtxos()`

[gringokiwi]

Context

VtxoManager.renewVtxos() does not accept a custom threshold argument, making it impossible to renew only VTXOs that are urgently expiring (beyond the globally configured threshold) without reconstructing the manager with a different config.

The underlying getExpiringVtxos(thresholdMs?: number) already accepts an optional override, but renewVtxos() uses either settlementConfig.vtxoThreshold or DEFAULT_RENEWAL_CONFIG.thresholdMs (72 hours) — with no way for callers to pass a different threshold at call time.

The VTXO management docs previously showed a threshold argument for renewVtxos() and getExpiringVtxos(), but this no longer matches the actual API (and the docs now reference a stale thresholdPercentage parameter that doesn't exist in code — a separate docs cleanup may be warranted).

---

Affected Components

• src/wallet/vtxo-manager.ts — renewVtxos() at line 625, getExpiringVtxos() at line 567
• Interface — IVtxoManager.renewVtxos() (line 368): signature must be updated in parallel
• Docs — wallets/v0.4/advanced/vtxo-management.mdx in arkade-os/docs (references stale thresholdPercentage and an old renewVtxos() signature)

---

Root Cause

renewVtxos() hardcodes the threshold resolution:

// vtxo-manager.ts ~L637
const vtxos = await this.getExpiringVtxos(
    this.settlementConfig !== false &&
        this.settlementConfig?.vtxoThreshold !== undefined
        ? this.settlementConfig.vtxoThreshold * 1000
        : DEFAULT_RENEWAL_CONFIG.thresholdMs
);

getExpiringVtxos already supports an override parameter; renewVtxos simply doesn't expose it.

---

Suggested Approach

Option A — Add thresholdMs param (matches existing internal API)

async renewVtxos(
    eventCallback?: (event: SettlementEvent) => void,
    thresholdMs?: number
): Promise<string>

Pass thresholdMs through to getExpiringVtxos() when provided.

Option B — Add thresholdSeconds param (matches SettlementConfig.vtxoThreshold units)

async renewVtxos(
    eventCallback?: (event: SettlementEvent) => void,
    options?: { thresholdSeconds?: number }
): Promise<string>

Converts to ms before passing to getExpiringVtxos(). More consistent with the rest of the public API.

Option B is preferred for consistency with SettlementConfig.vtxoThreshold (which uses seconds), though either approach works. An options object future-proofs the API better than positional params.

---

Changes Required

1. src/wallet/vtxo-manager.ts

   • Update renewVtxos() signature to accept optional threshold
   • Update the IVtxoManager interface accordingly
   • Pass the threshold override to getExpiringVtxos()

2. arkade-os/docs — wallets/v0.4/advanced/vtxo-management.mdx

   • Update code examples to reflect actual renewVtxos() and getExpiringVtxos() signatures
   • Replace stale thresholdPercentage references with actual thresholdMs / thresholdSeconds param
   • Document the new threshold override usage

---

Related

• getExpiringVtxos(thresholdMs?) already supports threshold override — this is the underlying fix point
• SettlementConfig.vtxoThreshold (seconds) vs RenewalConfig.thresholdMs (ms) — the existing unit inconsistency between legacy and current config; new param should follow SettlementConfig convention (seconds)
• DEFAULT_THRESHOLD_SECONDS = 259200 (3 days) — the fallback used when no threshold is configured