Газ-станция и автозаправка
В EVM-сетях с моделью газа, чтобы отправить токен, мало иметь на балансе сам переводимый актив — нужно ещё чем-то заплатить сетевую комиссию (gas). В таких сетях комиссия платится отдельным базовым активом: ETH в Ethereum, BNB в BNB Chain и т. д., а токены (например, USDT) живут «поверх» него. Если вы держите на адресе только токен, но базового актива на нём нет, сеть не примет перевод — платить за газ нечем.
Газ-станция решает эту проблему автоматически. Это назначенный vault, который выступает источником базового актива для остальных vault'ов того же workspace: когда на адресе заканчивается газ, газ-станция переводит туда базовый актив. Если перевод был отклонён из-за нехватки комиссии, после заправки его нужно повторить.
Два понятия, которые легко спутать
- Газ-станция — откуда берётся газ. Один vault на workspace, из кошельков которого финансируются заправки.
- Автозаправка (autofuel) — куда и включена ли. Признак на каждом отдельном vault: разрешено ли пополнять его газом автоматически. Газ-станция может быть назначена, но пока ни на одном vault не включена автозаправка, заправок не происходит.
Где применима
Стандартные настройки газ-станции предназначены для EVM-сетей: Ethereum и BNB Smart Chain, включая их testnet-аналоги. Для TRON ресурсы и делегация настраиваются отдельно. В Bitcoin комиссия покрывается входами транзакции.
Список поддерживаемых сетей задаётся конфигурацией
Конкретные базовые активы, для которых работает газ-станция, прописаны в конфигурации платформы — там же лежат и их значения по умолчанию. Если для базового актива нет ни значения по умолчанию, ни сохранённой настройки, автозаправка пропускается. Пользовательский API позволяет задать пороги явно, но это само по себе не добавляет поддержку новой сети.
Mainnet и testnet
Газ-станция работает и в mainnet-, и в testnet-воркспейсах. Набор валют в настройках всегда соответствует сети воркспейса: mainnet-воркспейс видит и настраивает только mainnet-активы, testnet-воркспейс — только их testnet-аналоги (например, ETH в Sepolia). Для testnet-активов действуют свои значения по умолчанию.
Валюта чужой сети недоступна в обе стороны:
- запрос её конфигурации (
GET /gas_station/{cid}) отвечает404(GAS_STATION_NOT_FOUND); - попытка задать ей конфигурацию (
PUT) отклоняется с400и кодомGAS_STATION_NETWORK_MISMATCH.
Модель
| Сущность | Сколько | Назначение |
|---|---|---|
| Газ-станция | одна на workspace | vault-источник базового актива для заправок |
| Per-asset конфигурация | по одной на базовый актив | пороги и лимиты заправки для конкретной сети |
| Автозаправка | признак на каждом vault | разрешает автоматически пополнять газ этого vault'а |
Газ-станция не заправляет сама себя
Vault, назначенный газ-станцией, не может быть целью заправки.
Попытка включить на нём автозаправку отклоняется с кодом
GAS_STATION_CANNOT_ASSIGN_SELF, а сам механизм заправки
пропускает случай, когда источник и цель совпадают — чтобы не
создать перевод vault'а самому себе.
Параметры заправки
Поведение заправки настраивается отдельно для каждого базового актива (каждой сети). Три параметра задают, когда и насколько пополнять газ. В таблице — названия как в консоли и соответствующие им поля API:
| Параметр в консоли | Поле API | Что задаёт |
|---|---|---|
| Порог | threshold |
нижняя граница: как только доступный баланс газа на адресе падает ниже этого значения, запускается заправка |
| Лимит баланса | cap |
целевой баланс: заправка доливает газ ровно до этого значения (cap − текущий баланс) |
| Комиссия за газ (макс) | max_gas_price |
максимальная комиссия, которую газ-станция готова заплатить за одну заправку; защита от заправок в момент дорогой сети |
Значения передаются и хранятся как целые числа в минимальных
единицах актива (wei и т. п.) в виде строк — чтобы не терять
точность на больших числах. Должно выполняться
cap > threshold > 0.
Семантика max_gas_price
| Значение в запросе | Эффект |
|---|---|
| поле не указано | значение не меняется |
"-1" |
без ограничения — заправка идёт при любой комиссии сети |
"0" |
комиссия не допускается |
| положительное число | заправка только если сетевая комиссия не выше этого лимита |
Если из-за высокой комиссии заправка не проходит, это не ошибка конфигурации: средства на станции есть, но сеть сейчас слишком дорогая. Достаточно повторить операцию позже, когда комиссии упадут.
Значения по умолчанию
Для поддерживаемых базовых активов на платформе заданы дефолтные
параметры заправки. Они применяются автоматически в момент назначения
газ-станции или включения автозаправки — для каждого актива, по
которому в соответствующем vault есть кошелёк, и затем могут быть
переопределены вручную. Если для актива дефолтов нет, заправка по
нему просто пропускается, пока вы не зададите cap и threshold
явно.
Конкретные текущие значения по сетям — на отдельной странице Значения по умолчанию.
Жизненный цикл настройки
- Назначить газ-станцию. Один vault workspace'а помечается как источник газа. При этом для каждого его базового актива создаются per-asset конфигурации со значениями по умолчанию.
- Включить автозаправку на тех vault'ах, газ которых нужно пополнять автоматически. Включение тоже досоздаёт недостающие per-asset конфигурации по дефолтам.
- При необходимости — переопределить параметры («Порог», «Лимит баланса», «Комиссия за газ») для конкретного актива.
Проверка пополнения выполняется при расчёте комиссии, а также при отказе создания токен-перевода из-за недостатка базового актива на комиссию — см. Как работает автозаправка.
Управление через API
Все операции выполняются в контексте текущего workspace (заголовок
X-Workspace-Id). Точные схемы запросов и ответов — в
справочнике API.
| Действие | Метод и путь | Право |
|---|---|---|
| Назначить vault газ-станцией | POST /gas_station/vault/{vid} |
EditWorkspace |
| Включить автозаправку на vault | POST /vault/accounts/{vid}/autofuel/activate |
EditWorkspace |
| Выключить автозаправку на vault | POST /vault/accounts/{vid}/autofuel/deactivate |
EditWorkspace |
| Обновить конфигурацию актива | PUT /gas_station/configuration/currency/{cid} |
EditWorkspace |
| Статус газ-станции workspace | GET /gas_station |
ViewWorkspace |
| Конфигурация конкретного актива | GET /gas_station/{cid} |
ViewWorkspace |
Если газ-станция не настроена
GET /gas_station всегда отвечает 200 — с признаком
configured: false, когда в workspace газ-станция ещё не назначена.
Это не ошибка: значит, автоматических заправок в этом workspace нет.
Действия с газ-станцией фиксируются в журнале аудита: назначение станции, включение и выключение автозаправки, изменение per-asset конфигураций.