API JSON-RPC de NEAR Protocol y configuración de nodo

La arquitectura fragmentada de NEAR y su superficie JSON-RPC

NEAR Protocol es una blockchain Layer 1 fragmentada y basada en cuentas que utiliza un modelo de producción de bloques fragmentado al estilo Nightshade. A diferencia de las cadenas EVM, donde se accede a un único trie de estado mediante métodos eth_*, el estado de NEAR está particionado en shards, y su API JSON-RPC lo refleja con métodos como status, block, chunk, gas_price, tx, query y validators. Esto significa que las herramientas y librerías EVM existentes no pueden usarse directamente; los desarrolladores deben adaptarse a los nombres de métodos y estructuras de datos de NEAR.

La especificación JSON-RPC 2.0 define el sobre de solicitud/respuesta, mientras que la documentación de la API de NEAR detalla la semántica de los métodos. La API es servida por nodos near-core y proveedores gestionados, con servicios de indexación como NEAR Indexer Framework y NEAR Lake que proporcionan consultas históricas y agregadas. Un nodo normal sirve eficientemente datos recientes, pero las consultas históricas pueden requerir un nodo de archivo.

• NEAR usa estado fragmentado, por lo que algunas consultas se resuelven contra un shard o chunk específico.
• Los nombres de métodos son específicos de NEAR: status, block, chunk, gas_price, tx, query, validators.
• Las herramientas EVM no aplican directamente; se requieren SDKs y librerías de NEAR.

Capas de acceso a datos: nodo, proveedor e indexador

Hay tres formas principales de acceder a los datos de NEAR: (1) un nodo near-core autoalojado que sirve la API JSON-RPC, (2) un proveedor gestionado que ofrece la misma API, y (3) servicios de indexación/archivo para consultas históricas y agregadas. Cada una tiene ventajas y desventajas. Un nodo autoalojado te da control total y localidad de datos, pero requiere recursos y mantenimiento significativos. Los proveedores gestionados ofrecen comodidad y fiabilidad, pero pueden tener límites de tasa o costos. Los servicios de indexación son esenciales para consultar datos históricos más allá de la ventana de retención del nodo.

Para la mayoría de los desarrolladores, un proveedor gestionado es suficiente para datos recientes, pero si necesitas consultar bloques antiguos o ejecutar analíticas, se requiere un nodo de archivo o un indexador. La documentación de NEAR proporciona una introducción a la API JSON-RPC y sus endpoints.

• Nodo autoalojado: control total, requiere toolchain de Rust, CPU/RAM/disco y tiempo de sincronización.
• Proveedor gestionado: comodidad, pero verifica límites de tasa y retención de datos.
• Indexador/archivo: para consultas históricas, agregados y analíticas.

Métodos JSON-RPC clave y sus retornos

El método status devuelve la identidad del nodo, el ID de cadena, el estado de sincronización y la última altura/hash de bloque. block y chunk devuelven datos de bloque y chunk por altura o hash, con opciones de finalidad. gas_price proporciona estimación de tarifas. tx devuelve el estado de la transacción y los recibos. query se usa para el estado de cuentas y llamadas de vista a contratos mediante la ruta de solo lectura. validators devuelve el conjunto actual de validadores.

El método query es particularmente importante para leer saldos de cuentas y el estado de contratos. Según la documentación de NEAR sobre el método query, admite consultas de estado de cuentas y contratos. Comprender estos métodos es crucial para construir aplicaciones fiables.

• status: identidad del nodo, ID de cadena, estado de sincronización, última altura/hash de bloque.
• block/chunk: datos de bloque y chunk por altura/hash, con finalidad.
• gas_price: estimación de tarifas.
• tx: estado de la transacción y recibos.
• query: estado de cuentas y llamadas de vista a contratos.
• validators: conjunto actual de validadores.

# Status: node identity, chain id and sync state
curl -s -X POST https://rpc.mainnet.near.org \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"status","params":[]}' | jq '.result.chain_id, .result.sync_info.latest_block_height'

# Block by finality: pass "final" or "optimistic" to choose the confirmation level
curl -s -X POST https://rpc.mainnet.near.org \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"block","params":{"finality":"final"}}' | jq '.result.header.height, .result.header.hash'

# query: read account state or call a view method (read-only, no gas)
curl -s -X POST https://rpc.mainnet.near.org \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"query","params":{"request_type":"view_account","finality":"final","account_id":"near"}}' | jq '.result.amount, .result.block_height'

Finalidad: optimista vs final y su impacto

NEAR distingue entre finalidad optimista y final. Cuando consultas un bloque o una transacción, debes especificar qué finalidad deseas. La finalidad optimista significa que el bloque probablemente será finalizado pero aún no está garantizado; la finalidad final significa que el bloque es irreversible. Esto afecta la confirmación de pagos: para transacciones de alto valor, debes esperar la finalidad final. La documentación de finalidad de NEAR lo explica en detalle.

Elegir la finalidad incorrecta puede llevar a suposiciones erróneas sobre el éxito de una transacción. Por ejemplo, consultar una transacción con finalidad optimista podría mostrarla como exitosa, pero aún podría revertirse. Usa siempre finalidad final para operaciones críticas.

• Finalidad optimista: el bloque probablemente es final pero no está garantizado.
• Finalidad final: el bloque es irreversible.
• Usa finalidad final para confirmación de pagos y cambios de estado críticos.

Ejecutar un nodo NEAR para servir la API JSON-RPC

