React dApp фронтенд: стек wagmi/viem, транзакції, помилки

Користувач підписує транзакцію, а інтерфейс мовчить — і він іде, не дочекавшись підтвердження. Ми розробляємо dApp на React під ключ: стани, робота з мережею та підтвердження вибудувані так, що завислі операції перестають бути нормою, а частка незавершених дій падає в рази.

React dApp фронтенд: стек wagmi/viem, транзакції, помилки

Web3 фронтенд: послуги блокчейн-розробкиСередній~1-2 тижні
Часті запитання

Чому розробка dApp на React ламається на транзакціях

Класичний збій у розробці dApp на React — інтерфейс і гаманець показують різний стан. Користувач підписав транзакцію, екран перейшов у «успішно», а в мережі вона відхилилася через nonce або була витіснена конкуруючим надсиланням.

Застосунок довіряє власній відповіді вузла й не звіряється з фактичним статусом, тому розсинхрон стану інтерфейсу виявляється не одразу — зазвичай після звернення до підтримки.

Друга група — помилки транзакцій dApp, які відтворюються через раз. Повторний підпис гаманця при подвійному кліку породжує другу дію з тим самим сенсом, але іншим хешем: перевірка на дубль за хешем не спрацьовує, бо на момент надсилання хешу ще немає.

Завислі транзакції та екрани очікування залишаються там, де підтвердження чекають за подією підписки, а вона губиться під час перемикання мережі або перезавантаження сторінки.

Третє місце відмови — кеш запитів. Після підтвердження дані не інвалідуються, інтерфейс показує старий баланс і старий дозвіл на списання, користувач надсилає повторну дію. Заміна транзакції з тим самим nonce і відкат мережі на кілька блоків не обробляються взагалі.

Стек на кшталт wagmi і viem знімає частину рутини, але не скасовує логіку синхронізації — її пишуть зверху й тестують окремо.

Ціна такої помилки — зростання ручних розборів і втрата довіри до продукту на рівному місці, хоча бізнес-логіка працює. Розбираємо, як це закривається.

Що дає передбачуваний фронтенд: стани, мережа, підтвердження

Поки операція живе в стані одного компонента, будь-яке перемонтування списку, зміна акаунта або мережі в гаманці перетворює інтерфейс на набір здогадів.

Користувач бачить «надіслано», хоча підпис не пішов, або навпаки — операція в мережі вже є, а екран пропонує натиснути кнопку вдруге. Кожен такий випадок — звернення до підтримки й ручний розбір журналів.

Ми виносимо статус операції в єдине джерело: скінченний автомат зі станами від чернетки й підпису до підтвердження заданою кількістю блоків і фіналізації.

Компоненти підписуються на нього, а не опитують вузол кожен сам по собі — кількість мережевих запитів падає, а частини інтерфейсу перестають показувати суперечливі дані.

Зміну мережі обробляємо без перезавантаження: запит на перемикання йде в гаманець, а в разі відмови інтерфейс залишається в попередньому стані й пояснює, чого не вистачає.

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

Ефект вимірний: частка операцій, що потребують ручного втручання, падає до поодиноких випадків, а звернення до підтримки з формулюванням «транзакція зависла» зникають разом із класом помилок, який їх породжував. Розбір інциденту займає хвилини — за журналом видно стан, на якому операція перервалася.

Способи підключення гаманця: що вибрати під задачу

У фронтенді React-застосунку підключення гаманця — перша дія користувача й найчастіша точка відмови: не той провайдер, зміна мережі, відключення посеред підпису. Порівнюємо робочі варіанти за тим, коли кожен доречний і чим за нього платять.

Вибір зводиться до трьох питань: скільки гаманців потрібно підтримати, чи є мобільний сценарій і де перевіряється підпис — у браузері чи на боці сервісу.

Варіанти та їхні межі

Варіант Коли підходить Обмеження
Готові компоненти підключення Потрібне швидке охоплення десктопних і мобільних гаманців Бібліотека диктує структуру стану; нестандартний вхід доводиться обходити
Власна реалізація на прямих викликах провайдера Один-два гаманці, нестандартний потік, жорсткі вимоги до ваги інтерфейсу Зміну мережі, відключення й конфлікт кількох провайдерів обробляємо самі
Підпис на боці сервісу Вхід без транзакції, прив’язка гаманця до акаунта Потрібні одноразові повідомлення, контроль строку життя підпису й захист від повтору
Вбудований гаманець у застосунку Аудиторія без гаманців, потрібен плавний вхід Ключі залишаються в нас — вищі вимоги до безпеки й відновлення доступу

На практиці беремо поєднання: готові компоненти закривають охоплення гаманців, прямі виклики провайдера — нестандартні сценарії, підпис на сервері — ідентифікацію користувача. Вибір фіксуємо в специфікації, щоб він не спливав заново під час додавання нового гаманця.

Порядок робіт: від аудиту поточного коду до передачі

