docs(escrow): on-device test checklist

Add a step-by-step Android verification checklist to ESCROW.md (preconditions,
advertise key -> buyer escrow -> seller redeem -> refund -> guard rails) and
point to it from the Status section and AGENTS.md. Escrow stays unverified until
every box passes on a device with tiny amounts.
This commit is contained in:
SkateSpots 2026-09-26 21:14:11 +07:00
parent c37e21e860
commit 6f28d1fe2a
2 changed files with 57 additions and 4 deletions

View file

@ -51,8 +51,9 @@ session with **no other memory of this project**. So:
(unit-tested). Protocol: `cashu_token` on the `31872`; each user advertises a (unit-tested). Protocol: `cashu_token` on the `31872`; each user advertises a
`cashu_escrow` pubkey in kind 0. UI wired: `useCashuEscrow`, `cashu_escrow` pubkey in kind 0. UI wired: `useCashuEscrow`,
`EscrowKeyCard` (Wallet), `EscrowRequestDialog` (listing card), `EscrowPanel` `EscrowKeyCard` (Wallet), `EscrowRequestDialog` (listing card), `EscrowPanel`
+ redeem (DM request banner). **Native-only and UNVERIFIED on a device** — + redeem (DM request banner), `Refund escrow` (listing card). **Native-only and
exercise with small amounts before trusting it with real money. UNVERIFIED on a device** — verify with the on-device checklist in `ESCROW.md`
(tiny amounts) before trusting it with real money.
- **Wallet**: `useCashu` (coco-cashu) is **native-only** — it returns early on - **Wallet**: `useCashu` (coco-cashu) is **native-only** — it returns early on
web (mints are CORS-blocked). Zap rails are NWC + WebLN + Cashu melt (`useZaps`). web (mints are CORS-blocked). Zap rails are NWC + WebLN + Cashu melt (`useZaps`).
- **Group DMs**: NIP-17 (`useDirectMessages`, `GroupConversationPage`). - **Group DMs**: NIP-17 (`useDirectMessages`, `GroupConversationPage`).

View file

@ -82,8 +82,60 @@ token in a public event is spendable by anyone who sees it.
- ✅ **Core** (`src/lib/cashuEscrow.ts`, unit-tested): pubkey normalisation, - ✅ **Core** (`src/lib/cashuEscrow.ts`, unit-tested): pubkey normalisation,
`escrowP2PKOptions`, offline token inspection/`parseEscrowToken`, `escrowP2PKOptions`, offline token inspection/`parseEscrowToken`,
locktime/refund policy, and the injectable `createEscrowToken` mint flow. locktime/refund policy, and the injectable `createEscrowToken` mint flow.
- 🟡 **Wallet UI** (native-only): needs a real mint + Android device to verify; - 🟡 **Wallet UI** (native-only): implement → verify with the **On-device test
do not treat as production until exercised end-to-end on-device. 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).
### 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 ## Files