Lectura del estado de HyperEVM mediante JSON-RPC: métodos EVM y puente HyperCore

La arquitectura de dos sistemas de Hyperliquid

Hyperliquid no es una única blockchain monolítica. Ejecuta dos interfaces distintas que cumplen propósitos diferentes. HyperCore es el motor nativo de libro de órdenes y perpetuos, que expone sus propias APIs REST y WebSocket Info y Exchange para datos de mercado, estado de cuentas y gestión de órdenes. HyperEVM es una cadena separada compatible con Ethereum que aloja contratos inteligentes EVM y expone el espacio de nombres JSON-RPC estándar eth_. Esta separación está documentada en la documentación de Hyperliquid HyperEVM.

Para los desarrolladores, la pregunta crítica es: ¿qué sistema contiene los datos que necesito? Los precios de mercado, los libros de órdenes, los saldos de cuentas en el motor de perpetuos y el historial de órdenes residen en HyperCore. El estado de los contratos inteligentes, los saldos de tokens EVM y los eventos de contratos residen en HyperEVM. A menudo es necesario hacer referencia cruzada a ambos sistemas para obtener una imagen completa. La guía Latencia RPC de Hyperliquid: HyperEVM vs API nativa cubre la selección de endpoints a alto nivel, mientras que este artículo se centra en la superficie de lectura EVM.

• HyperCore: motor nativo de libro de órdenes y perpetuos; APIs Info y Exchange; estado de mercado y cuentas.
• HyperEVM: cadena compatible con Ethereum; métodos JSON-RPC estándar eth_; estado de contratos inteligentes y saldos EVM.
• La ubicación de los datos determina qué interfaz consultar; confundirlas produce resultados vacíos o incorrectos.

Identidad de cadena y verificación en tiempo de ejecución de HyperEVM

HyperEVM mainnet usa el chain ID 999, como se publica en ChainList y en la documentación de Hyperliquid. Sin embargo, los chain IDs pueden falsificarse o configurarse mal en endpoints personalizados. Verifica siempre el chain ID en tiempo de ejecución usando eth_chainId antes de enviar cualquier solicitud de lectura o de cambio de estado. El método eth_chainId devuelve el chain ID como una cadena hexadecimal, mientras que net_version lo devuelve como una cadena decimal. Ambos forman parte de la especificación estándar JSON-RPC de Ethereum, documentada en ethereum.org.

Una discrepancia entre el chain ID esperado y el valor devuelto indica que estás conectado a la red incorrecta o a un endpoint mal configurado. Esta comprobación es especialmente importante cuando se utilizan proveedores RPC de terceros, donde el comportamiento del endpoint está documentado pero varía según el proveedor. Para obtener una lista de endpoints RPC de Hyperliquid, consulta la página Endpoints RPC de Hyperliquid (RPC Assistant).

• eth_chainId devuelve el chain ID como cadena hexadecimal (0x3e7 para 999).
• net_version devuelve el chain ID como cadena decimal ("999").
• Verifica siempre el chain ID antes de leer el estado para evitar consultar la red incorrecta.

Métodos de lectura EVM estándar en HyperEVM

HyperEVM expone los mismos métodos del espacio de nombres eth_ que cualquier cadena compatible con Ethereum. Los métodos de solo lectura más relevantes para la inspección de estado son eth_blockNumber, eth_getBalance, eth_call, eth_getCode, eth_getStorageAt, eth_getLogs, eth_getTransactionReceipt y eth_getTransactionByHash. Estos métodos se comportan de forma idéntica a sus equivalentes en Ethereum, según lo definido en la especificación JSON-RPC de Ethereum.

eth_blockNumber devuelve el número del último bloque. eth_getBalance devuelve el saldo del token nativo de una dirección. eth_call ejecuta una función de contrato de solo lectura sin crear una transacción. eth_getCode devuelve el bytecode en la dirección de un contrato, lo cual es útil para verificar que un contrato está desplegado. eth_getStorageAt lee una ranura de almacenamiento específica. eth_getLogs recupera registros de eventos dentro de un rango de bloques. eth_getTransactionReceipt y eth_getTransactionByHash proporcionan detalles de transacciones. Todos estos métodos están disponibles en un endpoint de HyperEVM, aunque los límites de velocidad y el comportamiento de caché específicos del proveedor pueden variar.

