Ethereum RPC Method Namespaces: eth, net, web3, debug, trace

Why Ethereum JSON-RPC Is Organised into Namespaces

The Ethereum JSON-RPC surface is not a flat list of methods. It is grouped by prefix, and each prefix is a namespace with a different purpose and a different availability profile. The Ethereum JSON-RPC specification presents the full method list grouped this way, and the JSON-RPC 2.0 specification defines the request and error envelope that all namespaces share.

Namespaces exist because the methods have different trust and cost profiles. Reading a balance is cheap and safe to expose on a shared endpoint. Tracing every internal call of a transaction is expensive, can leak node internals, and is often disabled by default. Grouping by prefix lets node operators enable or disable whole capability families with a single flag, and lets clients reason about what an endpoint can do before sending a request.

For a broader orientation to the network itself, see the Ethereum network page. The namespace map below is the practical layer on top of that: it tells you which family a method belongs to and what it is for.

• eth_ — chain state, blocks, transactions, calls, logs, fees: the workhorse.
• net_ — network and peer information.
• web3_ — client version and hashing utilities.
• debug_ — node/client debugging, including some transaction tracing.
• trace_ — Parity/OpenEthereum-style call and block tracing.
• txpool_ — pending-transaction inspection.

The eth_ Namespace: Chain State, Blocks, Transactions, and Fees

The eth_ namespace is the one you will use for almost every application-level task. It covers account balances, block retrieval, transaction submission and lookup, contract calls, logs, and fee estimation. If you are building a wallet, a dashboard, or a contract interaction flow, you will live here.

Method selection inside eth_ is mostly about the question you are asking. A balance read is eth_getBalance. A read-only simulation of a contract call without sending a transaction is eth_call. A pending transaction lookup uses eth_getTransactionByHash with a null block tag. Block retrieval has its own family, covered in the Ethereum block retrieval methods article.

The eth_ namespace is almost always enabled on managed endpoints because it is the baseline capability. That does not mean every method is free or unlimited; fee history and log queries can be heavier than a simple balance read, and providers may meter them differently. The RPC pricing page describes how metering is typically structured.

• Read balance → eth_getBalance.
• Simulate a call without sending → eth_call.
• Inspect a pending transaction → eth_getTransactionByHash with a null block tag.
• Estimate fees → eth_feeHistory or eth_gasPrice.
• Query logs → eth_getLogs (mind the block range).

The net_ and web3_ Namespaces: Network and Client Metadata

net_ and web3_ are small namespaces, but they are useful for diagnostics and for confirming which endpoint you are actually talking to. net_version returns the network ID as a string, and net_peerCount returns the number of connected peers. web3_clientVersion returns the client name and version string.

These methods are almost always enabled because they are cheap and do not expose sensitive state. They are the first thing to call when you are debugging a connection: if net_version returns the wrong network, you are pointed at the wrong endpoint. The Ethereum node identity methods article covers eth_chainId, web3_clientVersion, and related identity calls in more depth.

One subtlety: net_version returns the network ID, which is not always the same as the chain ID returned by eth_chainId. On most networks they match, but they are distinct fields and should not be treated as interchangeable in code.

• net_version — network ID as a string.
• net_peerCount — connected peer count.
• net_listening — whether the node is accepting connections.
• web3_clientVersion — client name and version.
• web3_sha3 — Keccak-256 hash of the input data.

The debug_ Namespace: Node Debugging and Transaction Tracing

The debug_ namespace is where node and client debugging lives. It includes methods for inspecting the node's internal state and, on some clients, tracing transaction execution. debug_traceTransaction returns a trace of a single transaction, and debug_traceCall traces a call without sending it. These are powerful for debugging failed transactions and understanding internal value movement.

The catch is availability. debug_ methods are commonly disabled on shared and managed endpoints because they are expensive and can leak internals. The Geth JSON-RPC documentation describes how namespaces are enabled and notes that the debug, trace, and admin groups are often restricted. If you depend on debug_, you must probe for it first.

The Ethereum transaction tracing with trace and debug article goes deeper into the tracing methods themselves. This reference focuses on where they sit in the namespace map and how to check whether they are available.

