Nodo TON y API RPC: Conexión a The Open Network

Arquitectura de TON y el modelo de cadena fragmentada

TON no es una única cadena lineal. Se organiza como una masterchain, que almacena el estado del protocolo y la información de los validadores, más una o varias workchains, cada una de las cuales puede dividirse a su vez en shardchains. Esto significa que cuando consultas una cuenta, el nodo debe resolver qué shard y workchain contienen esa cuenta. Una dirección lleva un id de workchain y, para los shards, un prefijo de shard, por lo que el modelo mental es el de muchas cadenas en lugar de una sola.

Este diseño fragmentado es la razón por la que los nodos y las API de TON difieren de los endpoints JSON-RPC de EVM. Un endpoint EVM genérico puede responder a eth_getBalance para cualquier dirección sin resolución de shard porque hay una única cadena canónica. En TON, el nodo primero debe determinar el shard correcto, que está codificado en la dirección. La página de la red TON ofrece una visión general de estos componentes.

El modelo de ejecución asíncrona distingue aún más a TON. Las transacciones son mensajes que pueden desencadenar otros mensajes, y la ejecución puede abarcar varios bloques. No hay un recibo síncrono que devuelva el estado final de una interacción compleja. En su lugar, se observa la confirmación sondeando el historial de transacciones de la cuenta relevante. La documentación de TON sobre mensajes y transacciones explica este modelo en detalle.

• Masterchain: almacena el estado del protocolo, el conjunto de validadores y la configuración.
• Workchains: cadenas independientes con sus propias reglas; existe al menos una workchain para contratos inteligentes.
• Shardchains: subdivisiones de las workchains que procesan cuentas en paralelo.
• Formato de dirección: id de workchain + hash de cuenta, a veces con un prefijo de shard para el enrutamiento interno.

Roles de nodo: validadores, nodos completos y liteservers

Un validador asegura la red participando en el consenso. Los validadores deben hacer staking de TON, mantener la elegibilidad y gestionar claves. Ejecutar un validador es una preocupación operativa separada de servir consultas de API. Un nodo completo, por el contrario, sincroniza la cadena y puede servir consultas a través del protocolo liteserver. Un nodo con liteserver habilitado expone una interfaz TCP binaria que los clientes pueden usar para solicitar bloques, estados de cuentas y ejecutar métodos.

La documentación de TON sobre ejecutar un nodo completo describe el proceso de configuración y la configuración del liteserver. Para la mayoría de los desarrolladores de aplicaciones, no es necesario ejecutar un nodo completo; en su lugar, se conectan a una API HTTP que envuelve un liteserver. Esta separación de responsabilidades significa que puedes elegir un endpoint gestionado de un proveedor en lugar de operar la infraestructura tú mismo.

Si operas un nodo, la guía de solución de problemas de nodos cubre problemas comunes como bloqueos de sincronización y configuración de puertos. La conclusión clave es que el protocolo liteserver es binario y específico del proveedor, por lo que la integración directa es rara fuera de los equipos de infraestructura.

• Validador: requiere stake, gestión de claves y elegibilidad; asegura el consenso.
• Nodo completo: sincroniza la cadena y puede habilitar liteserver para consultas.
• Liteserver: protocolo TCP binario para consultas directas al nodo.
• API HTTP: envoltorio JSON sobre HTTP alrededor de un liteserver, usado por la mayoría de las aplicaciones.

Capas de API: liteserver, envoltorios HTTP y API de indexadores

Hay tres capas prácticas de API. Primero, el protocolo liteserver sobre TCP es lo que un nodo autoalojado expone directamente. Es eficiente pero binario y no legible por humanos. Segundo, los envoltorios de API HTTP hablan JSON sobre HTTP con un liteserver; estos son con los que se integran la mayoría de las aplicaciones. TON Center y servicios similares proporcionan API HTTP v2 y v3. Tercero, las API de indexadores o exploradores ofrecen búsquedas históricas y agregadas, a menudo con indexación adicional para transacciones y mensajes.

