Three changes that harden the mint-fallback branch against upstream
failures and enable proper provider failover:
1. Mint health cache (src/daemon/wallet/index.ts)
Track mints that are temporarily unreachable (connection refused,
DNS failure, TLS error). Unhealthy mints are skipped by
getActiveMintUrl() and sendToken() so we don't waste a round-trip
on every request. Mints are automatically retried after a 60s
cooldown. The active mint switches to a healthy one when the current
one goes unhealthy.
This is critical for the xcashu 402 failover fix: when the primary
provider (localhost:8011) is down, the wallet needs to successfully
create a token via a healthy mint BEFORE the SDK's failover logic
can route the request to the next provider (routstr.otrta.me).
Without the health cache, every request wasted 2-3 seconds on a
failed mint.minibits.cash fetch before falling back to cubabitcoin.
2. xcashu token sweep (src/daemon/index.ts)
The scheduled refund loop now also sweeps pending xcashu tokens that
failed inline refund (e.g. 'proofs already spent' — the token stays
in storage and needs retry). This prevents orphaned IOUs from
accumulating and ensures the background refundXcashuTokens path
gets a chance to reclaim sats from tokens where the inline receive
raced with the sweep.
This is the race condition that caused the double-refund negative
satsSpent bug (xcashu-double-refund-negative-sats, prio 998): the
inline receive and the background sweep both received the same token,
producing a negative satsSpent written to usage_tracking.
3. Network error patterns (src/daemon/wallet/mint-fallback.ts)
Extend inspectForMintUnreachable to recognize Bun-specific network
failures: 'Failed to fetch mint <url>', 'NetworkError when attempting
to fetch resource', and 'Load failed'. These are treated as
mint-unreachable so the fallback to the next configured mint kicks
in immediately instead of surfacing the raw error.
This pairs with the SDK fix (routstr-sdk PR #32) that adds
'Unable to connect' and 'ECONNREFUSED' to isNetworkErrorMessage so
the SDK's failover path is triggered when the upstream provider is
completely unreachable (not just returning an HTTP error).
Related issues:
- Nostr: xcashu-402-body-refund-no-failover (prio 990, event a4d7e1cd...)
- Nostr: xcashu-double-refund-negative-sats (prio 998, event 14982f8d...)
- SDK PR: https://github.com/Routstr/routstr-sdk/pull/32
- SDK PR: https://github.com/Routstr/routstr-sdk/pull/31 (clamp fix)
In xcashu mode, Cashu tokens are sent per-request via X-Cashu header and
refunded in the response — no balance is kept with the provider. Falling
back to a Lightning invoice (routstr-core or local wallet) makes no
sense in this mode: it would create invoices that can never be settled
by the per-request token flow.
Added isXcashuMode() check in both installCreateProviderTokenFallback
and installMintFallbackTopUp. When all mints fail in xcashu mode, the
error now propagates immediately so the SDK's provider failover can
try the next available provider instead of attempting Lightning.
Removed the 'coming soon' guard that blocked xcashu mode selection.
The SDK fully supports xcashu: Cashu tokens are sent via X-Cashu header
per request, and refunds are received via x-cashu response header.
Verified working: request creates 1-sat token, sends X-Cashu header,
receives response with refund, no balance kept with provider.
Problem 1 — config overridden on restart:
parseArgs() always returned port=8008 when --port was not passed on the
CLI. index.ts then spread { ...config, port, provider } and saved,
silently overwriting the user's persisted port with 8008 on every daemon
restart.
Fix: parseArgs now returns null when --port is absent. index.ts falls
back to config.port (then 8008 as last resort), so the persisted config
is preserved across restarts.
Problem 2 — fetching models from disabled providers:
The SDK's fetchModels() still makes HTTP requests to every provider in
the list, even disabled ones — it only skips adding their models to the
best-priced map. models.ts passed unfiltered provider lists to
fetchModels in three places (bootstrap, getRoutstr21Models, refresh).
Fix: Added filterDisabled() helper that reads disabledProviders from the
store and strips them before fetchModels is called, preventing wasteful
HTTP requests to providers the user has explicitly disabled.
- Extract version-checking logic into src/utils/update-checker.ts (shared
between CLI and TUI)
- Updating routstrd...
bun add v1.2.22 (6bafe260)
installed routstrd@0.3.10 with binaries:
- routstrd
[649.00ms] done
routstrd updated successfully.
Updating cocod...
bun add v1.2.22 (6bafe260)
installed @routstr/cocod@0.0.24 with binaries:
- cocod
[692.00ms] done
cocod updated successfully.
Both routstrd and cocod have been updated!
Using remote daemon — skipping routstrd daemon restart.
cocod daemon was not running — skipping restart.
✓ All daemons restarted successfully. now checks npm for the latest version of each package
and only reinstalls when a newer version is available; skips daemon
restart when nothing was updated
- TUI shows a bold yellow 'UPDATE AVAILABLE' banner below the header on
all tabs when a new version is detected
- TUI checks for updates at most every 210 minutes to avoid spamming the
npm registry; first check fires 3s after startup (non-blocking)
- Bump version to 0.3.11
routstr-core's /lightning/invoice endpoint requires integer sats
but options.amount can be a float (e.g. 64.79) derived from msat
costs. Without Math.ceil the fallback crashed with HTTP 422:
'Input should be a valid integer, got a number with a fractional part'
Fix: Math.ceil() in both topUpAmount calculations + defense-in-depth
Math.ceil() inside createInvoiceViaRoutstrCore itself.
.pi-subagents/, data/, ROUTSTRD_OTRTA_FIX.md, kill-orphan-cocod.sh are
local-only debug/state files that accumulated during incident response
and shouldn't be tracked.
- Remove duplicate const controller/timeout declarations introduced during
sibling-agent parallel edits
- Reduce fetch timeout from 10s to 3s so the fallback chain stays snappy
and tests don't time out the 5s bun:test budget
When the local wallet runs out of proofs, the fallback chain now:
1. Retries across ALL configured mints (createProviderToken patched —
previously only topUp retried on 'Not enough proofs')
2. Creates a routstr-core Lightning invoice (POST /lightning/invoice)
→ uses 'topup' purpose when an existing API key is available
→ pays via NWC (payBolt11) if connected, then retries
→ otherwise surfaces invoice for manual payment + polls until paid/expired
3. Falls back to local wallet Lightning invoice + NWC funding
Hardening (15 new tests):
- SSRF protection: rejects non-HTTPS provider URLs (except localhost)
- Amount validation: clamps to [1, 1_000_000] sats
- bolt11 validation: must start with 'lnbc'
- invoice_id validation: must be non-empty string
- Fetch timeout: AbortController (10s) on invoice creation
- NWC exception handling: caught, not propagated
- Double-install idempotency: patch markers prevent re-patching
- Concurrent calls: no shared state corruption
- API key safety: never logged in error messages
- Poller lifecycle: stops after 84 attempts (~7min) or on expired status
New wallet adapter method:
- payBolt11(bolt11): pays externally-created invoices via NWC
Verified end-to-end:
- 50-request stress test: 44/50 success, 6 fallback triggers (fugu-ultra)
- Routstr-core topup: 64,781 → 114,340 msats (balance increased)
- Daemon stable post-stress (142MB RSS, immediate recovery)
- 48/48 tests pass (33 existing + 15 hardening)
When routstr.otrta.me rejects a Cashu token with 'mint_unreachable',
the mint fallback handler calls _spendToken with a fallback mint URL
(e.g. cubabitcoin.org). However, _spendToken's internal
_selectCandidateMints puts the highest-balance mint first regardless
of the preferredMintUrl parameter, so the fallback token was still
minted from the same unreachable mint (minibits).
Pass excludeMints: [initialMintUrl] to _spendToken so the failed
mint is excluded from candidate selection, forcing the fallback to
use the requested alternative mint.
- Redirect detached daemon stdout/stderr to ~/.routstrd/debug.log
instead of ignoring them, so uncaught exception stack traces are
no longer lost
- Add process-level uncaughtException/unhandledRejection handlers
that log to the file logger before the process dies
- Wrap setInterval async callbacks (model refresh + refund jobs) in
IIFE catch chains so rejected promises can't escape and kill the
process silently
The update command previously only downloaded and installed new
binaries for routstrd and cocod without restarting the running
daemons, so updates would not take effect until a manual restart.
- Add restartDaemonsAfterUpdate() helper that gracefully stops and
restarts both daemons after a successful update
- routstrd: uses POST /stop (drains active connections), polls for
shutdown, then calls startDaemon() with configured port/provider
- cocod: runs 'cocod stop', then spawns 'cocod daemon' detached,
polls 'cocod ping' until it comes back up
- Skips restart for daemons that weren't running
- Skips routstrd daemon restart when using a remote daemon
- Collects and reports failures without rolling back the update
- Bump @routstr/sdk to 0.3.15
- Bump routstrd version to 0.3.7
Closes nostr task: update-restart
renderToday declared todayStats/recentDays/hourlyMap with let but only
assigned inside if (stats.summary); TypeScript flagged them as used
before assignment (TS2454). Initialize with sensible defaults so the
function degrades gracefully when summary is missing.
The usage-summary tz-bucketing test used hardcoded May 2026 timestamps
with a comment dated 2026-06-02. Those entries aged out of
getUsageSummary's 30-day rolling window, so days came back empty.
Recompute timestamps relative to now and assert on dynamically-derived
local-day date strings.
Calls refreshNostrEvents() after initial bootstrap and in the 21-minute
recurring job, covering provider discovery (38421) and lgtm reviews
(38425) which were previously only refreshed on manual trigger.
Split the monolithic render() into two distinct functions:
- fetchData(): async background fetch that updates state and triggers
a repaint, guarded against overlapping calls
- render(): synchronous paint that reads current state and writes to
stdout, safe to call from key handlers without blocking
Run all four daemon calls concurrently via Promise.all to cut the
blocked window. Remove redundant isDaemonRunning() checks from each
fetch function in data.ts — the single check now lives in fetchData().
Key handlers now call the sync render() directly instead of
void render(false), so scrolling and tab switching feel instant.
The SDK dropped minTotalTokens/maxTotalTokens from AggregateUsageOptions
(routstr-sdk c98de6b), so replace the five aggregate() calls with a single
list() and bucket entries in-process.
routstrd providers list --refresh now:
- Re-fetches Nostr kind 38421 provider discovery events
- Re-fetches Nostr kind 38423 routstr21 model list
- Re-fetches Nostr kind 38425 review events (applies LGTM-based disable)
- Fetches models from all discovered providers
- Syncs fresh provider list and disabled status into the store
Usage: routstrd providers list --refresh
- Import ModelManager from @routstr/sdk/bun instead of @routstr/sdk
- Import storage helpers from @routstr/sdk/storage/bun instead of @routstr/sdk/storage
- Fix createBunSqliteUsageTrackingDriver call: async and no longer needs
manual bun:sqlite import (now handled internally by the sdk entrypoint)
- Verified sharded discovery adapter setup matches SDK pattern in
scripts/routstr-daemon.ts at 6077aa7
Paperclip Deployment Engineer
redshift
9qeklajc
redshiftandGitHub