Running an Ethereum node

Three decisions, made before you touch a machine, because each one changes the hardware by an order of magnitude and two of them cannot be changed later without a resync.

Full or archive

A full node has every block and can compute current state; an archive node keeps historical state so it can answer eth_getBalance at block 5,000,000 without replaying the chain. If you do not know that you need archive, you do not: it multiplies the disk requirement and most applications never ask a question that needs it. What providers actually serve is measured here in rungs, which is a good way to calibrate what “deep enough” means for you.

Validating or not

A validator has keys, duties, penalties and an entirely different risk profile. An RPC node has none of those and should have no keys on it at all. Keep them separate machines, always — the failure modes have nothing to do with each other, and combining them means an RPC traffic spike can cost you attestations.

Which pair of clients

Decided in the Ethereum clients article. It determines the disk footprint, the sync method and which non-standard methods exist, so it comes before sizing rather than after.

That covers both halves of the node together, and it is a full node, not an archive one. The stated minimum is lower — 2 cores, 8 GB, 2 TB — and a node built to the minimum spends its life almost out of disk, which is the condition under which a node fails at the least convenient moment.

Ethereum is the cheapest of the three chains measured here to run. BNB Smart Chain asks for roughly four times the machine, and a Solana RPC node is not really comparable at all.

Naively, a new node replays history from genesis. Nobody does that any more, and the shortcuts are the difference between an afternoon and a fortnight.

1. 1

   Start the consensus client from a checkpoint

   Checkpoint sync fetches a recent finalised state from a trusted URL instead of walking the beacon chain from the start, turning days into minutes. You are trusting whoever serves the checkpoint for exactly one thing — the state root you start from — and you can verify it against a second source, which is worth doing precisely because it is cheap.

2. 2

   Let the execution client sync against it

   With the consensus client following the head, the execution client syncs to it: snap sync on Geth and Reth, staged sync on Erigon. This is the long part, and it is disk-bound rather than network-bound — a slow SSD extends it far more than a slow connection.

3. 3

   Then wait, and watch the gap close

   A syncing node answers RPC quickly and wrongly — with state from where it has got to, not from the head. That is exactly the failure this platform counts as a failure rather than as latency, and it is why the first thing to monitor is not uptime but distance from the head.

The execution and consensus clients authenticate to each other with a shared secret. Both need the path to the same file, and it is generated once:

install -d -m 0750 /etc/ethereum
openssl rand -hex 32 > /etc/ethereum/jwtsecret
chmod 0640 /etc/ethereum/jwtsecret

Then point both processes at it. The shape, with Geth and Lighthouse:

# Execution client. Note --http.addr: see "exposing RPC" below.
geth \
  --syncmode snap \
  --authrpc.jwtsecret /etc/ethereum/jwtsecret \
  --http --http.addr 127.0.0.1 --http.api eth,net,web3

# Consensus client, started from a checkpoint rather than from genesis.
lighthouse bn \
  --execution-endpoint http://127.0.0.1:8551 \
  --execution-jwt /etc/ethereum/jwtsecret \
  --checkpoint-sync-url https://<a checkpoint provider you trust>

Peer-to-peer — must be reachable

Execution 30303 TCP and UDP, consensus 9000 by convention. Forward these. A node that cannot accept inbound peers still works, and is a worse citizen and a slower sync.

Engine API — must not be reachable

8551, between your two clients, on localhost. It is authenticated with the secret above precisely because control of it is control of what your node believes.

JSON-RPC — your decision, and the one people get wrong

8545 HTTP and 8546 WebSocket on the execution client, 5052 for the consensus client’s Beacon API. Read exposing RPC without giving it away before you bind any of these to anything but localhost.

Run both under a supervisor that restarts them — systemd units or a container runtime with a restart policy. Two details matter more than the choice between them: give the process a generous shutdown timeout, because a client killed mid-write can require a resync, and make sure the two units do not both restart into a state where each is waiting for the other.

The work does not end at sync. Ethereum forks on a schedule set by other people, and a client that is not upgraded in time does not degrade — it follows the wrong chain, or stops. Both halves need upgrading, and not always at the same time.

• Subscribe to both clients’ releases. Not the ecosystem newsletter — the two specific repositories whose binaries you run. That is where a fork-critical release is announced with an actual deadline attached.
• Pin versions and know how to roll back. Automatic upgrades on a node are how a bad release becomes your outage at the same moment it becomes everyone else’s.
• Watch the disk trend, not the disk. “80% full” is not an alert; “80% full and gaining a percent a week” is a date in your calendar.

When it is running and you want to know whether it is right, continue to knowing your node is healthy. When one node is no longer enough, serving RPC at scale picks up from here.