Espacios de nombres de métodos RPC de Ethereum: eth, net, web3, debug, trace

Por qué Ethereum JSON-RPC se organiza en espacios de nombres

La superficie de Ethereum JSON-RPC no es una lista plana de métodos. Está agrupada por prefijo, y cada prefijo es un espacio de nombres con un propósito diferente y un perfil de disponibilidad diferente. La especificación JSON-RPC de Ethereum presenta la lista completa de métodos agrupada de esta manera, y la especificación JSON-RPC 2.0 define el sobre de solicitud y error que comparten todos los espacios de nombres.

Los espacios de nombres existen porque los métodos tienen diferentes perfiles de confianza y coste. Leer un saldo es barato y seguro de exponer en un endpoint compartido. Trazar cada llamada interna de una transacción es costoso, puede filtrar interioridades del nodo y a menudo está deshabilitado por defecto. Agrupar por prefijo permite a los operadores de nodos habilitar o deshabilitar familias enteras de capacidades con un solo flag, y permite a los clientes razonar sobre lo que un endpoint puede hacer antes de enviar una solicitud.

Para una orientación más amplia sobre la red en sí, consulta la página de la red Ethereum. El mapa de espacios de nombres que aparece a continuación es la capa práctica sobre eso: te indica a qué familia pertenece un método y para qué sirve.

• eth_ — estado de la cadena, bloques, transacciones, llamadas, logs, comisiones: el caballo de batalla.
• net_ — información de red y de pares.
• web3_ — versión del cliente y utilidades de hashing.
• debug_ — depuración del nodo/cliente, incluido cierto trazado de transacciones.
• trace_ — trazado de llamadas y bloques al estilo Parity/OpenEthereum.
• txpool_ — inspección de transacciones pendientes.

El espacio de nombres eth_: estado de la cadena, bloques, transacciones y comisiones

El espacio de nombres eth_ es el que usarás para casi todas las tareas a nivel de aplicación. Cubre saldos de cuentas, recuperación de bloques, envío y búsqueda de transacciones, llamadas a contratos, logs y estimación de comisiones. Si estás construyendo una cartera, un panel o un flujo de interacción con contratos, vivirás aquí.

La selección de métodos dentro de eth_ se reduce principalmente a la pregunta que estás haciendo. Una lectura de saldo es eth_getBalance. Una simulación de solo lectura de una llamada a un contrato sin enviar una transacción es eth_call. Una búsqueda de transacción pendiente usa eth_getTransactionByHash con una etiqueta de bloque null. La recuperación de bloques tiene su propia familia, cubierta en el artículo sobre métodos de recuperación de bloques de Ethereum.

El espacio de nombres eth_ casi siempre está habilitado en endpoints gestionados porque es la capacidad básica. Eso no significa que todos los métodos sean gratuitos o ilimitados; el historial de comisiones y las consultas de logs pueden ser más pesados que una simple lectura de saldo, y los proveedores pueden medirlos de forma diferente. La página de precios de RPC describe cómo se suele estructurar la medición.

• Leer saldo → eth_getBalance.
• Simular una llamada sin enviarla → eth_call.
• Inspeccionar una transacción pendiente → eth_getTransactionByHash con una etiqueta de bloque null.
• Estimar comisiones → eth_feeHistory o eth_gasPrice.
• Consultar logs → eth_getLogs (ten en cuenta el rango de bloques).

Los espacios de nombres net_ y web3_: metadatos de red y del cliente

net_ y web3_ son espacios de nombres pequeños, pero son útiles para diagnósticos y para confirmar con qué endpoint estás hablando realmente. net_version devuelve el ID de red como una cadena, y net_peerCount devuelve el número de pares conectados. web3_clientVersion devuelve el nombre y la cadena de versión del cliente.

Estos métodos casi siempre están habilitados porque son baratos y no exponen estado sensible. Son lo primero que hay que llamar cuando estás depurando una conexión: si net_version devuelve la red incorrecta, estás apuntando al endpoint equivocado. El artículo sobre métodos de identidad de nodo de Ethereum cubre eth_chainId, web3_clientVersion y llamadas de identidad relacionadas con más profundidad.

Una sutileza: net_version devuelve el ID de red, que no siempre es el mismo que el ID de cadena devuelto por eth_chainId. En la mayoría de las redes coinciden, pero son campos distintos y no deben tratarse como intercambiables en el código.

• net_version — ID de red como cadena.
• net_peerCount — número de pares conectados.
• net_listening — si el nodo está aceptando conexiones.
• web3_clientVersion — nombre y versión del cliente.
• web3_sha3 — hash Keccak-256 de los datos de entrada.

El espacio de nombres debug_: depuración del nodo y trazado de transacciones

