NEAR Explorer: Cómo leer, verificar y consultar datos de la blockchain de NEAR

Qué muestra realmente un explorador de NEAR

Un explorador de NEAR es una interfaz sobre datos indexados de NEAR. Presenta bloques, transacciones, resultados de ejecución, recibos, saldos de cuentas, claves de acceso y llamadas a contratos en un formato legible para humanos. Los exploradores públicos como el NEAR Explorer Selector, NearBlocks y vistas especializadas como el explorador de NEAR Intents indexan y presentan diferentes porciones de la cadena, por lo que una misma transacción puede verse diferente según la vista que abras.

La distinción importante es entre el explorador como capa de presentación y el RPC de NEAR como fuente de verdad. Los exploradores suelen ejecutar sus propios indexadores, que pueden retrasarse respecto a la cabeza de la cadena durante segundos o minutos, pueden eliminar detalles históricos o pueden etiquetar datos mediante heurísticas. Cuando la precisión importa, confirma la vista del explorador con una llamada RPC directa. Para la selección de endpoints, el RPC Assistant cubre opciones concretas de proveedores; este artículo se centra en el método.

• Los exploradores de bloques muestran la altura del bloque, la marca de tiempo y el productor.
• Las vistas de transacciones muestran la transacción firmada y su resultado.
• Las vistas de recibos muestran la ejecución entre contratos, que es donde NEAR difiere de las cadenas con modelo de cuentas.
• Las vistas de cuentas muestran el saldo, el uso de almacenamiento, el hash del código y las claves de acceso.

Supuestos y requisitos previos

Los procedimientos a continuación asumen que tienes una URL de endpoint RPC de NEAR, que debes tratar como secreta si contiene una clave API. Necesitas curl o un entorno de ejecución de JavaScript con fetch, y opcionalmente Python para scripting. No se requiere ninguna clave privada para consultas de solo lectura; la firma solo es necesaria cuando envías transacciones, lo cual está fuera del alcance de este artículo.

Establece una variable de entorno para que los ejemplos sean portables. Nunca confirmes un endpoint con clave en un repositorio. Si estás eligiendo un proveedor, comienza desde la página de la red NEAR de OnFinality y la guía de endpoints RPC, luego usa el RPC Assistant para obtener una recomendación directa.

export RPC_URL="https://your-near-rpc-endpoint"
# Optional: confirm the endpoint responds
echo $RPC_URL

El modelo de ejecución de NEAR en un solo modelo mental

En NEAR, una transacción no es lo mismo que una ejecución. Una transacción firmada se incluye en un bloque, produciendo un resultado que contiene uno o más recibos. Los recibos son las unidades de trabajo entre contratos: una llamada a función puede generar recibos que se ejecutan en bloques posteriores. Por eso un explorador puede mostrar una transacción como final mientras un recibo aún está pendiente, y por eso un resultado de transacción exitoso no garantiza que todos los recibos posteriores hayan tenido éxito.

Cuando leas un explorador, sigue la cadena: hash de transacción, luego resultado, luego cada ID de recibo, luego cada resultado de recibo. Cuando consultes RPC, usa la misma secuencia. Tratar la transacción como la historia completa es la fuente más común de confusión en la resolución de problemas de NEAR.

• Transacción: la solicitud firmada enviada por un usuario o servicio.
• Resultado de ejecución: el resultado de aplicar esa transacción en un bloque.
• Recibo: una unidad de trabajo, a menudo una llamada entre contratos.
• Resultado de recibo: éxito o fracaso de esa unidad, con registros y gas consumido.

Verificar una transacción con curl

El RPC de NEAR expone métodos JSON-RPC que reflejan lo que muestran los exploradores. Para inspeccionar una transacción, llama a tx con el hash de la transacción y la cuenta que la firmó. Reemplaza los marcadores de posición con valores de la URL del explorador o de tus propios registros.

La respuesta incluye la transacción, su resultado de ejecución y cualquier recibo. Lee status.SuccessValue para el resultado de nivel superior, luego inspecciona receipts_outcome para el trabajo posterior. Un objeto Failure no vacío indica un error de ejecución, y los registros suelen contener la razón a nivel de contrato.

curl -s -X POST "$RPC_URL" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "near-explorer-guide",
    "method": "tx",
    "params": {
      "tx_hash": "TRANSACTION_HASH",
      "sender_account_id": "SENDER_ACCOUNT.near",
      "wait_until": "FINAL"
    }
  }' | python3 -m json.tool

Reproducir una vista de explorador en JavaScript

Un pequeño script hace que la verificación sea repetible. La función a continuación obtiene una transacción, imprime el estado de nivel superior y lista los resultados de recibos con su estado y gas consumido. Estos son los mismos datos que renderiza un explorador, menos las etiquetas y el formato del indexador.

Ejecútalo con Node 18 o posterior, que incluye fetch. Mantén el endpoint en una variable de entorno y registra solo campos no sensibles si pegas la salida en un ticket.

const RPC_URL = process.env.RPC_URL;

async function inspectTx(txHash, sender) {
  const res = await fetch(RPC_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 'near-explorer-guide',
      method: 'tx',
      params: { tx_hash: txHash, sender_account_id: sender, wait_until: 'FINAL' }
    })
  });
  const { result, error } = await res.json();
  if (error) throw new Error(JSON.stringify(error));

  const outcome = result.status;
  console.log('top-level:', outcome.SuccessValue !== undefined ? 'success' : 'failure');
  for (const r of result.receipts_outcome || []) {
    const s = r.outcome.status;
    console.log(r.id, s.SuccessValue !== undefined ? 'ok' : 'failed', 'gas:', r.outcome.gas_burnt);
  }
}

