Métodos JSON-RPC de Monad: superficie compatible con Ethereum

La interfaz JSON-RPC compatible con Ethereum de Monad

Monad está diseñado como una blockchain compatible con la EVM, lo que significa que expone una interfaz JSON-RPC que refleja los espacios de nombres de métodos definidos en la especificación JSON-RPC de Ethereum. Para los desarrolladores, este es el punto de partida: el vocabulario de métodos que ya conoces de las herramientas de Ethereum—eth_, net_, web3_* y, donde estén habilitados, debug_/trace_—es el mismo vocabulario que usarás contra un endpoint de Monad. El sobre de solicitud es el objeto estándar JSON-RPC 2.0 que contiene jsonrpc, method, params e id, tal como se define en la especificación JSON-RPC 2.0.

Esta compatibilidad reduce la barrera de entrada: las bibliotecas de Ethereum existentes, las integraciones de billeteras y los indexadores a menudo pueden apuntar a un endpoint RPC de Monad con cambios mínimos. OnFinality proporciona endpoints RPC de Monad que siguen esta superficie compatible, y la guía y endpoints RPC de Monad cubre el descubrimiento de endpoints y los conceptos básicos de conexión. Sin embargo, la compatibilidad es un punto de partida, no una garantía de comportamiento idéntico en cada método y cada proveedor.

• Espacios de nombres estándar: eth_, net_, web3_* son la base para las cadenas compatibles con la EVM.
• Espacios de nombres opcionales: debug_* y trace_* normalmente están deshabilitados en endpoints compartidos o públicos debido a su intensidad de recursos.
• Sobre de solicitud: { "jsonrpc": "2.0", "method": "...", "params": [...], "id": 1 }.
• Sobre de respuesta: { "jsonrpc": "2.0", "result": ..., "id": 1 } o { "jsonrpc": "2.0", "error": { "code": ..., "message": ... }, "id": 1 }.

Enumeración de los métodos soportados en un endpoint de Monad

No asumas que todos los métodos de Ethereum están habilitados en un endpoint de Monad dado. Los proveedores y las versiones de nodo varían en qué espacios de nombres exponen, y algunos métodos pueden estar deshabilitados por razones de rendimiento, seguridad u operativas. La única forma confiable de saber qué soporta un endpoint específico es sondearlo con un conjunto pequeño y seguro de métodos y registrar las respuestas. Un método que no es soportado normalmente devolverá un error JSON-RPC con el código -32601 (método no encontrado) o un mensaje específico del proveedor de 'no soportado'.

Al sondear, comienza con métodos de solo lectura que no tengan efectos secundarios: eth_chainId, eth_blockNumber, web3_clientVersion y una llamada eth_getLogs de rango pequeño. Evita enviar transacciones o llamar a métodos debug/trace durante el descubrimiento inicial de capacidades. Registra tanto el resultado como el error sin procesar de cada método para que puedas distinguir entre un método que está ausente, un método que está presente pero falla temporalmente y un método que requiere parámetros que no proporcionaste correctamente.

• Sondea primero con métodos de solo lectura: eth_chainId, eth_blockNumber, web3_clientVersion.
• Registra el código de error exacto y el mensaje para los métodos no soportados.
• Distingue -32601 (método no encontrado) de -32602 (parámetros inválidos) y -32603 (error interno).
• Vuelve a sondear después de actualizaciones del proveedor o del nodo; los conjuntos de capacidades pueden cambiar.

Grupos de métodos principales para desarrolladores de Monad

Los métodos que usarás con más frecuencia en Monad se dividen en cinco grupos funcionales. Los métodos de identidad de cadena y nodo—eth_chainId, net_version, web3_clientVersion—te indican a qué red estás conectado y qué software cliente está sirviendo el endpoint. Los métodos de lectura de bloques y transacciones—eth_blockNumber, eth_getBlockByNumber, eth_getTransactionByHash, eth_getTransactionReceipt—te permiten inspeccionar el estado de la cadena y los resultados de las transacciones. Los métodos de estado y simulación—eth_call, eth_estimateGas, eth_getBalance, eth_getCode, eth_getStorageAt—soportan la interacción con contratos y las comprobaciones previas.