• debug_traceTransaction — trace a single transaction.
• debug_traceCall — trace a call without sending it.
• debug_traceBlockByNumber — trace all transactions in a block.
• Availability: commonly disabled on shared endpoints; probe before use.
• Cost: expensive; may be metered or rate-limited differently.

The trace_ Namespace: Parity/OpenEthereum-Style Tracing

The trace_ namespace originated in Parity/OpenEthereum and provides call and block tracing. trace_block returns traces for all transactions in a block, trace_transaction returns traces for a single transaction, and trace_call traces a call. These methods are widely used by analytics and internal-transfer tools because they expose internal value transfers that eth_getLogs does not.

The important caveat is standardisation. trace_ methods are not standardised across clients in the same way eth_ methods are. Their exact parameters and return shapes can differ subtly between execution clients, and some clients implement only a subset. This is documented behaviour that varies by provider and client, so you should verify the shape against your specific endpoint rather than assuming portability.

Because trace_ is expensive, it is frequently disabled on shared endpoints. The same capability probe that checks debug_ should check trace_.

• trace_block — traces for all transactions in a block.
• trace_transaction — traces for a single transaction.
• trace_call — trace a call.
• trace_replayTransaction — replay a transaction and return traces.
• Not standardised across clients; verify return shape per endpoint.

The txpool_ Namespace: Pending-Transaction Inspection

The txpool_ namespace exposes the node's pending-transaction pool. txpool_status returns counts of pending and queued transactions, txpool_content returns the full pool contents, and txpool_inspect returns a summary. This is useful for mempool monitoring, gas estimation, and understanding why a transaction is stuck.

Like debug_ and trace_, txpool_ is not universally enabled. It can be disabled on shared endpoints because it exposes pending transaction data and can be expensive to serialise on a busy node. A capability probe is the right first step.

For a pending transaction, you have two options: txpool_content for a full pool view, or eth_getTransactionByHash with a null block tag for a specific transaction. The latter is in the eth_ namespace and is more likely to be available.

• txpool_status — counts of pending and queued transactions.
• txpool_content — full pool contents.
• txpool_inspect — summary of pool contents.
• Availability: commonly disabled on shared endpoints.
• Alternative: eth_getTransactionByHash with a null block tag.

Choosing the Right Method for a Task

Method selection is easier once you know the namespace map. The table below maps common tasks to the method family that solves them. Start with the eth_ option where one exists, because it is the most likely to be enabled and the most portable across clients.

When a task requires tracing internal value transfers, you move into trace_ or debug_. When it requires pending-transaction inspection, you move into txpool_ or use the eth_ fallback. The OnFinality Learn hub has per-method deep dives for the methods you will use most.

If you are unsure whether an endpoint supports a namespace, do not guess. Run the capability probe in the next section and record the result.

• Read balance → eth_getBalance.
• Simulate a call without sending → eth_call.
• Inspect a pending tx → txpool_content or eth_getTransactionByHash with a null block tag.
• Trace internal value transfers → trace_block or debug_traceTransaction.
• Check network identity → net_version or eth_chainId.
• Check client version → web3_clientVersion.

Probing Namespace Availability with a Node.js Script

Because debug_, trace_, and txpool_ are commonly disabled, a capability probe is mandatory before you depend on them. The script below sends one representative method per namespace to an endpoint and prints a capability matrix with raw errors. It uses only the built-in fetch available in modern Node.js, so there is no dependency to install.

Set the RPC_URL environment variable to your endpoint before running it. The script deliberately does not interpret errors beyond printing them, because the raw error code and message are what you need to record in your results table.

The probe uses eth_chainId, net_version, web3_clientVersion, txpool_status, debug_traceTransaction, and trace_block. The debug and trace probes use a stub transaction hash and block number; a method-not-found error means the namespace is disabled, while a different error may mean the namespace is enabled but the input was invalid.

// 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);

Recording Your Own Namespace Capability Matrix

The probe output is only useful if you record it. Fill the table below for your endpoint and keep it with your integration notes. The error code column is the most important: a -32601 method-not-found usually means the namespace is disabled on that endpoint, not that the method does not exist in the specification.

Run the probe against every endpoint you use, including failover endpoints. Availability can differ between them even within the same provider, and a failover that lacks trace_ will break a tracing feature that works on your primary.

