Інтеграція гаманця з WalletConnect

Інтеграція кошелька з WalletConnect

WalletConnect v2 — це не просто "додати кнопку Connect Wallet". Протокол побудований на relay-серверах Walletconnect Cloud, використовує власний JSON-RPC поверх WebSocket, та потребує розуміння сессійного управління, щоб не отримати broken UX при переключенні мережей або дисконнекті.

Як це працює під капотом

WalletConnect v2 використовує Sign API та Auth API поверх свого relay протоколу. Пара ключів (topic + symmetric key) створюється при ініціалізації сесії, QR-код кодує URI формату wc:topic@2?relay-protocol=irn&symKey=.... Кошелек (MetaMask Mobile, Trust, Rainbow) сканує QR, встановлює зашифрований канал через relay.walletconnect.com.

Для dApp розробки напрямки з WalletConnect SDK працювати не потрібно — це робить wagmi + @web3modal/wagmi (або ConnectKit, RainbowKit).

Інтеграція через wagmi v2 + Web3Modal

// config.ts
import { createConfig, http } from 'wagmi'
import { mainnet, polygon, arbitrum } from 'wagmi/chains'
import { walletConnect, injected, coinbaseWallet } from 'wagmi/connectors'

export const config = createConfig({
  chains: [mainnet, polygon, arbitrum],
  connectors: [
    injected(),
    walletConnect({ projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID! }),
    coinbaseWallet({ appName: 'Your App' }),
  ],
  transports: {
    [mainnet.id]: http(),
    [polygon.id]: http(),
    [arbitrum.id]: http(),
  },
})

projectId отримується на cloud.walletconnect.com — без нього з'єднання працює тільки в dev через публічний relay, в production впаде з rate limit.

Управління сесією

Критичний момент, який часто ігнорують: WalletConnect сесії персистентні. Користувач закрив вкладку, відкрив знову — сесія повинна відновитися без нового QR. wagmi обробляє це автоматично через localStorage, але потрібно правильно ініціалізувати WagmiProvider до будь-якого використання хуків:

// app/providers.tsx
'use client'
import { WagmiProvider } from 'wagmi'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { config } from './config'

const queryClient = new QueryClient()

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    </WagmiProvider>
  )
}

Переключення мережі

wallet_switchEthereumChain — стандартний RPC метод. Якщо мережа не додана в кошелек, потрібен wallet_addEthereumChain. wagmi це абстрагує через useSwitchChain, але поведінка відрізняється по кошельках: MetaMask показує popup, WalletConnect-підключені мобільні кошельки можуть ігнорувати запит або вимагати ручного підтвердження в додатку.

Розповсюджені проблеми

Hydration mismatch у Next.js — useAccount() повертає різне становище на сервері та клієнті. Рішення: ssr: false для компонентів з wallet state, або useEffect для читання становища тільки на клієнті.

Mobile deep links — на iOS/Android WalletConnect повинен відкрити кошелек через universal link. Web3Modal обробляє це, але якщо пишеш кастомний UI — потрібно передавати redirect параметр при ініціалізації сесії.

Session expiry — сесії живуть 7 днів за умовчанням. Потрібно обробляти session_expire подію та показувати користувачу пропозицію переподключитися.

Робота займає 2–3 дні: налаштування wagmi config, інтеграція Web3Modal або RainbowKit, тестування на реальних мобільних кошельках (MetaMask Mobile, Trust Wallet), обробка edge cases з network switching та session persistence.