Комиссии TRC20: TronFuel и Paymaster
Спонсирование комиссии означает, что третья сторона оплачивает energy и bandwidth, которые тратит транзакция TRON, поэтому отправляющему кошельку не нужен TRX. Для этого мы рекомендуем TronFuel. Paymaster от Chaingateway решал ту же задачу внутри API и отменён: существующие интеграции продолжают работать, но новые интеграции использовать его не должны.
Почему кошелёк TRON с токенами, но без TRX не может их отправить?
Заголовок раздела «Почему кошелёк TRON с токенами, но без TRX не может их отправить?»Перевод TRC20 — это вызов смарт-контракта. TRON взимает за него energy и bandwidth, и адрес оплачивает эти ресурсы либо сжигая TRX, либо используя ресурсы, которые он застейкал или которые ему делегировали. Сам токен никогда не платит.
Из-за этого рано или поздно с одной и той же ситуацией сталкивается любая интеграция с TRON. Клиент вносит депозит в USDT на только что созданный адрес. Теперь этот адрес держит токены и больше ничего. Отправка этих токенов дальше завершается ошибкой со статусом 422 и сообщением balance is not sufficient, потому что нет TRX на оплату стоимости ресурсов. Заранее пополнять TRX каждый депозитный адрес работает, но замораживает TRX на адресах, которые, возможно, никогда не будут использованы.
Спонсирование комиссии решает это с другой стороны. Третья сторона оплачивает стоимость ресурсов, и кошелёк отправляет свои токены, вообще не держа TRX.
Что использовать вместо Paymaster?
Заголовок раздела «Что использовать вместо Paymaster?»TronFuel — это то, что мы рекомендуем для этого сегодня. Сервис арендует energy оптом у стейкеров вместо сжигания TRX, и именно отсюда берётся экономия по сравнению с обычным сжиганием. Подробности изложены в статье Комиссии за транзакции TRC-20 в сети TRON: объяснение.
TronFuel — отдельный сервис. У него нет эндпоинта внутри API Chaingateway, поэтому в этой документации не описано, как его вызывать. Собственная документация сервиса — по ссылке выше.
Доступен ли Paymaster до сих пор?
Заголовок раздела «Доступен ли Paymaster до сих пор?»Paymaster от Chaingateway решал ту же задачу внутри API: он покрывал bandwidth и energy, так что кошельку не требовался TRX перед отправкой токенов TRC20, а стоимость списывалась с кредитного баланса вашего аккаунта.
Сервис отменён. Интеграции, которые уже вызывают эндпоинты Paymaster, продолжают работать, и поэтому эндпоинты по-прежнему задокументированы ниже. Не стройте на них новые интеграции.
| Эндпоинт | Назначение |
|---|---|
POST /api/v2/tron/paymaster | Создать запрос на спонсируемую транзакцию |
GET /api/v2/tron/paymaster | Получить список ваших запросов и их статусы |
GET /api/v2/tron/paymaster/{id} | Прочитать один запрос |
POST /api/v2/tron/paymaster/estimate | Оценить energy, bandwidth и комиссию |
GET /api/v2/tron/paymaster/balance | Прочитать остаток кредитного баланса |
Сначала — оценка стоимости
Заголовок раздела «Сначала — оценка стоимости»Сколько energy и bandwidth требуется транзакции, зависит от типа транзакции и от контракта, который она вызывает, поэтому сумма не фиксирована. POST /api/v2/tron/paymaster/estimate принимает то же тело запроса, что и сам запрос, и возвращает, во что обойдётся транзакция.
curl --request POST\ --url https://app.chaingateway.io/api/v2/tron/paymaster/estimate\ --header 'Accept: application/json'\ --header 'Content-Type: application/json'\ --header 'Authorization: Bearer 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 /api/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://app.chaingateway.io/api/v2/tron/paymaster\ --header 'Accept: application/json'\ --header 'Content-Type: application/json'\ --header 'Authorization: Bearer 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 /api/v2/tron/paymaster/{id} с этим id или получите список всех запросов через GET /api/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 вместо оплаты за каждую транзакцию?
Заголовок раздела «Можно ли застейкать TRX вместо оплаты за каждую транзакцию?»Если TRX и так ваш, вы можете застейкать его один раз и переиспользовать ресурсы вместо оплаты за каждую транзакцию. POST /api/v2/tron/freeze стейкает TRX ради energy или bandwidth, POST /api/v2/tron/delegate передаёт эти ресурсы другому адресу, а POST /api/v2/tron/undelegate и POST /api/v2/tron/unfreeze отменяют оба шага. Один застейканный адрес может снабжать стоящие за ним депозитные адреса — эта схема подходит для платёжного потока со множеством принимающих адресов.
Четыре эндпоинта стейкинга используют одинаковую форму тела запроса. Поля address, amount и resource обязательны, а resource — это BANDWIDTH или ENERGY. delegate и undelegate добавляют обязательное поле receiver. Как и везде в API, вы подписываете через password или privatekey.
curl --request POST\ --url https://app.chaingateway.io/api/v2/tron/freeze\ --header 'Accept: application/json'\ --header 'Content-Type: application/json'\ --header 'Authorization: Bearer YOUR_API_TOKEN'\ --data '{ "address": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH", "amount": 100, "resource": "ENERGY", "password": "test123"}'Успешный вызов возвращает data.result: true и txid транзакции стейкинга. К делегированию применяются два правила из файла OpenAPI: баланс должен быть заморожен до того, как его можно делегировать, а получатель должен отличаться от адреса владельца. Неудавшийся вызов возвращает статус 422 с сообщением узла, например no frozenBalance(Energy), если вы размораживаете больше, чем застейкали, или delegated Resource does not exist, если вы отменяете делегирование того, что никогда не делегировалось. Как застейканный TRX превращается в energy и bandwidth, описывает модель ресурсов TRON.
Какой вариант подходит для моей интеграции?
Заголовок раздела «Какой вариант подходит для моей интеграции?»Таблица сравнивает варианты по тому, что для них нужно и сколько они стоят.
| Вариант | Что нужно | Модель стоимости | Статус |
|---|---|---|---|
| Пополнить TRX каждый адрес | TRX на каждом депозитном адресе | TRX сжигается за каждую транзакцию | работает, замораживает TRX |
| TronFuel | отдельный сервис TronFuel вне API Chaingateway | energy арендуется вместо сжигания TRX | рекомендуется |
| Стейкинг и делегирование | TRX, который вы можете заблокировать | застейканный TRX даёт ресурсы вместо сжигания | работает |
| Paymaster | кредитный баланс на вашем аккаунте Chaingateway | комиссия списывается с кредитного баланса | отменён |
Перед отправкой проверьте баланс TRX на адресе через GET /api/v2/tron/balances/{address}. Адрес без TRX и без делегированных ресурсов завершается ошибкой с сообщением balance is not sufficient, описанным выше.
Сама отправка перевода разбирается в разделе Создание транзакций с токенами TRC20 на TRON.
Источники
Заголовок раздела «Источники»- TRON resource model определяет energy, bandwidth, стейкинг и делегирование.
- TRC20 protocol interface описывает функции контракта, которые вызывает перевод.