Do not record benchmark numbers you have not measured. The table is for capability, not performance. If you want latency data, measure it separately and label it as your own measurement.

• Namespace — eth, net, web3, debug, trace, txpool.
• Method probed — the representative method you sent.
• Enabled? — yes, no, or error.
• Error code — the JSON-RPC error code, e.g. -32601.
• Notes — provider, client, date, and any caveats.

How Error Codes Differ by Namespace

The JSON-RPC 2.0 specification defines a small set of standard error codes, including -32601 for method not found. In practice, a -32601 response to a debug_ or trace_ method usually means the namespace is disabled on that endpoint, not that the method is absent from the specification. The Decoding the JSON-RPC error object article explains how to read the code, message, and data fields together.

Other codes carry different meanings. A -32602 invalid params error means the namespace is enabled but your arguments are wrong. A -32000 server error can indicate a node-level failure or a rate limit, depending on the provider. The message and data fields often carry provider-specific detail, so log them raw.

The practical rule: treat -32601 as a capability signal, treat -32602 as a request-shape signal, and treat -32000 as a runtime signal. This distinction saves time when you are debugging a failing integration.

• -32601 — method not found; often means the namespace is disabled.
• -32602 — invalid params; namespace enabled, arguments wrong.
• -32000 — server error; node-level failure or rate limit.
• Always log the raw error object, including data.

Limitations and Tradeoffs of Namespace-Dependent Integrations

Namespace availability is provider- and client-specific. There is no universal guarantee that debug_, trace_, or txpool_ will be enabled on any given endpoint, and the same provider may enable them on one plan and not another. Design your integration so that tracing features degrade gracefully when the namespace is unavailable.

trace_ methods are not standardised across clients. Their parameters and return shapes can differ subtly between execution clients, so code that works against one client may need adjustment against another. This is documented behaviour that varies by provider and client, not a bug.

Expensive namespaces may be metered or rate-limited differently from eth_. A trace_block call can be far heavier than a balance read, and providers may apply separate limits. Check the RPC pricing and API service pages for how metering is typically structured, and never assume a tracing call is free because a balance read is.

• Availability varies by provider, plan, and client.
• trace_ is not standardised across clients.
• Expensive namespaces may be metered differently.
• Method semantics can differ subtly between execution clients.
• Design for graceful degradation when a namespace is missing.

Troubleshooting Namespace and Method Failures

When a method fails, the first question is whether the namespace is enabled. Run the capability probe against the endpoint and check the error code. If the probe returns -32601 for debug_ or trace_, the namespace is disabled and no amount of parameter tweaking will fix it.

If the probe returns -32602, the namespace is enabled but your arguments are wrong. Check the parameter count and types against the specification. If it returns -32000, the node is reachable but something failed at runtime; check the message and data fields for detail.

If the probe succeeds but your application still fails, check that you are sending the request to the same endpoint and that your JSON-RPC envelope is well-formed. The Ethereum RPC node guide covers endpoint setup and common connection issues.

• Probe first; do not assume a namespace is enabled.
• -32601 → namespace disabled; switch endpoint or feature.
• -32602 → fix parameter shape.
• -32000 → inspect message and data for runtime detail.
• Verify the endpoint and JSON-RPC envelope.

Next Steps for Namespace-Aware Integrations

Start by running the capability probe against every endpoint you use and recording the results in your own matrix. Then choose methods by task, preferring eth_ where a suitable method exists, and falling back to debug_, trace_, or txpool_ only when the task requires them and the probe confirms availability.

For deeper coverage of specific methods, the OnFinality Learn hub collects the per-method articles, including node identity, block retrieval, and transaction tracing. The Ethereum network page provides the network-level context, and the Ethereum RPC node guide covers endpoint setup.

If you are evaluating providers, check how each one documents namespace availability and metering. The RPC pricing and API service pages describe the OnFinality approach, and the Ethereum transaction tracing with trace and debug article goes deeper on the tracing namespaces.

• Probe every endpoint and record the matrix.
• Prefer eth_ methods where they exist.
• Use debug_, trace_, and txpool_ only when confirmed available.
• Re-probe after provider or plan changes.
• Keep raw error logs for support escalation.