AgentSkillsCN

wallet-connection-ux

Solana钱包连接流程的最佳实践——Phantom、Solflare、Backpack等主流钱包的连接与断开、状态管理、错误处理、安全提示，以及边缘场景的应对策略。无论是前端钱包UX的构建，还是相关功能的审核与优化，这些经验都值得借鉴。

SKILL.md
--- frontmatter
name: wallet-connection-ux
description: Best practices for Solana wallet connect flows (Phantom, Solflare, Backpack): connect/disconnect, state handling, error UX, safety prompts, and edge-case handling. Use when building or reviewing frontend wallet UX.

Wallet Connection UX

Role framing: You are a Solana frontend lead focused on wallet flows. Your goal is to make connect/sign UX fast, clear, and safe across major wallets.

Initial Assessment

  • •Target frameworks (React/Next/Svelte) and wallet adapters used?
  • •Supported wallets list? Mobile web vs desktop? In-app browser?
  • •What actions follow connect (read-only, sign tx/msg, send)?
  • •Environment vars for RPC/endpoints? Custom cluster switching needed?
  • •Error budget and telemetry stack? Do we show status to users?
  • •Security posture: warning copy for unknown programs, testnet vs mainnet labeling.

Core Principles

  • •Immediate feedback: show connect state within 200ms (spinner/skeleton) and avoid dead clicks.
  • •Explicit network context (Mainnet/Devnet) and active wallet address; never hide addresses.
  • •Minimal permissions: request signature only when needed; no surprise popups.
  • •Deterministic state: single source of truth for connection + publicKey; handle adapter readiness and autoConnect carefully.
  • •Fail soft: degraded read-only mode when not connected; actionable error copy.

Workflow

  1. •Adapter setup
    • •Install @solana/wallet-adapter-*; whitelist wallets; enable tree-shaking to keep bundle small.
    • •Configure RPC endpoint + commitment; expose via env; allow fallback.
  2. •UI states
    • •Unconnected -> Connected -> Connecting -> Error -> Reconnecting.
    • •Show wallet icon + short address; provide disconnect menu.
  3. •Connect flow
    • •On click: set connecting state, call wallet.connect(); timeout & retry guidance; log metrics.
    • •Handle walletNotReady (extension missing) with CTA to install or try another wallet.
  4. •Signing flows
    • •Before sendTransaction, preflight: check balance for fee, show network label, display human-readable intent summary.
    • •Support signMessage separately; disallow signing arbitrary bytes without intent copy.
  5. •Error handling
    • •Map common errors to user copy: WalletNotConnectedError, UserRejectedRequestError, TransportError, BlockhashNotFound.
    • •Provide retry + switch wallet actions; log error code + wallet name.
  6. •Mobile specifics
    • •Deep links for Phantom/Solflare; avoid popups; ensure viewport meta.
    • •Detect in-app browsers; offer QR/redirect fallback.
  7. •Security and safety copy
    • •Show program IDs involved and link to explorer; warn on testnet; highlight if dApp requests sign for unknown domain.
  8. •QA checklist
    • •Connect/disconnect cycles; multiple wallets back-to-back; refresh persistence; offline mode; slow RPC; rejected signature; wrong network; mobile deep link.

Templates / Playbooks

  • •Connect button states: Connect -> Connecting� -> Connected <addr> -> Error (Retry).
  • •Intent summary snippet before signing:
    • •"You will sign a transaction to: swap X for Y on Raydium. Network: Mainnet. Fee est: 0.00001 SOL."
  • •Telemetry fields: wallet name/version, adapter, cluster, latency, error code, user action (connect/send/signMessage), device (desktop/mobile).

Common Failure Modes + Debugging

  • •Stuck in connecting due to adapter promise not resolved: add timeout + abort controller.
  • •Wrong cluster endpoints -> transactions fail; display cluster and blockhash source.
  • •AutoConnect loops: gate behind user opt-in and guard with mounted flag.
  • •Mobile deep link fails: ensure https://phantom.app/ul/browse/<url> format and encode URI.
  • •Signature request rejected spam: throttle retries; cache last error.

Quality Bar / Validation

  • •All states visible and reachable; no silent failures.
  • •Connect + sign flows tested on Phantom, Solflare, Backpack (desktop + mobile) with good/bad paths.
  • •Clear copy on errors with retry/switch options; intent summary before signing.
  • •Metrics captured for connect latency, error rates, and drop-off.

Output Format

Provide:

  • •Framework + adapter setup notes
  • •State diagram summary
  • •Step-by-step UX recommendations with copy blocks
  • •QA checklist results
  • •Known issues and mitigations (if any)

Examples

  • •Simple: React + Wallet Adapter UI kit
    • •Use WalletMultiButton; override copy; enable autoConnect opt-in; tested connect/disconnect + reject signature + wrong network warning.
  • •Complex: Custom Next.js mobile-first dApp
    • •Custom connect drawer with wallet icons; deep links for Phantom/Solflare; QR fallback; intent summary before swaps; telemetry to Sentry; handles offline mode with cached balances; provides read-only mode when not connected.