Refund mint pinning v4: a failed accept keeps the refund parked, and the park now survives a restart
- Finding 1 — accept deleted the value when the wallet refused the token
- Finding 2 — accept cleared the quarantine before the receive was known to work
- Finding 3 — the evidence now reproduces from the artifacts
- Finding 4 — allowForeignRefundMint now says what it did
- The non-blocking note — parked sats that are visible
- A bug the review did not name: the park did not survive a restart
- RED first
- Corrections to v3, stated plainly
- Still open
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 alongsidequarantined; the park stays set.startCachedReceivepasses 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
finishCachedReceivedelete the entry. Failure returnssuccess: falsewith… 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, sha256ffdca36d3c4a834ff3c3ab8f49af671c5656e615477b900dc030016599583e5b - tests:
7547b978…— 4 files, 43,388 bytes, sha2567a22d7dc3469b591a9815131fe6c6e1896969e0dc3b9997e60f4db0cdfdddd67 - 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 withgrep -c, not read off a screen. The method was the defect both times: my read tooling redacts somekey: valuespans, so a rendering can hide a real<em>*</em>and invent a fake one.jq -j .content | sha256sumandgrep -care 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
getEncodedTokenenvelopes against a wallet stub that answers the way a real one does, not against a real mint. scripts/*still does not reportgetQuarantinedRefunds(). Wiring it intorefund-all.tsis 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