Los métodos de logs, principalmente eth_getLogs, son esenciales para la indexación de eventos, pero vienen con límites de rango de bloques que varían según el proveedor; consulta la guía dedicada sobre límites de rango de bloques de eth_getLogs en Monad para manejar errores de rango inválido. Los métodos de datos de tarifas y prioridad—eth_gasPrice, eth_feeHistory, eth_maxPriorityFeePerGas—te ayudan a construir transacciones, pero en Monad debes tener en cuenta el precio dual del gas, que se cubre en el artículo sobre estimación del precio del gas dual en Monad.

• Identidad de cadena/nodo: eth_chainId, net_version, web3_clientVersion.
• Lecturas de bloques y transacciones: eth_blockNumber, eth_getBlockByNumber, eth_getTransactionByHash, eth_getTransactionReceipt.
• Estado y simulación: eth_call, eth_estimateGas, eth_getBalance, eth_getCode, eth_getStorageAt.
• Logs: eth_getLogs (atención a los límites de rango de bloques).
• Tarifas y prioridad: eth_gasPrice, eth_feeHistory, eth_maxPriorityFeePerGas.

Particularidades de comportamiento específicas de Monad

Dos comportamientos específicos de Monad merecen atención al mapear la superficie JSON-RPC. Primero, Monad utiliza ejecución asíncrona, lo que significa que una transacción enviada puede no tener un recibo disponible de inmediato de la misma manera que sugiere la intuición síncrona de Ethereum. Se puede conocer un hash de transacción antes de que el estado del recibo sea definitivo; los desarrolladores deben sondear eth_getTransactionReceipt y manejar los resultados nulos con elegancia. El artículo sobre ciclo de vida de transacciones y estado de recibos en Monad lo explica en detalle.

Segundo, Monad emplea un precio dual del gas, lo que significa que eth_gasPrice por sí solo puede inducirte a error sobre el costo real de una transacción. Si tu aplicación depende únicamente de eth_gasPrice para la estimación de tarifas, puedes subestimar o sobreestimar las tarifas. Usa eth_feeHistory y eth_maxPriorityFeePerGas donde estén disponibles, y consulta la guía de precio dual del gas para un enfoque más preciso. Estas particularidades no son problemas de disponibilidad de métodos—los métodos existen—pero afectan cómo interpretas los resultados.

• Ejecución asíncrona: el recibo puede ser nulo inmediatamente después del envío; sondea con retroceso exponencial.
• Precio dual del gas: eth_gasPrice es un único punto de datos; combínalo con eth_feeHistory y eth_maxPriorityFeePerGas.
• La semántica del estado del recibo puede diferir de las cadenas EVM síncronas; verifícala con la documentación de Monad.
• Siempre concilie el comportamiento observado con la documentación actual de Monad.

Script ejecutable de sondeo de capacidades en Node.js

El siguiente script de Node.js sondea un endpoint de Monad para un conjunto pequeño de métodos e imprime OK o NOT-SUPPORTED para cada uno, junto con el error sin procesar cuando corresponda. Utiliza solo la API fetch integrada (Node.js 18+) y no requiere dependencias externas. Reemplaza la constante RPC_URL con la URL de tu endpoint de Monad. El script llama a eth_chainId, eth_blockNumber, eth_getBlockByNumber, eth_getBalance, eth_getLogs con un rango de bloques pequeño y web3_clientVersion.

Ejecuta este script contra tu propio endpoint para construir una matriz de capacidades. La salida mostrará qué métodos devuelven resultados y cuáles devuelven errores. Para eth_getLogs, usa un rango de bloques reciente de unos pocos bloques para evitar alcanzar los límites de rango; si el endpoint rechaza el rango, eso en sí mismo es información útil sobre las restricciones del proveedor.

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

