React dApp фронтенд: стек wagmi/viem, транзакции, ошибки

Пользователь подписывает транзакцию, а интерфейс молчит — и он уходит, не дождавшись подтверждения. Мы разрабатываем dApp на React под ключ: состояния, работа с сетью и подтверждения выстроены так, что зависшие операции перестают быть нормой, а доля незавершённых действий падает в разы.
Часто задаваемые вопросы

Почему разработка 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
    1574
  • Разработка веб-приложения для компании FEEDME
    Разработка веб-приложения для компании FEEDME
    1427
  • Разработка веб-сайта для компании БЕЛФИНГРУПП
    Разработка веб-сайта для компании БЕЛФИНГРУПП
    1105
  • Разработка интернет магазина для компании FURNORO
    Разработка интернет магазина для компании FURNORO
    1421
  • Разработка логотипа компании B2B Advance
    Разработка логотипа компании B2B Advance
    858
  • Разработка веб-приложения для компании Enviok
    Разработка веб-приложения для компании Enviok
    1181