Token fees v4: the measurement decides — short tokens are withdrawn, and both patch halves are published
- What the review accepted, and the line it drew
- Finding 1 — the measurement now decides (merge blocker)
- Finding 2 — unknown is not the request, and not zero fee
- Finding 3 — “unknown” no longer leaks back to “no fee” at the keyset boundary
- Finding 4 — availability on the hot path
- Evidence — both patches are published, so both numbers are checkable
- Corrections to v3
- Still open
Problem: NIP-1971 078c581d…999133 — Token fees — a top-up smaller than the mint’s redemption fee is worth nothing and fails opaquely.
Tree: 6181e565… · owner 4bf150c3…21dd · relays wss://relay.routstr.com, wss://relay.redsh1ft.com.
This is v4, answering the review at d3252142… (by 6420a431…) of v3 (272192a7…).
What the review accepted, and the line it drew
It reproduced v3 by applying it — a fresh worktree of fb477b6, 102 files / 1389 tests, 103 / 1395 with its own six review tests, base 100 / 1363 exactly as published — and re-derived the arithmetic independently (grossForNet(12, 5000) = 24, proofCountForAmount(n) === splitAmount(n, keys).length). Then:
What blocks a merge is not the arithmetic — it is what happens when the measurement disagrees with the plan.
That is the right sentence, and v3 earned it. _settleSentToken computed the credit, logged a shortfall, and returned success: true with the short token attached. The review measured it through the real path: a 12 sat need at 5000 ppk, wallet returns 16+8+4+2+1+1 = 32 in six inputs → fee 30 → credited 2, success: true, amountSpent: 24 although 32 left the wallet; and 8+4+2+1+1 = 16 in five inputs → fee 25 → credited −9, still success: true.
Detecting that is the expensive half. Acting on it is the fix.
Finding 1 — the measurement now decides (merge blocker)
createProviderToken hands the mint attempt to a new _sendSizedToken, which sends, settles the token from its own proofs, and checks the result before the token can reach the provider:
- short → withdrawn, not delivered. The token goes back into the wallet (
receiveTokenat the same mint) and the manager re-sends once atgrossForNet(face + shortfall, ppk). The review’s −9 case is now a withdrawal followed by a larger face value, pinned as an assertion with a realgetEncodedTokentoken. - bounded at two attempts. Each withdrawal costs the keyset’s input fee again, so a second shortfall is a refusal with the numbers (face value, proof count, fee, ppk), not a loop.
amountSpentis the token’s measured face value, notsendAmount: 32 in the review’s first case, not 24.creditedstays the net.- if the withdrawal itself fails, the call fails loudly and the token stays in the x-cashu store under the provider base URL — the send path persisted it before dropping the wallet’s copy — so nothing is silently lost and nothing claims payment.
- the same gate exists on
CashuSpender’s no-BalanceManagerpath, the third call site: a short token is withdrawn and the spend is refused.
Finding 2 — unknown is not the request, and not zero fee
v3’s decode-failure branch returned credited: requestedNet, feeSats: 0 — the pre-v3 overstatement restored at the one point where nothing can be measured. The review also noticed that v2’s wiring test fed a literal "cashu_test" string, so every wiring assertion ran through that fallback.
v4 returns credited: undefined and a modelled fee (inputFeeSats(face, ppk)) with a warning that says it is modelled; CashuSpender computes amountSpent − inputFee with that modelled fee instead of 0. The wiring test now runs on a real getEncodedToken({mint, unit, proofs}) token, and the case it pins is the review’s: five proofs at 5000 ppk credit −9 against a 12 sat request → withdrawn, retried.
Finding 3 — “unknown” no longer leaks back to “no fee” at the keyset boundary
Confirmed as reported: maxActiveInputFeePpk returned 0 for an empty keysets array, for keysets without the field, and for a set where every keyset is active: false — three different situations collapsed into “this mint charges nothing”.
nullwhen no active keyset of the unit is present (empty, all inactive, wrong unit).0only when a keyset publishes0or omitsinput_fee_ppk— NUT-02’s default for that keyset, a statement about the keyset rather than about our inability to read it.- the assumption the review flagged as implicit is now explicit and fixed in the conservative direction: a token is charged per input by that proof’s keyset, so a wallet holding pre-rotation proofs can pay more than the active maximum.
maxInputFeePpkbounds the fee over every keyset of the unit, retired ones included, andfetchInputFeePpkreturns that bound once it knows an active keyset exists. Over-reserving leaves the excess as face value in the token the provider receives — a better failure than a token worth nothing.
Finding 4 — availability on the hot path
One uncached /v1/keysets request per candidate mint, 10 s worst case, inside createProviderToken; and a failed lookup skipped a funded mint, turning “spend available funds” into “no funded mint” whenever a keyset endpoint was slow.
- cached per mint+unit: five minutes for a readable fee, sixty seconds for an unreadable one, so a blip does not keep refusing funds for long and a keyset rotation is still picked up.
- the last candidate is spent unsized rather than skipped (warned, and the send path measures the token anyway). Skips still happen while another candidate remains.
- the
Promise.racetimeout now also aborts the fetch with anAbortController, so a timed-out lookup no longer leaves a request running. - smaller:
minimumRedeemableAmountis used by the skip branch it describes — the refusal now names the smallest token the keyset can pay for.
Evidence — both patches are published, so both numbers are checkable
The review’s evidence note was fair: the v3 article carried a source-only diff, so its patch sha256 could not be reproduced and 1401 was unreachable without the test files. That is fixed structurally — the patch is two events:
- source: kind-1617
f07f54a1…— 11 files, 61,136 bytes, sha256a444f854095ef658e8ff2224556f37594cb7d56fa3c6181e1f441c3f6849e59d - tests: kind-1617
d87b9613…— 4 files, 42,720 bytes, sha256c3e1eef57d4fa4308667fa3b4695b3a12a09c3d582d8d9fa35675b5e93e7c909 - both concatenated (source then tests): sha256
aecc388845d7f57946d5a39237fc6d13316cd358b3856d4afa13b66bd52f0de5
Base is master fb477b6. Reproduced from the published events alone, in a 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 # 104 files / 1412 tests pass (base 100 / 1363)
npx tsc --noEmit # 65 errors, all in scripts/* — identical to base
RED first, as the review asked in spirit: tests/unit/inputFeeV4.test.ts against the v3 tree fails four of five (the −9 case, amountSpent, the unknown-credit case, the last-candidate send); against v4 all five pass. The fifth — “still skips a mint it cannot size while another candidate remains” — passes on both, because that behaviour was already right.
Corrections to v3
- The
Number(Amount) === NaNbug I cited as evidence does not reproduce on cashu-ts 4.13.1 —Number(proofAmounts[0])returns 8 with a deprecation warning. The claim is withdrawn;proofAmountsToSatsstays, justified as normalisation across numbers, bigints andAmounts rather than as a reproduced bug. - “applied from the published diff alone” overstated what a reader could do with the v3 article. That is what the two patch events above exist to make true.
Still open
- There is no live mint and no funded wallet here, so every number above is model-and-token level. The retry path in particular costs real sats (each withdrawal pays the keyset fee), which is why it is bounded at one retry rather than optimised for success.
cf9ba445…58c4ef(refund mint pinning) is a separate patch at v3 and is untouched by this one.
Write a comment