async function call(method, params = []) {
  const body = { jsonrpc: '2.0', method, params, id: 1 };
  const res = await fetch(RPC_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  if (json.error) {
    return { ok: false, error: json.error };
  }
  return { ok: true, result: json.result };
}

async function probe() {
  const latestHex = (await call('eth_blockNumber')).result;
  const latest = parseInt(latestHex, 16);
  const fromBlock = '0x' + Math.max(0, latest - 5).toString(16);
  const toBlock = '0x' + latest.toString(16);

  const probes = [
    ['eth_chainId', []],
    ['eth_blockNumber', []],
    ['eth_getBlockByNumber', [latestHex, false]],
    ['eth_getBalance', ['0x0000000000000000000000000000000000000000', 'latest']],
    ['eth_getLogs', [{ fromBlock, toBlock }]],
    ['web3_clientVersion', []],
  ];

  for (const [method, params] of probes) {
    const out = await call(method, params);
    if (out.ok) {
      console.log(`OK  ${method} ->`, JSON.stringify(out.result).slice(0, 120));
    } else {
      console.log(`NOT-SUPPORTED  ${method} ->`, JSON.stringify(out.error));
    }
  }
}

probe().catch(console.error);

Tabla de resultados reproducibles para tu endpoint

Usa la tabla a continuación para registrar los resultados de tu sondeo. Completa una fila por cada método que pruebes contra tu endpoint de Monad. La columna '¿Soportado?' debe ser Sí, No o Error. La columna 'Campo de respuesta de ejemplo' debe capturar un campo representativo del resultado (por ejemplo, el valor de chainId o el número de bloque). La columna 'Notas' es para observaciones específicas del proveedor, como límites de velocidad o parámetros requeridos.

Esta tabla está intencionalmente en blanco para que puedas medir contra tu propio endpoint en lugar de depender de afirmaciones de terceros. Vuelve a ejecutar el sondeo después de cambiar de proveedor o después de una actualización de nodo, y mantén la tabla con tus pruebas de integración. Si un método no es soportado, documenta el código de error exacto y el mensaje para que puedas manejarlo con elegancia en tu aplicación.

• Método: el nombre del método JSON-RPC, por ejemplo, eth_chainId.
• Espacio de nombres: eth, net, web3, debug, trace.
• ¿Soportado?: Sí / No / Error.
• Campo de respuesta de ejemplo: un campo clave del resultado, por ejemplo, result.chainId.
• Notas: comportamiento específico del proveedor, límites de velocidad, parámetros requeridos.

Interpretación de errores de método no encontrado y no soportado

Cuando un endpoint de Monad no soporta un método, la respuesta JSON-RPC contendrá un objeto de error. El código de error estándar para un método que no existe es -32601 (método no encontrado), tal como se define en la especificación JSON-RPC 2.0. Algunos proveedores pueden devolver un código diferente o un mensaje personalizado como 'método no soportado' o 'método deshabilitado'. Debes tratar cualquier respuesta de error como una señal de que el método no está disponible en ese endpoint, pero distingue entre un método que está realmente ausente y uno que no está disponible temporalmente debido a limitación de velocidad o errores internos.

Si recibes -32601, no reintentes el mismo método repetidamente; en su lugar, recurre a un método o endpoint alternativo. Si recibes -32602 (parámetros inválidos), verifica el formato de tus parámetros—por ejemplo, los números de bloque deben ser cadenas hexadecimales o las etiquetas 'latest', 'earliest', 'pending'. Si recibes -32603 (error interno), el método puede existir pero el nodo encontró un problema; reintenta con retroceso exponencial y considera cambiar de endpoint.

• -32601: método no encontrado o deshabilitado; no reintentes, usa un respaldo.
• -32602: parámetros inválidos; verifica la codificación hexadecimal y el número de parámetros.
• -32603: error interno; reintenta con retroceso exponencial, considera cambiar de endpoint.
• Códigos específicos del proveedor: consulta la documentación del proveedor para códigos de error personalizados.

Disponibilidad de los espacios de nombres debug y trace

Los espacios de nombres debug_* y trace_* proporcionan métodos de introspección potentes como debug_traceTransaction y trace_block. En endpoints de Monad compartidos o públicos, estos espacios de nombres normalmente están deshabilitados porque consumen muchos recursos y pueden degradar el rendimiento para otros usuarios. Si tu aplicación requiere trazado, es posible que necesites un nodo dedicado o un proveedor que ofrezca explícitamente estos espacios de nombres. No asumas que porque un método existe en la especificación JSON-RPC de Ethereum, está habilitado en tu endpoint de Monad.

Para verificar la disponibilidad, sondea con un método debug seguro como debug_traceTransaction en un hash de transacción conocido, o simplemente intenta una llamada trace_ e inspecciona el error. Si el endpoint devuelve -32601, el espacio de nombres no está expuesto. Para necesidades de trazado en producción, considera ejecutar tu propio nodo de Monad o usar un proveedor que documente el soporte de trace. Las páginas de servicio API y precios de RPC de OnFinality describen los niveles de servicio disponibles, pero siempre verifica el soporte del espacio de nombres con un sondeo directo.

• debug_* y trace_* normalmente están deshabilitados en endpoints compartidos.
• Sondea con un hash de transacción conocido para probar debug_traceTransaction.
• Para trazado, considera un nodo dedicado o un proveedor con soporte de trace documentado.
• Verifica el soporte del espacio de nombres directamente; no te bases en suposiciones.

Limitaciones y compensaciones de la compatibilidad con la EVM

La compatibilidad con la EVM no garantiza una disponibilidad o semántica idénticas de los métodos. Monad puede implementar los mismos nombres de métodos pero con características de rendimiento, límites de rango de bloques o comportamientos de error diferentes. Por ejemplo, eth_getLogs en Monad puede tener un límite de rango de bloques más bajo de lo que esperas de la red principal de Ethereum, y eth_gasPrice puede no reflejar con precisión el precio dual del gas. Estas diferencias no son errores; son propiedades de la red y sus proveedores.

Otra compensación es que algunos métodos de Ethereum pueden estar obsoletos o reemplazados en Monad, o se pueden introducir nuevos métodos que no forman parte de la superficie estándar de Ethereum. Siempre concilie tus suposiciones con la documentación actual de Monad y la documentación de tu proveedor. Si estás migrando una aplicación de Ethereum existente, ejecuta el script de sondeo de capacidades contra tu endpoint de Monad y compara los resultados con tu endpoint de Ethereum para identificar brechas temprano.

• La disponibilidad de métodos varía según el proveedor y la versión del nodo.
• Los límites de rango de bloques para eth_getLogs pueden diferir de Ethereum.
• El precio dual del gas afecta a los métodos relacionados con tarifas.
• Pueden existir métodos nuevos u obsoletos fuera de la superficie estándar de Ethereum.
• Siempre verifica con la documentación actual de Monad.

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

Si tu aplicación no puede conectarse o recibe errores inesperados, comienza verificando la URL del endpoint y la red. Usa eth_chainId para confirmar que estás en la red Monad prevista. Si eth_chainId devuelve un valor que no reconoces, es posible que estés apuntando a una testnet o a una cadena diferente. A continuación, verifica que tu sobre de solicitud sea JSON-RPC 2.0 válido: el campo jsonrpc debe ser exactamente '2.0', y el id debe ser un número o una cadena. Un sobre mal formado puede producir un error de análisis (-32700) o una solicitud inválida (-32600).

Si un método específico falla, aíslalo con un comando curl mínimo. Por ejemplo, curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' YOUR_RPC_URL. Si esto funciona pero tu aplicación falla, el problema probablemente esté en tu biblioteca cliente o en el formato de los parámetros. Si falla, es posible que el método no sea soportado o que el endpoint no esté disponible temporalmente. Para errores relacionados con logs, consulta la guía sobre límites de rango de bloques de eth_getLogs en Monad.

• Verifica la URL del endpoint y la red con eth_chainId.
• Valida el sobre JSON-RPC 2.0: jsonrpc, method, params, id.
• Aísla los métodos que fallan con un comando curl mínimo.
• Verifica los límites de rango de bloques para eth_getLogs.
• Consulta la documentación del proveedor para códigos de error personalizados.

Próximos pasos para la integración JSON-RPC de Monad

Después de sondear tu endpoint y completar la tabla de resultados, tienes una matriz de capacidades que puedes usar para diseñar tu integración. Para el descubrimiento de endpoints y la selección de proveedores, consulta la página de endpoints RPC de Monad (Asistente RPC). Para una visión más amplia del uso de RPC de Monad, la guía y endpoints RPC de Monad cubre la configuración de conexión y los patrones comunes. Si necesitas estimar tarifas con precisión, revisa el artículo sobre estimación del precio del gas dual en Monad.

Para implementaciones en producción, considera usar un proveedor que ofrezca los espacios de nombres que necesitas y documente sus límites de rango de bloques. Los endpoints RPC de Monad de OnFinality están diseñados para cargas de trabajo compatibles con la EVM, y el centro de aprendizaje de OnFinality contiene guías adicionales sobre comportamientos específicos de Monad. Vuelve a ejecutar siempre tu sondeo de capacidades después de cambios de proveedor o actualizaciones de nodo, y mantén tu tabla de resultados actualizada como parte de tu suite de pruebas de integración.

• Usa la matriz de capacidades para elegir métodos y endpoints de respaldo.
• Documenta los límites de rango de bloques y el manejo de errores para eth_getLogs.
• Vuelve a sondear después de actualizaciones del proveedor o del nodo.
• Revisa las guías específicas de Monad sobre gas, recibos y logs.
• Considera nodos dedicados para los espacios de nombres debug/trace.