Mobile Wallet Deeplinking

This page reflects the current WalletConnect and mobile deeplink behavior in the dapp. The deeplink system was simplified after refactors: we no longer persist session topics or maintain a dedicated WalletConnect store. Instead, deeplinking is handled in two places: the Connect Modal during connection and a lightweight helper used by transaction/signing flows to wake the wallet app.

What exists now

1) Connection-time WalletConnect handoff (ConnectModal)

When a user selects the WalletConnect connector, the Connect Modal listens for the display_uri event. On desktop, it shows a QR view; on mobile, it immediately redirects the browser to the WalletConnect URI.

• File: dapp/components/wallet/connectModal/hooks/useWalletConnection.ts
• Key behavior:
  • display_uri sets qrUri for the UI.
  • On mobile, window.location.href = uri performs the handoff.
  • No session topic persistence or URI sanitization is performed.

2) Best-effort wallet wake link (openWalletDeeplink)

After writes or signatures, the dapp uses a minimal helper to re-open the wallet app. This helper does not rebuild a session topic or guarantee OS chooser behavior; it simply navigates to a WC-style URI to prompt a handoff.

• File: dapp/app/utils/walletDeeplink.ts
• Default behavior:
  • Uses the fallback URI wc:ritoswap.
  • Appends a timestamp query string to force a fresh navigation on repeat calls.

import { openWalletDeeplink } from '@/app/utils/walletDeeplink'
 
if (isMobileDevice() && connector?.id === 'walletConnect') {
  openWalletDeeplink()
}

This helper is called from:

• dapp/app/hooks/useMintBurn.ts
• dapp/app/gate/components/GateModal/GateModal.tsx
• dapp/app/gate/components/GatePageWrapper.tsx
• dapp/components/wallet/processingModal/ProcessingModal.tsx
• dapp/components/wallet/OpenWalletButton/OpenWalletButton.tsx

Global redirect/popup guards

The app installs a lightweight guard to block known WalletConnect-related redirects and popups on mobile Chrome:

• File: dapp/app/hooks/useWalletConnectGuards.ts
• Behavior:
  • Blocks navigation to a small blacklist of wallet domains.
  • Blocks HTTP/HTTPS popups on Android Chrome.
  • Does not manage any WalletConnect session state.

This guard is wired from dapp/components/providers/providers.tsx.

File map

• app
  • utils
    • walletDeeplink.ts
  • hooks
    • useWalletConnectGuards.ts
    • useMintBurn.ts
  • gate
    • components
      • GateModal.tsx
      • GatePageWrapper.tsx
• components
  • wallet
    • connectModal
      • useWalletConnection.ts
    • processingModal
      • ProcessingModal.tsx
    • OpenWalletButton
      • OpenWalletButton.tsx

Constraints and expectations

WalletConnect availability

WalletConnect is optional. If NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID is not set, the app runs with injected wallets only (see dapp/components/providers/providers.tsx). Injected mobile wallets (e.g., MetaMask in-app browser) still work without any deeplink helper.

Related docs

• docs/content/dapp/wallet-ui/connectModal.mdx
• docs/content/dapp/smart-contract-ui/processing-modal.mdx
• docs/content/dapp/smart-contract-data/use-mint-burn.mdx
• docs/content/dapp/tokengate.mdx