Para ejecutar un nodo NEAR, necesitas compilar near-core desde el código fuente, lo que requiere un toolchain de Rust y recursos no triviales de CPU, RAM y disco. El nodo puede sincronizarse desde génesis o desde una snapshot de datos documentada. Una vez sincronizado, expone el endpoint JSON-RPC en un puerto configurado (por defecto 3030).

El proceso implica clonar el repositorio nearcore, compilar con cargo y configurar el nodo. Las instrucciones detalladas están disponibles en la documentación de NEAR. Para desarrolladores familiarizados con otros protocolos, la configuración es similar a ejecutar un nodo completo en otras redes, como requisitos de nodo completo de Aptos y configuración RPC o integración de nodo TON y API RPC.

• Requiere toolchain de Rust y recursos de hardware significativos.
• Sincronización desde génesis o una snapshot (la snapshot cambia confianza por velocidad).
• El puerto JSON-RPC por defecto es 3030.

Verificar un endpoint JSON-RPC de NEAR

Para verificar que un endpoint JSON-RPC de NEAR está activo y es honesto, comienza llamando a status y confirmando el chain_id reportado y la última altura de bloque. Luego llama a block en la altura reportada y confirma que el hash coincide. Finalmente, llama a query para una cuenta conocida para confirmar que las lecturas de estado funcionan. Esto detecta un endpoint que está activo pero obsoleto.

Puedes usar curl o un script de Node.js para realizar estas comprobaciones. A continuación se muestra un ejemplo ejecutable de Node.js que envía los métodos status, block y query e imprime la altura de bloque y el saldo de cuenta devueltos.

const fetch = require('node-fetch');

async function checkEndpoint(url) {
  const statusRes = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'status', params: [] })
  });
  const status = await statusRes.json();
  console.log('Chain ID:', status.result.chain_id);
  console.log('Latest block height:', status.result.sync_info.latest_block_height);

  const blockRes = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'block', params: { finality: 'final' } })
  });
  const block = await blockRes.json();
  console.log('Block hash:', block.result.header.hash);

  const queryRes = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 3, method: 'query', params: { request_type: 'view_account', finality: 'final', account_id: 'example.near' } })
  });
  const query = await queryRes.json();
  console.log('Account balance:', query.result.amount);
}

checkEndpoint('https://rpc.mainnet.near.org');

Verificación reproducible de endpoints con una tabla de resultados

Para que la verificación sea reproducible, registra las siguientes métricas para tu endpoint: chain_id reportado, última altura en T0 y T1, finalidad usada y latencia de consulta. Completa la tabla a continuación con tus propias mediciones. Este método no se basa en números inventados y te permite comparar endpoints objetivamente.

• Chain ID: [tu valor]
• Última altura en T0: [tu valor]
• Última altura en T1: [tu valor]
• Finalidad usada: [optimista/final]
• Latencia de consulta (ms): [tu valor]

Fallos comunes y solución de problemas

Al trabajar con NEAR JSON-RPC, puedes encontrar errores como UNKNOWN_BLOCK o 'does not exist while viewing' cuando un bloque aún no está finalizado. Las llamadas a gas_price pueden fallar en un nodo que no está completamente sincronizado. Las consultas de archivo o heredadas pueden fallar en un nodo no archivístico. Estos problemas a menudo provienen de elecciones de finalidad o del estado de sincronización del nodo.

Para solucionar problemas, asegúrate de usar el parámetro de finalidad correcto, verifica que tu nodo esté completamente sincronizado y confirma que estás consultando un nodo archivístico para datos históricos. Para solución de problemas generales de JSON-RPC, consulta JSON-RPC vs gRPC vs REST.

• UNKNOWN_BLOCK: el bloque aún no está finalizado; usa finalidad final o espera.
• 'does not exist while viewing': el estado de la cuenta o contrato no está disponible en ese bloque.
• Fallo de gas_price: el nodo no está completamente sincronizado.
• Fallo de consulta de archivo: el nodo no es archivístico.

Ventajas y limitaciones de los nodos autoalojados

Ejecutar un nodo NEAR autoalojado implica ventajas y desventajas. El estado fragmentado significa que algunas consultas se resuelven contra un shard o chunk específico, lo que puede complicar la agregación de datos. La sincronización basada en snapshot cambia confianza por velocidad, ya que dependes del proveedor de la snapshot. Un nodo autoalojado se justifica solo cuando el volumen de consultas o la localidad de datos superan a un endpoint gestionado.

Para muchos desarrolladores, un proveedor gestionado es más rentable y fiable. Sin embargo, si necesitas control total, indexación personalizada o acceso de baja latencia a shards específicos, un nodo autoalojado puede ser necesario. Considera tu caso de uso cuidadosamente antes de comprometerte con la operación de un nodo.

• Estado fragmentado: las consultas pueden necesitar apuntar a shards específicos.
• Sincronización por snapshot: más rápida pero requiere confiar en el proveedor de la snapshot.
• Autoalojamiento: justificado para alto volumen de consultas o localidad de datos.

Próximos pasos y recursos adicionales

Para seguir aprendiendo sobre NEAR y otros protocolos, explora el centro de aprendizaje de OnFinality. Para detalles de precios y servicio de API, consulta precios de RPC y servicio de API. Si te interesan otras redes, revisa la guía de la red Polkadot y Substrate state_getMetadata y versiones de runtime.

Para desarrollo específico de NEAR, consulta la documentación oficial de NEAR y considera usar un proveedor gestionado para cargas de trabajo en producción. El autoalojamiento es una opción para usuarios avanzados con requisitos específicos.

• Explora OnFinality Learn para más guías de protocolos.
• Revisa las páginas de precios de RPC y servicio de API para opciones gestionadas.
• Consulta guías hermanas para otras redes.