NEAR Scan: Lectura de datos on-chain de NEAR con exploradores, RPC y verificación de contratos

Qué lee realmente un NEAR scan

La frase "NEAR scan" describe la lectura de datos de la red NEAR Protocol: bloques, chunks, transacciones, receipts, saldos de cuentas, claves de acceso y estado de contratos. Un explorador de bloques es una interfaz de usuario sobre esos datos. Por debajo, los exploradores e indexadores llaman a endpoints JSON-RPC de NEAR, a menudo complementados con sus propias bases de datos para agregación histórica y búsqueda.

Esto importa porque la vista de un explorador es una decisión de producto, no el protocolo. Si una transacción falta en un explorador, la transacción aún puede ser final on-chain. Si un saldo parece diferente entre dos herramientas, una puede estar mostrando el saldo líquido mientras que la otra incluye cantidades en staking o bloqueadas. Un flujo de escaneo confiable comienza desde la respuesta RPC y trata al explorador como una capa de presentación.

Alcance: este artículo cubre el escaneo de solo lectura de datos de mainnet y testnet de NEAR, los conceptos de verificación de código fuente de contratos y los procedimientos de diagnóstico. No cubre trading, análisis de precios de tokens ni custodia de wallets.

• Explorador: búsqueda y visualización orientadas a humanos.
• RPC: acceso orientado a máquinas al estado canónico del nodo.
• Indexador: una base de datos construida a partir de RPC o datos en streaming para consultas históricas rápidas.
• Verificación de contratos: comparar el Wasm desplegado con el código fuente compilado desde un repositorio.

Requisitos previos y supuestos

Necesitas una URL de endpoint RPC de NEAR, a la que este artículo se refiere como RPC_URL. Puedes usar un endpoint público para pruebas ligeras, pero los endpoints públicos tienen límites de tasa y pueden retrasarse. Para escaneos repetidos o indexadores en producción, usa un endpoint gestionado o dedicado; consulta la guía de endpoints RPC multi-chain y los precios de RPC para saber cómo se aprovisiona la capacidad.

También necesitas curl o un entorno de scripting como Node.js o Python. Los ejemplos usan JSON-RPC 2.0 sobre HTTPS con el nombre del método en el cuerpo. Los métodos RPC de NEAR están documentados en la referencia de la API de NEAR; los nombres de métodos y las formas de los parámetros a continuación siguen esa interfaz documentada.

Supuesto: estás escaneando datos públicos de la cadena. No envíes claves privadas a un endpoint RPC. Los métodos de lectura no requieren firma.

El modelo mental: bloques, chunks, transacciones y receipts

NEAR produce bloques. Cada bloque contiene uno o más chunks, y cada chunk pertenece a un shard. Una transacción se incluye en un chunk, pero sus efectos son transportados por receipts, que pueden ejecutarse en bloques posteriores y en shards diferentes. Por eso una transacción puede mostrar un estado final mientras sus receipts aún se están procesando, y por eso un escaneo que solo mira el bloque de la propia transacción puede pasar por alto efectos posteriores.

El estado de la cuenta se almacena por shard. Una cuenta tiene un saldo, una cantidad bloqueada, uso de almacenamiento, hash de código y claves de acceso. El estado del contrato es un almacén clave-valor al que se accede mediante llamadas de vista o consultas de estado. Cuando escaneas una cuenta, decide cuál de estos necesitas; un único número de "saldo" rara vez cuenta toda la historia.

Finalidad: NEAR tiene referencias de bloque optimista y final. Para informes irreversibles, consulta con un parámetro de finalidad en lugar de una altura de bloque específica, o espera hasta que el bloque sea final. Los exploradores suelen etiquetar esto, pero las respuestas RPC sin procesar requieren que lo solicites.

• Bloque: contenedor con una cabecera y cabeceras de chunks.
• Chunk: porción de un bloque específica de un shard.
• Transacción: solicitud firmada incluida en un chunk.
• Receipt: efecto entre contratos o entre shards generado por la ejecución.
• Outcome: resultado de ejecución adjunto a una transacción o receipt.

Escaneo ejecutable: consultas de bloque, transacción y cuenta por RPC

Las siguientes llamadas curl usan marcadores de posición. Reemplaza RPC_URL con tu endpoint. La consulta de bloque solicita el último bloque final. La consulta de transacción usa un hash de transacción y la cuenta remitente, porque el método de estado de transacción de NEAR requiere ambos. La consulta de cuenta devuelve campos de saldo y almacenamiento.