La API HTTP v3 es la interfaz recomendada actual para nuevos trabajos. Expone métodos para la ejecución de run-method, el estado de cuentas, el historial de transacciones, la búsqueda de bloques y el envío de BOCs (bags of cells). Las solicitudes con clave usan un encabezado de API key para obtener límites de tasa más altos. La API v2 es heredada y debe evitarse para nuevos proyectos. Para una comparación de estilos de protocolo, consulta JSON-RPC vs gRPC vs REST.

Al elegir un endpoint, considera si necesitas profundidad histórica. Las API respaldadas por indexadores pueden servir historial profundo, pero un endpoint solo con liteserver puede retener únicamente bloques recientes. El artículo acceso a datos históricos de blockchain analiza los requisitos de archivo. Para endpoints específicos de TON, la página de endpoints RPC de TON enumera opciones gestionadas.

• Liteserver: TCP binario, acceso directo al nodo, específico del proveedor.
• API HTTP v3: JSON sobre HTTP, recomendada para nuevas integraciones.
• API HTTP v2: heredada, evitar para nuevos trabajos.
• API de indexadores: consultas históricas y agregadas, pueden requerir nodos de archivo.

Superficie de integración práctica: métodos de la API HTTP v3

La API HTTP v3 expone un conjunto de métodos que cubren necesidades comunes de integración. Para el estado de cuentas, puedes llamar a getAddressInformation o getAccountState para recuperar el saldo, el estado y el hash del código. Para la ejecución de run-method, runGetMethod te permite llamar al método get de un contrato inteligente sin enviar una transacción. Para el historial de transacciones, getTransactions devuelve una lista de transacciones de una cuenta. Para la búsqueda de bloques, getBlockHeader y getMasterchainInfo proporcionan metadatos de bloques. Para enviar mensajes, sendBoc acepta un BOC codificado en base64.

Las solicitudes con clave usan un encabezado de API key, normalmente X-API-Key, para autenticarse y recibir límites de tasa más altos. Sin una clave, los endpoints públicos pueden imponer límites estrictos. El nombre exacto del encabezado y los límites de tasa varían según el proveedor, así que consulta la documentación del proveedor. El servicio de API de OnFinality proporciona endpoints TON gestionados con soporte de API key.

Al construir solicitudes, presta atención al formato de dirección. La API puede aceptar tanto formas amigables para el usuario como raw, pero algunos métodos requieren un formato específico. Valida siempre la dirección antes de enviar una solicitud para evitar errores.

• getMasterchainInfo: devuelve el seqno y el shard del último bloque de la masterchain.
• getAddressInformation: devuelve el saldo, el estado y el código de la cuenta.
• runGetMethod: ejecuta un método get en un contrato.
• getTransactions: devuelve el historial de transacciones de una cuenta.
• sendBoc: difunde un mensaje externo firmado.

Formatos de dirección y semántica de mensajes en TON

Las direcciones TON suelen representarse en dos formas: amigable para el usuario (base64url) y raw (workchain:hash). La forma amigable incluye una suma de verificación y banderas, lo que la hace más segura para mostrar e introducir. La forma raw es un id de workchain de 64 bits seguido de un hash de cuenta de 256 bits, normalmente escrito como workchain:hex_hash. La conversión entre ellas requiere cuidado porque la forma amigable codifica la workchain y el hash con una etiqueta y una suma de verificación específicas.

Las transferencias en TON son mensajes asíncronos. Un mensaje external-in inicia una transacción, que puede producir mensajes internos a otras cuentas. No hay un recibo síncrono que devuelva el resultado final. En su lugar, debes sondear el historial de transacciones de la cuenta de destino para confirmar que el mensaje fue procesado. Esta es una diferencia fundamental con las cadenas EVM, donde se devuelve un recibo de transacción inmediatamente después de la minería.

La documentación de TON sobre mensajes y transacciones proporciona la explicación canónica de este modelo. Al integrar, diseña tu aplicación para manejar la confirmación asíncrona, por ejemplo sondeando getTransactions para la dirección de destino hasta que aparezca la transacción esperada.

• Dirección amigable: base64url con suma de verificación, p. ej. EQD....
• Dirección raw: workchain:hash, p. ej. 0:abc....
• Mensaje external-in: inicia una transacción desde fuera de la cadena.
• Mensaje interno: enviado entre cuentas, puede desencadenar más transacciones.
• Confirmación: se observa sondeando el historial de transacciones, no un recibo síncrono.

