web/docs/mobile-wallet-handoff.md

Mobile Wallet Handoff UX Spec (v1)

Goal

Provide deterministic cross-device path when user starts on desktop but wallet is on phone.

Entry Paths

1. Desktop with extension wallet available -> direct connect.
2. Desktop without extension -> QR handoff to mobile wallet.
3. Mobile browser with wallet app -> deep-link connect.

Desktop QR Handoff

1. User clicks I have a wallet.
2. If no injected provider detected, show QR panel.
3. QR encodes short-lived session handoff token.
4. Mobile wallet scan opens connect/sign flow.
5. Desktop polls handoff status until signature/tx complete or timeout.

Constraints

1. Handoff token TTL short (recommended 5 minutes).
2. Single-use token; replay denied.
3. If timeout occurs, restart with new token.

Fail-Closed

1. No completed handoff token -> no signature verify.
2. No membership confirm -> no acknowledged state.