TronWeb Введение: JavaScript SDK для TRON Blockchain

TronWeb — это основной JavaScript SDK для разработки TRON — аналог ethers.js в Ethereum. Он обрабатывает кодирование адресов, построение транзакций, вызовы смарт-контрактов и интеграцию кошельков для dApps, бэкэндов и скриптов.

В этом введении описываются установка, настройка, основные понятия и ваш первый перенос TRX из кода.

Когда использовать TronWeb

Используйте TronWeb, когда вам нужно:

• Создайте веб-приложение, которое подключается к TronLink или использует встроенные ключи.
• Запускайте серверные службы, которые отправляют USDT или запускают контракты.
• Развертывание и взаимодействие с контрактами TRC-20/Solidity.
• Подписка на события (с опросами или расширениями)

Для доступа по чистому HTTP без абстракций SDK см. TronGrid Руководство по API и Справочник по HTTP API.

Установка

npm install tronweb

Браузер: собирайте прототипы через webpack/vite или загружайте из CDN (для производства лучше использовать npm).

Базовая настройка

Только для чтения (без закрытого ключа)

⟦Т1⟧

Получите ключи API от TronGrid.

С ключом подписи (только на стороне сервера)

⟦Т2⟧

Тестовая сеть Шаста

const tronWeb = new TronWeb({
  fullHost: 'https://api.shasta.trongrid.io',
  privateKey: 'your-shasta-test-key',
});

Получите бесплатно Shasta TRX из сборщиков для тестирования развертывание TRC-20.

Основные объекты

Пример отправки TRX

⟦Т1⟧

Отслеживайте подтверждение с помощью API проверки транзакции.

TRC-20 взаимодействие

⟦Т2⟧

Подробное описание: запрос баланса TRC-20 и отправка USDT программно.

TronLink интеграция (браузер)

⟦Т3⟧

Пользователь подписывает транзакции во всплывающем окне кошелька — ваш сайт никогда не видит закрытый ключ.

Обработка ошибок

Распространенные неисправности:

• OUT_OF_ENERGY — аккаунт нуждается в TRX или замороженной энергии
• REVERT — смарт-контракт отклонил вызов
• Неверный адрес — всегда tronWeb.isAddress() перед отправкой

Сопоставьте удобные для пользователя сообщения в рабочих приложениях.

Советы по структуре проекта

• Отдельный экземпляр TronWeb только для чтения для общедоступных запросов.
• Модуль подписывающего лица изолирован на сервере с помощью секретов HSM или env.
• Ограничение скорости звонков TronGrid; номера блоков кэша
• Используйте прослушиватели событий для обнаружения депозитов.

Безопасность

• Безопасность смарт-контракта
• Проверьте все адреса, предоставленные пользователем.
• Никогда не регистрируйте закрытые ключи
• Имитировать вызовы контракта, когда это возможно, до отправки из основной сети.

TronWeb по сравнению с другими SDK

Разработчики Python используют tronpy; Команды Го используют gotron-sdk. TronWeb остается наиболее документированным для браузерных dApps и серверных частей Node.js. Выбирайте в зависимости от вашего стека — концепции (кодирование адреса, подпись, ABI) передаются между библиотеками.

Переменные среды и секреты

Никогда не передавайте приватные ключи. Используйте файлы .env, исключенные из git, или диспетчеры облачных секретов в рабочей среде. TronWeb экземпляры на серверах должны использовать выделенные горячие кошельки с минимальными балансами — перемещайте в холодное хранилище. Поменяйте ключи, если в журналах могут быть записаны дампы среды.

Контрольный список устранения неполадок

Если что-то пойдет не так на TRON, отнеситесь к этому как к проблеме структурированной отладки: подтвердите точный txid в цепочке, проверьте адрес целевого контракта и только затем решите, можно ли устранить сбой. В TRON многие «загадочные» проблемы — это просто одна из следующих: неправильная сеть (основная сеть или тестовая сеть), неправильный контракт токена (поддельный USDT / токены с одинаковым названием), недостаточность ресурсов (OUT_OF_ENERGY / пропускная способность) или задержка пользовательского интерфейса/индексатора между кошельком и проводником.

Начните с этих цепочек проверок:

