docs: bring release/3.6 to parity — stale flags, missing #22634, disk sizes - #22798
Merged
Conversation
The 3.5 series removed several flag families that the docs never absorbed, so release/3.5 (the deployed branch) still tells users to pass flags that no longer parse. * --p2p.allowed-ports (8 occurrences / 4 files). Removed by #21335 "p2p/sentry: share one p2p.Server across all eth protocols" (in 3.5, not 3.4): all eth protocol versions now share a single p2p.Server, so one listening port set via --port is sufficient. The migrating-from-geth examples are updated accordingly. This also fixes a latent casing bug in that page, which wrote --P2P.allowed-ports; Go flags are case-sensitive. * --clique.checkpoint / .snapshots / .signatures / .datadir. Clique is gone from the tree entirely — no clique package remains. * --diagnostics.endpoint.port and the --diagnostics.* lines in the downloader / sentry / txpool / rpc-daemon --help blocks. Removed by #21351 "cmd/diag, go.mod: remove diag CLI". The "Diagnostics" section of default-ports.md documented only this flag and is dropped with it. * --polygon.sync in the rpc-daemon --help block. Removed by #16035 "Remove unused polygon sync flags"; the polygon flags that remain are polygon.pos.ssf, polygon.pos.ssf.block and polygon.wit-protocol. * --rpc.maxgetproofrewindblockcount.limit in the same block. MaxGetProofRewindBlockCount survives as an internal config field (http_cfg.go, default 100_000) but has no CLI registration, so it is not settable and must not be documented as a flag. Verified per family: no Go string literal and no corresponding identifier on release/3.5, release/3.6 or main, and present through release/3.4 where applicable. Also in this change: * --beacon.api.ide.timeout -> --beacon.api.idle.timeout in caplin.md. The table carried the note "flag name is `ide` not `idle` — typo in source". That was accurate for v3.4, where flags.go really did define "beacon.api.ide.timeout", but #20289 "cmd: fix typo in flag beacon.api.ide.timeout" corrected the source for 3.5 and the note was left behind. Every live branch now defines only beacon.api.idle.timeout, so the flag name is corrected and the note removed. Default (25s) is unchanged and matches Value: 25. * Fix a 404: the Ethereum on ARM GitHub link pointed at diglos/ethereum-on-arm; the project is at diglos/ethereumonarm. * Type two bare code fences (architecture.md, database.md) per the docs style rule, so Prism highlights them. The --help paste blocks had only their obsolete lines removed rather than being regenerated wholesale; regenerating them from freshly built downloader/sentry/txpool/rpcdaemon binaries is worth doing as a follow-up. Pre-push gate: npm ci && npm run build green (onBrokenLinks/onBrokenAnchors throw), generate-llms.py --check OK (74 pages), render-disk-sizes.py --check OK, editorial-artifact scan clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Follow-up to review of this PR (Copilot + two adversarial passes). Wrong information corrected: * caplin.md documented the three Beacon API timeouts as `5s` / `31536000s` / `25s`, but all three are cli.Uint64Flag taking a bare integer number of seconds (Value: 5 / 31536000 / 25). `--beacon.api.idle.timeout=25s` does not parse. Values are now plain integers with "in seconds" in the description. * The Ethereum on ARM repository was transferred: diglos/ethereumonarm now 301-redirects to EOA-Blockchain-Labs/ethereumonarm. Point at the canonical URL rather than relying on the redirect. * default-ports.md still described the pre-#21335 two-listener model — separate `30303` (eth/68) and `30304` (eth/69) Sentry rows, plus prose saying both are typically exposed. Since #21335 there is a single listener on `:30303` serving ProtocolVersion [ETH69, ETH70, ETH71] (nodecfg/defaults.go), and eth/68 is not in the defaults at all. Same stale pair fixed in the default port allocation table of multiple-instances.md. * configuring-erigon.mdx gave `--p2p.protocol` defaults as `68, 69`; the actual default is the full ProtocolVersion slice `69, 70, 71`. * sentry.mdx --help block had two wrong defaults: `--maxpeers` is 64, not 32 (nodecfg/defaults.go MaxPeers), and `--p2p.protocol` is [69,70,71], not 68. * migrating-from-geth.mdx had an unmatched closing parenthesis (Copilot). Note on the diagnostics attribution in the previous commit message: those four flags were NOT removed by #21351, which only deleted the cmd/diag CLI. They last exist on release/3.3 (diagnostics/setup.go) and are already absent on release/3.4, so those docs had been stale since the 3.4 series rather than the 3.5 one. The deletions themselves are unaffected. Pre-push gate re-run: npm ci && npm run build green, generate-llms.py --check OK (74 pages), render-disk-sizes.py --check OK. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…#22634) ## What Documents 14 CLI flags that are registered on the `erigon` binary (present in `node/cli/default_flags.go`) but had no entry on the **CLI Reference** page (`configuring-erigon.mdx`). Found via a full audit of `default_flags.go` → var → CLI name → docs presence. | Flag | Section | Default | |------|---------|---------| | `--keep.stored.chain.config` | General Options | `false` | | `--snap.download.to.block` | Pruning and Snapshots | `0` (disabled) | | `--txpool.queued.dormancy` | Transaction Pool | `3h0m0s` (`0` disables) | | `--ws.max.connections` | RPC & API | `0` (unlimited) | | `--state.stream.disable` | RPC & API | `false` | | `--rpc.logs.querylimit` | RPC & API | `1000` (`≤0` unlimited) | | `--rpc.gethcompat` | RPC & API | `false` | | `--rpc.txsync.defaulttimeout` | RPC & API | `25s` | | `--rpc.txsync.maxtimeout` | RPC & API | `1m0s` | | `--rpc.subscription.filters.timeout` | RPC & API | `5m0s` (`0` disables) | | `--builder.maxblobs` | Consensus and Forks | unset (protocol max) | | `--polygon.wit-protocol` | Consensus and Forks | `false` | | `--caplin.local-discovery` | Caplin | `false` | | `--beacon.api.idle.timeout` | Caplin | `25` (seconds) | ## Verification All defaults verified against `cmd/utils/flags.go` / `node/cli/flags.go` on `main`. Descriptions were fact-checked against the wiring code, which corrected several source `Usage`-string inaccuracies: - `--builder.maxblobs`: the value is a cap on **blobs**; when unset the protocol maximum applies, and an explicit `0` excludes blob transactions entirely (`execution/builder/exec.go`). - `--beacon.api.idle.timeout`: wired to `http.Server.IdleTimeout` (keep-alive idle timeout); the source `Usage` string mislabels it as a "write time out" (copy-paste from `--beacon.api.write.timeout`). - `--polygon.wit-protocol`: **not** auto-enabled for Bor chains in current code (Bor is a precondition, not an auto-enabler) — the source `Usage` string is stale. `llms-full.txt` regenerated; `pnpm build` (npm) green locally. ## Notes - Dual-commit counterpart of #22633 (→ `release/3.5`). This PR additionally documents `--rpc.subscription.filters.timeout`, which is main-only (the flag does not exist on `release/3.5`). - Source `Usage`-string bugs for `--beacon.api.idle.timeout` and `--polygon.wit-protocol` are worth a separate code fix. Co-authored-by: Bloxster <gianni.morselli@erigon.tech>
release/3.6 still carried the 2025-09-01 manual figures, because the release/3.5 refresh (#22640) was never ported under the dual-commit rule — roughly eleven months of drift on a page users size hardware from. Copies disk-sizes.json from release/3.5 (mainnet and gnosis, all three modes, measured 2026-07-19 and 2026-07-21) and re-renders the static markers in hardware-requirements.mdx with render-disk-sizes.py. These are the v3.5 measurements rather than fresh v3.6 ones, which keeps a single consistent set of numbers across the live branches. For reference, the minimal-mode CI runs on release/3.6 and main currently measure higher (mainnet ~458-468 GB, gnosis ~256-257 GB against the 379 GB / 204 GB carried here), so these values are conservative for v3.6 and should be replaced once v3.6 has its own full-mode measurements. render-disk-sizes.py --check and generate-llms.py --check both pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the release/3.6 documentation set to match main/release/3.5 parity by removing documentation for flags that no longer exist, adding missing CLI reference entries (from #22634), and refreshing the measured disk-usage figures (via disk-sizes.json + re-rendered static markers).
Changes:
- Remove stale documentation for deleted flags (e.g.,
--p2p.allowed-ports,--diagnostics.*, clique-related flags,--polygon.sync, and a non-registered--rpc.maxgetproofrewindblockcount.limit). - Add missing CLI reference documentation for multiple registered flags (e.g.,
--keep.stored.chain.config,--rpc.gethcompat,--ws.max.connections,--beacon.api.idle.timeout). - Refresh disk size measurements and propagate them through the generated
llms-full.txtoutputs and the hardware requirements page.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| llms-full.txt | Regenerated aggregated docs output to reflect updated flags, ports, and disk sizes. |
| docs/site/static/llms-full.txt | Same as root llms-full.txt, for the docs site’s static output. |
| docs/site/src/data/disk-sizes.json | Updates measured disk usage bytes/display values and measurement dates. |
| docs/site/docs/get-started/migrating-from-geth.mdx | Removes --p2p.allowed-ports references and updates migration guidance accordingly. |
| docs/site/docs/get-started/installation/index.mdx | Updates the “Ethereum on ARM” GitHub link to the current canonical repo. |
| docs/site/docs/get-started/hardware-requirements.mdx | Updates disk-usage figures via static markers and refreshed measurement dates. |
| docs/site/docs/fundamentals/multiple-instances.md | Updates the port allocation table to the single-listener P2P model (30303 only). |
| docs/site/docs/fundamentals/modules/txpool.md | Removes stale --diagnostics.* flags from the txpool help block. |
| docs/site/docs/fundamentals/modules/sentry.mdx | Removes stale --diagnostics.*/--p2p.allowed-ports and updates defaults shown in the help block. |
| docs/site/docs/fundamentals/modules/rpc-daemon.md | Removes stale --diagnostics.*, --polygon.sync, and non-registered --rpc.maxgetproofrewindblockcount.limit from the help block. |
| docs/site/docs/fundamentals/modules/downloader.mdx | Removes stale --diagnostics.* flags from the downloader help block. |
| docs/site/docs/fundamentals/default-ports.md | Updates default ports guidance to the single P2P listener model; removes diagnostics section. |
| docs/site/docs/fundamentals/configuring-erigon.mdx | Adds missing flag docs (from #22634) and removes obsolete flags from the CLI reference page. |
| docs/site/docs/fundamentals/caplin.md | Fixes Beacon API timeout units (seconds as integers) and corrects the idle-timeout flag name. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The erigon binary registers --p2p.protocol as a slice (Value: DefaultConfig.P2P.ProtocolVersion), so "69, 70, 71" in configuring-erigon.mdx is right. The standalone sentry binary registers it as a single uint defaulting to Value[0] — cmd/sentry/main.go:68, UintVar(..., P2pProtocolVersionFlag.Value[0], ...) — which is ETH69 = 69 (p2p/protocols/eth/protocol.go:39). An earlier commit in this PR over-corrected that help block from "(default 68)" to "(default [69,70,71])"; it reads "(default 69)". The --maxpeers 32 -> 64 correction in the same block stands: cmd/sentry/main.go:70 takes MaxPeersFlag.Value, which is nodecfg.DefaultConfig.P2P.MaxPeers = 64. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
AskAlexSharov
approved these changes
Jul 29, 2026
lupin012
pushed a commit
to cshintov/erigon
that referenced
this pull request
Jul 30, 2026
… flag, disk sizes (erigontech#22799) The `main` side of this week's documentation maintenance (w31). Carries the same stale-flag cleanup as erigontech#22793 (`release/3.5`) and erigontech#22798 (`release/3.6`) under the dual-commit rule, plus three findings that apply only to `main`. ## 1. Flags removed from the code but still documented Identical to erigontech#22793 — see that PR for the per-family provenance: * `--p2p.allowed-ports` — 8 occurrences / 4 files, removed by erigontech#21335 *"share one p2p.Server across all eth protocols"*; a single `--port` now suffices. Also fixes the `--P2P.allowed-ports` casing bug. * `--clique.checkpoint` / `.snapshots` / `.signatures` / `.datadir` — clique is gone from the tree. * `--diagnostics.*` — last present on `release/3.3`, already absent from `release/3.4`. * `--polygon.sync` — removed by erigontech#16035. * `--rpc.maxgetproofrewindblockcount.limit` — an internal config field with no CLI registration. ## 2. Wrong information corrected Also identical to erigontech#22793: Beacon API timeouts are bare integer seconds (`25`, not `25s` — they are `cli.Uint64Flag`, so `25s` does not parse); the pre-erigontech#21335 two-listener port model removed from `default-ports.md` and `multiple-instances.md`; `--p2p.protocol` default is `69, 70, 71`; `--maxpeers` default is 64; the Ethereum on ARM link now points at the canonical `EOA-Blockchain-Labs/ethereumonarm`; one unmatched parenthesis. ## 3. `--db.read.concurrency` semantics — `main` only erigontech#22408 *"node, commitment: fix parallel exec deadlock on many-core machines"* rewrote this flag's behaviour, and three pages said the opposite of what the code does. Each parallel-execution worker holds a long-lived read transaction, so a ceiling below the worker count would deadlock. The value is silently **raised** to the worker count, and lowering the flag does not reduce read concurrency at all — `--exec.workers` is the knob for that. The docs advised the reverse: *"Low values are fine for low read-concurrency nodes (for example, validators)"*. Verified against source rather than the commit message: the clamp is `cmd/utils/flags.go:2041` (`RoTxsLimit(c, cfg.ExecWorkerCount)`), and the existing *"HTTP/WebSocket fail fast with an overload response"* wording is **still accurate** (`rpc/http.go:241`, `httpOverloadedKey` / `kv.ErrReadTxLimitExceeded`), so it is kept rather than dropped along with the rest. Does not apply to `release/3.5` or `release/3.6`, which predate erigontech#22408. ## 4. `--witness.cache.blocks` — new today erigontech#22384 *"rpc/jsonrpc: eager in-memory cache for `debug_executionWitness`"* registered `utils.WitnessCacheBlocksFlag` earlier today, leaving the CLI reference one flag behind. It trades memory for `debug_executionWitness` latency, so it is operator-facing and in scope per the flag-coverage rule. Documented from the source `Value`/`Usage`: default `0` (disabled), clamped at `96`, embedded RPC only, requires commitment history. The source `Usage` names the `--prune.experimental.include-commitment-history` alias; the docs use the canonical `--prune.include-commitment-history`. ## 5. Disk sizes `disk-sizes.json` is brought in line with `release/3.5` (mainnet and gnosis, all three modes, measured 2026-07-19 / 2026-07-21) and the static markers in `hardware-requirements.mdx` re-rendered with `render-disk-sizes.py`, so the live branches carry one consistent set of numbers. ## Verification * `npm ci && npm run build` — green (`onBrokenLinks` and `onBrokenAnchors` both `throw`) * `generate-llms.py --check` — OK, 4 files, 74 pages * `render-disk-sizes.py --check` — OK * Step-4c bidirectional sweep — **233 registered, 10 undocumented**, i.e. the intentionally-undocumented internal/dev baseline, with no stale flags remaining * No `allowed-ports` / `diagnostics.` / `clique.` / `beacon.api.ide` / `polygon.sync` / `maxgetproofrewind` / `eth/68` references left in `docs/site/docs` --------- Co-authored-by: Bloxster <gianni.morselli@erigon.tech> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Alex Sharov <AskAlexSharov@gmail.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
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.
release/3.6was cut frommainatafada21637on 2026-07-21 13:26 UTC, and #22634 — themainside of last week's CLI-reference fix — merged at 2026-07-22 03:01 UTC, about fourteen hours later. The new branch therefore shipped without it, and a Step-4c sweep onrelease/3.6reported 24 undocumented registered flags against a baseline of 10.This PR brings
release/3.6up to parity: the same stale-flag cleanup being applied torelease/3.5in #22793, plus the missing #22634 documentation, plus the disk-size refresh that was never ported.1. Flags removed from the code but still documented
Identical to #22793 (see that PR for the per-family provenance):
--p2p.allowed-ports— 8 occurrences / 4 files, removed by p2p/sentry: share one p2p.Server across all eth protocols #21335 "share one p2p.Server across all eth protocols"; one--portnow suffices. Also fixes the--P2P.allowed-portscasing bug.--clique.checkpoint/.snapshots/.signatures/.datadir— clique is gone from the tree.--diagnostics.*— last present onrelease/3.3, already absent fromrelease/3.4.--polygon.sync— removed by Remove unused polygon sync flags #16035.--rpc.maxgetproofrewindblockcount.limit— an internal config field with no CLI registration.The
--db.read.concurrencyhelp text in the rpc-daemon block is kept at therelease/3.6wording, not therelease/3.5one.2. Wrong information corrected
Also identical to #22793: Beacon API timeouts are bare integer seconds (
25, not25s—cli.Uint64Flag, so25sdoes not parse); the pre-#21335 two-listener port model removed fromdefault-ports.mdandmultiple-instances.md(one listener on:30303serving[ETH69, ETH70, ETH71]);--p2p.protocoldefault is69, 70, 71;--maxpeersdefault is 64; the Ethereum on ARM link points at the canonicalEOA-Blockchain-Labs/ethereumonarm; one unmatched parenthesis.3. The missing #22634 — 14 flags
Cherry-picked as-is. Documents
--beacon.api.idle.timeout,--builder.maxblobs,--caplin.local-discovery,--keep.stored.chain.config,--polygon.wit-protocol,--rpc.gethcompat,--rpc.logs.querylimit,--rpc.subscription.filters.timeout,--rpc.txsync.defaulttimeout,--rpc.txsync.maxtimeout,--snap.download.to.block,--state.stream.disable,--txpool.queued.dormancyand--ws.max.connections.After this, the Step-4c sweep on
release/3.6reports 10 undocumented — the same baseline of intentionally-undocumented internal/dev flags asmain(--chaos.monkey,--dev-validator-*,--etl.bufferSize,--miner.extradata, and similar).4. Disk sizes
disk-sizes.jsonis brought in line withrelease/3.5(mainnet and gnosis, all three modes, measured 2026-07-19 / 2026-07-21) and the static markers inhardware-requirements.mdxre-rendered withrender-disk-sizes.py, so the live branches carry one consistent set of numbers.Verification
npm ci && npm run build— green (onBrokenLinksandonBrokenAnchorsboththrow)generate-llms.py --check— OK, 4 files, 74 pagesrender-disk-sizes.py --check— OKallowed-ports/diagnostics./clique./beacon.api.ide/polygon.sync/maxgetproofrewind/eth/68references left indocs/site/docs