docs: clarify --serveHistoricalState and --chain.pruneHistory help text - #9328
Merged
nflaig merged 5 commits intoMay 6, 2026
Merged
Conversation
…lp text The current --help descriptions are too terse and lead to confusion about what these flags actually do. - --serveHistoricalState: clarify that it only spawns a regen worker for states the node already has; it does not backfill any historical data. Mention the related --chain.archiveStateEpochFrequency tradeoff. - --chain.pruneHistory: state the actual retention boundary (MIN_EPOCHS_FOR_BLOCK_REQUESTS, 33024 epochs / ~5 months on mainnet) and that all archived states before finalized are pruned too. 🤖 Generated with AI assistance
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request updates the CLI help descriptions for serveHistoricalState and chain.pruneHistory to provide more detailed information about their functionality and performance implications. Feedback suggests avoiding hardcoded default values and network-specific constants in these descriptions to prevent maintenance issues and user confusion on non-mainnet networks.
…n.pruneHistory help text Drop hardcoded `1024` default for `--chain.archiveStateEpochFrequency` in the `--serveHistoricalState` description (already documented on the flag itself), and prefix the `MIN_EPOCHS_FOR_BLOCK_REQUESTS` example with `e.g.,` to make it clear those are mainnet-specific values (2048 epochs on Sepolia/Holesky). 🤖 Generated with AI assistance
nflaig
reviewed
May 6, 2026
…uneHistory - Drop "Spawn a worker thread to" prefix from --serveHistoricalState; the worker-thread implementation detail isn't relevant for operators. - Replace em-dash with comma in the same description for consistency with the rest of the help text. - Revert the "e.g.," qualifier on `MIN_EPOCHS_FOR_BLOCK_REQUESTS` per reviewer preference; restore the original "33024 epochs / ~5 months on mainnet" wording. 🤖 Generated with AI assistance
nflaig
reviewed
May 6, 2026
…istoricalState The help text said "debug REST API" but --serveHistoricalState enables state regeneration for any state-dependent endpoint, not only the /eth/v2/debug/* namespace. 🤖 Generated with AI assistance
nflaig
reviewed
May 6, 2026
Apply Nico's wording suggestion on the prune-history help text.\n\n🤖 Generated with AI assistance
nflaig
approved these changes
May 6, 2026
nflaig
changed the title
nflaig
enabled auto-merge (squash)
May 6, 2026 12:57
Member
|
@lodekeeper seems like this is not correctly formatted on the docs page, see screenshot 
|
2 tasks
Contributor
Author
|
Good catch — root cause is Filed a hotfix in #9334 swapping |
nflaig
pushed a commit
that referenced
this pull request
May 6, 2026
## Summary Fix the broken docs render for the `--serveHistoricalState` help text on the docs site (reported in [PR #9328](#9328 (comment))). Replaces `{state_id}` with `head` in the example URL. ## Root cause `packages/cli/docsgen/markdown.ts:7` `sanitizeDescription()` HTML-encodes `{` → `{` and `}` → `}` globally — including text inside backtick code spans. Markdown code spans render their contents as literal text, so the encoded entities never decode back to `{` and `}` — users see `{state_id}` verbatim on the docs page. This is the only `{...}` placeholder I added in #9328. Sidestepping by using `head`, which is a valid `state_id` value (the user can substitute any other real value: `genesis`, `finalized`, `<slot>`, etc.). ## Follow-up The `sanitizeDescription` function should be fixed properly so future descriptions can use `{...}` placeholders (and `<...>` placeholders) without breaking docs rendering. Filing this as a separate concern — out of scope for this hot-fix. ## Test plan - [x] Locally verified the diff is the single-line change in `chain.ts`. - [ ] After merge: confirm the docs page renders the `serveHistoricalState` help text without HTML entity codes. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: lodekeeper <lodekeeper@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
The current
--helptext for--serveHistoricalStateand--chain.pruneHistoryis too terse, which leads to confusion about what these flags actually do. This came up in a question from yorickdowne on Discord about backfill semantics. Nico explained both flags in chat and asked for the help docs to be improved so users don't have to dig into the docs site.Description
Updates both descriptions in
packages/cli/src/options/beaconNodeOptions/chain.ts:--serveHistoricalState: clarifies that it only spawns a worker thread to regenerate states the node already has on demand (i.e. since genesis sync or--checkpointState); it does not backfill historical data. Also notes the regeneration cost tradeoff with--chain.archiveStateEpochFrequency.--chain.pruneHistory: states the actual retention boundary (MIN_EPOCHS_FOR_BLOCK_REQUESTS= 33024 epochs / ~5 months on mainnet) and clarifies that archived states before the finalized epoch are also pruned.No behavior changes —
--helptext only.Steps to test or reproduce
Closes #N/A