Cashu TS Migration

@cashu/cashu-ts v2 → v4 Migration

cashu-ts v3 was a hard breaking change: classes were renamed (CashuMint/CashuWallet → Mint/Wallet), keysets moved into a KeyChain, all amounts became an opaque Amount class, mint/melt quote helpers were split per-payment-method (Bolt11/Bolt12), and wallets must be explicitly initialized with loadMint(). v4 layered additional API hardening on top. The authoritative migration guide ships in the package itself: read node_modules/@cashu/cashu-ts/migration-4.0.0.SKILL.md before starting.

Pre-flight (do once)

1. Read node_modules/@cashu/cashu-ts/migration-4.0.0.SKILL.md end-to-end.
2. Pin the new version in package.json, run npm install.
3. Independent prerequisite — @noble/hashes ≥ v2: v2 dropped implicit .js extension resolution from ESM subpath imports. Sed-rename every from "@noble/hashes/utils" to from "@noble/hashes/utils.js" (and any other subpath you import). Skip and you get cryptic Next.js/Vite/Webpack module resolution errors that look like a cashu-ts problem.
4. @cashu/crypto/modules/common was dropped: hashToCurve is re-exported from @cashu/cashu-ts itself. Replace import { hashToCurve } from "@cashu/crypto/modules/common" with import { hashToCurve } from "@cashu/cashu-ts".

Step 1 — Class rename: import aliasing keeps blast radius small

CashuMint and CashuWallet no longer exist. Use the new Mint / Wallet exports. Aliasing in the import line preserves every downstream call site:

// before
import { CashuMint, CashuWallet } from "@cashu/cashu-ts";

// after
import { Mint as CashuMint, Wallet as CashuWallet } from "@cashu/cashu-ts";

This pattern lets new CashuMint(...) / new CashuWallet(...) keep working everywhere. Apply across all production AND test files.

Step 2 — Drop removed constructor options

The Wallet constructor no longer accepts { keys } (or other preload options). Construct the wallet with just the mint, then call loadMint():

// before
const wallet = new CashuWallet(mint, { keys: storedKeys });

// after
const wallet = new CashuWallet(mint);
await wallet.loadMint(); // hydrates mint info, keysets, keys

Step 3 — Method renames (BOLT11 helpers)

All quote-related wallet methods were split per payment method. For Lightning (the common case), append Bolt11. A bulk sed pass works because the names are unambiguous within wallet.X(:

for f in $(git ls-files '*.ts' '*.tsx'); do
  sed -i \
    -e 's/wallet\.createMintQuote(/wallet.createMintQuoteBolt11(/g' \
    -e 's/wallet\.checkMintQuote(/wallet.checkMintQuoteBolt11(/g' \
    -e 's/wallet\.mintProofs(/wallet.mintProofsBolt11(/g' \
    -e 's/wallet\.createMeltQuote(/wallet.createMeltQuoteBolt11(/g' \
    -e 's/wallet\.meltProofs(/wallet.meltProofsBolt11(/g' \
    -e 's/wallet?\.createMeltQuote(/wallet?.createMeltQuoteBolt11(/g' \
    "$f"
done

Be sure to handle optional-chain forms (wallet?.createMeltQuote() explicitly.

Step 4 — Keysets moved into KeyChain

wallet.getKeySets() is gone. Use wallet.keyChain.getKeysets() which returns Keyset[] (a domain class), not the raw API DTO MintKeyset.

sed -i 's/wallet\.getKeySets()/wallet.keyChain.getKeysets()/g' "$f"

If the codebase has type annotations using MintKeyset against the result, the cheapest fix is to alias Keyset as MintKeyset in the import — both classes expose .id so most call sites are unaffected:

import { Keyset as MintKeyset } from "@cashu/cashu-ts";

If your code reads more than .id (e.g. active), you'll need to switch to Keyset proper and adjust field accesses.

Step 5 — The Amount boundary (CRITICAL)

Amount is a class. Every quote/proof/response now carries Amount where v2 had number. The migration guide presents two strategies:

• Choice A: refactor your domain types to Amount end-to-end.
• Choice B (recommended for sat-denominated marketplaces below MAX_SAFE_INTEGER): keep internal types as number, convert at the cashu-ts boundary with .toNumber().

Choice B was the right call for shopstr (sat-only marketplace, simpler diff). Apply systematically:

// arithmetic — both Amounts → both .toNumber()
const total = meltQuote.amount.toNumber() + meltQuote.fee_reserve.toNumber();

// reduce sums over Proofs (Proof.amount is Amount in v3+)
const total = proofs.reduce((acc, p) => acc + p.amount.toNumber(), 0);

// passing to functions that take number (e.g. UI formatters)
formatWithCommas(meltQuote.fee_reserve.toNumber(), "sats");

// re-extracting an Amount from a response
const meltAmount = meltResponse.quote.amount.toNumber();

A single sed pass catches the high-volume reduce patterns:

sed -i \
  -e 's/acc + token\.amount/acc + token.amount.toNumber()/g' \
  -e 's/acc + p\.amount/acc + p.amount.toNumber()/g' \
  -e 's/acc + current\.amount/acc + current.amount.toNumber()/g' \
  -e 's/meltQuote\.amount + meltQuote\.fee_reserve/meltQuote.amount.toNumber() + meltQuote.fee_reserve.toNumber()/g' \
  "$f"

Method inputs that accept AmountLike (e.g. wallet.createMintQuoteBolt11(amount), wallet.send(amount, proofs, ...)) accept raw number. No conversion needed at input sites.

Step 6 — getDecodedToken requires a second argument

getDecodedToken(token, keysetIds: string[])

The second argument is the list of keyset IDs the caller is willing to trust for V2 (Hashed) keysets. Pass [] if your application only handles standard hex (V1) keyset IDs (the universal default for current Cashu mints). For mints using v2 hashed keyset IDs you must obtain the IDs out-of-band first via getTokenMetadata.

// before
const decoded = getDecodedToken(token);

// after (safe for v1 hex keysets)
const decoded = getDecodedToken(token, []);

Step 7 — MintQuoteState lives on the bolt11-specific response

MintQuoteBaseResponse is method-agnostic and does NOT carry state. Use the Bolt11 variants (returned by checkMintQuoteBolt11) which extend the base with state: MintQuoteState. Same story for fee_reserve on melt — only present on MeltQuoteBolt11Response. Once you've completed Step 3 the typed return values flow correctly.

import { MintQuoteState } from "@cashu/cashu-ts";
const status = await wallet.checkMintQuoteBolt11(quote);
if (status.state === MintQuoteState.PAID) { ... }