Gas Credit Backend

Что такое Gas Credit Backend

Gas Credit Backend — это сервис автоматического предфинансирования газа для кросс-чейн трансферов между TVM-сетями. Несмотря на название "credit" (кредит), это НЕ кредитная система в традиционном понимании.

Сервис позволяет пользователю оплатить газ в сети отправления, а система автоматически деплоит event-контракт в сети назначения, конвертируя стоимость газа по текущему USD-курсу между нативными токенами сетей.

Проблема которую решает

При TVM↔TVM трансферах пользователю необходимо:

1. Отправить транзакцию в сети отправления
2. Вручную задеплоить event-контракт в сети назначения (требует газ в нативном токене сети назначения)

Это создает UX-проблему: пользователь должен иметь нативные токены обеих сетей. Credit Backend решает это, принимая оплату газа в нативном токене сети отправления и автоматически деплоя event в сети назначения.

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

Условие	Описание
useCredit=true	API-запрос с включенным Credit режимом
attached_gas_USD >= required_gas_USD	Пользователь приложил достаточно газа
remaining_gas_to — валидный EventDeployer	Адрес возврата газа — один из EventDeployer'ов
Конфигурация не expired	end_timestamp не прошел
Source chain ID в whitelist	allowed_source_chain_ids содержит исходную сеть

Когда НЕ срабатывает (non-credit режим)

• useCredit=false в API-запросе — пользователь сам деплоит event через proof
• attached_gas в USD меньше required_gas в USD — трансфер отклоняется
• remaining_gas_to не является адресом EventDeployer — трансфер отклоняется
• Конфигурация expired или chain ID не в whitelist — игнорируется

Когда НЕ нужен:

• Пользователь имеет нативные токены обеих сетей и хочет сам управлять газом
• Для отладки/тестирования с ручным деплоем event
• При использовании relay-based подтверждений (EVM↔TVM)

Flow работы

Пошагово

1. Пользователь отправляет трансфер

   • Транзакция идет на Proxy контракт с attached_gas
   • Proxy эмитит событие TvmTvmNative или TvmTvmAlien

2. Credit Backend получает событие

   • process_event_emitter_event() парсит событие
   • Вызывает process_tvm_tvm_message()

3. Валидация сообщения

   • validate_tvm_tvm_remaining_gas_to() — проверяет адрес возврата газа
   • validate_tvm_tvm_attached_gas() — проверяет достаточность газа по USD

4. Расчет required_gas

   • event_initial_balance + expected_gas + deploy_token_value
   • Плюс tx_block_proof_fwd_fee (форвард proof через контракты)

5. Получение proof

   • Запрос к Proof API за tx_block_proof
   • Кеширование proof для повторных запросов

6. Отправка deployEvents

   • prepare_unsigned_tvm_tvm_message() формирует сообщение
   • deliver_message() подписывает и отправляет

7. Event деплоится

   • EventDeployer.deployEvents() вызывает EventConfiguration.deployEvents()
   • Event контракт верифицирует proof и минтит/анлочит токены

State Machine

Статус	Описание	Переходы
New	Событие получено, ожидает обработки	→ Completed, → Rejected, → Skipped
Rejected	Валидация не прошла (недостаточно газа или invalid remaining_gas_to)	Конечное
Completed	Event успешно задеплоен	Конечное
Skipped	Уже обработано (дублирующий message_hash)	Конечное

Риски и Edge Cases

Риск/Ошибка	Причина	Защита/Решение
Недостаточно газа	attached_gas_USD < required_gas_USD	Транзакция отклоняется (Rejected), газ остается у пользователя
Invalid remaining_gas_to	Адрес не является EventDeployer	Транзакция отклоняется
Волатильность цен	Курс изменился между отправкой и обработкой	Запас в item_buffer и transfer_reserve
Дублирующие события	Повторная обработка того же message_hash	message_hashes set, skip если уже есть
Expired конфигурация	end_timestamp прошел	Конфигурация удаляется из обработки
Недоступен Proof API	Сеть недоступна	Retry с maximum_failed_responses_time_sec
Alien token не задеплоен	Токен впервые бриджится	Добавляется deploy_token_value к required_gas

Формула расчета required_gas

// Константы цепочки форварда
DEPLOYER_TO_VERIFIER_CHAIN_SIZE = 3   // deployer → configuration → event → verifier
CONFIGURATION_TO_VERIFIER_CHAIN_SIZE = 2   // configuration → event → verifier

// Расчет комиссий за форвард proof
tx_block_proof_fwd_fee = calculate_fwd_fee(tx_block_proof)  // зависит от размера proof
full_chain_tx_block_proof_fwd_fee = tx_block_proof_fwd_fee × 3
shorten_chain_tx_block_proof_fwd_fee = tx_block_proof_fwd_fee × 2

// Базовый газ
essential_gas = event_initial_balance + expected_gas + deploy_token_value

// Итоговые значения
event_required_gas = essential_gas + shorten_chain_tx_block_proof_fwd_fee
total_required_gas = essential_gas + full_chain_tx_block_proof_fwd_fee

Компоненты формулы

Компонент	Описание
event_initial_balance	Начальный баланс event контракта (из EventConfiguration)
expected_gas	Газ для дополнительных операций, запрошенный пользователем (из события)
deploy_token_value	Стоимость деплоя токена в сети назначения (если Native и токен не predeployed в AlienProxy)
tx_block_proof_fwd_fee	Комиссия за форвард одной ячейки proof (зависит от размера BOC)

Два значения required_gas

Значение	Путь форварда	Использование
total_required_gas	EventDeployer → Configuration → Event → Verifier (×3)	Валидация: attached_gas_USD >= total_required_gas_USD
event_required_gas	Configuration → Event → Verifier (×2)	Отправка в EventConfiguration при деплое

Почему два значения?

EventDeployer уже оплачивает первый хоп форварда, поэтому в EventConfiguration отправляется event_required_gas (с коэффициентом ×2), а для валидации достаточности газа используется total_required_gas (с коэффициентом ×3).

Коды ошибок

Код	Константа	Описание
101	-	Отправитель не является factory (EventDeployer)
2112	ZERO_ADDRESS	Передан нулевой адрес
2213	TOO_LOW_DEPLOY_VALUE	Недостаточно средств для деплоя event
2215	EVENT_TIMESTAMP_HIGHER_THAN_END	Timestamp события превышает end time конфигурации
2801	UNKNOWN_MEDIATOR_OPERATION	Неизвестный тип операции в Mediator
2802	WRONG_GUARDIAN	Вызывающий не является guardian
2803	NOT_NATIVE_PROXY	Адрес не является native proxy
2804	WRONG_GAS_RECIPIENT	Неверный адрес получателя газа

Важные замечания

1. Credit режим включен по умолчанию — useCredit=true если не указано в API запросе
2. Валидация газа использует USD конверсию — attached gas конвертируется в USD для сравнения
3. EventDeployers предварительно пополнены — система поддерживает баланс на контрактах EventDeployer
4. Поддерживается batch-деплой — несколько событий могут быть задеплоены в одной транзакции