# Cashu Escrow (marketplace)

Status: **core implemented & unit-tested; wallet UI is native-only and awaits
on-device verification.** See "Status" at the bottom before trusting it with
real money.

## Goal

Let a buyer and seller close a marketplace deal where the buyer's funds are
**committed but recoverable**, so neither side has to trust the other blindly —
without a custodial third party and without an always-online oracle.

## Model — time-locked P2PK

Cashu **P2PK** (NUT-11) supports a **`locktime`** and **`refund` keys**. We use
exactly that:

```
buyer  ──locks funds to──▶  seller pubkey
                            locktime = now + N days
                            refund   = buyer pubkey
```

- **Seller delivered** → redeems with their key (any time).
- **Seller vanished / deal fell through** → after `locktime`, the **buyer**
  reclaims with their refund key.

This is real escrow (both sides protected) with **no witness/oracle** — the only
thing "release on attestation" needs is the locktime, which the mint enforces.

Contrast with the naive option (lock to the seller, no expiry): that's
**prepayment**, not escrow — the seller can take the money and never deliver —
so we deliberately don't do it.

## Keys

Cashu P2PK needs a secp256k1 key the wallet can **sign a witness** with. The
Nostr signer (Amber / NIP-07) can't produce a bare schnorr signature, so we use
the **Cashu wallet's own keyring** (`coco.keyring`), not the Nostr key.

Each user advertises one escrow pubkey for others to lock to:

- **kind 0** content field **`cashu_escrow`** — 33-byte compressed hex
  (`02…`), derived from the Cashu keyring. See `NIP.md` → Profile Metadata
  Extensions. Nostr x-only keys are accepted too (normalised with an `02`
  prefix, matching coco's own `getPublicKeyHex`).

## Flow

1. Seller advertises `cashu_escrow` (set when they touch their Cashu wallet).
2. Buyer reads the seller's pubkey, then **funds escrow by paying the mint's
   Lightning invoice** and mints fresh proofs locked to the seller:
   - `createMintQuote(amount)` → pay `request` via NWC/WebLN/Cashu melt
   - `mintProofs(amount, quote, { p2pk: { pubkey, locktime, refundKeys:[buyer] } })`
   - encode → the `cashu_token` on the `31872` confirmation request.
   - Funding by mint (not by spending the coco balance) keeps this independent
     of the coco wallet's proof state — no state bridging, no counter desync.
3. Seller sees the escrowed token on the request and redeems (`wallet.receive`).
4. If not delivered by `locktime`, the buyer refunds.

## Protocol

The escrow token rides the Attestations NIP's existing optional
`["cashu_token", "<token>"]` tag on the **kind 31872** request (`NIP.md` → Trade
Attestations). The lock is what makes publishing it safe: a plain (unlocked)
token in a public event is spendable by anyone who sees it.

## Threat model / limitations

- **Mint trust**: P2PK keeps the mint from spending your funds, but you still
  trust the mint to be solvent and redeemable. Use a reputable mint.
- **No delivery proof on-chain**: "delivered" is the seller's word; the buyer's
  protection is the locktime refund, and the marketplace reputation system
  (`31871`) records the outcome.
- **Locktime is unilateral**: the buyer can always refund after the deadline even
  if the seller did deliver but was slow to redeem — so redemption should happen
  promptly, and lock windows should be generous.
- **Native only**: the app's Cashu wallet is Capacitor-only, so escrow is too.

## Status

- ✅ **Core** (`src/lib/cashuEscrow.ts`, unit-tested): pubkey normalisation,
  `escrowP2PKOptions`, offline token inspection/`parseEscrowToken`,
  locktime/refund policy, and the injectable `createEscrowToken` mint flow.
- 🟡 **Wallet UI** (native-only): implement → verify with the **On-device test
  checklist** below before treating as production. Do not use real money until
  every box passes.

## On-device test checklist (Android)

Escrow is native-only and its mint paths are unverified — run this on a real
device with **tiny amounts** before trusting it. Check every box; anything that
fails is a bug to fix (or a mint that doesn't support P2PK — note which).

### Producing a test build
```bash
# First time only — generates android/ (gitignored)
npm run android:init

# Build the web assets + sync into the native project
npm run android:sync

# Debug APK (debug keystore — no release secrets needed)
cd android && ./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk
```
To test both sides you need **two accounts** — easiest is one device (this build)
plus one other client/device with a different key.

### Preconditions
- [ ] Latest Android build installed (`npm run android:build`), logged in.
- [ ] Cashu wallet initialised and a reachable, trusted **mint** added (Wallet).
- [ ] A funded **NWC** connection (Wallet → NWC) to pay the mint invoice.
- [ ] **Two accounts** (seller + buyer) on two devices/profiles.
- [ ] First pass: **10 sats**, **1‑day** lock.

### 1. Seller advertises the escrow key
- [ ] Wallet → Escrow → **Publish escrow key** → toast "Escrow key published".
- [ ] Badge flips to "Escrow key active"; persists after reload.
- [ ] The kind 0 event on a relay contains `cashu_escrow` (66 hex chars, `02…`).

### 2. Buyer creates escrow
- [ ] Buyer sees **Escrow & request** on the seller's listing (native only).
- [ ] Enter 10 sats / 1 day → **Lock & request**.
- [ ] NWC pays the mint invoice; toast "Escrow created".
- [ ] Buyer balance drops by ~10 sats **+ mint/Lightning fees**.

### 3. Token looks right
- [ ] DM thread shows the escrow panel: "Escrowed 10 sats", mint host, refund date ≈ +1 day.
- [ ] Buyer can still retrieve the token (needed for the refund test).

### 4. Seller redeems on delivery
- [ ] Seller's DM shows **Confirm this sale?** + panel + **Redeem escrow**.
- [ ] Redeem → toast "Escrow redeemed"; seller balance rises ~10 sats.
- [ ] **Confirm sale** publishes the `31871`; buyer then sees **Confirm this trade**.
- [ ] Buyer confirms → both profiles show **1 verified trade** (trust-weighted).

### 5. Refund path (seller never delivers)
- [ ] New escrow, 1‑day lock; seller does **not** redeem.
- [ ] Before the deadline: no "Refund escrow" on the buyer's card (expected).
- [ ] After the deadline: **Refund escrow** appears → tap → balance returns.
- [ ] A second redeem of the same token fails cleanly (already spent).

### 6. Guard rails
- [ ] Web build: escrow action hidden; panel is read-only if a token exists.
- [ ] No NWC/WebLN → "No Lightning wallet available…" on lock.
- [ ] No mint → "No Cashu mint available…".
- [ ] Seller hasn't published `cashu_escrow` → buyer only sees the plain request.

### Watch for
- **Mint rejects P2PK** (some disable it) → creation errors; record the mint.
- **coco can't redeem P2PK** (witness signing) → redeem/refund errors.
- **Clock skew** — keep lock windows generous.

## Files

- `src/lib/cashuEscrow.ts` (+ `.test.ts`) — pure escrow policy & inspection.
- `src/hooks/wallet/useCashu.ts` — Cashu wallet (native-only), keyring source.
- `src/hooks/useTradeAttestations.ts` — `31872` request carries `cashu_token`.
- `NIP.md` — profile field + protocol notes.