El espacio de nombres debug_ es donde vive la depuración del nodo y del cliente. Incluye métodos para inspeccionar el estado interno del nodo y, en algunos clientes, trazar la ejecución de transacciones. debug_traceTransaction devuelve un trazado de una sola transacción, y debug_traceCall traza una llamada sin enviarla. Son potentes para depurar transacciones fallidas y comprender el movimiento interno de valor.

El problema es la disponibilidad. Los métodos debug_ suelen estar deshabilitados en endpoints compartidos y gestionados porque son costosos y pueden filtrar interioridades. La documentación JSON-RPC de Geth describe cómo se habilitan los espacios de nombres y señala que los grupos debug, trace y admin a menudo están restringidos. Si dependes de debug_, debes comprobarlo primero.

El artículo sobre trazado de transacciones de Ethereum con trace y debug profundiza en los propios métodos de trazado. Esta referencia se centra en dónde se sitúan en el mapa de espacios de nombres y cómo comprobar si están disponibles.

• debug_traceTransaction — traza una sola transacción.
• debug_traceCall — traza una llamada sin enviarla.
• debug_traceBlockByNumber — traza todas las transacciones de un bloque.
• Disponibilidad: comúnmente deshabilitado en endpoints compartidos; comprobar antes de usar.
• Coste: costoso; puede medirse o limitarse de forma diferente.

El espacio de nombres trace_: trazado al estilo Parity/OpenEthereum

El espacio de nombres trace_ se originó en Parity/OpenEthereum y proporciona trazado de llamadas y bloques. trace_block devuelve los trazados de todas las transacciones de un bloque, trace_transaction devuelve los trazados de una sola transacción, y trace_call traza una llamada. Estos métodos son ampliamente utilizados por herramientas de analítica y de transferencias internas porque exponen transferencias internas de valor que eth_getLogs no muestra.

La advertencia importante es la estandarización. Los métodos trace_ no están estandarizados entre clientes de la misma manera que los métodos eth_. Sus parámetros exactos y formas de retorno pueden diferir sutilmente entre clientes de ejecución, y algunos clientes implementan solo un subconjunto. Este es un comportamiento documentado que varía según el proveedor y el cliente, por lo que debes verificar la forma contra tu endpoint específico en lugar de asumir portabilidad.

Como trace_ es costoso, con frecuencia está deshabilitado en endpoints compartidos. La misma comprobación de capacidades que verifica debug_ debe verificar trace_.

• trace_block — trazados de todas las transacciones de un bloque.
• trace_transaction — trazados de una sola transacción.
• trace_call — traza una llamada.
• trace_replayTransaction — reproduce una transacción y devuelve los trazados.
• No estandarizado entre clientes; verifica la forma de retorno por endpoint.

El espacio de nombres txpool_: inspección de transacciones pendientes

El espacio de nombres txpool_ expone el pool de transacciones pendientes del nodo. txpool_status devuelve recuentos de transacciones pendientes y en cola, txpool_content devuelve el contenido completo del pool, y txpool_inspect devuelve un resumen. Esto es útil para la monitorización del mempool, la estimación de comisiones y comprender por qué una transacción está atascada.

Al igual que debug_ y trace_, txpool_ no está habilitado universalmente. Puede deshabilitarse en endpoints compartidos porque expone datos de transacciones pendientes y puede ser costoso de serializar en un nodo ocupado. Una comprobación de capacidades es el primer paso correcto.

Para una transacción pendiente, tienes dos opciones: txpool_content para una vista completa del pool, o eth_getTransactionByHash con una etiqueta de bloque null para una transacción específica. Esta última está en el espacio de nombres eth_ y es más probable que esté disponible.

• txpool_status — recuentos de transacciones pendientes y en cola.
• txpool_content — contenido completo del pool.
• txpool_inspect — resumen del contenido del pool.
• Disponibilidad: comúnmente deshabilitado en endpoints compartidos.
• Alternativa: eth_getTransactionByHash con una etiqueta de bloque null.

Elegir el método adecuado para una tarea

La selección de métodos es más fácil una vez que conoces el mapa de espacios de nombres. La tabla siguiente asigna tareas comunes a la familia de métodos que las resuelve. Empieza con la opción eth_ donde exista, porque es la que más probablemente esté habilitada y la más portable entre clientes.

Cuando una tarea requiere trazar transferencias internas de valor, pasas a trace_ o debug_. Cuando requiere inspección de transacciones pendientes, pasas a txpool_ o usas el respaldo de eth_. El centro de aprendizaje de OnFinality tiene análisis en profundidad por método para los métodos que más usarás.

Si no estás seguro de si un endpoint admite un espacio de nombres, no lo adivines. Ejecuta la comprobación de capacidades de la siguiente sección y registra el resultado.

