Как работает автозаправка
Заправка проверяется при POST /transactions/fee. Если при
POST /transaction базового актива не хватает на комиссию токен-перевода,
платформа также запускает фоновую проверку дозаправки. Текущий перевод
отклоняется: его нужно повторить после поступления газа. Отдельного
пользовательского вызова «заправить аккаунт» нет.
Когда срабатывает
Проверка газа встроена в расчёт комиссии на старте создания транзакции и срабатывает только если выполнены все условия:
- в workspace назначена газ-станция;
- на исходном vault включена автозаправка;
- vault не является самой газ-станцией;
- переводится не базовый актив сети (для перевода самого базового актива заправлять нечего — он и есть газ);
- для базового актива есть per-asset конфигурация с корректными
capиthreshold.
Если хотя бы одно условие не выполнено, заправка молча пропускается, и транзакция идёт обычным путём.
Алгоритм
Решение о заправке зависит от порога threshold: если доступный
баланс не ниже порога, долив не создаётся. Это условие действует
и при проверке, запущенной после ошибки недостатка комиссии.
Пошагово:
- Определяется цель — кошелёк базового актива в том vault'е, чей токен пользователь пытается отправить.
- Сравнение с порогом. Если доступный баланс газа
≥ threshold— заправка не нужна, выход. - Сумма заправки считается как
cap − текущий баланс: долив до потолка, а не фиксированная порция. - Дедупликация. Если от газ-станции на этот адрес уже идёт заправка — новая не создаётся (см. ниже).
- Оценка комиссии. Сеть оценивает стоимость самой заправки. Если
она выше
max_gas_price— заправка откладывается. - Проверка средств станции. На vault'е газ-станции должно хватать
на
сумму заправки + комиссию. Если нет — заправка не создаётся. - Создание заправки. Платформа создаёт перевод базового актива с газ-станции на адрес от имени системного (сервисного) аккаунта. После того как он подтвердится в блокчейне, исходную транзакцию пользователя можно повторить — газ на месте.
Заправка переживёт отмену запроса
Перевод-заправка создаётся как самостоятельный фоновый эффект: даже если исходный HTTP-запрос пользователя оборвётся, уже создание заправки продолжит выполняться в пределах минутного таймаута. Успешное подтверждение сетью этим не гарантируется. Создаётся она от системного аккаунта, а не от имени пользователя.
Возможные исходы
Попытка заправки приводит к одному из состояний:
| Исход | Что значит | Что делать |
|---|---|---|
| Газа достаточно | баланс выше threshold (порога) |
ничего, транзакция идёт дальше |
| Заправка запущена / уже идёт | создан (или уже существует) перевод газа, он подтверждается в сети | повторить операцию через некоторое время |
| Сеть слишком дорогая | средства на станции есть, но комиссия превышает max_gas_price |
повторить позже, когда комиссии в сети упадут |
| На станции нет средств | газ-станции не хватает на сумму + комиссию | пополнить vault газ-станции базовым активом |
Когда расчёт комиссии для транзакции не проходит, а заправка в этот
момент уже выполняется, ответ содержит дополнительный код
GAS_REFUEL_IN_PROGRESS_EXISTS. Это сигнал клиенту: «газ доливается,
повтори чуть позже», а не окончательная ошибка.
Параллельные запросы и дубли
Перед созданием проверяется активная заправка от станции на тот же адрес по тому же активу. Уже найденная заправка повторно не создаётся. Абсолютной гарантии отсутствия дублей при одновременных запросах нет; проверяйте фактические транзакции и не рассчитывайте на точное однократное пополнение.
Коды ошибок
| Код | HTTP | Когда возникает |
|---|---|---|
GAS_STATION_NOT_FOUND |
404 | для workspace не назначена газ-станция либо нет конфигурации по запрошенному активу |
GAS_STATION_CANNOT_ASSIGN_SELF |
400 | попытка включить автозаправку на vault'е, который сам является газ-станцией |
GAS_STATION_NETWORK_MISMATCH |
400 | попытка задать конфигурацию для валюты чужой сети: mainnet-валюта в testnet-воркспейсе или наоборот |
TRANSACTION_INSUFFICIENT_FEE_BALANCE |
409 | при создании токен-перевода не хватает базового актива на комиссию; возможна фоновая дозаправка |
GAS_REFUEL_IN_PROGRESS_EXISTS |
— | дополнительный код в ответе: газ доливается, операцию стоит повторить позже |
См. также Структуру кошельков.