add plan

docs/nip60.md

@@ -0,0 +1,236 @@
+# NIP-60: cashu wallet — implementation plan
+
+Spec: https://github.com/nostr-protocol/nips/blob/master/60.md
+CDK: https://github.com/cashubtc/cdk (crates `cdk`, `cdk-sqlite`, `cdk-nostr` 0.18.x)
+
+NIP-60 stores a user's cashu wallet state on relays: the wallet config
+(kind `17375`), its unspent proofs (kind `7375`), and an optional spending
+history (kind `7376`). All content is NIP-44 encrypted to self. This plan
+implements it inside coop using the CDK for all cashu/mint operations and
+the app's existing nostr client/signer for events.
+
+## Analysis
+
+| Kind   | Replaceable | Content (NIP-44 to self)                        | Purpose                          |
+| ------ | ----------- | ----------------------------------------------- | -------------------------------- |
+| 17375  | yes         `[[privkey, hex], [mint, url], ...]`            | wallet config: P2PK key + mints  |
+| 7375   | no          `{mint, unit, proofs[], del[]}`                 | unspent proofs (per mint)        |
+| 7376   | no          `[[direction], [amount], [unit], [e, ...]]`     | spend/receive history (optional) |
+| 7374   | no          `quote-id` + `mint`/`expiration` tags           | pending mint quote (optional)    |
+| 10019  | yes         empty, `relay` tags                             | wallet relay list                |
+
+Key mechanics:
+
+- Wallet state transitions are rollover: spending part of a token event
+  publishes a new `7375` with the unspent proofs + `del: [old-event-id]`,
+  then NIP-09 deletes the old event (the delete MUST carry `["k", "7375"]`).
+- The `privkey` in `17375` is a wallet-only key (never the nostr identity
+  key). It exists to unlock P2PK-locked ecash, i.e. redeeming NIP-61
+  nutzaps.
+- NIP-60 itself does not move money to/from others. Receiving ecash from
+  peers is NIP-61 (nutzaps): gift-wrapped token events P2PK-locked to the
+  wallet pubkey. Redemption is `receive` + a `7376` with an `e` tag
+  marked `redeemed` (this one tag stays unencrypted).
+- History (7376) and quote events (7374) are optional; the spec recommends
+  local state for quotes. We publish 7376, skip 7374 (cdk keeps quotes in
+  its local DB).
+
+## How it fits coop
+
+Follows the existing crate patterns exactly; no new architecture.
+
+- One protocol crate: `crates/nip60`, mirroring `nip4e`/`nip29` — a
+  registry entity set as GPUI global by `init(cx)`, `EventEmitter` for
+  UI updates, `SmallVec<Task>` + `SmallVec<Subscription>` fields, flume
+  signal channel for background results, reset/reload on
+  `NostrRegistry::signer_changed` (see `crates/nip29/src/lib.rs`).
+- Desktop-only: crate-level `#![cfg(not(target_arch = "wasm32"))]` like
+  `crates/auto_update/src/lib.rs`. Wallet UI is only wired on desktop.
+- Tokio bridge: all cdk calls run through `gpui_tokio::Tokio::spawn(cx, ...)`
+  (runtime is already initialized by `state::init`). The `cdk-nostr`
+  inbox listener also runs on that runtime.
+- Signer-agnostic encryption: the signer may be a bunker/extension, so we
+  never use `nostr::nip60::*::prepare` (they need an owned `SecretKey`).
+  We build payloads as plain JSON, encrypt with
+  `signer.nip44_encrypt(self_pubkey, json)` and sign with
+  `EventBuilder::new(kind, content).finalize_async(signer)` — the same
+  pattern as `crates/nip4e/src/storage.rs`. Parsing is decrypt-then-parse:
+  `TokenEvent` derives `Deserialize`; `17375` content is a trivial
+  `Vec<Vec<String>>` parse.
+- Existing facts we build on:
+  - rust-nostr (git, already a dependency) ships `nostr::nip60` with the
+    event data types (`WalletEvent`, `TokenEvent`, `SpendingHistory`,
+    `QuoteEvent`, `CashuProof`) and kinds
+    (`Kind::CashuWallet` = 17375, `CashuWalletUnspentProof` = 7375,
+    `CashuWalletSpendingHistory` = 7376, `CashuWalletQuote` = 7374).
+    It is behind the `nip60` feature, which coop does not enable yet.
+  - `state::NostrRegistry` gives the `Client` (LMDB cache + bootstrap
+    relays + gossip) and the `UniversalSigner`.
+  - Local file storage precedent: `NostrLmdb::open(config_dir().join("nostr"))`
+    in `crates/state/src/lib.rs`; cdk's sqlite store goes to
+    `config_dir().join("cashu")`.
+
+## Dependencies
+
+Workspace `Cargo.toml`:
+
+```toml
+nostr = { git = "https://github.com/rust-nostr/nostr", features = [ "nip59", "nip49", "nip44", "nip60", "nip98" ] }
+
+[patch.crates-io]
+# cdk publishes against crates.io nostr 0.45.x; coop uses the git source.
+# The patch unifies both on one copy of the crate so types cross crate
+# boundaries (cdk-nostr inbox events, keys) without conversion.
+nostr = { git = "https://github.com/rust-nostr/nostr" }
+nostr-sdk = { git = "https://github.com/rust-nostr/nostr" }
+```
+
+`crates/nip60/Cargo.toml` (all under `cfg(not(wasm32))`):
+
+```toml
+cdk = { version = "0.18", default-features = false, features = ["wallet"] }
+cdk-sqlite = { version = "0.18", default-features = false, features = ["wallet"] }
+cdk-nostr = { version = "0.18", default-features = false } # inbox, for NIP-61
+```
+
+Version-unification is the one risky step; Phase 0 is a spike that proves
+`cdk 0.18.x` + git rust-nostr build together. Fallback if the patch fights
+back: convert only at the cdk-nostr inbox boundary (hex/serde) and skip the
+patch for `nostr-sdk`.
+
+## Design
+
+### Key material
+
+- On first `setup(mint_url)` (explicit user action, no auto-creation):
+  generate `SecretKey::generate()` as the wallet key, publish `17375`
+  containing it + the mint list (encrypted to self, signed by the user).
+- The cdk seed is derived deterministically from the wallet key
+  (`HKDF-SHA256(wallet_privkey, info = "coop cashu seed")` -> `[u8; 64]`).
+  No extra local storage, and a fresh device recovers the full wallet from
+  the relay state alone. Tradeoff: the derivation is coop-specific (NIP-60
+  does not standardize seed derivation), so it does not restore into other
+  apps — acceptable, see open questions.
+- Proof-level secrets/counters live in cdk's sqlite store; NUT-13 restore
+  from mints works because the seed is deterministic.
+
+### Local state
+
+- cdk sqlite store at `config_dir().join("cashu")` (one `WalletDatabase`
+  shared by all mint wallets).
+- `WalletRegistry` holds: parsed `17375` (`WalletEvent` + event id), the
+  active `7375` events per mint (event id + `TokenEvent`), cdk `Wallet`
+  per mint (`CurrencyUnit::Sat` only in v1), and the subscription handle.
+
+### Relay sync
+
+- One subscription: `authors: [me], kinds: [17375, 7375, 7376]` plus
+  kind `5` with `k: 7375`, on the existing client (bootstrap relays).
+  Notifications flow through the nip29-style flume channel.
+- Published relays: the same client/relays coop already uses. Publishing a
+  `10019` wallet relay list with those relays is a one-liner for interop;
+  reading `10019` from other clients is skipped in v1 (coop always uses
+  its own relay set).
+
+### Operations
+
+Each op runs on tokio and ends with the same `sync` tail:
+read unspent proofs from cdk -> publish one `7375` per changed mint
+(rolling up previous event ids into `del`) -> NIP-09 delete old events with
+a `k:7375` tag -> publish `7376` history -> update registry state and emit.
+
+- `setup(mint_url)`: create wallet key + seed, publish `17375`, build cdk
+  `Wallet`, open subscription.
+- `create_mint_quote(amount)`: `wallet.mint_quote` -> return invoice to UI;
+  poll / subscribe quote state, then `wallet.mint(quote_id)` -> sync.
+  On load, `mint_unissued_quotes` claims quotes paid elsewhere.
+- `melt(invoice)`: `wallet.melt` -> sync (change proofs roll over).
+- `send_token(amount)`: `wallet.send` -> return token string for the user
+  to share -> sync. (No in-chat token delivery in v1.)
+- `receive_token(token)`: `wallet.receive` -> sync.
+- Redeem nutzap (NIP-61): verify the gift-wrapped proofs are P2PK-locked to
+  the wallet pubkey, then `wallet.receive_proofs(proofs, ReceiveOptions {
+  p2pk_signing_keys: [wallet_key] })` -> `7376` with unencrypted
+  `e <nutzap-id> "" redeemed` tag -> sync.
+- Remote `7375` from another device: import its unspent proofs into the
+  cdk store as the new local truth (cdk proof insertion + state check via
+  `check_proofs_spent`); superseded `7375`s reconcile through `del`/NIP-09.
+- On every load: `recover_incomplete_sagas` and `mint_unissued_quotes`
+  (required by cdk to clear interrupted operations), then re-derive the
+  unspent set from `7375` minus deletes.
+
+### Crate layout (3 files, kept small on purpose)
+
+- `lib.rs` — `init`, `WalletRegistry`, `WalletEvent` (`Updated`, `Error`),
+  subscription/notification handling, `reset` on signer change.
+- `keys.rs` — wallet key/seed derivation, `17375` build/parse via signer.
+- `ops.rs` — cdk operations + the shared `sync` tail (rollover, deletes,
+  history), NIP-61 redemption.
+
+Wiring: `nip60::init(cx)` in `desktop/src/main.rs` after `nip4e::init(cx)`;
+`nip60 = { path = "../crates/nip60" }` added to `desktop/Cargo.toml` (and
+the UI crate when Phase 3 lands).
+
+## Phases
+
+### Phase 0 — dependency spike (small, throwaway)
+
+1. Enable `nip60` on the `nostr` workspace dep; confirm
+   `nostr::nip60` types and the four kinds compile.
+2. Add the `[patch.crates-io]` block and a scratch dependency on
+   `cdk`/`cdk-sqlite`/`cdk-nostr`; `cargo check` desktop. Resolve the
+   nostr unification here before writing any code.
+
+### Phase 1 — bootstrap + load + balance
+
+1. `crates/nip60` skeleton: registry, `init`, signer-changed reset.
+2. `keys.rs`: wallet key generation, seed derivation, `17375` parse/build.
+3. Load path: query cached + subscribed events, build the unspent set,
+   open cdk wallets, import proofs, expose `balance()` and emit `Updated`.
+4. `setup(mint_url)` + mint list update (republish `17375`).
+
+### Phase 2 — moving money
+
+1. `ops.rs` sync tail: rollover `7375`, NIP-09 deletes (`k` tag), `7376`
+   history.
+2. `create_mint_quote` (+ claim-on-load), `melt`, `send_token`,
+   `receive_token`, each with error propagation to the registry event.
+
+### Phase 3 — NIP-61 redemption (cdk-nostr)
+
+1. `cdk_nostr::NostrInbox` on the wallet key + relays, started in
+   `Tokio::spawn`, stopped on reset; rumors parsed into proofs + mint.
+2. Redemption path with `p2pk_signing_keys`, `redeemed` history tag.
+
+### Phase 4 — UI
+
+- Settings entry for the mint URL (`settings` crate pattern).
+- Minimal wallet surface in the workspace (balance, receive invoice,
+  paste-token receive, send-token, history list) subscribing to
+  `WalletEvent`. Follows `nip29_ui`'s split if it grows beyond a panel.
+
+## Tests
+
+- `keys.rs` round-trips: encrypt/decrypt `17375` payloads against the
+  rust-nostr reference types (mirrors `nostr::nip60` unit tests).
+- Rollover logic: given prior token events + a new unspent set, assert the
+  produced `7375`/delete/`7376` trio (pure functions, no network).
+- Integration (optional, behind `#[ignore]`): testnut mint mint -> melt
+  cycle against cdk's memory store.
+
+## Open questions / tradeoffs
+
+- Seed derivation is coop-specific; cross-app portability of proof
+  restores is unsolved by NIP-60 generally. Revisit if a derivation
+  convention lands in the NIP or cdk.
+- v1 is single-unit (`sat`) and effectively single-mint in the UI, even
+  though the event format and registry support many mints.
+- Concurrent spends from two devices double-spend; recovery is the spec's
+  Appendix-1 validation (check proofs at the mint, roll over survivors) —
+  implemented as reconciliation on sync, not real-time locking.
+- Web target gets no wallet in v1: `cdk-sqlite` (rusqlite bundled) does
+  not build on wasm32; the crate compiles to nothing there (auto_update
+  pattern). A wasm store would need a cdk `WalletDatabase` over
+  IndexedDB — explicitly out of scope.
+- `7374` quote events are skipped (local cdk state per the spec); pending
+  quotes are not visible to other devices until claimed.