SDK tronweb

TronWeb es el SDK de JavaScript definitivo para interactuar con la blockchain de TRON, ofreciendo una interfaz unificada para la gestión de cuentas, la firma de transacciones y la interacción con contratos. Esta referencia completa cubre la inicialización, utilidades principales y patrones avanzados para construir aplicaciones robustas.

Arquitectura del SDK

TronWeb es el SDK oficial y canónico de JavaScript para la blockchain de TRON. Aunque los desarrolladores que vienen de Ethereum encontrarán familiar la sintaxis de Solidity, los modelos de estado y recursos subyacentes de la red son únicos. TronWeb está diseñado específicamente para aprovechar el motor de TRON, proporcionando interfaces nativas para gestionar la Energía y el Ancho de banda, interactuar con tokens TRC-10 y compatibles con EVM, y derivar direcciones con el prefijo T.

Ya sea que estés construyendo una DApp basada en el navegador con TronLink o un servicio de backend de alto rendimiento en Node.js, TronWeb sirve como el puente principal entre la lógica de tu aplicación y los nodos de la red.

Instalación

Terminal

# Tarea: Instalar el SDK oficial de JavaScript de TRON.
npm install tronweb

tronweb funciona en Node.js (CommonJS y ESM) y en el navegador. Los tipos de TypeScript están incluidos en el paquete.

---

Inicialización

init.js

// Tarea: Instanciar TronWeb para la red principal usando una clave privada.
import TronWeb from "tronweb"

// Con clave privada (lado del servidor / scripts)
const tronWeb = new TronWeb({
  fullHost: 'https://api.trongrid.io', // red principal
  privateKey: process.env.PRIVATE_KEY,
});

// Solo lectura (sin clave privada — solo para consultas)
const tronWebReadOnly = new TronWeb({
  fullHost: 'https://api.trongrid.io',
});

Endpoints de TronGrid

Red	fullHost
Red principal	https://api.trongrid.io
Red de prueba Nile	https://nile.trongrid.io
Red de prueba Shasta	https://api.shasta.trongrid.io

TronGrid requiere una clave de API para uso en producción por encima del límite de tasa gratuito. Configúrala así:

init_apikey.js

// Tarea: Configurar TronWeb con una clave de API Pro de TronGrid.
const tronWeb = new TronWeb({
  fullHost: 'https://api.trongrid.io',
  headers: { 'TRON-PRO-API-KEY': process.env.TRONGRID_API_KEY },
  privateKey: process.env.PRIVATE_KEY,
});

---

Utilidades de Direcciones

addresses.js

// Tarea: Validar direcciones y convertir entre formatos Hex/Base58.
// Verificar si una dirección es válida
tronWeb.isAddress('TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb2Jq'); // true

// Convertir dirección hex a Base58 (prefijo T)
const base58 = tronWeb.address.fromHex('41e552f6487585c2b58bc2c9bb4492bc1f17132cd0');
// → 'TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb2Jq'

// Convertir Base58 a hex
const hex = tronWeb.address.toHex('TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb2Jq');
// → '41e552f6487585c2b58bc2c9bb4492bc1f17132cd0'

// Derivar dirección desde clave privada
const address = tronWeb.address.fromPrivateKey(process.env.PRIVATE_KEY);

---

Cuenta y Saldo

balance.js

// Tarea: Consultar el saldo de TRX y los recursos de Energía/Ancho de banda de una cuenta.
// Saldo de TRX (devuelto en Sun — dividir por 1,000,000 para obtener TRX)
const balanceSun = await tronWeb.trx.getBalance('TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb2Jq');
const balanceTRX = balanceSun / 1_000_000;

// Información completa de la cuenta (saldo, recursos, montos congelados, permisos)
const account = await tronWeb.trx.getAccount('TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb2Jq');

// Información de recursos de la cuenta (saldos y límites de Energía y Ancho de banda)
const resources = await tronWeb.trx.getAccountResources('TN3W4H6rK2...');
console.log(resources.EnergyLimit);      // Energía total disponible
console.log(resources.EnergyUsed);       // Energía consumida en este período
console.log(resources.NetLimit);         // Ancho de banda total disponible
console.log(resources.freeNetUsed);      // Ancho de banda gratuito consumido hoy

---

Enviar TRX

send.js

// Tarea: Transferir TRX nativo a otra dirección.
// Enviar TRX — el monto está en Sun (1 TRX = 1,000,000 Sun)
const tx = await tronWeb.trx.sendTransaction(
  'TRecipientAddress...',   // destinatario
  10_000_000,               // monto: 10 TRX
);
console.log(tx.txid);       // hash de la transacción

Todos los montos en Sun

tronweb representa los montos de TRX en Sun en todo el SDK. Siempre multiplica los valores de TRX por 1,000,000 antes de pasarlos a tronweb, y divide por 1,000,000 al mostrar saldos a los usuarios.

---

Interacción con Contratos

Cargar un Contrato Desplegado

contract_load.js

// Tarea: Cargar una instancia de contrato usando su dirección y ABI opcional.
// Cargar un contrato por dirección (obtiene el ABI de la cadena si está verificado)
const contract = await tronWeb.contract().at('TContractAddress...');

