op-reth: remove unsupported --minimal option (breaking change)

[claude]

Requested by Josh Klopfenstein · Slack thread

Stacked on #22108 (base = claude/op-reth-cli-snapshot-test, so CI here includes the CLI surface snapshot test). Retarget to develop after #22108 merges.

Before

op-reth accepted the upstream reth flag

--minimal

which enables maximum pruning, including pruning block bodies to a fixed 10,064-block window. op-node reads the L1-info deposit transaction from historical block bodies during derivation, so a node running with it eventually fails EL sync with

l2 block is missing L1 info deposit tx

The docs told operators not to use the flag, but nothing enforced that.

After (breaking change)

op-reth now rejects the flag. A node started with it exits immediately with an error (BLOCKS placeholders shown in angle brackets in the real output):

error: --minimal is not supported by op-reth and has been removed.

It prunes block bodies to a fixed 10,064-block window, which breaks op-node derivation
(op-node reads the L1-info deposit transaction from historical block bodies).

For a pruned (non-archive) node, use the supported pruning recipe instead:
  --prune.minimum-distance BLOCKS
  --prune.receipts.distance BLOCKS
  --prune.account-history.distance BLOCKS
  --prune.storage-history.distance BLOCKS
Do NOT prune block bodies.

See https://docs.optimism.io/node-operators/guides/management/archive-node#pruning-op-reth

The flag is also hidden from all op-reth help output.

Operator impact: any node previously running with the flag will now exit at startup with the message above. Such datadirs were already in an unsupported state (bodies pruned) and need a resync to a supported configuration regardless — the hard error surfaces that instead of letting the node keep running toward a derivation failure.

How

The flag lives in upstream reth arg structs that op-reth reuses, so it cannot be removed at the type level. The in-tree cli crate instead gets a small deny-list in rust/op-reth/crates/cli/src/lib.rs: a DENIED_ARGS const of (subcommand, argument id, error message) entries, currently containing the single entry (node, minimal, MINIMAL_REMOVED_HELP). Future entries from the #21687 audit are one-line additions. The list is applied in two places:

• Parse time: the clap command is built with denied args hidden, and after parsing, any denied arg that was passed on the command line produces the hard error above (clap still accepts hidden args, hence the post-parse check). All shared parse entrypoints route through this — parse_args, try_parse_args_from, and the new parse_with_denied_args now used by the op-reth binary — so denial is the default behavior of the shared crate, not an opt-in call sites must remember.
• Run time backstop: CliApp::run rejects a parsed node command with the flag set. This covers binaries that construct their clap command directly instead of using the shared parse methods — specifically the vendored op-rbuilder, whose launcher parses itself but runs through CliApp::run. op-rbuilder therefore also refuses to start with the flag, though its own help output still lists it (its vendored code builds the command from CommandFactory directly and is slated for deprecation, so it was left untouched).

Unit tests cover the parse-time rejection (error kind and message), that the flag is absent from rendered node help, and that the adjacent pruning flags still parse. The CLI surface snapshot from #22108 now renders the flag with a [hidden] marker, documenting the deny decision, and the snapshot-regen note in rust/UPDATING-RETH.md tells future reth bumpers that deny-listed flags must stay rejected.

The bin crate no longer uses clap directly after switching entrypoints, so its clap dependency edge is dropped (workspace lockfile entry updated by hand; clap itself stays in the graph).

Docs

Minimal prose updates to say op-reth rejects the flag at startup instead of do-not-use: archive-node.mdx, execution-clients.mdx, network-architecture.mdx.

The generated CLI reference page docs/public-docs/node-operators/op-reth/cli/op-reth/node.mdx was deliberately left untouched: it is generated from the compiled binary help output, there is no in-repo generator that runs without building op-reth, and the page is already stale relative to the current reth pin (e.g. it shows the old --full help text mentioning MINIMUM_PRUNING_DISTANCE where the pinned source now says MINIMUM_UNWIND_SAFE_DISTANCE, and it predates several engine/rollup flags). It needs a proper regen by someone who can build the binary; when that happens the --minimal entry disappears automatically.

Refs #21687