• eth_blockNumber: altura del último bloque.
• eth_getBalance: saldo del token nativo de una dirección.
• eth_call: ejecución de función de contrato de solo lectura.
• eth_getCode: bytecode del contrato en una dirección.
• eth_getStorageAt: valor de una ranura de almacenamiento sin procesar.
• eth_getLogs: registros de eventos dentro de un rango de bloques.
• eth_getTransactionReceipt: recibo de transacción por hash.
• eth_getTransactionByHash: detalles de transacción por hash.

El puente de HyperCore a HyperEVM y el movimiento de activos

Activos como HYPE pueden moverse entre HyperCore y HyperEVM a través de un mecanismo de puente. El puente utiliza una dirección de sistema en el lado EVM para representar activos que se originan en HyperCore. Al leer saldos, es esencial consultar el lado correcto: un saldo en HyperCore no es lo mismo que un saldo en HyperEVM, incluso para el mismo activo. La documentación de Hyperliquid HyperEVM describe el puente y la dirección del sistema.

Para los integradores, esto significa que el saldo de HYPE de un usuario en HyperCore (utilizado para operar) es independiente de su saldo de HYPE en HyperEVM (utilizado en contratos inteligentes). Para mostrar un saldo unificado, debes consultar ambos sistemas y combinar los resultados. La dirección del puente en sí es un contrato en HyperEVM, y su estado puede leerse usando eth_call o eth_getBalance. Confirma siempre la dirección del puente para la red específica (mainnet vs testnet) a partir de la documentación oficial, ya que las direcciones de los contratos difieren según la red.

• El saldo en HyperCore y el saldo en HyperEVM son distintos; consulta ambos para obtener una visión completa.
• La dirección del sistema del puente en HyperEVM contiene los activos transferidos desde HyperCore.
• Las direcciones de los contratos difieren entre mainnet y testnet; verifícalas en fuentes oficiales.

Estructura JSON-RPC y formas de error

Todas las solicitudes JSON-RPC de HyperEVM siguen la especificación JSON-RPC 2.0. Un objeto de solicitud debe incluir jsonrpc: "2.0", un id único, una cadena method y un array (u objeto) params. La respuesta contiene un campo result o un objeto error con code, message y data opcional. Los códigos de error comunes incluyen -32601 (método no encontrado), -32602 (parámetros inválidos) y -32000 (error del servidor). Los errores específicos del proveedor pueden usar códigos personalizados.

Al depurar, comprueba siempre primero el objeto de error. Un error -32601 normalmente significa que el método no es compatible con el endpoint. Un error -32602 indica parámetros mal formados, como una dirección o una etiqueta de bloque no válidas. Un error -32000 puede indicar limitación de velocidad o un problema interno del servidor. Para detalles sobre límites de velocidad, consulta la guía Límites de velocidad de la API de Hyperliquid.

• Solicitud: { jsonrpc: "2.0", id: 1, method: "eth_chainId", params: [] }
• Respuesta exitosa: { jsonrpc: "2.0", id: 1, result: "0x3e7" }
• Respuesta de error: { jsonrpc: "2.0", id: 1, error: { code: -32601, message: "Method not found" } }

Ejemplo ejecutable en Node.js: chain ID, número de bloque, saldo y código

El siguiente script de Node.js utiliza la API nativa fetch para enviar solicitudes JSON-RPC sin procesar a un endpoint de HyperEVM. Primero verifica el chain ID, luego obtiene el último número de bloque, el saldo nativo de una dirección y el bytecode en la dirección de un contrato. Reemplaza la URL del endpoint por el endpoint de HyperEVM de tu proveedor. Este ejemplo asume Node.js 18 o posterior, que incluye fetch de forma predeterminada.

