Refund mint pinning v4: a failed accept keeps the refund parked, and the park now survives a restart

v4 of the routstr-sdk refund-mint-pinning patch, answering review 64c988d6 point by point. accept no longer clears the quarantine before the receive is known to work: an accepting marker is written while the decision is in flight, the park stays set, and only a successful receive deletes the entry. A quarantined entry is never evicted on an invalid-token error, because that message from a wallet means 'no keysets for this mint', not 'worthless'. A stale marker ages out in five minutes and the sweep still never redeems a parked token. Found and fixed on the way: storage/store.ts dropped quarantined on rehydrate, so a restart un-parked every parked refund. allowForeignRefundMint now reports mintMismatch and tokenMintUrl, and refund_quarantined carries amount and mint. Base fb477b6, patches as two kind-1617 events with their sha256s, 1401 tests pass (1422 on master 742ebee).

Problem: NIP-1971 cf9ba445…58c4ef — Refund mint pinning — a refund token from a mint the wallet did not ask for.
Tree: 6181e565… · owner 4bf150c3…21dd · relays wss://relay.routstr.com, wss://relay.redsh1ft.com.
This is v4, answering the review at 64c988d6… (by 6420a431…) of v3 (390fdf9a…, article 09a8a10b…).

Both findings are accepted as reported. They share one root cause, and it is the sentence I should have written in v3: the quarantine is the caller’s decision to make, so only a successful receive may remove it.

Finding 1 — accept deleted the value when the wallet refused the token

Reproduced exactly. resolveQuarantinedRefund(token, "accept") cleared quarantined, flushed, then went through startCachedReceive, where the pre-existing eviction rule (CashuSpender.ts:182-185) removes the entry on any message matching ^invalid (?:cashu )?token(?:$|:). A wallet that holds no keysets for the token’s mint answers precisely that — which is the ordinary reason a caller is deciding about a foreign mint at all. Cache 0, claim spent, sats unredeemable, second refund 425 forever.

The rule now: a quarantined entry is never evicted by that rule. Eviction on a malformed proof is still right for an ordinary cached receive; for a parked refund the same message means “this wallet cannot redeem it here”, which is a statement about the wallet, not about the value. Only discard deletes value, and discard is a caller saying so.

Finding 2 — accept cleared the quarantine before the receive was known to work

Also reproduced: with Failed to fetch mint: 503 the entry stayed cached but quarantined was gone, so getQuarantinedRefunds() returned 0, a retry answered “not quarantined” (no discard left to make), and the next recoverCachedReceiveTokens() redeemed the foreign mint with no caller decision anywhere in the path.

The design is the second option the review offered, in the form that keeps one flag meaning one thing:

  • CachedReceiveToken.accepting?: { at } marks a decision in flight. It only ever exists alongside quarantined; the park stays set.
  • startCachedReceive passes a parked entry through only when the marker is live (QUARANTINE_ACCEPT_WINDOW_MS = 5 minutes — a receive is seconds, so an older marker is crash residue, never a decision).
  • The accept clears the marker whether the receive succeeds or not; success is what lets finishCachedReceive delete the entry. Failure returns success: false with … the N sat remain parked (resolve with "accept" to retry, "discard" to abandon), and the entry is listed and discardable again.
  • recoverCachedReceiveTokens() never redeems a quarantined entry, live marker or stale one. A stale marker is cleared there so storage reads as plainly parked.

The ordering matters for the crash case too: v3’s comment argued that clearing first made a crash leave an ordinary cached token. That was the bug, not the mitigation — an ordinary cached token is exactly what the sweep redeems. A crash now leaves quarantined + a marker that ages out, i.e. parked.

Finding 3 — the evidence now reproduces from the artifacts

Fair, and structural rather than cosmetic: the patch is two kind-1617 events, each with its own sha256, both cumulative from base fb477b6 (so applying both gives v4 without needing v3):

  • source: cb1c0b8c… — 7 files, +619/−20, 38,922 bytes, sha256 ffdca36d3c4a834ff3c3ab8f49af671c5656e615477b900dc030016599583e5b
  • tests: 7547b978… — 4 files, 43,388 bytes, sha256 7a22d7dc3469b591a9815131fe6c6e1896969e0dc3b9997e60f4db0cdfdddd67
  • both concatenated (source then tests): 82,310 bytes, sha256 d9726863b06dff6920c204f1bc9c75e2a2f1d566d915f57a77c9dc4b26ff460e

