TronWeb Introducción: SDK de JavaScript para TRON Blockchain

TronWeb es el SDK de JavaScript principal para el desarrollo de TRON, análogo a ethers.js en Ethereum. Maneja la codificación de direcciones, la creación de transacciones, las llamadas de contratos inteligentes y la integración de billeteras para dApps, backends y scripts.

Esta introducción cubre la instalación, la configuración, los conceptos básicos y su primera transferencia TRX desde el código.

Cuándo usar TronWeb {#cuándo}

Utilice TronWeb cuando necesite:

• Cree una dApp web que se conecte a TronLink o utilice claves integradas
• Ejecutar servicios backend que envían USDT o activan contratos
• Implementar e interactuar con TRC-20 / Contratos de solidez
• Suscríbete a eventos (con encuestas o extensiones)

Para acceso HTTP puro sin abstracciones de SDK, consulte la TronGrid guía API y la referencia de API HTTP.

Instalación

npm install tronweb

Navegador: paquete a través de webpack/vite o carga desde CDN para prototipos (prefiera npm para producción).

Configuración básica

Sólo lectura (sin clave privada)

const TronWeb = require('tronweb');

const tronWeb = new TronWeb({
  fullHost: 'https://api.trongrid.io',
  headers: { 'TRON-PRO-API-KEY': 'your-api-key' },
});

Obtenga claves API de TronGrid.

Con clave de firma (solo del lado del servidor)

const tronWeb = new TronWeb({
  fullHost: 'https://api.trongrid.io',
  privateKey: process.env.TRON_PRIVATE_KEY,
  headers: { 'TRON-PRO-API-KEY': process.env.TRONGRID_KEY },
});

Red de prueba de Shasta

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

Obtenga Shasta TRX gratis en faucets para probar la implementación de TRC-20.

Objetos principales

Enviar ejemplo TRX

async function sendTrx(toAddress, amountTrx) {
  const amountSun = tronWeb.toSun(amountTrx);
  const tx = await tronWeb.trx.sendTransaction(toAddress, amountSun);
  return tx;
}

Realice un seguimiento de la confirmación con verificar API de transacción.

TRC-20 interacción

const USDT = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t';

async function getUsdtBalance(address) {
  const contract = await tronWeb.contract().at(USDT);
  const balance = await contract.balanceOf(address).call();
  return tronWeb.toBigNumber(balance).div(1e6).toString();
}

Análisis profundo: consultar TRC-20 balance y enviar USDT programáticamente.

integración TronLink (navegador)

async function getTronWeb() {
  if (window.tronLink && window.tronLink.ready) {
    return window.tronLink.tronWeb;
  }
  throw new Error('TronLink not found');
}

El usuario firma transacciones en la ventana emergente de billetera: su sitio nunca ve la clave privada.

Error al manejar

Fallos comunes:

• OUT_OF_ENERGY — la cuenta necesita TRX o energía congelada
• REVERT — llamada rechazada de contrato inteligente
• Dirección no válida: siempre tronWeb.isAddress() antes de enviar

Asigne mensajes fáciles de usar en aplicaciones de producción.

Consejos para la estructura del proyecto

• Instancia separada de solo lectura TronWeb para consultas públicas
• Módulo firmante aislado en el servidor con secretos HSM o env
• Límite de tarifa de llamadas TronGrid; números de bloque de caché
• Utilice escuchas de eventos para la detección de depósitos

Seguridad

• Seguridad de contratos inteligentes
• Validar todas las direcciones proporcionadas por el usuario
• Nunca registres claves privadas
• Simular llamadas de contrato cuando sea posible antes de que se envíe la red principal.

TronWeb frente a otros SDK

Los desarrolladores de Python usan tronpy; Los equipos Go usan gotron-sdk. TronWeb sigue siendo el más documentado para dApps de navegador y backends de Node.js. Elija según su pila: los conceptos (codificación de direcciones, firma, ABI) se transfieren entre bibliotecas.

Variables de entorno y secretos

Nunca confirmes claves privadas. Utilice archivos .env excluidos de git o administradores de secretos en la nube en producción. Las instancias TronWeb en los servidores deben usar billeteras activas dedicadas con saldos mínimos: pasar al almacenamiento en frío. Gire las claves si los registros pueden haber capturado volcados del entorno.

Lista de verificación para solucionar problemas

Si algo sale mal en TRON, trátelo como un problema de depuración estructurado: confirme el txid exacto en la cadena, verifique la dirección del contrato de destino y solo entonces decida si la falla es recuperable. En TRON, muchos problemas "misteriosos" son simplemente uno de: red incorrecta (mainnet vs testnet), contrato de token incorrecto (falso USDT/tokens con nombres similares), recursos insuficientes (OUT_OF_ENERGY/ancho de banda) o retraso en la interfaz de usuario/indexador entre la billetera y el explorador.

Comience con estas comprobaciones en cadena:

• Copie siempre el txid/hash completo de su billetera o explorador.
• Confirme el estado del resultado del tx en TronScan (SUCCESS, REVERT, OUT_OF_ENERGY o aún pendiente).
• Compruebe si la dirección del destinatario/contrato coincide con la que desea enviar.
• Si se trata de una llamada de contrato, confirme que el selector de función y los parámetros coincidan con el estándar de token que cree que está utilizando (TRC-20 vs TRC-10 vs BEP-20 en BSC).

Luego aplique la ruta de corrección para su categoría:

• Confirmar el estado y los parámetros de la transacción.
• Verificar direcciones (contrato de token, destinatario, enrutador/gastador).
• Agregar o delegar recursos (Energía/Ancho de banda) cuando el fallo esté basado en recursos.

Errores comunes

Estos patrones causan la mayoría de los errores a nivel de usuario:

• Usar direcciones de mainnet en testnet (o al revés).
• Copiar un símbolo de token en lugar de la dirección del contrato TRC-20 real.
• Firmar la dirección de aprobación/gastador incorrecta porque el enlace de la interfaz de usuario es malicioso o está desactualizado.
• Reintentar sin cambiar la entrada fallida (por ejemplo, REVERT sigue revirtiéndose hasta que corrija el parámetro).

Si no está seguro, no “simplemente envíe de nuevo”. Realice un cambio controlado, verifique en TronScan y luego continúe.

Preguntas frecuentes

¿Cómo sé si una transacción está realmente confirmada?

Utilice TronScan y verifique el estado del resultado del tx. Las etiquetas "pendientes" de la billetera pueden retrasarse; El estado de la cadena es la fuente de la verdad. Copie txid y verifique SUCCESS/REVERT/OUT_OF_ENERGY, no solo el texto de la interfaz de usuario.

¿Por qué la interfaz de usuario difiere de TronScan?

Algunas billeteras y dApps utilizan diferentes indexadores o capas de caché. Es normal que haya un breve retraso entre la transmisión y la indexación; compare txid y espere a que la cadena se estabilice antes de concluir que hay una falla.

¿Qué debo hacer después de un REVERT?Detenga y decodifique la llamada fallida. La mayoría de los REVERT se deben a parámetros no válidos, dirección de contrato incorrecta, aprobaciones faltantes o una falta de coincidencia entre el estándar del token y el método. Solucione la causa y luego vuelva a firmar.

¿Es seguro firmar una aprobación ilimitada?

Las aprobaciones ilimitadas son seguras solo para direcciones de gastadores confiables que usted haya verificado (fuente verificada, enrutador correcto y contrato de token esperado). Para las pruebas, prefiera aprobaciones limitadas y revoque una vez que haya terminado.

¿Qué recursos requiere TRON para las llamadas de contrato?

La ejecución de contratos inteligentes consume principalmente energía, mientras que los bytes de transacciones consumen ancho de banda. Si recibe OUT_OF_ENERGY, agregue/congela/delegue energía. Si se agota el ancho de banda, concéntrese en mantener suficiente líquido TRX para bytes y asignación de recursos.

¿Cómo puedo reducir los tickets de soporte?

Muestre a los usuarios un mensaje claro de "qué sucedió" basado en el estado de la cadena y vincule directamente a la guía relevante (pendiente, fallida, sin energía o verificación). Guarda txid para que puedas conciliar rápidamente.

Guías relacionadas

• TronGrid Guía API
• Activar contrato inteligente
• TRON Referencia de API HTTP
• Implementar TRC-20 TronWeb

Preguntas frecuentes

¿Qué es TronWeb?

TronWeb es la biblioteca oficial de JavaScript para interactuar con la cadena de bloques TRON: cuentas, contratos, transacciones y consultas desde Node.js o aplicaciones de navegador.

¿Necesito una clave privada para leer los datos de blockchain?

No. Las operaciones de solo lectura, como las consultas de saldo, funcionan con un nodo público completo o una clave API TronGrid sin exponer claves privadas.

¿TronWeb frente a TronGrid?

TronGrid es la infraestructura API alojada. TronWeb es el SDK del cliente que se comunica con TronGrid o su propio nodo completo.

¿TronWeb es compatible con TypeScript?

Utilice los paquetes comunitarios @types o los tipos incluidos de TronWeb cuando estén disponibles. Envuelva llamadas de contrato con interfaces escritas en el código de la aplicación.

¿Qué versión debo usar?

Fije la última versión estable de npm y pruebe en Shasta antes de que se implemente la red principal.