Verificar la actividad del endpoint con la información de masterchain

Antes de integrarte en profundidad, verifica que el endpoint elegido está sirviendo datos en vivo. Un método ligero como getMasterchainInfo devuelve el seqno del último bloque de la masterchain. Si el seqno avanza con el tiempo, el endpoint está sincronizando y sirviendo datos actuales. También puedes leer el estado de una cuenta y confirmar que la hora de la última transacción es reciente.

El siguiente ejemplo de curl consulta la información de la cabeza de la masterchain desde un endpoint de API HTTP de TON. Reemplaza YOUR_API_KEY y la URL base con los detalles de tu proveedor. La respuesta incluye el seqno, que puedes comparar entre llamadas para confirmar la actividad.

Para una comprobación más exhaustiva, consulta el estado de una cuenta activa y el resultado de un run-method. La siguiente sección proporciona un ejemplo en Node.js que hace las tres cosas.

curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://toncenter.com/api/v3/masterchainInfo" | jq '.result.last.seqno'

Ejemplo ejecutable en Node.js: masterchain, estado de cuenta y run-method

Este script de Node.js consulta un endpoint de API HTTP de TON para la cabeza de la masterchain, el estado de una cuenta y el resultado de un run-method. Utiliza la API fetch integrada (Node.js 18+). Reemplaza YOUR_API_KEY y la URL base con los detalles de tu proveedor. El script imprime el seqno de la masterchain, el estado de la cuenta y el resultado del método.

El ejemplo también contrasta una dirección amigable con su forma raw. Puedes convertir entre ellas usando bibliotecas como @ton/core, pero para la demostración mostramos ambas cadenas. La forma raw se deriva de la forma amigable decodificando el base64url y extrayendo la workchain y el hash.

Ejecuta el script y observa la salida. Si el seqno de la masterchain es un número grande y el estado de la cuenta es active, el endpoint está sirviendo datos en vivo. Si el run-method devuelve un resultado, el contrato es invocable.

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://toncenter.com/api/v3';
const USER_FRIENDLY = 'EQD...'; // replace with a real address
const RAW = '0:...'; // replace with the raw form

async function main() {
  const headers = { 'X-API-Key': API_KEY };

  // 1. Masterchain info
  const mc = await fetch(`${BASE_URL}/masterchainInfo`, { headers }).then(r => r.json());
  console.log('Masterchain seqno:', mc.result.last.seqno);

  // 2. Account state (user-friendly)
  const state = await fetch(`${BASE_URL}/addressInformation?address=${USER_FRIENDLY}`, { headers }).then(r => r.json());
  console.log('Account status:', state.result.status);
  console.log('Balance (nanotons):', state.result.balance);

  // 3. Run-method (raw address)
  const run = await fetch(`${BASE_URL}/runGetMethod?address=${RAW}&method=seqno`, { headers }).then(r => r.json());
  console.log('Run-method result:', run.result.stack);
}

main().catch(console.error);

Tabla de resultados reproducibles para tu endpoint

Para verificar sistemáticamente un endpoint, completa la siguiente tabla con tus observaciones. Usa los métodos descritos anteriormente. La tabla te ayuda a comparar proveedores y detectar inconsistencias. Registra la URL del endpoint, el método llamado, el campo esperado, el valor observado y cualquier nota como latencia o errores.

Para cada método, llámalo al menos dos veces con un breve retraso para ver si los valores avanzan. Para getMasterchainInfo, el seqno debería aumentar. Para getAddressInformation, el saldo puede cambiar si la cuenta está activa. Para runGetMethod, el resultado debería ser consistente para un método determinista.

Este método es reproducible y no se basa en benchmarks fabricados. Es un enfoque verificado por el lector: mides contra tu propio endpoint y registras los resultados.

• Método: getMasterchainInfo | Campo esperado: result.last.seqno | Observado: [rellenar] | Notas: [rellenar]
• Método: getAddressInformation | Campo esperado: result.status | Observado: [rellenar] | Notas: [rellenar]
• Método: runGetMethod | Campo esperado: result.stack | Observado: [rellenar] | Notas: [rellenar]
• Método: getTransactions | Campo esperado: result.length | Observado: [rellenar] | Notas: [rellenar]

