For the complete documentation index, see llms.txt. This page is also available as Markdown.

Tier 4: Control Access

Only known clients, only allowed methods. Required for nodes with debug or trace.

Goal: only known clients can reach the node, and each client can only call the methods it needs. Required for any node with debug or trace enabled, including "private" nodes.

Validators: skip this tier, except the network rules in 4.3.

Who can do this tier.

Unlike Tiers 1–3, this tier isn't copy-and-paste. It needs someone who can run and maintain a web proxy (such as nginx), manage TLS certificates, and read JSON-RPC requests.

The proxy is the main thing standing between attackers and debug/trace, and a small mistake in its rules can silently let dangerous requests through. If nobody on your team can own that, don't enable debug/trace on your own nodes. Use a provider that offers tracing, or contact the Sonic team at [email protected].

Why "private" isn't enough

A node with no public access can still be attacked. "Private" usually means "anyone on the internal network can call it": every server, every laptop on the VPN, every CI job. Common ways an attacker ends up "inside":

  • An internal app that passes user input to the node. Block explorers, indexers, transaction simulators, and "trace this transaction" features often take parameters from public users and forward them to debug_trace*. To the node, the attack looks like it comes from your own app. Check every internal app that calls debug_*/trace_* and make sure it never forwards user-supplied tracer settings.

  • A compromised developer laptop, CI runner, or other server on the same network.

  • A VPN account shared too widely.

Treat the node's RPC like a database: authenticated, limited to known clients, every call logged.

4.1 Separate public and private nodes

  • Public nodes: standard methods only (eth, net, web3, sonic, ...). Never debug/trace.

  • Debug/trace nodes: separate machines, reachable only through the proxy below, only by named internal clients.

Don't mix the two roles on one machine.

4.2 Put a filtering proxy in front of the node

The node listens only on 127.0.0.1 (Tier 1.3). A proxy on the same machine is the only thing reachable from the network. The proxy must:

  1. Identify the client. Use an API key per client (or client certificates/mTLS). Reject requests without one.

  2. Allow only listed methods, per client. Deny everything else by default. This includes every item in a batch request, not just the first.

  3. For debug_trace*, allow only built-in tracers that can't run code from the request (callTracer, prestateTracer, 4byteTracer, flatCallTracer, or no tracer). Reject any other tracer value. A custom JavaScript tracer is just text, so anything that isn't an exact name from this list must be rejected.

    Don't allow muxTracer, even though it's built in: it takes a list of other tracers inside its settings, and the node treats any name it doesn't recognize as JavaScript code.

    If you turned custom tracers on (Tier 1.2), allow them only for the clients that need them.

  4. Limit size and rate: maximum request size, batch size, requests per second per client, concurrent trace calls.

  5. Log client, source IP, method, and (for rejected requests) the request body.

  6. Read each request exactly the way the node does, or reject it. The node ignores upper/lower case in field names (Tracer and tracer are the same to it), and when a field appears twice it uses the last one. A proxy that reads requests differently can be fooled: it checks one value, and the node uses another. Reject requests with unexpected top-level fields, field names that differ only in case, and field names with unusual characters.

WebSocket: simple proxies can't inspect WebSocket messages. On debug/trace nodes, keep debug/trace out of --ws.api, or disable --ws entirely.

A worked example using nginx is in Appendix D. Any proxy that can read JSON request bodies works; the six requirements are what matter.

4.3 Network layout

Set these rules in your cloud firewall / security groups / network switches. Server-level rules (Tiers 1–3) can be undone by an attacker who gains full control of the server; network-level rules can't.

From
To
Allowed

Internet

Node

Peer-to-peer port (5050 TCP/UDP) only. For public RPC nodes: also the RPC or proxy port.

Named internal clients

Node

Proxy port only

Monitoring server

Node

Metrics port only, never the profiling port (see 1.3)

Admin VPN / bastion

Node

SSH only

Node

Internal networks

Nothing, except specific services it truly needs (e.g. DNS)

Node

Internet

Allowed (needed for peers)

Validators: the same rules apply without the RPC rows. From the internet, only the peer-to-peer port; from internal clients, nothing.

Ideally, put RPC nodes and validators in their own network segments (subnet/VLAN), separate from each other and from databases, CI and office networks.

4.4 Limit expensive calls

Tracing is expensive and can be used to overload the node. In the proxy, limit concurrent debug_trace* calls per client. In the node, keep the built-in limits on, and lower them if your clients allow it:

Flag
Limits
Default

--rpc.timeout, --rpc.evmtimeout

How long a call may run

5s

--rpc.gascap

Gas for eth_call / eth_estimateGas

50,000,000

--rpc.batch-request-limit

Requests in one batch

1000

--rpc.batch-response-max-size

Bytes returned by one batch

25,000,000

--rpc.tracefilterrange

Blocks covered by one trace_filter call

1000

--rpc.structloglimit

Opcode log entries in one debug trace

2000

Don't set any of them to 0: for most of them, 0 means unlimited.

✅ Tier 4 checklist

Last updated