How to use WalletConnect for desktop DApps? (QR Code Scan)

Understanding WalletConnect Protocol

1. WalletConnect is an open-source protocol that enables secure communication between desktop decentralized applications and mobile crypto wallets.

2. It operates through end-to-end encryption, ensuring private keys never leave the user’s device during session initiation or transaction signing.

3. The protocol uses a relay server to forward encrypted payloads between the dApp and wallet without accessing message content.

4. Desktop dApps generate a unique pairing URI containing a temporary topic and bridge URL, which serves as the handshake foundation.

5. Session establishment requires mutual approval: the dApp requests connection, and the wallet must explicitly confirm before any interaction proceeds.

QR Code Generation on Desktop

1. When launching a desktop dApp, users click “Connect Wallet” and select WalletConnect as the preferred method.

2. The application renders a dynamically generated QR code using the WalletConnect v2.0 session proposal format, embedding project ID, required chains, and metadata.

3. This QR code encodes a deep link formatted as wc:// or wc: followed by base64-encoded session parameters and version identifier.

4. Some dApps display fallback text—such as a 12-word phrase or alphanumeric code—for manual entry if scanning fails.

5. The QR code remains valid for approximately three minutes; expiration triggers automatic regeneration upon refresh.

Scanning with Mobile Wallets

1. Users open compatible wallets like MetaMask Mobile, Trust Wallet, or Rainbow and navigate to the WalletConnect scanner interface.

2. The camera activates and detects the QR code, parsing its payload into a structured session request object.

3. The wallet displays dApp name, requested permissions, supported networks, and icon fetched from the dApp’s metadata endpoint.

4. After user approval, the wallet sends an acknowledgment payload back via the relay, establishing a persistent WebSocket channel.

5. Once connected, the wallet shows an active session badge, allowing signature requests for transactions or sign-in messages.

Session Management and Security Considerations

1. Each active WalletConnect session is assigned a unique topic hash, visible in the wallet’s connection list alongside last-used timestamp.

2. Users can terminate sessions manually within their wallet app, instantly cutting off all pending and future RPC calls from that dApp.

3. Desktop dApps cannot initiate arbitrary calls—permissions are scoped to methods declared during pairing, such as eth_sendTransaction or personal_sign.

4. If a dApp attempts unauthorized RPC methods, the wallet rejects the call and logs it locally without broadcasting error details to the relay.

5. Relay servers do not store session payloads beyond message delivery; payloads are encrypted with ephemeral keys discarded after transmission.

Frequently Asked Questions

Q: Can I use WalletConnect with hardware wallets on desktop?Yes—Ledger Live and Trezor Suite support WalletConnect v2.0 natively. They act as intermediaries, forwarding signing requests from the desktop dApp to the physical device via USB or Bluetooth.

Q: Why does my wallet show “Unknown dApp” even though I scanned the QR code?This occurs when the dApp fails to include valid metadata (name, description, icons) in its session proposal. Wallets default to generic labels when metadata fields are missing or malformed.

Q: Is it safe to scan WalletConnect QR codes from untrusted websites?No. Scanning initiates a cryptographic handshake that grants the dApp limited access to your wallet. Always verify domain authenticity and inspect the dApp’s source code or audit reports before connecting.

Q: What happens if I close my desktop browser while a WalletConnect session is active?The session remains open on the wallet side until manually disconnected or timed out. The dApp loses its ability to send new requests but retains no control over the wallet once the browser tab is closed.