Ejecútalas en orden y compara la altura de bloque en la respuesta de la transacción con la altura de bloque que obtuviste. Si la transacción es más reciente que tu consulta de bloque, vuelve a consultar con finalidad.

curl -s -X POST "$RPC_URL" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"block","method":"block","params":{"finality":"final"}}'

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

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

Resultado de verificación esperado y cómo interpretarlo

Una respuesta de bloque exitosa contiene un resultado con una cabecera y chunks. La cabecera incluye altura, hash y timestamp. Una respuesta de transacción exitosa contiene un estado de ejecución final y uno o más receipts de resultado. Una consulta de cuenta exitosa contiene amount, locked, code_hash, storage_usage y storage_paid_at.

Lista de verificación: la altura del bloque incluido en la transacción debe ser menor o igual que la altura del bloque final que obtuviste. El estado de ejecución final de la transacción debe ser SuccessValue o SuccessReceiptId para una llamada completada. Si es Failure, la respuesta incluye un objeto de error; léelo antes de asumir que el escaneo está roto.

Para una tabla de resultados, registra una fila por consulta con columnas: tipo de consulta, ID de solicitud, altura de bloque, finalidad, estado y latencia medida por tu cliente. No copies números de latencia de otro entorno; mide desde la máquina y la ruta de red que realmente usarás.

• La altura de bloque aumenta monotónicamente; una altura menor después de una mayor indica un endpoint retrasado.
• El estado de transacción FINAL significa que la transacción es irreversible bajo la finalidad solicitada.
• El code_hash de la cuenta cambia cuando se despliega o actualiza un contrato; úsalo para detectar actualizaciones.

Escaneo programado con JavaScript y Python

Para escaneos repetidos, envuelve la llamada RPC en una función con reintentos y finalidad explícita. El ejemplo de JavaScript usa fetch y un pequeño bucle de reintentos. El ejemplo de Python usa urllib e imprime un resumen compacto. Ambos usan los marcadores de posición RPC_URL y ACCOUNT_ID.

Mantén el ID de solicitud único por llamada para que los registros puedan correlacionarse. Trata las respuestas HTTP 429 y 5xx como reintentables con backoff; trata los errores JSON-RPC con un código y mensaje como errores de aplicación que necesitan inspección.

// scan.mjs
const RPC_URL = process.env.RPC_URL;
const ACCOUNT_ID = process.env.ACCOUNT_ID || 'ACCOUNT.near';

async function rpc(method, params, id) {
  const res = await fetch(RPC_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id, method, params })
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const json = await res.json();
  if (json.error) throw new Error(`${json.error.code}: ${json.error.message}`);
  return json.result;
}

const block = await rpc('block', { finality: 'final' }, 'b1');
const acct = await rpc('query', {
  request_type: 'view_account', finality: 'final', account_id: ACCOUNT_ID
}, 'a1');
console.log({ height: block.header.height, account: ACCOUNT_ID, amount: acct.amount, code_hash: acct.code_hash });

# scan.py
import json, os, urllib.request
RPC_URL = os.environ['RPC_URL']
ACCOUNT_ID = os.environ.get('ACCOUNT_ID', 'ACCOUNT.near')

def rpc(method, params, req_id):
    body = json.dumps({'jsonrpc': '2.0', 'id': req_id, 'method': method, 'params': params}).encode()
    req = urllib.request.Request(RPC_URL, data=body, headers={'Content-Type': 'application/json'})
    with urllib.request.urlopen(req, timeout=15) as resp:
        data = json.load(resp)
    if 'error' in data:
        raise RuntimeError(data['error'])
    return data['result']

block = rpc('block', {'finality': 'final'}, 'b1')
acct = rpc('query', {'request_type': 'view_account', 'finality': 'final', 'account_id': ACCOUNT_ID}, 'a1')
print({'height': block['header']['height'], 'account': ACCOUNT_ID, 'amount': acct['amount'], 'code_hash': acct['code_hash']})

Verificación de contratos: comparar el código fuente con el Wasm desplegado

La verificación de contratos responde a una pregunta diferente a la del escaneo de transacciones: ¿el código fuente de un repositorio compila al Wasm actualmente desplegado en una cuenta? Los exploradores que ofrecen una función de verificación de contratos suelen compilar el código fuente enviado en un entorno controlado y comparar el hash del Wasm resultante o el bytecode con el hash del código on-chain.