Аудит фронтенду dApp починається не з інтерфейсу, а з розбору поточного стану: які мережі підключені, як зберігається стан гаманця, де обробляються відмови під час надсилання. Ми фіксуємо слабкі місця й оцінюємо обсяг робіт. Далі все йде етапами, і кожен закінчується перевірюваним результатом, а не звітом про прогрес.

  1. Аудит фронтенду dApp. Розбираємо компоненти, шар роботи з мережею, обробку підпису й підтвердження, покриття перевірками. На виході — карта проблем із пріоритетами: що рве користувацький шлях, що заважає розвитку.
  2. Схема потоку транзакції. Описуємо життєвий цикл операції: ініціалізація, підпис у гаманці, надсилання, очікування підтвердження, скасування або заміна, реорганізація ланцюжка. Схема стає контрактом між інтерфейсом і логікою.
  3. Проєктування станів. Розводимо «очікування», «підтверджено», «відхилено»; у кожного свій текст і наступний крок для користувача. Відмова від підпису й відмова мережі обробляються по-різному.
  4. Реалізація. Ведемо роботу невеликими змінами, кожну перевіряємо в тестовій мережі на живих сценаріях: нестача коштів, повторне надсилання, обрив з’єднання.
  5. Перевірка сценаріїв. Проганяємо повний шлях від підключення гаманця до підтвердження, включно зі зміною мережі й повторним входом.
  6. Приймання сценаріїв. Йде за списком, погодженим заздалегідь: ви бачите кожен крок і підтверджуєте поведінку до релізу.
  7. Передача. Репозиторій, опис потоку транзакції, інструкції з розгортання й розбір коду з вашою командою.

Що залишається в репозиторії після передачі

Передача проєкту — це не архів вихідників, а відтворюваний набір рішень, за яким нова команда піднімає стенд і випускає правку без археології за листуванням.

Ми фіксуємо склад артефактів як критерій готовності: поки кожен пункт нижче не лежить у репозиторії й не перевірений другим інженером, робота не вважається зданою.

  • Конфігурація мереж: ідентифікатори ланцюжків, адреси контрактів, основний і резервний вузли читання, перемикання між бойовою та тестовою мережею через змінні середовища без правок у коді.
  • Опис станів застосунку: перелік екранних станів — гаманець не підключено, підключено не до тієї мережі, транзакцію надіслано й очікується підтвердження, підтверджено, відхилено користувачем — і що саме бачить людина в кожному випадку.
  • Обробка помилок транзакцій: відмови розкладено за класами (відхилення в гаманці, нестача коштів на комісію, повернення коштів контрактом, прострочене очікування квитанції), для кожного класу свій текст в інтерфейсі й зрозумілий наступний крок.
  • Політика оновлення даних: коли перечитуються баланси й статуси після підтвердження, щоб цифри на екрані не розходилися зі станом ланцюжка.
  • Документація для команди: локальний запуск, призначення змінних середовища, де змінювати адреси під час підключення нового контуру, обов’язкові перевірки перед випуском.
  • Регламент випуску й відкату: порядок збирання, прогін на тестовій мережі, умови повернення на попередню версію.
  • Журнал рішень: чому структура проєкту така й які варіанти відхилено — щоб наступна команда не перепроєктувала це заново.

Кейс: як скоротили частку завислих операцій

Замовник прийшов із React-застосунком, де частина транзакцій губилася між підписом у гаманці та підтвердженням у мережі. Статус перевірявся опитуванням за таймером: у разі обриву зв’язку запит просто לא повторювався, а користувач бачив «надіслано», хоча операція не йшла.

Окрема біда — подвійний клік по кнопці: другий підпис створював дубль, і розбиратися доводилося вручну за логами вузла.

Зібрали єдиний шар стану транзакції на wagmi: підписку на події підтвердження замість опитування, ідемпотентний ключ на кожну операцію та чергу повторних спроб з обмеженням за кількістю кроків.

Після перезавантаження сторінки застосунок звіряє незавершені хеші з мережею й відновлює актуальний статус — «зависла» операція або доїжджає, або чесно позначається помилкою.

Метрики до й після: частка операцій без підтвердження впала з 9% до 0,4%. Кількість повторних підписів при подвійному кліку — з 30 до нуля, кнопка блокується до фінального статусу. Час відновлення після збою зв’язку скоротився з ручної звірки на 10–15 хвилин до кількох секунд.

Головне — зник цілий клас відмов «користувач підписав, а операція не пішла». Підтвердження стало ідемпотентним, стан відновлюється з мережі, а не з пам’яті вкладки, тому повторний вхід у застосунок більше не створює дублів.

Чим відрізняється надсилання транзакції від її підтвердження в React?

Повернення з writeContract означає рівно одне: гаманець підписав виклик і надіслав його в мережу, повернувши хеш. Операція ще не в блоці — вона в черзі непідтверджених, її можуть відкинути або замінити транзакцією з тим самим nonce. Інтерфейс, що знімає блокування за цією подією, показує «успіх» там, де стан контракту не змінився.