El script imprime cada resultado en un formato legible. Si utilizas un proveedor que requiere una clave de API, inclúyela en la URL o en los encabezados según lo documente ese proveedor. El mismo patrón se aplica a cualquier cadena compatible con EVM, pero la comprobación del chain ID garantiza que estás en HyperEVM.

const endpoint = 'https://your-hyperevm-endpoint.example';

async function rpc(method, params = []) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params })
  });
  const data = await response.json();
  if (data.error) throw new Error(`${method}: ${data.error.message}`);
  return data.result;
}

async function main() {
  const chainId = await rpc('eth_chainId');
  console.log('Chain ID:', chainId, '(', parseInt(chainId, 16), ')');

  const blockNumber = await rpc('eth_blockNumber');
  console.log('Latest block:', parseInt(blockNumber, 16));

  const address = '0x0000000000000000000000000000000000000000';
  const balance = await rpc('eth_getBalance', [address, 'latest']);
  console.log('Balance:', parseInt(balance, 16) / 1e18, 'HYPE');

  const contract = '0xYourContractAddress';
  const code = await rpc('eth_getCode', [contract, 'latest']);
  console.log('Code length:', code.length);
}

main().catch(console.error);

Ejemplo ejecutable en Node.js: eth_call para una función view

El método eth_call ejecuta una función de solo lectura en un contrato inteligente. Requiere un objeto de transacción con to, data y, opcionalmente, from y gas. El campo data es el selector de función codificado en ABI y los argumentos. Para una función view simple como balanceOf(address), el selector es 0x70a08231 seguido de la dirección rellenada a 32 bytes. El siguiente ejemplo llama a balanceOf en un contrato ERC-20 hipotético y decodifica el uint256 devuelto.

Este patrón funciona para cualquier función view o pure. Para tipos de retorno complejos, utiliza una biblioteca como ethers.js o viem para codificar y decodificar automáticamente. El enfoque JSON-RPC sin procesar es útil para comprender la mecánica subyacente y para scripts ligeros.

const endpoint = 'https://your-hyperevm-endpoint.example';

async function rpc(method, params = []) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params })
  });
  const data = await response.json();
  if (data.error) throw new Error(`${method}: ${data.error.message}`);
  return data.result;
}

async function main() {
  const token = '0xYourTokenAddress';
  const holder = '0xYourHolderAddress';
  const selector = '0x70a08231';
  const paddedHolder = holder.slice(2).padStart(64, '0');
  const data = selector + paddedHolder;

  const result = await rpc('eth_call', [{ to: token, data }, 'latest']);
  const balance = BigInt(result);
  console.log('Token balance:', balance.toString());
}

main().catch(console.error);

Tabla de resultados reproducible para tu endpoint

Para comparar endpoints o verificar el comportamiento del proveedor, completa la siguiente tabla con mediciones de tu propio entorno. Ejecuta cada método varias veces y registra la latencia mediana. La tabla está intencionalmente en blanco para que puedas rellenarla con tus propios datos. No te bases en cifras de referencia de terceros; mide contra tu endpoint específico y tus condiciones de red.

Utiliza un método de medición consistente, como performance.now() en Node.js o time_total de curl. Registra el chain ID devuelto por eth_chainId para confirmar que estás en HyperEVM mainnet (0x3e7) o testnet. El último número de bloque cambiará con el tiempo, así que anota la marca de tiempo de tu medición.

• URL del endpoint: ________________
• eth_chainId devuelto: ________________
• Último bloque (eth_blockNumber): ________________
• Precio del gas (eth_gasPrice): ________________
• Latencia de eth_call (ms): ________________
• Latencia de eth_getBalance (ms): ________________
• Marca de tiempo de la medición: ________________

Limitaciones y compensaciones de las lecturas JSON-RPC de HyperEVM

