# 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): needs a real mint + Android device to verify;
  do not treat as production until exercised end-to-end on-device.

## 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.