• Leer saldo → eth_getBalance.
• Simular una llamada sin enviarla → eth_call.
• Inspeccionar una transacción pendiente → txpool_content o eth_getTransactionByHash con una etiqueta de bloque null.
• Trazar transferencias internas de valor → trace_block o debug_traceTransaction.
• Comprobar la identidad de la red → net_version o eth_chainId.
• Comprobar la versión del cliente → web3_clientVersion.

Comprobar la disponibilidad de espacios de nombres con un script de Node.js

Dado que debug_, trace_ y txpool_ suelen estar deshabilitados, es obligatorio realizar una comprobación de capacidades antes de depender de ellos. El script siguiente envía un método representativo por espacio de nombres a un endpoint e imprime una matriz de capacidades con los errores sin procesar. Solo utiliza el fetch integrado disponible en Node.js moderno, por lo que no hay dependencias que instalar.

Establece la variable de entorno RPC_URL con tu endpoint antes de ejecutarlo. El script deliberadamente no interpreta los errores más allá de imprimirlos, porque el código y el mensaje de error sin procesar son lo que necesitas registrar en tu tabla de resultados.

La comprobación usa eth_chainId, net_version, web3_clientVersion, txpool_status, debug_traceTransaction y trace_block. Las comprobaciones de debug y trace usan un hash de transacción y un número de bloque de relleno; un error method-not-found significa que el espacio de nombres está deshabilitado, mientras que un error diferente puede significar que el espacio de nombres está habilitado pero la entrada no era válida.

// probe-namespaces.mjs
// Run: RPC_URL=https://your-endpoint node probe-namespaces.mjs

const RPC_URL = process.env.RPC_URL;
if (!RPC_URL) {
  console.error('Set RPC_URL environment variable');
  process.exit(1);
}

const probes = [
  { namespace: 'eth',    method: 'eth_chainId',            params: [] },
  { namespace: 'net',    method: 'net_version',            params: [] },
  { namespace: 'web3',   method: 'web3_clientVersion',     params: [] },
  { namespace: 'txpool', method: 'txpool_status',          params: [] },
  { namespace: 'debug',  method: 'debug_traceTransaction', params: ['0x0000000000000000000000000000000000000000000000000000000000000000', {}] },
  { namespace: 'trace',  method: 'trace_block',            params: ['latest'] }
];

async function call(method, params) {
  const body = { jsonrpc: '2.0', id: 1, method, params };
  const res = await fetch(RPC_URL, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(body)
  });
  const json = await res.json();
  return json;
}

const rows = [];
for (const p of probes) {
  try {
    const json = await call(p.method, p.params);
    const enabled = json.error ? 'no' : 'yes';
    const code = json.error ? json.error.code : '';
    const message = json.error ? json.error.message : 'ok';
    rows.push({ namespace: p.namespace, method: p.method, enabled, code, message });
  } catch (err) {
    rows.push({ namespace: p.namespace, method: p.method, enabled: 'error', code: '', message: String(err) });
  }
}

console.table(rows);

Registrar tu propia matriz de capacidades por espacio de nombres

La salida de la comprobación solo es útil si la registras. Rellena la tabla siguiente para tu endpoint y guárdala con tus notas de integración. La columna del código de error es la más importante: un -32601 method-not-found normalmente significa que el espacio de nombres está deshabilitado en ese endpoint, no que el método no exista en la especificación.

Ejecuta la comprobación contra cada endpoint que uses, incluidos los endpoints de conmutación por error. La disponibilidad puede diferir entre ellos incluso dentro del mismo proveedor, y un failover que carece de trace_ romperá una función de trazado que funciona en tu primario.

No registres números de referencia que no hayas medido. La tabla es para capacidades, no para rendimiento. Si quieres datos de latencia, mide por separado y etiquétalos como tu propia medición.

• Espacio de nombres — eth, net, web3, debug, trace, txpool.
• Método comprobado — el método representativo que enviaste.
• ¿Habilitado? — sí, no o error.
• Código de error — el código de error JSON-RPC, p. ej. -32601.
• Notas — proveedor, cliente, fecha y cualquier advertencia.

Cómo difieren los códigos de error según el espacio de nombres

La especificación JSON-RPC 2.0 define un pequeño conjunto de códigos de error estándar, incluido -32601 para método no encontrado. En la práctica, una respuesta -32601 a un método debug_ o trace_ normalmente significa que el espacio de nombres está deshabilitado en ese endpoint, no que el método esté ausente de la especificación. El artículo sobre decodificar el objeto de error JSON-RPC explica cómo leer juntos los campos code, message y data.

Otros códigos tienen significados diferentes. Un error -32602 invalid params significa que el espacio de nombres está habilitado pero tus argumentos son incorrectos. Un error -32000 server error puede indicar un fallo a nivel de nodo o un límite de velocidad, según el proveedor. Los campos message y data a menudo contienen detalles específicos del proveedor, así que regístralos sin procesar.