HyperEVM es una cadena separada de la API nativa de HyperCore. Hacer referencia cruzada entre datos de mercado y estado EVM requiere consultar ambas interfaces, lo que introduce complejidad y posibles inconsistencias si los dos sistemas no están sincronizados. No existe un único método JSON-RPC que devuelva tanto los datos del libro de órdenes de HyperCore como el estado de los contratos de HyperEVM. Los desarrolladores deben diseñar su capa de datos para manejar ambas fuentes.

Las direcciones de los contratos difieren según la red. Una dirección en HyperEVM mainnet no es la misma que en testnet, y la dirección del sistema del puente también puede diferir. Verifica siempre las direcciones en la documentación oficial o en fuentes on-chain. El comportamiento del endpoint está documentado pero varía según el proveedor: algunos proveedores pueden almacenar en caché los resultados de eth_call, limitar los rangos de bloques de eth_getLogs o imponer límites de velocidad. Estas variaciones pueden afectar la consistencia y la latencia. Para datos históricos de mercado, las API nativas son más apropiadas; consulta la guía API de datos históricos de mercado de Hyperliquid.

• Dos sistemas: HyperCore para estado de mercado/cuentas, HyperEVM para estado de contratos.
• No hay un método RPC unificado; la referencia cruzada requiere ambas interfaces.
• Las direcciones de los contratos difieren según la red; verifícalas en fuentes oficiales.
• Se aplican caché, límites de velocidad y restricciones de rango de bloques específicos del proveedor.

Solución de problemas comunes de JSON-RPC en HyperEVM

Si eth_chainId devuelve un valor inesperado, es probable que estés conectado a la red incorrecta o a un endpoint mal configurado. Vuelve a comprobar la URL del endpoint y cualquier clave de API. Si eth_call devuelve un resultado vacío o un error, verifica la dirección del contrato, el selector de función y la codificación de los argumentos. Un error común es usar el número incorrecto de decimales o no rellenar las direcciones a 32 bytes. Para eth_getLogs, si recibes un error sobre el rango de bloques, reduce el rango o utiliza un proveedor que admita consultas más grandes.

La limitación de velocidad a menudo se manifiesta como HTTP 429 o error JSON-RPC -32000. Implementa retroceso exponencial y considera usar múltiples endpoints. Si un método no se encuentra (-32601), es posible que el endpoint no admita ese método; consulta la documentación del proveedor. Para problemas persistentes, consulta la página Endpoints RPC de Hyperliquid (RPC Assistant) o el centro de aprendizaje de OnFinality para guías relacionadas.

• Chain ID inesperado: comprueba la URL del endpoint y la red.
• Errores de eth_call: verifica la dirección, el selector y el relleno de argumentos.
• Errores de rango de eth_getLogs: reduce el rango de bloques o cambia de proveedor.
• Límites de velocidad: implementa retroceso y usa múltiples endpoints.
• Método no encontrado: confirma que el proveedor admite el método.

Próximos pasos y recursos adicionales

Ahora que puedes leer el estado de HyperEVM, explora las API nativas de HyperCore para datos de mercado y cuentas. La guía Precios del oráculo de Hyperliquid y la subasta del builder explica cómo se exponen los precios del oráculo a través de la API Info. Para obtener una lista completa de las redes compatibles, consulta la página de la red Hyperliquid. Si necesitas acceso RPC confiable, considera los precios de RPC de OnFinality o el servicio de API para endpoints gestionados.

Para profundizar en el rendimiento y la selección de endpoints, lee el artículo Latencia RPC de Hyperliquid: HyperEVM vs API nativa. Para detalles sobre límites de velocidad, la guía Límites de velocidad de la API de Hyperliquid proporciona umbrales detallados. Prueba siempre con tu propio caso de uso y mide con la tabla de resultados anterior.

• Explora las API Info y Exchange de HyperCore para datos de mercado.
• Revisa la página de la red Hyperliquid para las cadenas compatibles.
• Considera proveedores RPC gestionados para cargas de trabajo en producción.
• Mide el rendimiento de tu propio endpoint con la tabla de resultados.