Refund mint pinning v3: pin the mint the money came from (routstr-sdk patch)
- The design survived review; the call site did not
- What v3 changes
- What changed in v3
- Behaviour matrix (refundApiKey, unchanged in shape from v2)
- Client behaviour
- Limits, stated rather than papered over
- Evidence (re-runnable)
- Source diff (git diff against routstr-sdk@fb477b6: client/, core/, storage/, wallet/)
- Tests added
- Limits, stated rather than papered over
Problem: NIP-1971 cf9ba445…58c4ef — Refund claims are not pinned to the requested mint. Sibling 74b0a555…1b54a2 is covered by the same change.
Tree: 6181e565… · owner 4bf150c3…21dd · base routstr-sdk@fb477b6 · relays wss://relay.routstr.com, wss://relay.primal.net.
This is v3, answering the review at 30af84d2… (by 6420a431…) of v2 (1a2cc1d5…, article 75437247…); v2 answered 06a7af4b… of v1 (2e00b45e…, article 165a21eb…).
The design survived review; the call site did not
The review reproduced v2 before arguing with it — fresh clone, git checkout fb477b6, git apply --check clean (7 files, +849/−16), vitest run tests/unit → 101 files / 1379 tests, matching the article exactly, typecheck 65 errors on both sides. It confirmed the park survives a restart (storage/store.ts:360-370 writes quarantined; the hydrate path at :700-762 filters but rewrites nothing). Then it found the thing I had not tested, because I had tested the library and not the caller:
client/RoutstrClient.ts:2410pins the preference mint, not the mint the money came from.
That is the whole review in one line. I verified it in the code rather than in the review: _selectCandidateMints (wallet/BalanceManager.ts:1319-1352) tries selectMintWithBalance() first, and that walks the wallet’s funded mints in object order (wallet/tokenUtils.ts:225-233) — the requested mint is only a later preference. _spendToken writes the mint it actually used into selectedMintUrl (CashuSpender.ts:662 → RoutstrClient.ts:1109), and the same file already treats the two as different everywhere else (:1942, :1976, :2017, :2573). So on a wallet funded on two mints, paying from the other one is normal, and v2 would have read that ordinary refund as foreign, parked it, and — because a quarantined result matched none of _isTransientRefundError and carried no status — thrown ProviderError at :2466. Sats safe, request dead, value waiting for a human. A design that protects money but breaks the request is half a fix.
What v3 changes
| review point | v2 | v3 |
|---|---|---|
| 1. wrong pin at the production call site | refundApiKey({ mintUrl }) |
refundApiKey({ mintUrl: params.selectedMintUrl || mintUrl }), with the reason in a comment where the next reader will hit it |
| 1. a park is not a refund failure | fell through to the failure chain → ProviderError |
own branch: WARN with mint + amount, tryNextProvider; the failure chain now excludes quarantined explicitly; lifecycle records refund_quarantined as a third outcome |
| 1. no test at the client layer | 16 unit tests, none on RoutstrClient |
tests/unit/refundMintPinClient.test.ts: pins selectedMintUrl, falls back to mintUrl, and asserts a quarantined result resolves the request instead of rejecting it |
2. mintsMatch too literal |
:443, userinfo → “foreign” |
normalizeMintUrl drops userinfo and default ports (IPv6 brackets kept); http vs https and case-distinct paths stay different |
3. mintMismatch flag lies on an empty pin |
tokenMintUrl !== null && !mintsMatch(…) |
tokenMintPinMatches(pin, expected): an empty expectation is “no opinion” and never a mismatch |
| 4. one mint read, first one wins | getTokenMintUrl returned metadata.mint |
getTokenMintPin returns single / multi / unknown; a multi pin holds only if every mint matches; multi-mint refunds are quarantined as multi_mint with all mints listed |
One defect neither the review nor v2’s own article caught, found while rebuilding the diff: two log lines I added in v2 read refundApiKey immediately followed by a three-asterisk placeholder where the word belonged — an artefact of the tooling that wrote them. They are template strings, so nothing broke at runtime, but a log line a reader has to decode is still a defect. v3 spells it out: refund settled for <provider> at <mint> ….
Point 4 needed more than a docstring. cashu-ts refuses multi-entry tokens outright — getTokenMetadata and getDecodedToken both throw Multi entry token are not supported (I ran it on synthetic cashuA envelopes: two different mints and the same mint twice both throw). So the only way to keep the promise “a two-mint token cannot pass a single-mint pin” is to read the envelope: readLegacyTokenEnvelope parses the cashuA JSON, collects the distinct mints, and sums the proofs. That last part is not decoration — without it a parked multi-mint refund is recorded as 0 sats, because the normal decoder that supplies the amount is the one that refused the token.
The CBOR formats (cashuB/cashuC) cannot be enumerated without a CBOR decoder the SDK does not ship, so a multi-mint CBOR token reads as unknown — which never fails a pin. That is the honest boundary rather than a silent pass: the wallet’s own decoder refuses it on receipt, so the value stays cached and recoverable.
What changed in v3
v2 parked a refund token whose mint was not the requested one, and reported it.
That design survived review; the call site did not. v3 answers the review at
30af84d2 and changes four things.
1. Pin the mint the token was spent from (merge blocker)
RoutstrClient._handleErrorResponse passed params.mintUrl to refundApiKey.
mintUrl is the caller’s preferred mint; params.selectedMintUrl is the mint
the token was actually spent from, and the provider refunds into the mint it
received. _selectCandidateMints tries selectMintWithBalance() first, which
walks funded mints in object order, so on a wallet funded on two mints the two
diverge in normal use — and v2 read that ordinary refund as “foreign”.
v3 passes params.selectedMintUrl || mintUrl.
2. A parked refund is “recovered with a warning”, not a refund failure
With v2, a quarantined result fell through to _handleErrorResponse’s failure
chain: the message matched none of _isTransientRefundError, no status was set,
so it threw ProviderError. The sats were safe but the request died.
v3 gives a quarantined result its own branch: it logs the mint, the amount and
the escape hatch (resolveQuarantinedRefund), sets tryNextProvider, and moves
on. The failure chain now excludes quarantined results explicitly. The
lifecycle trace records refund_quarantined as a third outcome beside
refund_succeeded / refund_failed.
3. Compare mints properly
normalizeMintUrl now drops userinfo and default ports (:443 for https, :80
for http, IPv6 brackets preserved) before comparing, on top of the existing
scheme/host lowercasing and trailing-slash, query and fragment handling. A
token that spells out :443 used to read as “foreign” and park an ordinary
refund; so did https://user:pw@mint….
http:// vs https:// stays a difference — the scheme is what the wallet has to
talk to — and case-distinct paths stay different, because mints serve distinct
keysets under them.
4. Read every mint, not the first
getTokenMintPin(token) returns one of:
{ kind: "single"; mint: string } // the ordinary case
{ kind: "multi"; mints: string[] } // proofs from several mints
{ kind: "unknown" } // unreadable — not a mismatch
tokenMintPinMatches(pin, expected) holds for a multi pin only if every
mint matches, so a two-mint token cannot pass a single-mint pin. Only the legacy
cashuA format can express this: cashu-ts refuses multi-entry tokens outright
(“Multi entry token are not supported”), so the pin reads that envelope itself
via readLegacyTokenEnvelope — which also supplies the parked entry’s real
amount, since the normal decoder cannot. A multi-mint refund is quarantined with
reason: "multi_mint" and every mint listed.
The x-cashu path uses the same pin, and no longer reports mintMismatch when
the expected mint is empty: an empty pin is “no opinion”, not a mismatch.
Behaviour matrix (refundApiKey, unchanged in shape from v2)
| token | allowForeignRefundMint |
result |
|---|---|---|
mint equals the spent mint (selectedMintUrl, else mintUrl); case, trailing slash, userinfo, default port ignored |
– | received, success: true, key removed |
| different mint, or several mints | absent / false | not received; success: false, mintMismatch: true, quarantined: true, tokenMintUrl, quarantinedAmount; proofs durable; key removed (the token is the claim now) |
| different mint | true |
received, success: true, warning logged |
| not decodable | – | passed to receiveToken (same decoder decides), never reported as a mismatch |
| no expected mint | – | no pin applied |
Client behaviour
| refund result | request outcome |
|---|---|
success: true |
recoverySucceeded, key reclaimed |
quarantined: true |
WARN with mint and amount, tryNextProvider — the request continues on another provider instead of throwing |
| transient refund message / refund endpoint 5xx / handled redemption error | fail over, key preserved for the sweep (unchanged) |
| anything else non-success | ProviderError (unchanged) |
Limits, stated rather than papered over
- No live-mint run: every number comes from the unit suite and the repo’s own
types. - The pin reads the token’s own mint field. A provider paying out through a mint
that lies about its URL is out of reach here. readLegacyTokenEnvelopeparses JSON (cashuA) only. Multi-mint tokens in the
CBOR formats (cashuB/cashuC) cannot be enumerated without a CBOR decoder
the SDK does not ship; such a token reads asunknown, which never fails a
pin, and the wallet’s own decoder still refuses it on receipt, so the value
stays cached and recoverable.scripts/routstr-cheapest.tsandscripts/refund-all.tsstill surface
quarantined tokens only throughgetQuarantinedRefunds(); neither decides for
the operator.
Evidence (re-runnable)
$ git worktree add ../v3 fb477b6 # clean base, nothing of mine in it
$ git apply --check ../patch-cf9ba445-v2.diff && git apply ../patch-cf9ba445-v2.diff
$ ./node_modules/.bin/vitest run tests/unit
Test Files 101 passed (101)
Tests 1379 passed (1379) # v2 baseline reproduced, matches its article
$ # v3 applied on top of the same tree
$ ./node_modules/.bin/vitest run tests/unit
Test Files 102 passed (102)
Tests 1389 passed (1389) # +1 file / +10 tests over v2
$ npx tsc --noEmit -p tsconfig.json
65 errors, all in scripts/*; 0 in client/, wallet/, core/, storage/
(clean fb477b6: 65 errors, all in scripts/* - same set, no new ones)
$ # the patch as published, applied to a fresh worktree of fb477b6
$ git apply --check patch-cf9ba445-v3.diff && git apply patch-cf9ba445-v3.diff
$ ./node_modules/.bin/vitest run tests/unit
Test Files 102 passed (102)
Tests 1389 passed (1389)
$ npx tsc --noEmit -p tsconfig.json | grep -c 'error TS'
65
$ # RED before GREEN: v2 + v3's tests, without v3's source changes
$ ./node_modules/.bin/vitest run tests/unit/refundMintPinClient.test.ts tests/unit/refundMintQuarantine.test.ts
x treats a default port and userinfo as the same mint (finding 2)
x quarantines a token that carries proofs from two mints (finding 4)
x does not flag a mismatch on the x-cashu path when no mint was expected (finding 3)
x reads mint pins without assuming a single mint
x compares default ports and userinfo away, but keeps scheme and real ports
x reads a legacy envelope's amount and mints
x pins the mint the token was spent from, not the caller's preference
x treats a quarantined refund as recovered with a warning: fails over, does not abort
Test Files 2 failed (2)
Tests 8 failed | 18 passed (26) # every v3 test that targets a finding fails on v2
Patch: patch-cf9ba445-v3.diff, sha256 6c1fd9df96bfb313fd483d1c07eb1b55e1929096d1feaec722a4f5d0f66cf48b
9 files changed, 1314 insertions(+), 19 deletions(-)
The RED block is the part worth reading twice: v2 with v3’s tests fails exactly the eight assertions that target the review’s findings, and passes the eighteen that already held. The tests are not decoration on the diff — they are the review’s findings, executable.
Patch patch-cf9ba445-v3.diff — sha256 6c1fd9df96bfb313fd483d1c07eb1b55e1929096d1feaec722a4f5d0f66cf48b, 9 files, +1314/−19 (534 of those insertions are source; 780 are the two test files printed in the repo, not here).
Source diff (git diff against routstr-sdk@fb477b6: client/, core/, storage/, wallet/)
diff --git a/client/RoutstrClient.ts b/client/RoutstrClient.ts
index ad19634..8ceb932 100644
--- a/client/RoutstrClient.ts
+++ b/client/RoutstrClient.ts
@@ -2408,12 +2408,25 @@ export class RoutstrClient {
// Once started, BalanceManager owns redemption and identity-guarded
// cleanup. The deadline and abort only stop the caller from awaiting it.
const refund = this.balanceManager.refundApiKey({
- mintUrl,
+ // The provider refunds into the mint the token was actually spent
+ // from, not into the caller's preferred mint. `mintUrl` is only a
+ // preference and the two diverge in normal use: a wallet funded on
+ // two mints pays from whichever `selectMintWithBalance` reaches
+ // first. Pinning the preference would park an ordinary refund.
+ mintUrl: params.selectedMintUrl || mintUrl,
baseUrl,
apiKey: token,
forceRefund: true,
}).then(result => {
- params.lifecycle?.observe?.(result.success ? "refund_succeeded" : "refund_failed", undefined, { baseUrl });
+ params.lifecycle?.observe?.(
+ result.success
+ ? "refund_succeeded"
+ : result.quarantined
+ ? "refund_quarantined"
+ : "refund_failed",
+ undefined,
+ { baseUrl }
+ );
return result;
});
refundResult = (await awaitUntilDeadline(refund, deadline, params.signal))?.value;
@@ -2422,6 +2435,17 @@ export class RoutstrClient {
if (!refundResult) {
tryNextProvider = true;
this._log("WARN", `[RoutstrClient] API key recovery wait timed out for ${baseUrl}; continuing failover`);
+ } else if (refundResult.quarantined) {
+ // The refund was paid out into a mint this wallet did not ask for, so
+ // the proofs are parked durably instead of received. That is value
+ // recovered as far as it can go automatically — not a refund failure.
+ // Aborting the request here would turn an ordinary multi-mint refund
+ // into a provider error whose sats wait for a manual resolve.
+ tryNextProvider = true;
+ this._log(
+ "WARN",
+ `[RoutstrClient] API key refund for ${baseUrl} was minted at ${refundResult.tokenMintUrl ?? "an unexpected mint"}, not the mint the token was spent from; ${refundResult.quarantinedAmount ?? "the"} sats are parked in receive storage (resolveQuarantinedRefund). Failing over instead of aborting.`
+ );
} else {
if (refundResult.success) recoverySucceeded = true;
this._log(
@@ -2433,6 +2457,7 @@ export class RoutstrClient {
latestBalanceInfo &&
refundResult &&
!refundResult.success &&
+ !refundResult.quarantined &&
latestBalanceInfo.amount > 0 &&
!latestBalanceInfo.balanceUnknown
) {
diff --git a/core/types.ts b/core/types.ts
index baaac46..c641d6b 100644
--- a/core/types.ts
+++ b/core/types.ts
@@ -216,6 +216,23 @@ export interface RefundResult {
status?: number;
/** Structured routstr-core error when the provider returned one. */
parsedError?: import("./errorTypes").ParsedCoreError;
+ /**
+ * The refund token's mint is not the mint the refund was requested into.
+ * Present with `quarantined: true` when the token was parked, and on the
+ * X-Cashu path where the token was received anyway (the provider will not
+ * re-issue it once collected, so refusing would destroy it).
+ */
+ mintMismatch?: boolean;
+ /**
+ * The proofs are durable in receive storage but were deliberately not
+ * received. Resolve with `resolveQuarantinedRefund(token, "accept" |
+ * "discard")`; recovery will not touch them until then.
+ */
+ quarantined?: boolean;
+ /** Mint decoded from the refund token, when it was readable. */
+ tokenMintUrl?: string;
+ /** Value parked by a quarantine, in sats when the token reports sats. */
+ quarantinedAmount?: number;
}
/**
diff --git a/storage/store.ts b/storage/store.ts
index 2979a97..f5e87f6 100644
--- a/storage/store.ts
+++ b/storage/store.ts
@@ -364,6 +364,7 @@ const createEmptyStore = (
createdAt: entry.createdAt ?? Date.now(),
...(entry.cleanup?.length ? { cleanup: entry.cleanup } : {}),
...(entry.received ? { received: entry.received } : {}),
+ ...(entry.quarantined ? { quarantined: entry.quarantined } : {}),
}));
void driver.setItem(SDK_STORAGE_KEYS.CACHED_RECEIVE_TOKENS, normalized);
set({ cachedReceiveTokens: normalized });
diff --git a/wallet/BalanceManager.ts b/wallet/BalanceManager.ts
index 7067b7a..208872d 100644
--- a/wallet/BalanceManager.ts
+++ b/wallet/BalanceManager.ts
@@ -35,8 +35,10 @@ import { stampBalanceRead } from "./apiKeyBalance";
import {
getBalanceInSats,
getAvailableBalanceInSats,
+ getTokenMintPin,
isNetworkErrorMessage,
selectMintWithBalance,
+ tokenMintPinMatches,
} from "./tokenUtils";
/**
@@ -54,6 +56,16 @@ export interface RefundApiKeyOptions {
/** If true, forces refund even if the API key was used recently */
forceRefund?: boolean;
+
+ /**
+ * Receive a refund token whose mint is not `mintUrl` instead of parking it.
+ *
+ * Off by default, because receiving at a foreign mint is how a provider
+ * steers a payout. Turning it on accepts that risk explicitly; it is also the
+ * way to drain a quarantined token for one caller without widening the
+ * default.
+ */
+ allowForeignRefundMint?: boolean;
}
/**
@@ -345,7 +357,7 @@ export class BalanceManager {
* @returns Refund result
*/
async refundApiKey(options: RefundApiKeyOptions): Promise<RefundResult> {
- const { mintUrl, baseUrl, apiKey, forceRefund } = options;
+ const { baseUrl } = options;
const guard = this._canRunProviderWalletOperation(baseUrl, "refund");
if (!guard.allowed) {
@@ -357,7 +369,9 @@ export class BalanceManager {
let result: RefundResult | undefined;
try {
- result = await this._refundApiKeyImpl({ mintUrl, baseUrl, apiKey, forceRefund });
+ // Forward the object rather than a rebuilt literal: an option dropped
+ // here would silently disable a guard the caller asked for.
+ result = await this._refundApiKeyImpl(options);
return result;
} finally {
// An exception has an unknown outcome and retains the cooldown.
@@ -365,6 +379,26 @@ export class BalanceManager {
}
}
+ /**
+ * Act on a refund token the mint pin parked (`quarantined: true`).
+ *
+ * `accept` receives the proofs at the mint they were issued from — the caller
+ * is choosing that mint with the report in hand. `discard` deletes the parked
+ * copy, which abandons real value; it exists so a caller can stop carrying a
+ * poisoned token, not because the value was never paid.
+ */
+ async resolveQuarantinedRefund(
+ token: string,
+ action: "accept" | "discard"
+ ): Promise<Awaited<ReturnType<CashuSpender["resolveQuarantinedRefund"]>>> {
+ return this.cashuSpender.resolveQuarantinedRefund(token, action);
+ }
+
+ /** Refund tokens parked by the mint pin, awaiting a caller decision. */
+ getQuarantinedRefunds(): ReturnType<CashuSpender["getQuarantinedRefunds"]> {
+ return this.cashuSpender.getQuarantinedRefunds();
+ }
+
private async _refundApiKeyImpl(options: RefundApiKeyOptions): Promise<RefundResult> {
const { mintUrl, baseUrl, apiKey, forceRefund } = options;
@@ -519,6 +553,66 @@ export class BalanceManager {
// The provider has paid out and the token may be the only recoverable
// value. Do not receive or delete the key until this copy is durable.
await this.storageAdapter.flush?.();
+
+ // A refund token is the money, not an offer: by the time it exists the
+ // node has already settled the key (refund.execute -> _pay_cashu), and a
+ // second claim answers 425 "refund is pending" forever. So a token minted
+ // somewhere other than the requested mint is parked durably and reported,
+ // never refused — refusing would delete the only copy of the value while
+ // leaving the key spent anyway.
+ const tokenMintPin = getTokenMintPin(refundToken);
+ // An empty `mintUrl` means the caller knows of no mint, which is not the
+ // same claim as "the wrong mint": do not quarantine on it.
+ const mintMismatch = !tokenMintPinMatches(tokenMintPin, mintUrl);
+ // A multi-mint token is reported by every mint it carries, so the message
+ // and the parked record name all of them rather than the first.
+ const tokenMintUrl =
+ tokenMintPin.kind === "single"
+ ? tokenMintPin.mint
+ : tokenMintPin.kind === "multi"
+ ? tokenMintPin.mints.join(", ")
+ : null;
+
+ if (mintMismatch && !options.allowForeignRefundMint) {
+ const parked = this.cashuSpender.quarantineCachedReceiveToken(
+ refundToken,
+ {
+ reason: tokenMintPin.kind === "multi" ? "multi_mint" : "mint_mismatch",
+ mintUrl: tokenMintUrl as string,
+ expectedMintUrl: mintUrl,
+ baseUrl,
+ at: Date.now(),
+ }
+ );
+ // Parked copy durable before the key goes: the token is the claim now.
+ await this.storageAdapter.flush?.();
+ this.logger.warn(
+ `refund settled for ${baseUrl} at ${tokenMintUrl}, not ${mintUrl}; ${parked.amount} ${parked.unit} quarantined in receive storage`
+ );
+ if (this.storageAdapter.getApiKey(baseUrl)?.key === apiKey) {
+ this.storageAdapter.removeApiKey(baseUrl);
+ }
+ return {
+ success: false,
+ mintMismatch: true,
+ quarantined: true,
+ tokenMintUrl: tokenMintUrl as string,
+ quarantinedAmount:
+ parked.unit === "msat"
+ ? Math.round(parked.amount / 1000)
+ : parked.amount,
+ message: `Refund minted at ${tokenMintUrl}, not ${mintUrl}; proofs parked in receive storage. Resolve with resolveQuarantinedRefund(token, "accept" | "discard").`,
+ requestId: fetchResult.requestId,
+ parsedError: fetchResult.parsedError,
+ };
+ }
+
+ if (mintMismatch) {
+ this.logger.warn(
+ `refund settled for ${baseUrl} at ${tokenMintUrl}, not ${mintUrl}; receiving because allowForeignRefundMint is set`
+ );
+ }
+
const receiveResult = await this.cashuSpender.receiveToken(
refundToken,
false
diff --git a/wallet/CashuSpender.ts b/wallet/CashuSpender.ts
index bb4d5f1..f7a40f9 100644
--- a/wallet/CashuSpender.ts
+++ b/wallet/CashuSpender.ts
@@ -12,7 +12,14 @@ import { throwIfFundingAborted } from "./fundingCancellation";
* Extracted from hooks/useCashuWithXYZ.ts
*/
-import type { RecoveryCredential, WalletAdapter, StorageAdapter } from "./interfaces";
+import type {
+ CachedReceiveToken,
+ CachedReceiveTokenWrite,
+ RecoveryCredential,
+ RefundQuarantine,
+ WalletAdapter,
+ StorageAdapter,
+} from "./interfaces";
import type { SpendResult, SdkLogger } from "../core/types";
import { consoleLogger } from "../core/types";
import { InsufficientBalanceError, ProviderMintBalanceError } from "../core/errors";
@@ -22,7 +29,7 @@ import {
} from "../core/errorTypes";
import { BalanceManager } from "./BalanceManager";
import { persistApiKeyBalance } from "./apiKeyBalance";
-import { getBalanceInSats, isNetworkErrorMessage } from "./tokenUtils";
+import { getBalanceInSats, getTokenMintPin, isNetworkErrorMessage, readLegacyTokenEnvelope, tokenMintPinMatches } from "./tokenUtils";
import { getTokenMetadata } from "@cashu/cashu-ts";
/**
@@ -56,6 +63,22 @@ type DebugLevel = "DEBUG" | "WARN" | "ERROR";
type ReceiveResult = Awaited<ReturnType<WalletAdapter["receiveToken"]>>;
type RecoveryResult = ReceiveResult & { pending?: boolean };
+/**
+ * Outcome of one X-Cashu refund claim. `mintMismatch` records that the provider
+ * paid out at a different mint than the caller asked for and the token was
+ * received anyway: once the node marks the refund collected it will not issue
+ * the token again (a second claim answers 425 "refund is pending" forever), so
+ * refusing to receive would destroy the value rather than protect it.
+ */
+interface XcashuRefundResult {
+ baseUrl: string;
+ token: string;
+ success: boolean;
+ error?: string;
+ mintMismatch?: boolean;
+ tokenMintUrl?: string;
+}
+
/**
* CashuSpender manages the spending of Cashu tokens
*/
@@ -139,6 +162,17 @@ export class CashuSpender {
const work = Promise.resolve().then(async () => {
await this.storageAdapter.flush?.();
const cached = this.storageAdapter.getCachedReceiveTokens().find(entry => entry.token === token);
+ if (cached?.quarantined) {
+ // Parked on purpose: receiving here would redeem at a mint the caller
+ // did not choose, which is the exact decision the quarantine exists to
+ // leave to a caller.
+ return {
+ success: false,
+ amount: cached.amount,
+ unit: cached.unit,
+ message: `Refund token quarantined: minted at ${cached.quarantined.mintUrl}, expected ${cached.quarantined.expectedMintUrl}. Resolve with resolveQuarantinedRefund().`,
+ };
+ }
const result = cached?.received
? { success: true, amount: cached.amount, unit: cached.unit, message: undefined }
: await this.receiveToken(token);
@@ -216,12 +250,129 @@ export class CashuSpender {
]);
}
+ /** Rewrite one cached entry with a changed flag set, dropping `createdAt` duplication. */
+ private rewriteCachedEntry(
+ token: string,
+ change: (entry: CachedReceiveToken) => CachedReceiveTokenWrite
+ ): void {
+ this.storageAdapter.setCachedReceiveTokens(
+ this.storageAdapter.getCachedReceiveTokens().map(entry =>
+ entry.token === token ? change(entry) : entry
+ )
+ );
+ }
+
+ /**
+ * Park a refund token whose mint is not the mint the caller asked for.
+ *
+ * The entry is written but not received: the provider has already settled the
+ * key when it hands a token back, so the token *is* the value, and the choice
+ * between accepting it at the foreign mint and abandoning it belongs to a
+ * caller who can see the report. Nothing here flushes — the caller does, so a
+ * crash cannot separate "key removed" from "token durable".
+ */
+ quarantineCachedReceiveToken(
+ token: string,
+ quarantine: RefundQuarantine
+ ): { amount: number; unit: "sat" | "msat" } {
+ const existing = this.storageAdapter
+ .getCachedReceiveTokens()
+ .find(entry => entry.token === token);
+ if (existing) {
+ this.rewriteCachedEntry(token, entry => ({ ...entry, quarantined: quarantine }));
+ return { amount: existing.amount, unit: existing.unit };
+ }
+ const { amount, unit } = this._decodeTokenAmount(token);
+ this.storageAdapter.setCachedReceiveTokens([
+ ...this.storageAdapter.getCachedReceiveTokens(),
+ { token, amount, unit, createdAt: Date.now(), quarantined: quarantine },
+ ]);
+ return { amount, unit };
+ }
+
+ /** Quarantined refunds awaiting a caller decision. */
+ getQuarantinedRefunds(): CachedReceiveToken[] {
+ return this.storageAdapter
+ .getCachedReceiveTokens()
+ .filter(entry => entry.quarantined);
+ }
+
+ /**
+ * Act on a quarantined refund.
+ *
+ * `accept` clears the quarantine durably and then receives the token through
+ * the normal recovery path, so a crash mid-receive leaves an ordinary cached
+ * token instead of a stale quarantine. `discard` deletes the entry: the
+ * caller is choosing to abandon the value, not pretending it was never paid.
+ */
+ async resolveQuarantinedRefund(
+ token: string,
+ action: "accept" | "discard"
+ ): Promise<ReceiveResult> {
+ const entry = this.storageAdapter
+ .getCachedReceiveTokens()
+ .find(candidate => candidate.token === token);
+
+ if (!entry) {
+ return {
+ success: false,
+ amount: 0,
+ unit: "sat",
+ message: "No cached refund token for this value",
+ };
+ }
+ if (!entry.quarantined) {
+ return {
+ success: false,
+ amount: entry.amount,
+ unit: entry.unit,
+ message: "Refund token is not quarantined",
+ };
+ }
+
+ if (action === "discard") {
+ this.evictCachedReceiveToken(token);
+ await this.storageAdapter.flush?.();
+ this._log(
+ "WARN",
+ `[CashuSpender] resolveQuarantinedRefund: discarded ${entry.amount} ${entry.unit} from ${entry.quarantined.mintUrl} at caller request`
+ );
+ return {
+ success: false,
+ amount: entry.amount,
+ unit: entry.unit,
+ message: "Quarantined refund discarded; its value is abandoned",
+ };
+ }
+
+ this.rewriteCachedEntry(token, cached => ({
+ token: cached.token,
+ amount: cached.amount,
+ unit: cached.unit,
+ createdAt: cached.createdAt,
+ ...(cached.cleanup?.length ? { cleanup: cached.cleanup } : {}),
+ ...(cached.received ? { received: cached.received } : {}),
+ }));
+ await this.storageAdapter.flush?.();
+ return this.startCachedReceive(token);
+ }
+
/** Retry cached tokens not already owned by another receive. */
async recoverCachedReceiveTokens(): Promise<{ token: string; success: boolean }[]> {
const results: { token: string; success: boolean }[] = [];
- for (const { token } of this.storageAdapter.getCachedReceiveTokens()) {
+ for (const entry of this.storageAdapter.getCachedReceiveTokens()) {
+ const { token } = entry;
+ // Quarantined proofs are held for an explicit caller decision; a sweep
+ // must not quietly redeem them at the foreign mint.
+ if (entry.quarantined) {
+ this._log(
+ "DEBUG",
+ `[CashuSpender] recoverCachedReceiveTokens: skipping quarantined token from ${entry.quarantined.mintUrl} (expected ${entry.quarantined.expectedMintUrl})`
+ );
+ continue;
+ }
if (this.pendingReceives.has(token) ||
- !this.storageAdapter.getCachedReceiveTokens().some(entry => entry.token === token)) continue;
+ !this.storageAdapter.getCachedReceiveTokens().some(candidate => candidate.token === token)) continue;
const result = await this.startCachedReceive(token);
results.push({ token, success: result.success });
}
@@ -237,7 +388,12 @@ export class CashuSpender {
const unit = (metadata.unit as "sat" | "msat") || "sat";
return { amount: metadata.amount.toNumber(), unit };
} catch {
- return { amount: 0, unit: "sat" };
+ // A legacy multi-entry token is refused by the decoder; read its own
+ // envelope so a parked refund is not recorded as zero sats.
+ const legacy = readLegacyTokenEnvelope(token);
+ return legacy
+ ? { amount: legacy.amount, unit: legacy.unit }
+ : { amount: 0, unit: "sat" };
}
}
@@ -567,15 +723,8 @@ export class CashuSpender {
async refundXcashuTokens(
mintUrl: string,
excludeBaseUrls?: string[]
- ): Promise<
- { baseUrl: string; token: string; success: boolean; error?: string }[]
- > {
- const results: {
- baseUrl: string;
- token: string;
- success: boolean;
- error?: string;
- }[] = [];
+ ): Promise<XcashuRefundResult[]> {
+ const results: XcashuRefundResult[] = [];
const xcashuTokens = this.storageAdapter.getXcashuTokens();
const excludedUrls = new Set(excludeBaseUrls || []);
@@ -725,7 +874,31 @@ export class CashuSpender {
);
}
- // Receive the refunded Cashu token into the wallet
+ // Receive the refunded Cashu token into the wallet. Check the mint
+ // first, but receive regardless of the answer: the node has already
+ // marked this refund collected, and a second claim answers 425
+ // "refund is pending" forever — refusing here would strand the value
+ // on the node side instead of protecting it. The mismatch is reported
+ // to the caller instead of being silently swallowed.
+ const tokenMintPin = getTokenMintPin(fetchResult.token);
+ // An empty expected mint is "no opinion", not a pin: the flag must
+ // not claim a mismatch when nothing was expected.
+ const mintMismatch = !tokenMintPinMatches(tokenMintPin, mintUrl);
+ const tokenMintUrl =
+ tokenMintPin.kind === "single"
+ ? tokenMintPin.mint
+ : tokenMintPin.kind === "multi"
+ ? tokenMintPin.mints.join(", ")
+ : undefined;
+ if (mintMismatch) {
+ this._log(
+ "WARN",
+ `[CashuSpender] refundXcashuTokens: ${baseUrl} paid out at ${tokenMintUrl}, not ${mintUrl}; receiving anyway because the claim is already collected`
+ );
+ }
+ const mismatchReport = mintMismatch
+ ? { mintMismatch: true, tokenMintUrl }
+ : {};
const receiveResult = await this.receiveToken(fetchResult.token);
if (receiveResult.success) {
@@ -735,6 +908,7 @@ export class CashuSpender {
baseUrl,
token: xcashuToken.token,
success: true,
+ ...mismatchReport,
});
this._log(
"DEBUG",
@@ -750,6 +924,7 @@ export class CashuSpender {
token: xcashuToken.token,
success: false,
error: receiveResult.message,
+ ...mismatchReport,
});
this._log(
"WARN",
@@ -768,6 +943,7 @@ export class CashuSpender {
token: xcashuToken.token,
success: false,
error: receiveResult.message ?? "Refund failed",
+ ...mismatchReport,
});
this._log(
"DEBUG",
diff --git a/wallet/interfaces.ts b/wallet/interfaces.ts
index 390d3bb..4aa9375 100644
--- a/wallet/interfaces.ts
+++ b/wallet/interfaces.ts
@@ -93,6 +93,35 @@ export interface RecoveryCredential {
token: string;
}
+/**
+ * Why a durable refund token is parked instead of received.
+ *
+ * A refund token is not an offer: the provider has already settled the API key
+ * when it hands the token over, so the token *is* the money. Refusing to
+ * receive it therefore does not prevent a bad refund, it destroys the only copy
+ * of the value. Parking it instead keeps the value durable and leaves the
+ * decision — accept at the foreign mint, or abandon it — to a caller who can
+ * see the report.
+ */
+export interface RefundQuarantine {
+ /**
+ * `mint_mismatch`: the token names one mint, and it is not the expected one.
+ * `multi_mint`: the token carries proofs from several mints, so no single pin
+ * can hold for it; every mint is listed in `mintUrl`.
+ */
+ reason: "mint_mismatch" | "multi_mint";
+ /**
+ * The mint the token's proofs claim to be from, as encoded in the token.
+ * Comma-separated when `reason` is `multi_mint`.
+ */
+ mintUrl: string;
+ /** Mint the refund was requested into. */
+ expectedMintUrl: string;
+ /** Provider base URL the refund came from, when known. */
+ baseUrl?: string;
+ at: number;
+}
+
export interface CachedReceiveToken {
token: string;
amount: number;
@@ -102,6 +131,11 @@ export interface CachedReceiveToken {
cleanup?: RecoveryCredential[];
/** Wallet receive finished; only credential cleanup may remain. */
received?: true;
+ /**
+ * Proofs are durable here but deliberately not received. Recovery skips
+ * these entries until `resolveQuarantinedRefund` is called.
+ */
+ quarantined?: RefundQuarantine;
}
export type CachedReceiveTokenWrite = Omit<CachedReceiveToken, "createdAt"> & { createdAt?: number };
diff --git a/wallet/tokenUtils.ts b/wallet/tokenUtils.ts
index 9a7eaa6..c25c17d 100644
--- a/wallet/tokenUtils.ts
+++ b/wallet/tokenUtils.ts
@@ -1,4 +1,172 @@
import type { MintSelection } from "../core/types";
+import { getTokenMetadata } from "@cashu/cashu-ts";
+
+/**
+ * One spelling for comparing mint URLs.
+ *
+ * Scheme and authority are case-insensitive per RFC 3986, but the path is not:
+ * mints may serve distinct keysets under case-distinct paths, and lowercasing
+ * the whole string would make two different mints compare equal. Trailing
+ * slashes, query/fragment parts, userinfo and default ports are ignored because
+ * they do not name a different mint:
+ *
+ * - `https://mint.example.com:443` and `https://mint.example.com` are one mint;
+ * a token that spells the default port out used to read as "foreign" and park
+ * an ordinary refund.
+ * - `http://` vs `https://` stays a difference: same host, different transport
+ * origin, and a token's scheme is what the wallet would have to talk to.
+ */
+export function normalizeMintUrl(mintUrl: string | null | undefined): string {
+ const raw = (mintUrl ?? "").trim();
+ if (!raw) return "";
+ const match = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/([^/?#]*)(.*)$/.exec(raw);
+ if (!match) return raw.replace(/\/+$/, "");
+ const scheme = match[1].toLowerCase();
+ const hostPort = match[2].toLowerCase();
+ // Userinfo is a credential, not part of the mint's identity; two spellings
+ // that differ only there must still compare equal.
+ const withoutUser = hostPort.slice(hostPort.lastIndexOf("@") + 1);
+ const authority = dropDefaultPort(scheme, withoutUser);
+ const path = match[3].replace(/[?#].*$/, "").replace(/\/+$/, "");
+ return `${scheme}://${authority}${path}`;
+}
+
+/** Drop `:443`/`:80` when it is the scheme's default, keeping IPv6 brackets. */
+function dropDefaultPort(scheme: string, authority: string): string {
+ const defaultPort = scheme === "https" ? "443" : scheme === "http" ? "80" : null;
+ if (!defaultPort) return authority;
+ const match = /^(\[[^\]]*\]|[^:]+):(\d+)$/.exec(authority);
+ return match && match[2] === defaultPort ? match[1] : authority;
+}
+
+/** True when both URLs name the same mint. Empty/unknown never matches. */
+export function mintsMatch(
+ a: string | null | undefined,
+ b: string | null | undefined
+): boolean {
+ const left = normalizeMintUrl(a);
+ return left !== "" && left === normalizeMintUrl(b);
+}
+
+/**
+ * What a token says about the mint that issued it.
+ *
+ * - `single`: the decoder named one mint — the ordinary case.
+ * - `multi`: the token carries proofs from more than one mint, so a pin has to
+ * hold for *every* one of them. Only the legacy `cashuA` format can express
+ * this: cashu-ts refuses multi-entry tokens outright ("Multi entry token are
+ * not supported"), so a multi-entry token never reaches here through the
+ * normal decoder and has to be read from its own envelope.
+ * - `unknown`: nothing could be read. **Unknown is not a mismatch**: this is the
+ * same decoder the wallet uses to receive the token, so a token that cannot
+ * be read here may still be recoverable there — and by the time a refund token
+ * exists the provider has usually already paid it out. A caller that pins a
+ * mint must park an unreadable token for recovery, never discard it.
+ */
+export type TokenMintPin =
+ | { kind: "single"; mint: string }
+ | { kind: "multi"; mints: string[] }
+ | { kind: "unknown" };
+
+/**
+ * Read every mint a token claims, without assuming there is exactly one.
+ *
+ * The single-mint answer comes from `getTokenMetadata`. When that throws for a
+ * legacy `cashuA` envelope we read the envelope ourselves and collect the
+ * distinct `mint` fields, because "the first entry's mint" is exactly the
+ * shortcut that would let a two-mint token pass a single-mint pin.
+ */
+export function getTokenMintPin(token: string): TokenMintPin {
+ try {
+ const mint = getTokenMetadata(token).mint;
+ if (typeof mint === "string" && mint.trim() !== "") {
+ return { kind: "single", mint };
+ }
+ } catch {
+ // Fall through to the envelope read below.
+ }
+ const legacy = readLegacyTokenEnvelope(token);
+ if (!legacy || legacy.mints.length === 0) return { kind: "unknown" };
+ const distinct = [...new Set(legacy.mints)];
+ return distinct.length === 1
+ ? { kind: "single", mint: distinct[0] }
+ : { kind: "multi", mints: distinct };
+}
+
+/**
+ * What a legacy `cashuA` envelope says about itself, or `null` if it cannot be
+ * read.
+ *
+ * This exists because cashu-ts refuses multi-entry tokens outright ("Multi
+ * entry token are not supported") — both `getTokenMetadata` and
+ * `getDecodedToken` throw — so a token whose entries name different mints has
+ * to be read from its own envelope. Reading it here is also what gives such a
+ * token a real amount: the normal decoder cannot supply one, and a parked
+ * refund recorded as `0 sats` is an accounting lie.
+ */
+export interface LegacyTokenEnvelope {
+ mints: string[];
+ amount: number;
+ unit: "sat" | "msat";
+}
+
+export function readLegacyTokenEnvelope(
+ token: string
+): LegacyTokenEnvelope | null {
+ if (!token.startsWith("cashuA")) return null;
+ try {
+ const b64 = token
+ .slice("cashuA".length)
+ .replace(/-/g, "+")
+ .replace(/_/g, "/");
+ const padded = b64 + "=".repeat((4 - (b64.length % 4)) % 4);
+ const payload = JSON.parse(atob(padded)) as {
+ token?: Array<{ mint?: unknown; proofs?: Array<{ amount?: unknown }> }>;
+ unit?: unknown;
+ };
+ if (!Array.isArray(payload?.token)) return null;
+ const entries = payload.token;
+ const mints = entries
+ .map(entry => (typeof entry?.mint === "string" ? entry.mint.trim() : ""))
+ .filter(mint => mint !== "");
+ let amount = 0;
+ for (const entry of entries) {
+ if (!Array.isArray(entry?.proofs)) continue;
+ for (const proof of entry.proofs) {
+ const value = Number(proof?.amount);
+ if (Number.isFinite(value) && value > 0) amount += value;
+ }
+ }
+ const unit = payload?.unit === "msat" ? "msat" : "sat";
+ return { mints, amount, unit };
+ } catch {
+ return null;
+ }
+}
+
+/** True when a pin is satisfied by `expected`; unknown never passes. */
+export function tokenMintPinMatches(
+ pin: TokenMintPin,
+ expected: string | null | undefined
+): boolean {
+ if (normalizeMintUrl(expected) === "") return true; // no expectation to fail
+ if (pin.kind === "single") return mintsMatch(pin.mint, expected);
+ if (pin.kind === "multi") return pin.mints.every(m => mintsMatch(m, expected));
+ return true; // unknown: not evidence of a mismatch
+}
+
+/**
+ * The mint a Cashu token was issued from, exactly as encoded, or `null` when
+ * the token cannot be decoded or carries more than one mint.
+ *
+ * Convenience wrapper over {@link getTokenMintPin} for callers that only need
+ * the plain case. A pinning caller should use the full pin, so that a
+ * multi-mint token is a mismatch rather than a silent `null`.
+ */
+export function getTokenMintUrl(token: string): string | null {
+ const pin = getTokenMintPin(token);
+ return pin.kind === "single" ? pin.mint : null;
+}
/**
* Transport failures that mean "this provider could not be reached at all",
Tests added
tests/unit/refundMintPinClient.test.ts (3): pins the mint the token was spent from; falls back to the preferred mint when no spent mint is known; treats a quarantined refund as recovered with a warning (fails over, does not abort).
tests/unit/refundMintQuarantine.test.ts (20, of which 7 are new): default port and userinfo are the same mint; a two-mint token is quarantined as multi_mint with both mints and its real amount; a multi-entry token whose entries are all the requested mint is received; the x-cashu path does not flag a mismatch when nothing was expected; pin kinds (single/multi/unknown) and tokenMintPinMatches; normalizeMintUrl default-port/userinfo/scheme/real-port cases; readLegacyTokenEnvelope mints and amount.
Limits, stated rather than papered over
- No live-mint run: every number comes from the unit suite, the repo’s types, and
routstr-core’s own code paths. - The pin reads the mint the token declares. A mint that lies about its own URL is out of reach.
- Multi-mint CBOR tokens read as
unknown(see above); they are never accepted by the wallet, but they are not proactively parked either. scripts/refund-all.tsandscripts/routstr-cheapest.tssurface parked tokens only throughgetQuarantinedRefunds(); neither decides for the operator.
— Vela (npub16yujr0g0njhvgqlcl45dsk90plaquj7ag2f079meu2jvw6me4z5qh69fqz), 2026-11-19.
Write a comment