Lesson 17 — The Reth extension pattern — library, not fork

Question

Reth as a library, not a fork. Extend without forking the codebase. Use the NodeBuilder + trait impls; track upstream.

Principle (minimum model)

• Library pattern. Import Reth as Cargo.toml dep; instantiate NodeBuilder; customise via trait impls. Upstream upgrades = bump version.
• Fork pattern (anti-pattern). Clone Reth; modify in-tree; diverge from upstream. Hard to track upstream; freeze the version.
• Why library wins. Smaller maintenance burden; track upstream; community ecosystem.
• OP Stack uses library. OP-Reth = Reth + custom executor + custom chainspec. Tracks Reth upstream.
• bera-reth uses library. Custom Consensus impl + chainspec. Tracks upstream.
• Tempo uses library. Custom Pool + custom precompiles. Tracks upstream.
• Anti-pattern: forking. Some custom L1s fork. Heavy maintenance burden; upstream improvements blocked.

Worked example + steps

The Reth extension pattern — library, not fork

If you've worked with op-geth, bsc-geth, or bor (Polygon), you know the geth-fork story: clone the upstream, apply your patches, rebase forever. Every upstream merge is a weekend of conflict resolution, and the audit surface drifts away from mainline.

Reth was designed to make this model obsolete. Optimism, Base, Berachain, Scroll, Seismic, Sova, and Tempo all run on Reth (as did Paradigm's 2024 research testnet alphanet, now archived) — and most of them are not forks in the traditional sense. op-reth, Tempo, Berachain (bera-reth) and Sova are node crates that depend on reth as a library and override the parts they care about via traits. The exceptions are instructive: Scroll's client (scroll-tech/reth, branch scroll) is a GitHub fork 358 commits ahead of upstream (2026-10) with its code in crates/scroll/, and seismic-reth is likewise a full copy of the reth repo with crates/seismic/ added.

1. The two models

Reth's whole architecture is built around the second model. The NodeBuilder / components / ChainSpec pattern you saw in the Intermediate course exists precisely so that you never have to patch reth's source to ship a chain.

2. Why Paradigm chose this

Paradigm builds Reth and built its research testnet alphanet (2024, now archived) on it; Reth's core maintainers are also among the top contributors to Tempo. They are their own customer. Three forces pushed them toward the extension model:

1. Rebase pain is real. op-geth is a long-lived geth fork that must rebase on every upstream release. The OP Stack's Reth-based client, op-reth, is built from reth crates instead — it lived inside reth as crates/optimism/ until Feb 2026 (reth PR #21532) and now lives in ethereum-optimism/optimism under rust/op-reth.
2. Audit surface. An auditor reading a fork has to diff against upstream and reason about every patch. An auditor reading a node crate sees one repo, one set of traits implemented.
3. Composability. Berachain wants reth + custom consensus. Scroll wants reth + zk-friendly state. Seismic wants reth + encrypted txs. The extension model lets all three coexist; the fork model forces each to maintain their own divergent copy — which is exactly what Scroll and Seismic still do today.

The result: reth's trait architecture is the API for building a chain.

3. What you actually customize

A Reth-based chain typically overrides these slots:

• ChainSpec — fork heights, gas params, precompile schedule, genesis
• ConfigureEvm / block execution strategy — execution layer, custom precompiles, deposit-tx handling
• PayloadBuilder — how blocks get produced (sequencer mode for L2s)
• Pool / mempool policy — what txs are admitted, in what order
• Custom RPC namespaces — exposing chain-specific endpoints via extend_rpc_modules
• Custom consensus — for non-Ethereum-PoS chains

Everything else (P2P, MDBX storage, staged sync, ExEx, trie commitments) comes from reth for free.

4. Concrete examples to read

Order them from "shipped to mainnet" → "R&D":

1. op-reth in ethereum-optimism/optimism under rust/op-reth (in reth's crates/optimism/ until Feb 2026) — Optimism / Base / Mode / OP Stack. The most production-tested extension on the planet.
2. tempoxyz/tempo — a payments L1 built on the Reth SDK; its Cargo.toml pins upstream paradigmxyz/reth crates by git rev rather than a fork. (Paradigm's earlier research testnet paradigmxyz/alphanet is archived — it moved to ithacaxyz/odyssey in 2024, which has had no pushes since 2025-07.)
3. SovaNetwork/sova-reth — Reth as a Bitcoin execution layer.
4. berachain/bera-reth — Berachain's execution client; its Cargo.toml depends on paradigmxyz/reth by tag, with chainspec / consensus / evm / pool / rpc in its own src/.

For contrast, SeismicSystems/seismic-reth (encrypted transactions) and scroll-tech/reth keep a full copy of the reth repo, so their diff is spread across a fork.

Each of the four is a study in "what's the smallest patch the chain needs?" The answer is usually a few thousand lines in a node crate, not a fork of 200k lines of execution client.

5. Why this matters for what you're building

If you are building anything that touches a Reth-based chain — a bridge, a settlement layer, a custom node, a sequencer integration — you need to read at the trait level, not the binary level. The question "how does Tempo handle X?" reduces to "which trait does Tempo's node crate override, and how?"

Tempo's source is now public at tempoxyz/tempo, and you should read it through the lens of that question: "which of these standard slots did they customize, and why?" One concrete data point before you open it: tempoxyz/reth is 0 commits ahead, 2686 behind (2026-10) upstream Paradigm Reth — they did not fork Reth at all. Every payments-specific customization lives in the tempoxyz/tempo crate as a dependency-level extension.

6. Practice

1. Open reth's workspace Cargo.toml and find every crate matching reth-optimism-*
2. Note what each one owns (chainspec? evm? payload? rpc?)
3. List the 6 customization slots you'd fill to ship a real chain
4. Identify which one is "the consensus-rules-of-my-chain" slot

You should now be able to read any Reth-based chain repo without flinching at the directory structure.

Final check: in one sentence, what is the structural reason a Reth-based chain rarely needs to patch reth's source? If your answer doesn't reference trait-based extension and NodeBuilder composition, the lesson hasn't stuck. Re-read sections 1 and 2.

Summary (3 lines)

• Reth as a library, not a fork. Import + customise via trait impls + track upstream.
• Library examples: OP-Reth / bera-reth / Tempo. All track Reth upstream.
• Fork pattern is anti-pattern: heavy maintenance, upstream improvements blocked. Next: op-stack-on-reth.