Mobile Wallet Deeplinking

This page reflects the current WalletConnect and mobile deeplink behavior in the dapp. We still do not persist real WalletConnect session URIs or topics, but the dapp now distinguishes between a generic WalletConnect flow and a chooser-driven mobile-wallet flow. Deeplinking is handled in two places: the Connect Modal during connection and a shared helper used by transaction/signing flows to wake the wallet app after the user is already connected.

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, there are now two branches:

Regular WalletConnect button: redirects to the raw WalletConnect URI.
Choose Mobile Wallets: lazy-loads WalletConnect Explorer wallets, lets the user pick a specific wallet, and then launches that wallet’s native/universal link with the fresh display_uri.
File: dapp/components/wallet/connectModal/hooks/useWalletConnection.ts
Key behavior:
- display_uri sets qrUri for the UI.
- The explorer list is fetched only after the chooser screen is opened and then cached in memory for the page session.
- Chooser launches prefer universal links on iPhone-like devices and native links on other mobile devices.
- The regular WalletConnect button stays generic and does not reuse chooser memory.

Why there are two mobile paths

Regular WalletConnect button is the generic, raw WalletConnect path. This is the Android-oriented default because Android wallets generally handle raw WalletConnect deeplinks and intents correctly and can resolve the open-wallet intent on their own.
Choose Mobile Wallets exists primarily for iPhone and iOS compatibility. Many iPhone wallet flows require a wallet-specific universal link instead of a raw WalletConnect deeplink, so the chooser wraps the same WalletConnect session in explorer-provided wallet launch links.
Android can still use Choose Mobile Wallets, but it is usually not required there. In practice, it is an optional wallet-specific wrapper around WalletConnect, while iPhone is the platform that usually needs it.

2) Post-connect wallet wake link (`openWalletDeeplink`)

After writes or signatures, the dapp uses a shared helper to re-open the wallet app. The helper still does not rebuild a WalletConnect session topic, but it now supports two relaunch modes:

Generic fallback: uses the placeholder URI wc:ritoswap.
Chooser-aware relaunch: if the current session was started from Choose Mobile Wallets, the helper reuses the active wallet launcher and opens that wallet’s native/universal link with the placeholder URI.
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.
- Reuses the active chooser wallet launcher when one exists for the current session.
- Falls back to the raw WalletConnect placeholder when no active launcher exists.


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

Chooser memory is split into two scopes:

Last-used chooser wallet: persisted so the chooser can label the last-used wallet on later opens.
Active session launcher: persisted separately for the current session so Open Wallet buttons can keep reopening the same wallet after connection.

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

- - walletDeeplink.ts
- - useWalletConnectGuards.ts
  - useMintBurn.ts
- - - GateModal.tsx
    - GatePageWrapper.tsx
- - - useWalletConnection.ts
  - - ProcessingModal.tsx
  - - OpenWalletButton.tsx

Constraints and expectations

⚠️

Deeplinking is still best-effort. The helper does not persist real WalletConnect session topics or URIs, and chooser memory is only wallet launcher metadata. Validate on real devices whenever you change wallet flows, especially iPhone universal-link behavior.

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.

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