Puedes reproducir la comprobación central sin un explorador. Obtén el code_hash de la cuenta y el código del contrato vía RPC, luego compila el repositorio localmente con la misma cadena de herramientas y flags de compilación que documenta el proyecto. Compara los hashes. Una discrepancia puede provenir de una versión del compilador diferente, flags de características diferentes o una revisión del código fuente diferente, no necesariamente de código malicioso.

Comportamiento documentado: las cuentas de NEAR exponen un campo code_hash, y el código del contrato se puede recuperar mediante RPC. La receta exacta de compilación es específica de cada proyecto; no asumas que una compilación genérica reproduce un artefacto desplegado.

• Fija las versiones del compilador y de las herramientas de compilación en el repositorio.
• Registra el commit del código fuente y el comando de compilación junto al hash del código desplegado.
• Compara hashes, no tamaños de archivo, como señal principal.
• Trata una discrepancia primero como un problema de reproducibilidad y después como un problema de seguridad.

Solución de problemas comunes de NEAR scan

La mayoría de las discrepancias en el escaneo caen en unas pocas categorías: finalidad, sharding, retraso de indexación y elecciones de presentación. Revísalas en ese orden antes de asumir una pérdida de datos.

Si no se encuentra una transacción, confirma el hash y la cuenta remitente. El método de estado de transacción de NEAR requiere el remitente, y un hash por sí solo es insuficiente. Si la transacción es muy reciente, consulta con wait_until establecido en FINAL o reintenta después de un breve retraso.

Si los saldos difieren entre herramientas, verifica si la herramienta muestra la cantidad líquida, la cantidad bloqueada o ambas, y si incluye costos de almacenamiento. Si una llamada a contrato devuelve un estado inesperado, confirma la altura de bloque o la finalidad usada para la llamada de vista; una vista en un bloque anterior puede diferir legítimamente del estado actual.

Si un endpoint devuelve errores de límite de tasa o tiempo de espera, reduce la concurrencia y añade backoff. Para escaneos sostenidos, pasa a un endpoint dedicado; consulta nodo dedicado y la guía de alojamiento de nodos blockchain.

• Transacción faltante: verifica hash más remitente, luego reintenta con finalidad.
• Altura retrasada: compara dos endpoints y prefiere el más cercano a final.
• Resultado de vista inesperado: fija explícitamente la altura de bloque o la finalidad.
• 429 frecuente: reduce la tasa de solicitudes o usa un endpoint gestionado.

Limitaciones y compensaciones del escaneo basado en exploradores

Los exploradores están optimizados para la búsqueda humana, no para la extracción masiva. Pueden paginar, ocultar receipts internos o agregar transferencias de tokens de formas que son convenientes pero no canónicas. Sus bases de datos históricas pueden retrasarse respecto a la punta de la cadena, y sus índices de búsqueda pueden no cubrir todas las cuentas o métodos de contrato.

El RPC directo es canónico pero no es una base de datos. Responde bien a consultas puntuales; no proporciona búsqueda eficiente de historial completo en todas las cuentas. Para analítica, combina RPC con un indexador que controles o cuyo modelo de datos entiendas. Para comprobaciones puntuales, un explorador suele ser más rápido.

Las compensaciones de costo y fiabilidad importan a escala. Los endpoints públicos son gratuitos pero compartidos; los endpoints gestionados cuestan dinero pero proporcionan capacidad predecible. Mide tu propia latencia y tasa de errores en lugar de confiar en afirmaciones publicadas.

Próximos pasos para flujos de trabajo fiables con datos de NEAR

Empieza estandarizando la finalidad en cada consulta, luego añade reintentos e IDs de solicitud. Crea un pequeño script de escaneo que registre la altura de bloque, el hash de código de la cuenta y el estado de la transacción para las cuentas que te interesan. Ejecútalo de forma programada y almacena los resultados para poder detectar cambios a lo largo del tiempo.

Cuando necesites rendimiento de producción, elige un endpoint a través del servicio API de OnFinality y revisa las redes soportadas. Para orientación sobre selección de endpoints en lugar de detalles de implementación, RPC Assistant cubre recomendaciones concretas de proveedores y redes; consulta la guía de endpoints RPC para el marco general.

Por último, documenta tu receta de verificación: versión del compilador, comando de compilación, commit del código fuente y hash de código esperado. Ese registro es lo que hace que un NEAR scan sea reproducible meses después.