// O proporcionar el ABI explícitamente (más rápido, funciona para contratos no verificados)
const abi = [ /* array ABI */ ];
const contractExplicit = tronWeb.contract(abi, 'TContractAddress...');

Llamar a Funciones View (gratuitas)

Las funciones view y pure no consumen Energía cuando se llaman fuera de cadena:

contract_call.js

// Tarea: Ejecutar una llamada a un método de solo lectura sin crear una transacción.
// .call() para funciones de solo lectura — sin transacción, sin comisión
const result = await contract.balanceOf('TUserAddress...').call();
console.log(result.toString()); // BigNumber

Enviar Transacciones (que cambian el estado)

contract_send.js

// Tarea: Crear y enviar una transacción para un método que cambia el estado.
// .send() para funciones que cambian el estado — crea una transacción
const txId = await contract.transfer('TRecipient...', 1_000_000).send({
  feeLimit: 1_000_000_000,   // máximo TRX a quemar si no hay Energía (en Sun)
  callValue: 0,              // TRX a enviar con la llamada (en Sun), normalmente 0
  shouldPollResponse: true,  // esperar confirmación antes de devolver el resultado
});
console.log(txId); // hash de la transacción

Pasar Argumentos del Constructor al Desplegar

contract_deploy.js

// Tarea: Desplegar un nuevo contrato inteligente usando ABI y bytecode.
const deployed = await tronWeb.contract().new({
  abi: compiledAbi,
  bytecode: compiledBytecode,
  feeLimit: 1_000_000_000,
  parameters: [constructorArg1, constructorArg2],
});
console.log(deployed.address);

---

Operaciones con Tokens TRC-20

trc20_ops.js

// Tarea: Realizar verificaciones de saldo y transferencias estándar de TRC-20.
const usdtAddress = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'; // USDT en la red principal

const usdt = await tronWeb.contract().at(usdtAddress);

// Saldo (devuelto en la unidad mínima del token — USDT usa 6 decimales)
const balance = await usdt.balanceOf('TYourAddress...').call();
const usdtAmount = balance / 1_000_000;

// Transferir
await usdt.transfer('TRecipient...', 5_000_000).send({
  feeLimit: 1_000_000_000,
  shouldPollResponse: true,
});

// Aprobar
await usdt.approve('TSpenderContract...', 1_000_000_000).send({
  feeLimit: 100_000_000,
});

---

Escuchar Eventos

events.js

// Tarea: Observar en tiempo real los eventos Transfer en un contrato.
const contract = await tronWeb.contract().at('TContractAddress...');

// Observar todos los eventos Transfer en un contrato TRC-20
contract.Transfer().watch((err, event) => {
  if (err) return console.error(err);
  console.log('Transfer:', {
    from: event.result.from,
    to: event.result.to,
    value: event.result.value.toString(),
    txId: event.transaction,
  });
});

---

Estado de Transacción

tx_info.js

// Tarea: Obtener recibos de transacciones y datos de consumo de Energía.
// Obtener información de la transacción (incluye Energía consumida, resultado, bloque)
const info = await tronWeb.trx.getTransactionInfo('txHashHere...');
console.log(info.receipt.result);        // 'SUCCESS' o 'FAILED'
console.log(info.receipt.energy_usage);  // Energía consumida

// Obtener transacción sin procesar
const tx = await tronWeb.trx.getTransaction('txHashHere...');

---

Manejo de Errores

tronweb lanza o rechaza con objetos de error que incluyen un campo message. Envuelve las llamadas en try/catch:

error_handling.js

// Tarea: Capturar y analizar errores del SDK y reversiones de contratos.
try {
  const tx = await contract.someMethod().send({ feeLimit: 100_000_000 });
} catch (err) {
  if (err.includes('REVERT')) {
    // El contrato revirtió — verifica tus entradas y el límite de Energía
  }
  if (err.includes('bandwith')) { // nota: tronweb lo escribe sin 'd'
    // Ancho de banda insuficiente
  }
  console.error(err);
}

Cadenas de error de tronweb

tronweb suele rechazar con cadenas de texto simples en lugar de objetos Error. Verifica typeof err === 'string' al manejar errores. Los mensajes de error del nodo no siempre son consistentes — registra el valor completo durante el desarrollo.

---

Usar tronweb en una DApp de Navegador

Al crear una DApp de navegador, usa el window.tronWeb inyectado por TronLink en lugar de instanciar tronweb tú mismo. Esto usa automáticamente la billetera conectada del usuario sin exponer una clave privada:

dapp_usage.js

// Tarea: Conectarse a la instancia de TronLink inyectada del usuario.
if (typeof window.tronWeb === 'undefined') {
  alert('TronLink is not installed.');
  return;
}

const tronWeb = window.tronWeb;

// Verificar si el usuario ha aprobado la conexión
if (!tronWeb.defaultAddress.base58) {
  // El usuario aún no ha conectado su billetera a tu DApp
}

const userAddress = tronWeb.defaultAddress.base58;
const contract = await tronWeb.contract().at('TContractAddress...');

El window.tronWeb inyectado está preconfigurado con la cuenta del usuario y firma las transacciones a través de la extensión TronLink sin que tu DApp vea nunca la clave privada.