archy/docs/cashu-cdk-migration-plan.md

Cashu: move to the reference implementation (cashu / CDK)

Status: planned (2026-08-17). Scoped from the framework-pt keyset incident.

Why

The node's Cashu support is hand-rolled: the NUT-00 token codec (wallet/cashu.rs), the blind-DH crypto (wallet/bdhke.rs) and the mint HTTP client (wallet/mint_client.rs) are ours. That was fine while the protocol was small; it isn't any more.

The cost showed up on 2026-08-17: a Minibits token could not be redeemed because it carried a NUT-02 v2 keyset id truncated to 8 bytes. The mint — itself CDK-based — rejected the swap with NUT02: ID length invalid. The reference implementation has carried the resolver for this exact case (Id::from_short_keyset_id) since v0.11, and requires the mint's keyset list to turn a token into proofs, so it cannot forward a truncated id. We shipped an equivalent repair by hand (2277fc46); the general lesson is that we are tracking a moving spec on our own, and we keep finding out where we lag from production failures.

Other gaps we carry today:

• No DLEQ verification. V4 tokens' d/w fields are parsed and discarded, so we cannot prove a mint signed with the keyset it claims.
• No deterministic secrets (NUT-13). bdhke::generate_secret is pure randomness, which means the ecash wallet cannot be restored from a seed — losing wallet/ecash.json loses the coins.
• We emit only cashuA (V3); most wallets now default to cashuB (V4).

What we adopt

The cashu crate alone (MIT, from cashubtc — the crate CDK itself is built on), not the full cdk wallet with its WalletDatabase.

That gives us, from audited upstream code:

• nut00::Token — encode and decode both cashuA and cashuB, plus to_v3_string() for older wallets
• nut02::{Id, KeySetVersion, KeySetInfo} — correct v1 (8-byte) and v2 (33-byte) ids, and Id::from_short_keyset_id for the truncated case
• dhke::{hash_to_curve, blind_message, unblind_message} — the crypto, with upstream's test vectors
• DLEQ verification
• NUT-13 deterministic secrets

It is a light dependency: ~7 transitive crates, no reqwest, no runtime opinions. bitcoin ^0.32.2 matches our pinned =0.32.5, so secp256k1 stays a single copy in the tree.

What we deliberately keep

• wallet/ecash.rs and every on-disk file, unchanged. wallet/ecash.json, accepted_mints.json, pending_swaps.json, swap_liquidity.json keep their exact schemas — including StoredProof's flattened shape and the capital-C field. Balances, history and trusted mints survive the update untouched.
• EcashTransaction — Fedimint and Ark write the same struct; it is a cross-backend contract, not Cashu-private.
• MintClient's HTTP surface, its Tor-capable with_client seam, and the NUT error-code → plain-English table (which is better UX than upstream's raw errors).
• Our multi-mint logic — swap_between_mints, plan_payment, the liquidity cache and the crash-safe swap journal have no upstream equivalent.

What we do NOT adopt, and why

cdk::wallet::Wallet requires implementing WalletDatabase — ~50 methods. Roughly 30 have no home in our format (keyset caches, NUT-13 counters, sagas, uuid-keyed reservations, KV, P2PK), and the ~20 that do map are lossy in both directions on exactly the records that hold real money (proof state, and a transaction type shared with two other backends). A permanent compatibility shim over live funds is the wrong trade. If we ever want the full wallet, it should come with a one-way format migration, decided separately.

Seed backup, derived from the node seed

Today the ecash wallet has no seed and cannot be recovered. With NUT-13 it can, and it should not introduce a second thing for the operator to write down:

• Derive the Cashu wallet seed from the existing node master seed over a dedicated BIP32 path, alongside the node's other derived keys. The node's 24 words then already back up the ecash wallet — nothing new to record, and a restored node re-derives the same secrets.
• Persist the per-keyset NUT-13 counter (upstream's increment_keyset_counter) in a new sidecar file. It is recovery metadata, not funds: a lost counter costs a restore scan, not coins.
• Surface it in the UI the way the node seed already is: a "back up / restore ecash" path that states plainly that the node's recovery phrase covers it.

The words we show, and why they are their own mnemonic

Derive a dedicated BIP-39 mnemonic for the Cashu wallet from the node master seed (deterministic, fixed path), rather than showing the node's own 24 words. Both properties matter:

• it is still covered by the node's recovery phrase — a restored node re-derives the same ecash wallet, nothing extra to write down;
• but it is portable: the operator can restore their ecash in any NUT-13 wallet (Minibits, Nutstash, cdk-cli) without handing over the node's master seed. Showing the node seed here would make "back up my ecash" and "expose the key to everything" the same action.

Where it appears — the existing seed-reveal pattern, unchanged

Mirror the Lightning seed backup exactly; do not invent a second pattern.

Piece	Lightning (existing)	Ecash (to build)
Shared UI	components/SeedRevealPanel.vue (:words, Words/QR tabs, tap-to-reveal blur, SeedQR)	same component, reused as-is
App detail page	views/appDetails/LndSeedBackup.vue, rendered from AppDetails.vue:22 when packageKey === 'lnd' && pkg.installed	views/appDetails/EcashSeedBackup.vue, rendered the same way for the ecash-bearing app
Settings	views/settings/BackupSection.vue:352	same section, a panel beside it
Status RPC	lnd.seed-backup-status	wallet.ecash-seed-status
Reveal RPC	lnd.seed-reveal	wallet.ecash-seed-reveal
Auth gate	verify_reveal_auth(&params, "the Lightning seed") — password re-entry	same helper, "the ecash seed"

Pass SeedRevealPanel without the aezeed flag: unlike LND's aezeed, this is standard BIP-39, so the SeedQR tab works and third-party wallets can consume it.

Open question for the operator: whether to also allow importing an externally generated ecash mnemonic (bring-your-own, breaking the derived-from-node link). Default should be derived-from-node.

Options this unlocks (worth considering, not committed)

• Run our own mint. Upstream ships cdk-mintd. Packaged as an app it would make a node its own Cashu mint — the same shape as the fedimint-clientd sidecar, and launchable from the dashboard if it has a UI. Independent of the wallet work here.
• P2PK / locked tokens (NUT-11) — send ecash only a specific pubkey can redeem, which fits the mesh/federation identity we already have.
• Multi-unit support beyond sats.

Sequencing

1. Repair truncated v2 keyset ids so the failing case works now — done, 2277fc46.
2. Swap wallet/cashu.rs + wallet/bdhke.rs internals for the cashu crate, keeping every public signature and the on-disk contract. Existing tests in both modules stay as the regression net; add upstream's DLEQ vectors.
3. Emit cashuB (V4) by default, keep cashuA for compatibility.
4. NUT-13 deterministic secrets + node-seed derivation, the reveal/restore surfaces above (app detail page and Settings), and a restore-from-words path so a wallet can be rebuilt from the mnemonic alone.
5. Then reconsider cdk-mintd and NUT-11 as separate features.

Verify each step against a real mint on a test node before the fleet, and keep wallet/ecash.json from a pre-migration node to prove it still loads.