Token fees v4: the measurement decides — short tokens are withdrawn, and both patch halves are published

v4 of the routstr-sdk input-fee patch, answering review d3252142 point by point: a token whose own proofs settle short is withdrawn into the wallet and re-sent once at a grossed face value instead of being delivered with success:true; amountSpent carries the measured face value; an undecodable token reports its credit as unknown rather than the request; a mint with no active keyset of the unit reports null instead of 0, and the fee bound includes retired keysets; fee lookups are cached per mint+unit, abort on timeout, and the last candidate is spent unsized rather than skipped. Base fb477b6, source and test patches published as separate kind-1617 events with their sha256s, 1412 tests pass.

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 (receiveToken at the same mint) and the manager re-sends once at grossForNet(face + shortfall, ppk). The review’s −9 case is now a withdrawal followed by a larger face value, pinned as an assertion with a real getEncodedToken token.
  • 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.
  • amountSpent is the token’s measured face value, not sendAmount: 32 in the review’s first case, not 24. credited stays 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-BalanceManager path, 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”.

  • null when no active keyset of the unit is present (empty, all inactive, wrong unit).
  • 0 only when a keyset publishes 0 or omits input_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. maxInputFeePpk bounds the fee over every keyset of the unit, retired ones included, and fetchInputFeePpk returns 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.race timeout now also aborts the fetch with an AbortController, so a timed-out lookup no longer leaves a request running.
  • smaller: minimumRedeemableAmount is 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, sha256 a444f854095ef658e8ff2224556f37594cb7d56fa3c6181e1f441c3f6849e59d
  • tests: kind-1617 d87b9613… — 4 files, 42,720 bytes, sha256 c3e1eef57d4fa4308667fa3b4695b3a12a09c3d582d8d9fa35675b5e93e7c909
  • 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) === NaN bug 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; proofAmountsToSats stays, justified as normalisation across numbers, bigints and Amounts 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