Підтвердження — окремий стан, його дає useWaitForTransactionReceipt: чекає квитанцію з полем status і лише тоді вважає операцію виконаною. Між цими точками — весь життєвий цикл: симуляція виклику, підпис, публікація, включення в блок, набір підтверджень. Кожен перехід заслуговує на свій статус, а не на один булевий прапорець завантаження.

Симуляція виклику до підпису відсікає повернення через неправильні аргументи або змінений стан контракту: користувач не підписує наперед провальну операцію й не бачить помилку вже після підтвердження в гаманці.

Час очікування включення непередбачуваний — він залежить від завантаження мережі та запропонованої комісії, тому чекати його фіксованим таймером безглуздо.

Стан тримають на подіях, кнопку розблоковують за квитанцією, а не за хешем, і окремо відстежують заміну: у витісненої операції квитанція за старим хешем не з’явиться ніколи.

Окрема гілка — відмова користувача в гаманці: це не збій мережі, і змішувати її з помилкою надсилання не можна, інакше інтерфейс React-застосунку лякає червоним текстом там, де людина просто передумала.

Технічні сумніви, які варто зняти до старту

Розбір заперечень починаємо з частого випадку: фронтенд на React уже є, написаний попередньою командою або власними силами. Перш ніж щось змінювати, ми дивимося три точки — як зберігається стан, де ізольовано шар підпису транзакцій і як обробляються відмови мережі. За ними видно, що доопрацьовувати, а що збирати заново.

Нижче — те, що зазвичай проговорюємо до підписання плану.

У нас уже є код — будете переписувати?

Ні, за замовчуванням. Якщо шар підпису транзакцій ізольовано від інтерфейсу, ми залишаємо його й змінюємо лише те, що заважає. Переписуємо, коли логіка гаманця розмазана по компонентах: тоді кожна нова мережа ламає верстку, і підтримка коштує дорожче за акуратне збирання заново.

Де закінчується ваша відповідальність і починається наша?

Ми відповідаємо за клієнтську частину: підключення гаманця, надсилання й підтвердження транзакцій, стани інтерфейсу та розбір помилок. Контракти, ключі та права доступу залишаються на вашому боці — ми звертаємося до них як до зовнішнього інтерфейсу й не зберігаємо секрети в себе.

Як додасте новий гаманець або мережу?

Шар підключення тримаємо окремо від екранів, тому новий провайдер — це конфігурація, а не переписування інтерфейсу. Перевіряємо на ньому підключення, підпис і перемикання мережі, і лише після цього виводимо кнопку користувачам.

Як ви перевіряєте збої?

Окремо відтворюємо відмову користувача й відмову мережі: відхилений підпис, втрату зв’язку, довгу відповідь, повторне надсилання. На кожен випадок — зрозумілий стан в інтерфейсі; без нього користувач натискає кнопку вдруге й отримує підвішену транзакцію.

Обговоримо задачу й повернемося з оцінкою та планом

Щоб оцінка була інженерною, а не «за відчуттями», потрібні вхідні дані по проєкту — чим конкретніші дані, тим менше припущень у плані робіт і тим точніші строки. Достатньо того, що вже є в роботі: репозиторій, документація, доступ до тестового середовища.

  • адреси й мережі контрактів, з якими працюватиме інтерфейс, та описи їхніх публічних методів;
  • перелік користувацьких сценаріїв: підключення гаманця, підпис, надсилання транзакції, очікування підтвердження, відмова;
  • які гаманці та способи підключення мають підтримуватися — розширення, мобільний, апаратний;
  • дизайн-макети або посилання на поточний інтерфейс, навіть чернеткові;
  • доступи до середовищ: тестова мережа, вузол або провайдер, ключ лише для читання;
  • вимоги до обробки збоїв: що показуємо при відхиленому підписі, відхиленні на боці контракту й заміні транзакції;
  • поточний стек інтерфейсу — версія React, бібліотеки для роботи з контрактами, обмеження збирання.

Далі наш крок. Протягом двох робочих днів розбираємо вхідні дані, звіряємо сценарії з контрактами й повертаємося з планом робіт: етапи, обсяг, залежності, точки, де потрібні ваші рішення, і критерії приймання за кожним сценарієм.

Опишіть задачу в зручній формі — повернемося з оцінкою та планом.

Напрямки блокчейн-розробки

Останні роботи

  • Розробка сайту компанії B2B ADVANCE
    Розробка сайту компанії B2B ADVANCE
    1575
  • Розробка веб-додатків для компанії FEEDME
    Розробка веб-додатків для компанії FEEDME
    1427
  • Розробка веб-сайту для компанії БЕЛФІНГРУП
    Розробка веб-сайту для компанії БЕЛФІНГРУП
    1105
  • Розробка інтернет магазину для компанії FURNORO
    Розробка інтернет магазину для компанії FURNORO
    1421
  • Розробка логотипу компанії B2B Advance
    Розробка логотипу компанії B2B Advance
    858
  • Розробка веб-додатків для компанії Enviok
    Розробка веб-додатків для компанії Enviok
    1181