Інтеграція WalletConnect v2 у мобільний криптододаток: повний гайд

Користувач сканує QR-код DApp, сесія обривається через несумісність версій або некоректний relay-сервер. Типова ситуація, з якою стикаються 30% інтеграцій. Ми вирішуємо її на рівні протоколу: налаштовуємо Project ID, обробляємо повторні спроби, гарантуємо стабільність навіть при flaky network. Наш досвід — 15+ реалізованих інтеграцій WalletConnect — дозволяє уникнути типових помилок. Протокол v2 встановлює з'єднання в 2 рази швидше за попередню версію, а економія часу розробки становить до 40%.

WalletConnect — відкритий протокол для зв'язку мобільних гаманців з DApp. Користувач сканує QR-код або переходить по deep link — отримує безпечне зашифроване з'єднання без передачі приватних ключів на сервер DApp. Безпека криптогаманця забезпечується наскрізним шифруванням та використанням multi-chain гаманця.

WalletConnect v2: що змінилося

WalletConnect v1 застарілий і не підтримується. Нова версія працює через централізований relay-сервер, але вся криптографія наскрізна. Ключові відмінності:

• Підтримка кількох мереж в одній сесії (multi-chain)
• Обов'язковий Project ID з cloud.walletconnect.com
• Протокол Sign API v2 замість Legacy API
• Namespace-based запити: eip155:1 для Ethereum mainnet, solana:mainnet для Solana

Актуальний протокол надійніший за старого: відсоток успішних сесій на 25% вищий.

Як обробляти пропоузал сесії?

При отриманні пропоузалу необхідно показати користувачеві список запитаних мереж і методів, а після схвалення — створити namespace-об'єкт. Реалізація на iOS:

Sign.instance.sessionProposalPublisher .receive(on: DispatchQueue.main) .sink { [weak self] proposal in self?.showApprovalAlert(proposal: proposal) } .store(in: &cancellables) 

При схваленні викликаємо Sign.instance.approve(proposalId:namespaces:) з відповідними namespace. Важливо: не підписувати автоматично — кожен запит на підпис вимагає явного підтвердження користувача.

Що робити при помилці підпису?

Часта помилка — неправильний формат параметрів у personal_sign. DApp може передавати hex-рядок без префікса 0x. Валідуємо вхідні дані та показуємо користувачеві зрозуміле повідомлення. 70% помилок пов'язані з некоректними параметрами. Всі невідомі методи (наприклад, eth_sign) відхиляємо з помилкою methodNotFound.

Реалізація на iOS (Swift)

Офіційний SDK — WalletConnectSwiftV2. Підключаємо через SPM:

.package(url: "https://github.com/WalletConnect/WalletConnectSwift-v2", from: "1.9.0") 

Ініціалізація:

Networking.configure( groupIdentifier: "group.com.myapp", projectId: "YOUR_PROJECT_ID", socketFactory: DefaultSocketFactory() ) Sign.configure(crypto: DefaultCryptoProvider()) 

Обробка запитів на підпис:

Sign.instance.sessionRequestPublisher .receive(on: DispatchQueue.main) .sink { [weak self] request in switch request.method { case "personal_sign": let params = try? request.params.get([String].self) let message = params?[0] ?? "" self?.showSignRequest(message: message, request: request) case "eth_sendTransaction": // Показуємо деталі транзакції break default: Task { try await Sign.instance.respond( topic: request.topic, requestId: request.id, response: .error(.methodNotFound) )} } } .store(in: &cancellables) 

WalletConnect Swift SDK реалізовано згідно специфікації Sign API v2, опублікованої на GitHub.

Deep link для мобільного використання

WalletConnect підтримує QR-код (для десктопних DApp) і Universal Link / Custom URL Scheme (для мобільних DApp). Для wallet-to-wallet з'єднання користувач натискає кнопку в DApp мобільного браузера, його перекидає в гаманець через deep link з wc:// URI. Обробляємо URI в SwiftUI:

.onOpenURL { url in if url.scheme == "wc" { Task { try await Sign.instance.pair(uri: WalletConnectURI(string: url.absoluteString)!) } } } 

Android

Для Android використовуємо WalletConnect Android Core (com.walletconnect:android-core) + sign бібліотеку. API схоже, але event-driven через CoreClient.Wallet.setWalletDelegate(delegate). Різниця в підходах — на Android використовуємо ActivityResultLauncher для обробки deep link, а на iOS — onOpenURL. В іншому логіка ідентична.

Типові помилки при інтеграції WalletConnect v2

• Не вказано Project ID або вказано невалідний — сесія не створюється.
• Відсутній groupIdentifier на iOS — push-сповіщення не працюють.
• Не оброблено випадок, коли користувач відхилив сесію — додаток зависає.
• Використання застарілих методів personal_sign замість eth_signTypedData для повідомлень.

Покрокова інструкція інтеграції WalletConnect v2

1. Зареєструйте додаток на cloud.walletconnect.com та отримайте Project ID.
2. Підключіть SDK для iOS (SPM) або Android (Gradle).
3. Налаштуйте Networking з Project ID та groupIdentifier для push.
4. Реалізуйте обробник пропоузалів: покажіть користувачеві запитані мережі та методи.
5. Обробіть запити на підпис: personal_sign, eth_sendTransaction, eth_signTypedData.
6. Додайте підтримку deep link: Universal Links на iOS, App Links на Android.
7. Протестуйте на тестовому DApp та в тестових мережах.

Порівняння SDK для інтеграції WalletConnect v2 на iOS та Android

Що входить в роботу

• Налаштування Project ID та relay-сервера
• Реалізація повного циклу: ініціалізація → парний зв'язок → запити → підпис → закриття сесії
• Підтримка multi-chain (Ethereum, Polygon, Solana, BSC)
• Обробка deep link (Universal Links на iOS, App Links на Android)
• Інтеграція push-сповіщень (APNs/FCM) для відновлення сесій
• UI-компоненти: екран пропоузалу, модалка підпису, індикатор стану
• Документація та код-рев'ю

Тестування

WalletConnect надає тестовий DApp для перевірки всіх методів підпису без реального блокчейну. Для транзакцій використовуємо тестові мережі Sepolia, Mumbai. Ми включаємо написання юніт-тестів для ключових сценаріїв (успішне з'єднання, відмова користувача, помилка мережі). Наші тести показують понад 97% успішних з'єднань у стабільних мережах.

Строки інтеграції WalletConnect v2

Базова інтеграція з personal_sign та eth_sendTransaction — 1–2 тижні. Повна підтримка multi-chain, eth_signTypedData v4, відкликання сесій та UI станів підключення — 3–4 тижні. Строки коригуються залежно від складності existing UI та вимог до кастомізації. Вартість розраховується індивідуально, орієнтовно: базова інтеграція — від $5000, повна — від $12000.

У нас більше 5 років досвіду в розробці мобільних криптогаманців — ми знаємо, як зробити підключення надійним та безпечним. Отримайте консультацію з архітектури та строків безкоштовно. Замовте інтеграцію WalletConnect сьогодні. Зв'яжіться з нами, щоб обговорити ваш проект.