La regla práctica: trata -32601 como una señal de capacidad, trata -32602 como una señal de forma de la solicitud, y trata -32000 como una señal de tiempo de ejecución. Esta distinción ahorra tiempo cuando estás depurando una integración que falla.

• -32601 — método no encontrado; a menudo significa que el espacio de nombres está deshabilitado.
• -32602 — parámetros inválidos; espacio de nombres habilitado, argumentos incorrectos.
• -32000 — error del servidor; fallo a nivel de nodo o límite de velocidad.
• Registra siempre el objeto de error sin procesar, incluido data.

Limitaciones y compensaciones de las integraciones dependientes de espacios de nombres

La disponibilidad de espacios de nombres depende del proveedor y del cliente. No hay garantía universal de que debug_, trace_ o txpool_ estén habilitados en un endpoint dado, y el mismo proveedor puede habilitarlos en un plan y no en otro. Diseña tu integración para que las funciones de trazado se degraden de forma elegante cuando el espacio de nombres no esté disponible.

Los métodos trace_ no están estandarizados entre clientes. Sus parámetros y formas de retorno pueden diferir sutilmente entre clientes de ejecución, por lo que el código que funciona contra un cliente puede necesitar ajustes contra otro. Este es un comportamiento documentado que varía según el proveedor y el cliente, no un error.

Los espacios de nombres costosos pueden medirse o limitarse de forma diferente a eth_. Una llamada trace_block puede ser mucho más pesada que una lectura de saldo, y los proveedores pueden aplicar límites separados. Consulta las páginas de precios de RPC y servicio de API para saber cómo se suele estructurar la medición, y nunca asumas que una llamada de trazado es gratuita porque lo sea una lectura de saldo.

• La disponibilidad varía según el proveedor, el plan y el cliente.
• trace_ no está estandarizado entre clientes.
• Los espacios de nombres costosos pueden medirse de forma diferente.
• La semántica de los métodos puede diferir sutilmente entre clientes de ejecución.
• Diseña para una degradación elegante cuando falte un espacio de nombres.

Solución de problemas de espacios de nombres y métodos

Cuando un método falla, la primera pregunta es si el espacio de nombres está habilitado. Ejecuta la comprobación de capacidades contra el endpoint y revisa el código de error. Si la comprobación devuelve -32601 para debug_ o trace_, el espacio de nombres está deshabilitado y ningún ajuste de parámetros lo arreglará.

Si la comprobación devuelve -32602, el espacio de nombres está habilitado pero tus argumentos son incorrectos. Verifica el número y los tipos de parámetros contra la especificación. Si devuelve -32000, el nodo es accesible pero algo falló en tiempo de ejecución; revisa los campos message y data para obtener detalles.

Si la comprobación tiene éxito pero tu aplicación sigue fallando, verifica que estás enviando la solicitud al mismo endpoint y que tu sobre JSON-RPC está bien formado. La guía del nodo RPC de Ethereum cubre la configuración del endpoint y los problemas de conexión comunes.

• Comprueba primero; no asumas que un espacio de nombres está habilitado.
• -32601 → espacio de nombres deshabilitado; cambia de endpoint o de función.
• -32602 → corrige la forma de los parámetros.
• -32000 → inspecciona message y data para obtener detalles de tiempo de ejecución.
• Verifica el endpoint y el sobre JSON-RPC.

Próximos pasos para integraciones conscientes de los espacios de nombres

Empieza ejecutando la comprobación de capacidades contra cada endpoint que uses y registrando los resultados en tu propia matriz. Luego elige los métodos por tarea, prefiriendo eth_ donde exista un método adecuado, y recurriendo a debug_, trace_ o txpool_ solo cuando la tarea los requiera y la comprobación confirme su disponibilidad.

Para una cobertura más profunda de métodos específicos, el centro de aprendizaje de OnFinality recopila los artículos por método, incluidos identidad de nodo, recuperación de bloques y trazado de transacciones. La página de la red Ethereum proporciona el contexto a nivel de red, y la guía del nodo RPC de Ethereum cubre la configuración del endpoint.

Si estás evaluando proveedores, comprueba cómo documenta cada uno la disponibilidad de espacios de nombres y la medición. Las páginas de precios de RPC y servicio de API describen el enfoque de OnFinality, y el artículo sobre trazado de transacciones de Ethereum con trace y debug profundiza en los espacios de nombres de trazado.

• Comprueba cada endpoint y registra la matriz.
• Prefiere los métodos eth_ donde existan.
• Usa debug_, trace_ y txpool_ solo cuando se confirme su disponibilidad.
• Vuelve a comprobar tras cambios de proveedor o de plan.
• Conserva los registros de errores sin procesar para escalar a soporte.