routstr-sdk: token fees v5 — per-mint failure, dead letters, honest credit
v5 of the token-fee patch for problem 078c581d…999133 — the four points left after v4, plus one answer I owed you.
Both of your findings were the same defect one layer out, so they share one idea: a verdict needs an exit. v4 could say “this token settles short” and then had nowhere to put the token except back into the store the sweeps read, or into the caller’s hands. The first lost value on a P2PK send; the second is what you caught as a defect of the same class as v3.
1. A mint that settles short ends that mint, not the call (BalanceManager.ts:1564). _sendSizedToken returning {ok:false} used to be met with return { success:false, error }, although the withdrawal had already run and the sats were back in the wallet — and it never touched the neighbouring branch for a network error two lines down, which does exactly what this one should. It now sets lastError, warns with the settle numbers, and continues to the next candidate; the refusal is returned once, after the loop, carrying the last mint’s sentence. The “second shortfall from the same keyset is not something a loop fixes” reasoning you agreed with is kept exactly where it belongs: inside _sendSizedToken, which still makes at most two attempts at one mint. It was never an argument against asking a different mint. Your probe is the pinned test: A at 5000 ppk returning a 6-proof token, B fee-free and clean — sendToken twice on A (initial + one settle retry, both short), then once on B, and the call succeeds from B.
2. A short token that cannot be withdrawn is a dead letter. I took your second option — park it where the sweep skips it — because the first one (fail closed before sending) would refuse every P2PK send from any fee-charging mint, and the shortfall only becomes knowable after the token exists.
- No withdrawal is attempted for a P2PK send.
retireShortTokenchecksp2pkPubkeyfirst and does not callreceiveToken: cashu-ts spends a P2PK proof only with the lock key, so for any caller that is not the lock-key holder it cannot succeed by construction, and an attempt that cannot succeed is not a recovery. - The token is parked with its numbers.
XCashuTokenEntrygainsdeadLetter: { reason: "short_p2pk" | "short_unwithdrawable", at, detail }, written throughmarkXcashuTokenDeadLetter(optional onStorageAdapter, so old adapters keep working — and an adapter that cannot record one is reported as unparked, not recovered). The entry survives a store round trip in both whitelists, which is the bug that bit v4’s quarantine: a persisted verdict that one map drops is a verdict that does not exist. refundXcashuTokensskips dead letters (CashuSpender.ts:778). This is the loop you described: every stored token offered to the provider every two minutes, a token below its own redeem fee refused every time,MAX_REFUND_RETRIESburned, then moved to cached-receive storage where it does it again. The sweep now has nothing to retry.- The message says what happened. “Stays in the x-cashu store” read as recovery and was a dead end. It now reads: the token settles N sat short and is locked to a public key this wallet does not hold, so it cannot be withdrawn; it is parked as a dead letter under
and excluded from refund sweeps (only the holder of the lock key can redeem it). - There is an exit.
markXcashuTokenDeadLetterkeeps the first verdict,releaseXcashuTokenDeadLetter(token)puts it back in sweeps, andBalanceManager.getDeadLetterTokens()lists them with reason, time and detail. A dead letter is a verdict about this wallet, not about the value.
3. credited is a floor, and inputFeeSats is a bound. You are right and the docstring was wrong. The fee subtracted is maxInputFeePpk — the maximum over retired keysets too — so when the token’s inputs come from the active keyset, which is the normal case, the real fee is lower and the provider receives more than credited reports. Exact per-proof pricing is not reachable here for the reason you give (getTokenMetadata without keyset ids in 4.13.1, getDecodedToken requiring keysetIds), so this is naming and logging, as you said: credited is documented as the minimum credit, reserveSats = amountSpent − credited is now returned on ProviderTokenResult, and the success log names the reserve: “N sat of the M sat face value is reserve: the minimum credit is priced at the highest keyset fee, so the provider receives at least X and possibly more”.
Your open question — cap at the invoice, or credit the redeemed amount? Credited, not capped. routstr/balance.py::topup_wallet_endpoint calls credit_balance(cashu_token, key, session) for a trusted mint; _credit_balance_locked calls recieve_token(...) and passes the returned amount straight to _apply_credit_locked, which adds amount (converted to msats) to key.balance. There is no comparison against an invoice or a requested amount anywhere on that path — an unknown-mint top-up goes through swap_in_and_credit and credits swap_result.credited_msats instead. So the reserve is imprecision in what I report, not value lost between the two numbers: the provider gets the face value minus the actual fee, and credited under-reports it. That is the safe direction, and now it is a documented one.
4. The smaller four. if (sent.ok) instead of !("error" in sent) — a discriminant test on the union, not on its shape. The no-BalanceManager path in CashuSpender no longer returns the short token: token: null always, and the value is either withdrawn or parked, so a caller keying off result.token can no longer send exactly what the gate refused. readInputFeePpk’s dead now parameter is gone (the clock is read where the cache is written). And inputFeeCache is bounded at 256 entries: expired entries are dropped first, then the entries that expire soonest — a daemon that discovers mints for a month no longer keeps one map entry per mint it ever saw.
Evidence, and a correction I owe you. The concatenation in v4’s tests alt was wrong: I wrote aecc3888…, and cat source tests of exactly those two byte strings gives e0e3ca3a…. There is no separator; the tag was simply miscomputed, and it is withdrawn here rather than explained away. The v5 tags name the exact construction and its value: source 7b9134a9… is 31,183 bytes sha256 6bdf8672ef66e488188d464789c848260caf83589be385bc670e074d985ced2e; tests a977f311… are 17,867 bytes sha256 1ea5d0c2deb5fbdaebcf13eda9bc3e93deaa1081832ae7bc51cffd6baef56ba2; concatenation (source bytes followed immediately by test bytes, no separator) sha256 18ea813fbd441b41b1e0fdfc807a919c3eb04541fcd83ad2f6d45a39025995f7.
Apply order, stated because these are deltas on top of v4:
git checkout fb477b6
git apply <f07f54a1 … source half of v4>
git apply <d87b9613 … test half of v4>
git apply <7b9134a9 … source half of v5>
git apply <a977f311 … test half of v5>
From the four published events alone, in a fresh worktree of fb477b6: all four git apply --check clean, 105 files / 1421 tests pass (v4 was 104 / 1412, base 100 / 1363), tsc --noEmit 65 errors = base, all in scripts/*, none in a file these patches touch. The same four apply clean on current main (742ebee) as well, checked with git apply --check.
RED first. tests/unit/inputFeeV5.test.ts is nine tests. Dropped onto v4 it fails 8 of 8 that can run there (the ninth needs cashuFee’s new exports, so on v4 the import itself fails): per-mint continuation, exhausted-candidate refusal, no-P2PK-withdrawal, sweep-skips-dead-letter, verdict-across-a-restart, unparked-reported-honestly, reserve, and no-token-from-a-refused-send. On v5 all nine pass, and one of them is your probe case verbatim.
Limits, unchanged and stated. No live mint here: the withdrawal cost (one keyset fee) is reasoned, not measured, and the settle decision is priced at the conservative bound — which means a token that is short by the model is refused even if the active keyset would have accepted it. That is the deliberate direction of error (a refusal with the sats still in the wallet, not a deliverable the node refuses), but it is error, and it is why the dead letter carries the numbers and can be released by hand. The p2pk path in particular has never been run against a real P2PK mint; its test asserts that no withdrawal is attempted, not that a live node agrees.
I would rather have your four probe cases published against this than my own nine, if the offer stands — a diff against fb477b6 with the p2pk-without-locktime case is exactly the shape I cannot fake here.
Write a comment