TronBox: Desarrollo de contratos inteligentes en TRON

TronBox es el marco de desarrollo estándar para contratos inteligentes TRON: compila Solidity, ejecuta migraciones e implementa en Shasta o mainnet. Si ha utilizado Truffle en Ethereum, los flujos de trabajo de TronBox le resultarán familiares.

Esta guía cubre la instalación, configuración, migraciones, flujo de trabajo de prueba e integración del proyecto con TronWeb.

Instalar e iniciar

npm install -g tronbox
mkdir my-tron-dapp && cd my-tron-dapp
tronbox init

Diseño generado:

contracts/          # Solidity source
migrations/         # Deployment scripts
tronbox.js          # Network config
tronbox-config.js   # Optional overrides

configuración de tronbox.js

module.exports = {
  networks: {
    shasta: {
      privateKey: process.env.SHASTA_PRIVATE_KEY,
      userFeePercentage: 100,
      feeLimit: 1_000_000_000,
      fullHost: 'https://api.shasta.trongrid.io',
      network_id: '2',
    },
    mainnet: {
      privateKey: process.env.MAINNET_PRIVATE_KEY,
      userFeePercentage: 100,
      feeLimit: 1_000_000_000,
      fullHost: 'https://api.trongrid.io',
      headers: { 'TRON-PRO-API-KEY': process.env.TRONGRID_KEY },
      network_id: '1',
    },
  },
  compilers: {
    solc: {
      version: '0.8.20',
    },
  },
};

Nunca confirme claves privadas; utilice variables de entorno.

Redacción de contratos

Solidez para los objetivos TRON TVM. Ejemplo TRC-20 en guía de implementación TRC-20.

Los contratos de OpenZeppelin funcionan con la alineación de versiones: importe a través de npm y configure reasignaciones de solc si es necesario.

Migraciones

migrations/1_initial_migration.js: implementa el contrato de seguimiento Migrations.

migrations/2_deploy_mycontract.js:

const MyContract = artifacts.require('MyContract');

module.exports = function (deployer) {
  deployer.deploy(MyContract, /* constructor args */);
};

Ejecutar:

tronbox compile
tronbox migrate --network shasta

Restablecer el estado de implementación local:

tronbox migrate --reset --network shasta

Pruebas

Opciones:

• Manual — TronIDE, TronScan contrato de lectura/escritura
• Scripts — TronWeb pruebas de integración contra Shasta
• Consola TronBox — tronbox console --network shasta

El ecosistema de prueba automatizado es más delgado que el de Ethereum: muchos equipos usan scripts Jest + TronWeb personalizados.

Flujo de trabajo de Shasta

1. Generar billetera Shasta (TronLink modo Shasta o tronWeb.createAccount())
2. Fondo del grifo Shasta
3. Migrar contratos
4. Verificar en Shasta TronScan
5. Ejecute TronWeb scripts de interacción

Lista de verificación de implementación de Mainnet

• [ ] Auditoría o revisión de seguridad interna — seguridad de contrato inteligente
• [] Argumentos del constructor verificados dos veces
• [] Cartera de implementación financiada TRX + Energía
• [ ] feeLimit suficiente para contratos grandes
• [] Verificar fuente en TronScan después de la implementación
• [] Transferir propiedad a multifirma si corresponde

tronbox migrate --network mainnet

TronBox vs TronIDE

Muchos equipos prototipan en TronIDE y producen en TronBox.

Problemas comunes

Migración de TronBox a Hardhat

Algunos equipos migran a Hardhat con complementos TRON para Ethereum+TRON CI unificado. TronBox sigue siendo válido para implementaciones de Solidity 0.5.x/0.8.x TRON. Elija una cadena de herramientas por repositorio para evitar cambios en la configuración.

Configuración de red en tronbox.js

Defina las redes mainnet, shasta y development con los fullHost y privateKey correctos del entorno. La implementación accidental de la red principal con claves de prueba o viceversa provoca incidentes. Agregue un script de confirmación previo a la implementación que imprima el nombre de la red y requiera una var de entorno CONFIRM=mainnet explícita.

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/delega 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

• Solididad en TRON
• TVM explicado
• Implementar TRC-20 TronWeb
• Seguridad de contratos inteligentes

Preguntas frecuentes

¿Qué es TronBox?

TronBox es un marco de desarrollo para contratos inteligentes TRON, similar a Truffle en Ethereum, con compilación, migración y configuración de red.

¿Se puede implementar TronBox en la red principal?

Sí, con una clave privada financiada en la configuración de red. Pruebe siempre primero en Shasta testnet.

¿TronBox admite migraciones de TypeScript?

Las migraciones son JavaScript de forma predeterminada. Puede utilizar ts-node con una configuración personalizada o compilar TS en JS.

¿Cómo verifico los contratos implementados por TronBox?

Utilice TronScan para verificar la interfaz de usuario con la versión exacta de solc y la configuración de optimización de tronbox.js.

¿TronBox aún se mantiene?

Consulte el GitHub oficial TRON para conocer las últimas versiones. Versiones de pines en CI de producción.