Спонсирование комиссий TRC20: TronFuel и Paymaster

Проблема: токены без TRX не двигаются

Перевод TRC20 — это вызов смарт-контракта. TRON взимает за него energy и bandwidth, и адрес оплачивает эти ресурсы либо сжигая TRX, либо используя ресурсы, которые он застейкал или которые ему делегировали. Сам токен никогда не платит.

Из-за этого рано или поздно с одной и той же ситуацией сталкивается любая интеграция с TRON. Клиент вносит депозит в USDT на только что созданный адрес. Теперь этот адрес держит токены и больше ничего. Отправка этих токенов дальше завершается ошибкой со статусом 422 и сообщением balance is not sufficient, потому что нет TRX на оплату стоимости ресурсов. Заранее пополнять TRX каждый депозитный адрес работает, но замораживает TRX на адресах, которые, возможно, никогда не будут использованы.

Спонсирование комиссии решает это с другой стороны. Стороннее лицо оплачивает стоимость ресурсов, и кошелёк отправляет свои токены, вообще не держа TRX.

TronFuel — рекомендуемый способ

TronFuel — это то, что мы рекомендуем для этого сегодня. Сервис арендует energy оптом у стейкеров вместо сжигания TRX, и именно отсюда берётся экономия по сравнению с обычным сжиганием. Подробности изложены в статье Экономьте до 60% на комиссиях за транзакции TRON TRC-20.

TronFuel — отдельный сервис. У него нет эндпоинта внутри API Chaingateway, поэтому в этой документации не описано, как его вызывать. Собственная документация сервиса — по ссылке выше.

Paymaster отменён

Paymaster от Chaingateway решал ту же задачу внутри API: он покрывал bandwidth и energy, так что кошельку не требовался TRX перед отправкой токенов TRC20, а стоимость списывалась с кредитного баланса вашего аккаунта.

Сервис отменён. Интеграции, которые уже вызывают эндпоинты Paymaster, продолжают работать, и поэтому эндпоинты по-прежнему задокументированы ниже. Не стройте на них новые интеграции.

Эндпоинт	Назначение
`POST /v2/tron/paymaster`	Создать запрос на спонсируемую транзакцию
`GET /v2/tron/paymaster`	Получить список ваших запросов и их статусы
`GET /v2/tron/paymaster/{id}`	Прочитать один запрос
`POST /v2/tron/paymaster/estimate`	Оценить energy, bandwidth и комиссию
`GET /v2/tron/paymaster/balance`	Прочитать остаток кредитного баланса

Сначала — оценка стоимости

Сколько energy и bandwidth требуется транзакции, зависит от типа транзакции и от контракта, который она вызывает, поэтому сумма не фиксирована. POST /v2/tron/paymaster/estimate принимает то же тело запроса, что и сам запрос, и возвращает, во что обойдётся транзакция.

curl --request POST\
  --url https://api.chaingateway.io/v2/tron/paymaster/estimate\
  --header 'Accept: application/json'\
  --header 'content-type: application/json'\
  --header 'Authorization: YOUR_API_TOKEN'\
  --data '{
    "type": "TRC20",
    "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH",
    "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": "1"
}'

{
  "status": 200,
  "ok": true,
  "message": "Successfully estimated the fees",
  "data": {
    "energy_consumption": 32000,
    "bandwidth_consumption": 368,
    "paymaster_fee": 0.15
  }
}

Комиссия списывается с кредитного баланса после завершения запроса. Баланс, которого недостаточно, приводит к ошибке запроса. GET /v2/tron/paymaster/balance возвращает остаток.

Создание спонсируемого запроса

type принимает значения TRX, TRC10, TRC20 и TRC721. Наряду с from, to и amount это поле обязательно. Для TRC20 и TRC721 дополнительно передаётся contractaddress, для TRC721 и TRC10 — tokenid. Подпись работает так же, как и везде в API: password для защищённого паролем адреса Chaingateway, иначе privatekey. Необязательный callback_url получает результат.

curl --request POST\
  --url https://api.chaingateway.io/v2/tron/paymaster\
  --header 'Accept: application/json'\
  --header 'content-type: application/json'\
  --header 'Authorization: YOUR_API_TOKEN'\
  --data '{
    "type": "TRC20",
    "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH",
    "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": "1",
    "password": "test123",
    "callback_url": "https://example.com/callback"
}'

Ответ — не хеш транзакции, а id запроса:

{
  "status": 200,
  "ok": true,
  "message": "Successfully created paymaster request",
  "data": {
    "id": "9c72d676-8180-4cd2-a406-f0f1cd097506"
  }
}

Отслеживание запроса

Опрашивайте GET /v2/tron/paymaster/{id} с этим id или получите список всех запросов через GET /v2/tron/paymaster. Поле status проходит через pending, пока запрос ожидает, processing, пока транзакция в пути, и completed, когда она завершена. При ошибке значение выглядит как failed - [reason], где причина указана после дефиса. Итоговый хеш транзакции появляется в записи после завершения транзакции.

{
  "id": "9cfbfcaf-68b2-47e9-bf55-5b6b4875e84d",
  "type": "TRC20",
  "from": "THG9nncwASg3ub5rvVquocAHwwQbnKZxpH",
  "to": "TPUjdnMrS7XDUFp5W6zgh4QDCW34nXa2x1",
  "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "amount": "200",
  "token_id": null,
  "transaction_hash": "80a223e0cb20ef692fbd23d3cbaf3cc1dfa2b9667aaef70c7da8ca8f707ec28b",
  "status": "success",
  "used_credits": "2.178413",
  "callback_url": "https://api.chaingateway.io/receiver/webhooks/tron",
  "created_at": "2024-09-11T15:28:57.000000Z"
}

Стейкинг как третий вариант

Если TRX и так ваш, вы можете застейкать его один раз и переиспользовать ресурсы вместо оплаты за каждую транзакцию. POST /v2/tron/freeze стейкает TRX ради energy или bandwidth, POST /v2/tron/delegate передаёт эти ресурсы другому адресу, а POST /v2/tron/undelegate и POST /v2/tron/unfreeze отменяют оба шага. Один застейканный адрес может снабжать стоящие за ним депозитные адреса — эта схема подходит для платёжного потока со множеством принимающих адресов.

Отправка самого перевода разбирается в разделе Создание транзакций с токенами TRC20.