Running an OP Stack L2 with reth

An OP Stack rollup looks intimidating until you see that it’s four long-running processes wired to an L1, and one shared secret holding two of them together. I had a half-finished deployment of one — op-stack-reth, a docker-compose setup using reth as the execution client instead of the usual op-geth — and I finished it. The interesting parts were what “finishing” meant.

The four processes and the handshake

op-reth     execution layer — runs the EVM, holds L2 state, serves eth_* RPC
op-node     consensus layer — derives the L2 chain from L1, drives block production
op-batcher  posts L2 transaction batches down to L1 (as blobs)
op-proposer posts L2 state roots to L1 (so withdrawals can be proven)

The handshake is the part worth internalizing. op-node doesn’t execute transactions; op-reth doesn’t decide what the chain is. They talk over the Engine API — the same engine_forkchoiceUpdated / engine_getPayload interface Ethereum L1 uses between its consensus and execution clients — and that interface is authenticated with a JWT secret the two share. op-node says “build a block on top of this head”; op-reth builds and executes it; op-node says “this is now canonical.” That’s the whole dance. Everything else — the batcher, the proposer — is about getting that L2 chain onto L1 so it inherits Ethereum’s security.

op-node and op-reth share the Engine API (authenticated by a JWT); op-node also derives the chain from L1, while the batcher and proposer push data and state roots back down to L1.

What “finishing it” actually meant

The deployment mostly existed. What it lacked was everything that makes infra trustworthy rather than just present:

Every image was :latest. That’s a time bomb — docker compose pull six months apart gives you two different rollups, and one of them won’t boot. I pinned all six (op-reth, op-node, batcher, proposer, prometheus, grafana) to released, env-overridable tags tracking op-contracts v4.0.0.
Genesis was a manual chore. The README said “generate genesis.json and rollup.json using the Optimism monorepo” — a clone-and-pray step. The modern answer is op-deployer: one tool that deploys the L1 contracts and emits both files. I wired it into a make config so the path from nothing to a configured chain is a single command.
A real config bug. In replica mode, reth’s --rollup.sequencer-http defaulted to the node’s own op-node. A replica is supposed to forward transactions to the external sequencer; pointing it at itself is a quiet footgun. Fixed.

The part that caught bugs was CI, not me

Here’s the honest bit. I can’t run Docker in my environment, so I can’t boot the chain to prove it works — and I said so in the README, in a “what’s verified vs what needs Docker” section, rather than implying a green I didn’t earn. What I could do is make the repo verify itself: a make validate (script syntax, YAML, JSON) that runs anywhere, plus a CI workflow that adds shellcheck, yamllint, and crucially docker compose config on GitHub’s runners.

And the first thing CI did was fail — on my own scripts. shellcheck flagged the validation script I’d just written: an unguarded cd, a loop that could only run once, an unchecked source. bash -n had passed them happily; shellcheck didn’t. I fixed the three, pushed, and watched docker compose config validate the pinned compose file on a machine that actually had Docker — the one check I couldn’t run myself, now green.

That’s the whole reason to wire up CI on an infra repo you can’t fully exercise locally: it runs the checks your laptop can’t, and it has no investment in your code being correct. The finalized deployment boots a reth-powered OP Stack L2 in replica or sequencer mode; the green check next to it is the part I didn’t have to take on faith.