From 6f28d1fe2a7bf8271759e5a9959105bb15d9ecfd Mon Sep 17 00:00:00 2001
From: SkateSpots <skatespots>
Date: Sat, 26 Sep 2026 21:14:11 +0700
Subject: [PATCH] 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.
---
 AGENTS.md |  5 +++--
 ESCROW.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 57 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e0703a0..55af41b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -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
   `cashu_escrow` pubkey in kind 0. UI wired: `useCashuEscrow`,
   `EscrowKeyCard` (Wallet), `EscrowRequestDialog` (listing card), `EscrowPanel`
-  + redeem (DM request banner). **Native-only and UNVERIFIED on a device** —
-  exercise with small amounts before trusting it with real money.
+  + redeem (DM request banner), `Refund escrow` (listing card). **Native-only and
+  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
   web (mints are CORS-blocked). Zap rails are NWC + WebLN + Cashu melt (`useZaps`).
 - **Group DMs**: NIP-17 (`useDirectMessages`, `GroupConversationPage`).
diff --git a/ESCROW.md b/ESCROW.md
index 3c4e62b..7efa194 100644
--- a/ESCROW.md
+++ b/ESCROW.md
@@ -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,
   `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.
+- 🟡 **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).
+
+### 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