• Всегда копируйте полный txid/хэш из своего кошелька или проводника.
• Подтвердите статус результата передачи на TronScan (SUCCESS, REVERT, OUT_OF_ENERGY или все еще в ожидании).
• Проверьте, соответствует ли адрес получателя/договора тому, что вы намеревались отправить.
• Если это вызов контракта, убедитесь, что селектор функций и параметры соответствуют стандарту токена, который, по вашему мнению, вы используете (TRC-20 vs TRC-10 vs BEP-20 на BSC).

Затем примените путь исправления для вашей категории:

• Подтвердите статус и параметры транзакции.
• Проверка адресов (контракт токена, получатель, маршрутизатор/отправитель).
• Добавляйте или делегируйте ресурсы (энергию/пропускную способность), если сбой связан с ресурсами.

Распространенные ошибки

Эти шаблоны вызывают большинство сбоев на уровне пользователя:

• Использование адресов основной сети в тестовой сети (или наоборот).
• Копирование символа токена вместо фактического адреса контракта TRC-20.
• Подписание неправильного адреса одобрения/платежа, поскольку ссылка пользовательского интерфейса является вредоносной или устаревшей.
• Повторная попытка без изменения ошибочного ввода (например, REVERT продолжает возвращаться до тех пор, пока вы не исправите параметр).

Если вы не уверены, не «просто отправьте еще раз». Внесите одно контролируемое изменение, проверьте на TronScan, затем продолжайте.

Часто задаваемые вопросы

Как узнать, действительно ли транзакция подтверждена?

Используйте TronScan и проверьте статус результата передачи. Ярлыки кошелька «ожидающие» могут отставать; Статус цепочки является источником истины. Скопируйте txid и проверьте SUCCESS/REVERT/OUT_OF_ENERGY, а не только текст пользовательского интерфейса.

Почему пользовательский интерфейс отличается от TronScan?

Некоторые кошельки и децентрализованные приложения используют разные индексаторы или уровни кэша. Короткая задержка между трансляцией и индексированием является нормальной; сравните txid и подождите, пока цепочка стабилизируется, прежде чем сделать вывод об ошибке.

Что мне делать после REVERT?Остановитесь и декодируйте неудачный вызов. Большинство ошибок REVERT вызваны недопустимыми параметрами, неправильным адресом контракта, отсутствием утверждений или несоответствием между стандартом токена и методом. Устраните причину и подпишите заново.

Безопасно ли подписывать неограниченное разрешение?

Неограниченное одобрение безопасно только для проверенных вами адресов доверенных отправителей (проверенный источник, правильный маршрутизатор и ожидаемый контракт токена). Для тестирования отдавайте предпочтение ограниченному утверждению и отзыву после завершения.

Какие ресурсы требуются TRON для вызовов по контракту?

Выполнение смарт-контракта в основном потребляет энергию, а байты транзакций потребляют пропускную способность. Если вы получили OUT_OF_ENERGY, добавьте/заморозьте/делегируйте Энергию. Если полоса пропускания исчерпана, сосредоточьтесь на сохранении достаточного количества TRX для байтов и распределения ресурсов.

Как я могу уменьшить количество обращений в службу поддержки?

Покажите пользователям четкое сообщение «что произошло» на основе статуса цепочки и дайте прямую ссылку на соответствующее руководство (ожидание, сбой, отсутствие энергии или проверка). Сохраните txid, чтобы можно было быстро выполнить согласование.

Похожие руководства {#связанные}

• TronGrid Руководство по API
• Триггерный смарт-контракт
• TRON Справочник по HTTP API
• Развертывание TRC-20 TronWeb

Часто задаваемые вопросы

Что такое TronWeb?

TronWeb — официальная библиотека JavaScript для взаимодействия с блокчейном TRON — учетными записями, контрактами, транзакциями и запросами из Node.js или браузерных приложений.

Нужен ли мне закрытый ключ для чтения данных блокчейна?

Нет. Операции только для чтения, такие как запросы баланса, работают с общедоступным полным узлом или ключом API TronGrid без раскрытия закрытых ключей.

TronWeb против TronGrid?

TronGrid — это размещенная инфраструктура API. TronWeb — это клиентский SDK, который взаимодействует с TronGrid или вашим собственным полным узлом.

Поддерживает ли TronWeb TypeScript?

Используйте пакеты сообщества @types или связанные типы TronWeb, если они доступны. Оберните вызовы контракта типизированными интерфейсами в коде приложения.

Какую версию мне использовать?

Закрепите последнюю стабильную версию из npm и протестируйте ее на Shasta перед развертыванием основной сети.