Статусы, подтверждения и реорги

Жизнь задания на sweep

queued ──▶ processing ──▶ swept
   ▲            │  ├────▶ failed
   └── повтор ◀─┘  └────▶ rejected

Статус	Что значит
queued	Принято и ждёт батча или повторной попытки.
processing	В батче, который готовится, уже в пути или ждёт подтверждений.
swept	Окончательный. Средства в горячем кошельке: swept_amount, tx_hash, gas, fee.
failed	Окончательный. Перевод откатился в сети или кончились попытки. Почему — в reason.
rejected	Окончательный. Задание так и не отправилось: проверка перед отправкой не проходила. Какая — в reason.

attempts — число попыток. Окончательный статус приходит событием вебхука sweep.swept, sweep.failed или sweep.rejected. reason — всегда один из стабильных кодов ниже: ветвитесь по нему. Сообщения самой ноды остаются в наших логах; могут появиться новые коды — незнакомый обрабатывайте как internal.

Почему задание отклонено

Перед отправкой батча сервис проверяет все адреса на одном блоке. Задание, не прошедшее проверку, проверяется снова после паузы — всего три раза, потому что нода может ещё не видеть только что пришедших средств или делегации. Если проверка так и не прошла, задание отклоняется:

reason	Что случилось	Что делать
not_upgraded	Адрес не делегирован на делегат этого горячего кошелька, а авторизации в запросе не было.	Отправьте sweep снова с авторизацией.
stale_authorization	Nonce авторизации не совпадает с nonce адреса: после подписи адрес отправил транзакцию.	Подпишите заново с текущим nonce.
would_fail	Симуляция показывает, что перевод упадёт: например, нет баланса или он меньше amount.	Проверьте баланс адреса.
nothing_to_sweep	С keep_one_unit на адресе нет ничего сверх оставляемой единицы.	Ничего: сметите адрес после следующего депозита.

Почему задание упало

failed с именем ошибки контракта значит, что перевод откатился в сети — внутри батча, который прошёл:

reason	Что значит
TokenTransferFailed	Токен отказал в переводе.
NativeTransferFailed	Горячий кошелёк не принял нативную монету.
NothingToSweep	К моменту выполнения батча баланса уже не было.
Unauthorized	К моменту выполнения батча адрес был делегирован на другой делегат.
reverted	Перевод откатился без ошибки наших контрактов — например, токен израсходовал все 300 000 газа, отведённые одному адресу.

Такое задание несёт свою долю газа, но без комиссии. Любая другая reason у failed — причина последней попытки.

Причины неудачной попытки

Попытка может не пройти целиком: например, батч не отправить, пока на газ-кошельке нет газа, или вся транзакция откатилась. Тогда задание возвращается в queued и ждёт повтора, а reason до следующей попытки говорит, что случилось. У задания пять попыток с растущими паузами между ними; когда они кончились, задание получает failed с причиной последней. Те же причины бывают в reason снятия делегации и в error горячего кошелька.

reason	Что случилось	Что делать
insufficient_gas_balance	Баланса газ-кошелька за вычетом комиссий к выводу, которые лежат на нём в резерве, не хватает на транзакцию.	Пополните газ-кошелёк: задания в очереди продолжатся сами.
gas_limit_exceeded	Одному sweep нужно больше газа, чем можно транзакции, — например, из-за необычного токена.	Напишите в поддержку.
transaction_reverted	Транзакция откатилась целиком — в сети или при оценке газа.	Ничего: попытка повторится. Если это повторяется, напишите в поддержку.
nonce_conflict	Nonce газ-кошелька заняла другая транзакция.	Ничего: попытка повторится со следующим nonce.
chain_unavailable	Нода сети не ответила или не выполнила запрос.	Ничего: попытка повторится.
internal	Другой сбой на нашей стороне.	Ничего: попытка повторится. Если это повторяется, напишите в поддержку.

Подтверждения

Сервис записывает итог, только когда над блоком транзакции набралось достаточно блоков: в тестнетах — три, считая её собственный. До этого задание остаётся в processing.

Если реорг выкинет блок в пределах этих подтверждений, receipt транзакции пропадёт, и сервис снова отправит ту же транзакцию из своего журнала. Вы увидите только задержку: ни дублей, ни потерянных заданий. Итог записывается, когда подтверждения набраны; более глубокий реорг после этого не обрабатывается — в Ethereum и BSC такие реорги очень редки.

Зависшие транзакции сервис тоже доводит сам: переотправляет их в ноду, а если они так и ждут — заменяет той же транзакцией с более высокой комиссией сети. Переотправлять что-либо вам не нужно.

Горячие кошельки

Статус	Что значит
pending	Делегат разворачивается. Пока кошелёк не станет активным, sweep в него получают 409 hot_wallet_not_active.
active	Делегат в сети: tx_hash — транзакция развёртывания. Приходит событие hot_wallet.active.
failed	Развернуть не удалось, причина — в error. Приходит событие hot_wallet.failed. Чтобы повторить, снова отправьте POST /v1/hot-wallets.

error — тоже код. Чаще всего это insufficient_gas_balance: пополните газ-кошелёк и зарегистрируйте горячий кошелёк снова. not_deployed значит, что транзакция развёртывания прошла, но делегата по его адресу нет: напишите в поддержку. Любой другой код — причина неудачной попытки.

Снятия делегации

Снятие проходит queued и processing, как sweep, и заканчивается статусом revoked, failed или rejected:

Статус	reason	Что значит
revoked		Делегации на адресе больше нет.
rejected	not_delegated	Снимать было нечего: делегации на адресе нет.
rejected	stale_authorization	Nonce адреса уже не тот, для которого вы подписали.
rejected	invalid_authorization	Авторизация не прошла проверку перед отправкой. Подпишите заново.
failed	not_applied	Транзакция прошла, но сеть пропустила авторизацию: nonce адреса сменился после проверки. Подпишите заново.
failed	другая	Причина последней попытки, когда попытки кончились.

См. Снятие делегации.