Перейти к содержанию

Как работает автозаправка

Заправка проверяется при POST /transactions/fee. Если при POST /transaction базового актива не хватает на комиссию токен-перевода, платформа также запускает фоновую проверку дозаправки. Текущий перевод отклоняется: его нужно повторить после поступления газа. Отдельного пользовательского вызова «заправить аккаунт» нет.

Когда срабатывает

Проверка газа встроена в расчёт комиссии на старте создания транзакции и срабатывает только если выполнены все условия:

  • в workspace назначена газ-станция;
  • на исходном vault включена автозаправка;
  • vault не является самой газ-станцией;
  • переводится не базовый актив сети (для перевода самого базового актива заправлять нечего — он и есть газ);
  • для базового актива есть per-asset конфигурация с корректными cap и threshold.

Если хотя бы одно условие не выполнено, заправка молча пропускается, и транзакция идёт обычным путём.

Алгоритм

Решение о заправке зависит от порога threshold: если доступный баланс не ниже порога, долив не создаётся. Это условие действует и при проверке, запущенной после ошибки недостатка комиссии.

баланс газа на адресе < threshold?ниженетбаланс выше порогаrefuelAmount = cap − текущий балансждать завершениядаесть заправкав процессе?запросить у сети комиссиюза заправкуотложить — сеть дорогаядакомиссия > max_gas_price?нетгаз-станция пустанетна газ-станции хватаетна сумму + комиссию?дасоздать транзакцию-заправкус газ-станции на адресждать подтверждения в сети
баланс газа на адресе < threshold?ниженетбаланс выше порогаrefuelAmount = cap − текущий балансждать завершениядаесть заправкав процессе?запросить у сети комиссиюза заправкуотложить — сеть дорогаядакомиссия > max_gas_price?нетгаз-станция пустанетна газ-станции хватаетна сумму + комиссию?дасоздать транзакцию-заправкус газ-станции на адресждать подтверждения в сети

Пошагово:

  1. Определяется цель — кошелёк базового актива в том vault'е, чей токен пользователь пытается отправить.
  2. Сравнение с порогом. Если доступный баланс газа ≥ threshold — заправка не нужна, выход.
  3. Сумма заправки считается как cap − текущий баланс: долив до потолка, а не фиксированная порция.
  4. Дедупликация. Если от газ-станции на этот адрес уже идёт заправка — новая не создаётся (см. ниже).
  5. Оценка комиссии. Сеть оценивает стоимость самой заправки. Если она выше max_gas_price — заправка откладывается.
  6. Проверка средств станции. На vault'е газ-станции должно хватать на сумму заправки + комиссию. Если нет — заправка не создаётся.
  7. Создание заправки. Платформа создаёт перевод базового актива с газ-станции на адрес от имени системного (сервисного) аккаунта. После того как он подтвердится в блокчейне, исходную транзакцию пользователя можно повторить — газ на месте.

Заправка переживёт отмену запроса

Перевод-заправка создаётся как самостоятельный фоновый эффект: даже если исходный 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 — дополнительный код в ответе: газ доливается, операцию стоит повторить позже

См. также Структуру кошельков.