inspectTx('TRANSACTION_HASH', 'SENDER_ACCOUNT.near').catch(console.error);

Consultar bloques, cuentas y estado de contratos

Los exploradores también muestran datos a nivel de bloque y de cuenta. El método block devuelve el encabezado del bloque y los fragmentos; el método view_account devuelve el saldo y el uso de almacenamiento; view_state devuelve las claves del estado del contrato. Estas llamadas son de solo lectura y seguras de ejecutar contra un endpoint de producción, sujetas a límites de tasa.

Para el estado de un contrato, prefiere view_state con un prefijo o usa una llamada de vista que devuelva exactamente el campo que necesitas. Volcar el estado completo de un contrato grande puede ser lento y puede alcanzar los límites de tamaño de respuesta. Si necesitas estado histórico, ten en cuenta que el RPC de NEAR generalmente sirve el estado actual; las consultas históricas requieren un indexador o un servicio de archivo.

curl -s -X POST "$RPC_URL" -H 'Content-Type: application/json' -d '{
  "jsonrpc":"2.0","id":"block","method":"block",
  "params":{"finality":"final"}
}' | python3 -c "import sys,json; b=json.load(sys.stdin)['result']; print(b['header']['height'], b['header']['hash'])"

curl -s -X POST "$RPC_URL" -H 'Content-Type: application/json' -d '{
  "jsonrpc":"2.0","id":"acct","method":"view_account",
  "params":{"finality":"final","account_id":"ACCOUNT.near"}
}' | python3 -m json.tool

Un procedimiento de tabla de resultados para comparar explorador y RPC

Cuando la vista de un explorador y tu aplicación no coinciden, crea una pequeña tabla de comparación en lugar de discutir con capturas de pantalla. Para cada transacción bajo investigación, registra los campos a continuación de ambas fuentes y anota la marca de tiempo de cada observación. No rellenes números que no hayas observado; la tabla es un registro de medición, no una estimación.

Una discrepancia en la altura del último bloque generalmente indica retraso del indexador. Una discrepancia en el número o estado de los recibos es más grave y debe resolverse confiando en la respuesta RPC, luego verificando si el indexador del explorador se ha puesto al día. Registra la altura del bloque en el momento de la consulta para que la comparación sea reproducible.

Solución de problemas comunes de discrepancias en exploradores

La mayoría de las discrepancias se dividen en unas pocas categorías. Los errores de transacción desconocida a menudo significan que la transacción aún no se ha incluido, que el hash está truncado o que la cuenta remitente es incorrecta. Una transacción que muestra éxito mientras un usuario reporta un fallo generalmente significa que un recibo posterior falló. Las diferencias de saldo pueden provenir de staking, costos de almacenamiento o recibos pendientes.

Si un explorador muestra una llamada a contrato como exitosa pero tu aplicación ve un error, verifica si tu aplicación está leyendo el resultado de la transacción o el resultado del recibo. Si consultas por ID de recibo, confirma que estás usando el ID del recibo y la cuenta que produjo el recibo, no el firmante original.

• Transacción desconocida: espera la finalidad, luego vuelve a consultar con el hash y el remitente exactos.
• Éxito con fallo visible para el usuario: inspecciona receipts_outcome para objetos Failure y registros.
• Discrepancia de saldo: ten en cuenta el uso de almacenamiento, los bloqueos de staking y los recibos en vuelo.
• Historial faltante: el endpoint puede estar podado; usa un indexador o archivo para datos antiguos.
• Límites de tasa: agrupa o cachea lecturas en lugar de sondear cada bloque.

Limitaciones y compensaciones de los flujos de trabajo centrados en el explorador

Los exploradores son excelentes para la investigación humana y deficientes como sistema de registro. Introducen un indexador entre tú y la cadena, lo que agrega latencia y una segunda implementación que puede discrepar del RPC. También aplican etiquetas y heurísticas que son convenientes para navegar pero inadecuadas para decisiones automatizadas.

Para sistemas de producción, trata el explorador como una ayuda de depuración y el RPC como la interfaz. Si necesitas consultas históricas, análisis agregados o lecturas de baja latencia a escala, considera un nodo dedicado o una canalización de indexación en lugar de extraer datos de páginas de exploradores. Las páginas de oferta de nodos dedicados y servicio API de OnFinality describen las opciones de infraestructura; los precios de RPC se documentan por separado.

• Los datos del explorador pueden retrasarse respecto a la cabeza de la cadena.
• El estado histórico generalmente no está disponible en el RPC estándar.
• Las etiquetas y marcas son heurísticas, no autoritativas.
• Extraer HTML de exploradores es frágil; usa JSON-RPC en su lugar.

Próximos pasos: de la navegación al acceso programático

Una vez que puedas reproducir una vista de explorador con llamadas RPC, el siguiente paso es decidir si necesitas un endpoint gestionado o tu propio nodo. Para aplicaciones con muchas lecturas, un endpoint RPC gestionado confiable con límites de tasa claros suele ser suficiente. Para indexación, consultas de archivo o retención personalizada, un nodo dedicado te da control sobre la poda y el rendimiento.

Revisa la descripción general de la red NEAR, compara los precios de RPC y usa el RPC Assistant para obtener una recomendación concreta de endpoint. Luego adapta los scripts anteriores a tu monitoreo: alerta sobre recibos fallidos, rastrea el retraso del indexador comparando las alturas de los últimos bloques y mantén una tabla de comparación para incidentes.

• Lee la guía de la red NEAR de OnFinality: /en/networks
• Compara opciones de RPC gestionado: /en/api-service
• Revisa los precios de RPC: /en/pricing/rpc
• Explora nodos dedicados: /en/dedicated-node
• Guía general de endpoints: /en/learn/rpc-endpoints-guide