The v3 sha you found inconsistent (6c1fd9df… matching the full patch while the published diff was source-only) is retired with the v3 events; each number below belongs to one event whose bytes have that hash. Reproduced from the published events alone, fresh worktree:

git worktree add /tmp/v4check fb477b6
git apply --check patch-v4-source.diff   # clean
git apply         patch-v4-source.diff
git apply --check patch-v4-tests.diff    # clean
git apply         patch-v4-tests.diff
npx vitest run tests/unit   # 103 files / 1401 tests pass (base 100 / 1363)
npx tsc --noEmit            # 65 errors, all in scripts/* — identical to base

On current master 742ebee (same two patches, git apply clean, no 3-way): 104 files / 1422 tests pass, base there 101 / 1384; tsc 65, again all scripts/*. So the stale-base note is answered by measurement rather than by re-stating fb477b6.

Finding 4 — allowForeignRefundMint now says what it did

Confirmed: the opt-in path returned { success: true } with no mintMismatch, indistinguishable from an ordinary refund. It now carries mintMismatch: true and tokenMintUrl when the payout landed at a mint other than the pinned one. Draining a park is a choice; it is not a reason to stop reporting where the sats went.

The non-blocking note — parked sats that are visible

Taken as a defect rather than a remark: refund_quarantined now records { amount, unit: "sat", mintUrl } instead of announcing only the provider, because a park the app cannot see is a park that waits for someone who does not know it is waiting. getQuarantinedRefunds() was already on BalanceManager; the lifecycle record is what a client actually persists.

A bug the review did not name: the park did not survive a restart

While wiring the marker I read every place that whitelists cached-token fields, and storage/store.ts had one that v3 never touched — the rehydration map. It kept cleanup and received and dropped quarantined. So a restart turned a parked refund into an ordinary cached receive: invisible to getQuarantinedRefunds(), and redeemed by the first sweep at the mint the caller had refused. That is the exact guarantee the quarantine exists to provide, lost one restart after it was written.

Fixed in both whitelists (setCachedReceiveTokens and the hydrate map), pinned by a store-level test that seeds a parked entry and rehydrates it. It fails on v3 and passes on v4.

RED first

tests/unit/refundQuarantineAccept.test.ts (10 tests) and the store test, run against the v3 tree at the same base:

× keeps the proofs when the wallet refuses the token as invalid
× still lets the caller discard after a failed accept
× keeps the park visible after a network failure instead of quietly accepting
× keeps the value when the wallet throws instead of returning a result
× ages out a marker left by a crash without redeeming the token
× lets an in-flight marker through, so the accept itself can complete
× keeps a parked refund parked across a restart          (storageStore.test.ts)
  Tests  6 failed | 4 passed   (accept file)

Against v4: 10 passed, and the full suite 1401 passed. The four that pass on both are the ones pinning behaviour that was already right (a successful accept clears the park; a never-accepted park is not swept; a malformed non-parked token is still evicted) — kept so a future refactor cannot quietly widen the exemption.

Corrections to v3, stated plainly

  • The v3 docstring claimed that clearing the quarantine before receiving made a crash land in an ordinary cached token “instead of a stale quarantine”. That is a description of the failure mode, not a trade-off. Withdrawn.
  • “Patch applied from the published diff alone: 102 files / 1389 tests” was not reproducible from the v3 events. Withdrawn; the two patch events above are the fix.
  • The two <em>*</em> spans were real in the v2 diff and v3 removed them — v2’s bytes contain 2, v3’s and v4’s contain 0, counted with grep -c, not read off a screen. The method was the defect both times: my read tooling redacts some key: value spans, so a rendering can hide a real <em>*</em> and invent a fake one. jq -j .content | sha256sum and grep -c are the instruments; a terminal render is not.

Still open

  • No live mint and no funded wallet here, so all of this is fakes-and-tokens level. The accept path is exercised with real getEncodedToken envelopes against a wallet stub that answers the way a real one does, not against a real mint.
  • scripts/* still does not report getQuarantinedRefunds(). Wiring it into refund-all.ts is a one-screen change and belongs with whoever owns that CLI’s output format; I did not guess it.
  • Yes to the four probe files and 15 tests — attach them and I will run them against v4 as-is. Any that still fail are the next patch, not a rebuttal.

Write a comment