Limitaciones y compensaciones de la integración de nodos y API de TON

El protocolo liteserver es binario y específico del proveedor, por lo que la mayoría de los equipos usan un envoltorio HTTP en lugar de hablarlo directamente. Esto añade una dependencia de la disponibilidad y los límites de tasa del envoltorio. La API v2 es heredada y debe evitarse para nuevos trabajos en favor de la v3. La profundidad histórica depende del indexador del endpoint; el historial profundo puede requerir un proveedor con capacidad de archivo, como se analiza en nodo de archivo vs nodo completo.

Se requieren API keys para obtener límites de tasa significativos en endpoints públicos. Sin una clave, puedes encontrar limitación de tasa. El modelo de mensajes asíncronos de TON significa que 'la transacción tuvo éxito' debe derivarse del historial de transacciones en lugar de un recibo síncrono. Esto complica la integración para desarrolladores acostumbrados a los recibos estilo EVM.

Por último, los errores de conversión de direcciones pueden provocar pérdida de fondos o consultas fallidas. Valida siempre las direcciones y usa bibliotecas bien probadas para la conversión. La guía de nodo RPC de Bittensor ofrece una comparación de patrones de integración de nodos en otro ecosistema.

• Liteserver: binario, específico del proveedor, rara vez se integra directamente.
• API v2: heredada, evitar para nuevos proyectos.
• Profundidad histórica: depende del indexador; se necesitan proveedores de archivo para historial profundo.
• API keys: necesarias para límites de tasa más altos.
• Modelo asíncrono: confirmación mediante sondeo, no recibos síncronos.

Solución de problemas comunes de integración de la API de TON

Si getMasterchainInfo devuelve un seqno obsoleto, el endpoint puede estar desincronizado o limitado por tasa. Verifica tu API key y prueba otro endpoint. Si runGetMethod falla, asegúrate de que la dirección esté en el formato correcto y el nombre del método sea correcto. Algunos métodos requieren argumentos; pásalos como un array en el cuerpo de la solicitud.

Si sendBoc devuelve un error, verifica que el BOC esté correctamente codificado en base64 y firmado. El mensaje externo debe tener una firma y un número de secuencia válidos. Si las transacciones no aparecen en getTransactions, es posible que el mensaje aún no se haya procesado; espera y vuelve a sondear. La guía de solución de problemas de nodos cubre problemas del lado del nodo.

Para errores de límite de tasa, reduce la frecuencia de solicitudes o actualiza a un nivel superior. La página de precios de RPC de OnFinality describe los planes disponibles. Maneja siempre las respuestas HTTP 429 con retroceso exponencial.

• Seqno obsoleto: verifica el estado de sincronización y la API key.
• Fallo de run-method: verifica el formato de dirección y el nombre del método.
• Error de sendBoc: verifica la codificación del BOC y la firma.
• Transacciones faltantes: vuelve a sondear después de un retraso.
• Límites de tasa: usa API key y retroceso en 429.

Próximos pasos para la integración de TON

Para avanzar, elige un endpoint TON gestionado de un proveedor que ofrezca soporte de API v3 y suficiente profundidad histórica. La página de endpoints RPC de TON enumera opciones. Si necesitas ejecutar tu propio nodo, sigue la guía de nodo completo y habilita liteserver.

Para el desarrollo de aplicaciones, comienza con la API HTTP v3 y usa los ejemplos ejecutables anteriores para verificar la conectividad. Implementa sondeo para la confirmación de transacciones y maneja flujos de mensajes asíncronos. Explora el centro de aprendizaje de OnFinality para obtener más guías sobre integración de blockchain.

Por último, considera tus necesidades de archivo. Si requieres historial profundo, selecciona un proveedor con capacidad de archivo. El artículo acceso a datos históricos de blockchain explica las compensaciones. Con estos pasos, puedes integrar TON en tu aplicación de forma fiable.

• Elige un endpoint gestionado con API v3 y soporte de API key.
• Ejecuta tu propio nodo si necesitas acceso directo al liteserver.
• Implementa sondeo para la confirmación asíncrona.
• Selecciona un proveedor de archivo para historial profundo.
• Consulta OnFinality Learn para más guías de integración.