docs: experimental commitment flags + db.read.concurrency help fix - #22415
Merged
Conversation
…y help Weekly docs maintenance (w29), main / future v3.6. configuring-erigon.mdx (Execution section): - Document --experimental.parallel-commitment and --experimental.streaming-commitment (both new, registered in node/cli/default_flags.go, previously undocumented). Streaming takes precedence over parallel per the flag Usage. modules/rpc-daemon.md: - Fix the stale --db.read.concurrency line in the rpcdaemon --help listing. #21762 corrected the flag Usage in cmd/utils/flags.go (used by the rpcdaemon subcommand via config.go), but the reproduced help block still showed "equal to GOMAXPROCS ... (default 1408)". Updated to the actual formula min(max(10, GOMAXPROCS*64), 9000) and dropped the machine-specific default value. Regenerated llms-full.txt (static + repo root); generate-llms.py --check passes (74 pages). Docusaurus build green (onBrokenLinks: throw). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- rpc-daemon.md: reframe the flag listing as a non-verbatim summary (was "reproduced below"), so the corrected db.read.concurrency line no longer conflicts with a verbatim-snapshot claim; add the "extra readers wait for a slot" behavior from the source Usage. (must-fix, both reviewers) - configuring-erigon.mdx: separate the commitment flags from the --exec.* block with a "Commitment-trie construction" lead-in so the section's "all --exec.* new in v3.5" preamble no longer mis-scopes them. - Add *(New in v3.6)* version markers (page convention) to all three new flags — avoids "flag not defined" surprises on a v3.5 binary. - parallel-commitment: "hasher" -> "fully parallel ParallelPatriciaHashed" (matches source "trie"); document COMMITMENT_PARALLEL env twin. - streaming-commitment: note it has no env equivalent; "if set" wording. - Document --commitment.plainValues under Database and Caching (fresh- datadir, one-time, per-datadir format choice). Regenerated llms-full.txt; --check OK (74 pages); build green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Documentation maintenance for upcoming v3.6: adds operator-facing documentation for newly introduced commitment-trie/DB flags and updates the RPC Daemon docs to avoid presenting a hand-edited --help excerpt as verbatim, while correcting the stale --db.read.concurrency help description.
Changes:
- Document
--experimental.parallel-commitment,--experimental.streaming-commitment(incl. precedence) and--commitment.plainValueswith “New in v3.6” markers. - Update
modules/rpc-daemon.mdto present the flag list as a non-verbatim summary and refresh the--db.read.concurrencydescription/formula. - Regenerate/update
llms-full.txtoutputs to reflect the docs changes.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| llms-full.txt | Updates generated LLM-facing docs output with new flag docs and rpcdaemon help-summary edits. |
| docs/site/static/llms-full.txt | Same as llms-full.txt, for the docs site static artifact. |
| docs/site/docs/fundamentals/modules/rpc-daemon.md | Reframes --help excerpt as non-verbatim and updates --db.read.concurrency line. |
| docs/site/docs/fundamentals/configuring-erigon.mdx | Adds new v3.6 flag documentation for commitment-trie construction and commitment plain-values regime. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
rpc-daemon.md: the summary line claimed excess DB readers "wait for a slot rather than error", but rpcdaemon's HTTP/WS RPC paths fail fast (kv.ErrReadTxLimitExceeded via kv.WithNonBlockingAcquire) when the read-tx semaphore is full. Reword to match configuring-erigon.mdx:75: readers wait, though RPC paths (HTTP/WebSocket) fail fast with an overload response. Regenerated llms-full.txt; --check OK (74 pages); build green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
bloxster
marked this pull request as ready for review
July 13, 2026 05:52
Make the third site-wide mention consistent with configuring-erigon.mdx and modules/rpc-daemon.md — same "ceiling on concurrent open MDBX read transactions (read-tx semaphore)" framing and raise/low-values guidance, keeping the datadir-sharing context. Now one consistent description of the flag across the docs. Regenerated llms-full.txt; --check OK (74 pages); build green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
AskAlexSharov
requested changes
Jul 13, 2026
AskAlexSharov
left a comment
AskAlexSharov
left a comment
Collaborator
There was a problem hiding this comment.
ceiling on - it's phrase from advanced English. Better don't use it when working on International product.
"Ceiling on" reads as advanced/idiomatic English. Replace with "Maximum number of" across all three db.read.concurrency descriptions (configuring-erigon.mdx, modules/rpc-daemon.md, database.md) so the wording is plain and consistent for an international audience. Regenerated llms-full.txt; --check OK (74 pages); build green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Collaborator
Author
|
@AskAlexSharov good catch — fixed in d783cda. Replaced "ceiling on" with "Maximum number of" in all three |
AskAlexSharov
approved these changes
Jul 13, 2026
github-merge-queue
Bot
removed this pull request from the merge queue due to failed status checks
Jul 13, 2026
pull Bot
pushed a commit
to Dustin4444/erigon
that referenced
this pull request
Jul 29, 2026
…rigontech#22848) One-line change to the `--db.read.concurrency` help text. The flag claimed a behaviour the code does not have. ## The problem `cmd/utils/flags.go:407` said: > extra readers wait for a slot **rather than error** That is only true for callers that do not opt into fail-fast acquisition. The RPC layer does: * `rpc/websocket.go:83` tags every WebSocket connection context with `kv.WithNonBlockingAcquire`, unconditionally. * `node/rpcstack.go:87-90` tags HTTP requests whenever the admission handler is active — which is the default: `--rpc.max.concurrency` defaults to `0` (`cmd/utils/flags.go:410-414`), and `cmd/rpcdaemon/cli/config.go:764-775` resolves `0` to `db.read.concurrency`, always ≥ 10. * `db/kv/mdbx/kv_mdbx.go:700-705` then takes the `TryAcquire` branch and returns `kv.ErrReadTxLimitExceeded` immediately instead of blocking. * `rpc/handler.go:631-639` remaps that to JSON-RPC `-32005`, and `rpc/http.go:239-241` surfaces it as HTTP 503 with `Retry-After`. So under read-tx exhaustion an operator gets an overload response, not a stalled request — the opposite of what `--help` promised. ## The fix Only the second clause changes; the rest of the string is untouched: > extra readers wait for a slot **by default, though some RPC paths (HTTP/WebSocket) fail fast with an overload response** ## Why "some RPC paths" rather than naming HTTP outright Deliberate hedge. These HTTP-served paths do **not** fail fast: | Path | Where | Behaviour | |---|---|---| | Engine API (auth) HTTP | `config.go:1001-1005` — built `limit=0, tagAsRPC=false`, with a comment saying so | blocks | | GraphQL | `config.go:952-956` routes `/graphql` before the tagged handler | blocks | | Healthcheck | `config.go:958-961`, same | blocks | | Unix/TCP socket transport | `config.go:742-762`, no tag | blocks | | Public HTTP with `--rpc.max.concurrency=-1` | admission control disabled | blocks | A tighter phrasing such as *"JSON-RPC over HTTP/WebSocket fails fast"* was considered and rejected: the Engine API **is** JSON-RPC over HTTP and deliberately blocks, so that wording would be wrong in a new way. `some RPC paths` is vague but true; the exhaustive list belongs in prose docs, not a help string. ## Relationship to erigontech#22799 This closes a source↔docs divergence that exists on `main` today. `docs/site/docs/fundamentals/modules/rpc-daemon.md:51` already describes the fail-fast behaviour (merged in erigontech#22415) while the Go string still claimed the opposite. Open PR erigontech#22799 refines that same docs sentence; the string in this PR is **byte-identical (548 chars)** to what erigontech#22799 lands, so once both merge, `erigon --help` and the docs help block agree verbatim. The two PRs are independent and can merge in either order — no docs generator reads the Go source (`generate-llms.py` derives the exports from the markdown pages), so nothing needs regenerating here. ## Testing * `go build ./cmd/utils/` and `go vet ./cmd/utils/` — clean. * No test, golden file, fixture, or docs generator asserts on this string or on `--help` output, so nothing else changes. Verified across `cmd/utils/flags_test.go`, `node/cli/helpers_test.go`, and a tree-wide search for the literal. * `cmd/utils/flags.go:407` is the only definition and the only occurrence in Go sources. ## Two pre-existing issues noticed, not addressed here Both are out of scope for a help-string fix; happy to file issues or follow-up PRs if wanted. 1. **Engine API over WebSocket fails fast, contradicting the intent stated for Engine over HTTP.** `createEngineListener` deliberately leaves the engine HTTP stack untagged so CL↔EL calls block (`config.go:1001-1005`), but its WS handler goes through `engineSrv.WebsocketHandler` → the unconditional tag at `rpc/websocket.go:83`. A CL speaking engine-over-WS can receive `-32005` under read-tx exhaustion. Related: the comment at `config.go:1001` refers to "TxPriorityRPC", an identifier that no longer exists anywhere in the tree — the mechanism is `kv.WithNonBlockingAcquire`. 2. **The unchanged tail understates the floor.** It says a value below the parallel-exec worker count "is raised to it", but `RoTxsLimit` floors at `execWorkers + 23` (5 permanent + 2 read-ahead + 16 reserve — `cmd/rpcdaemon/cli/httpcfg/http_cfg.go:38-62`). erigontech#22799 repeats the same simplification in the docs, so correcting it means touching both. Co-authored-by: Bloxster <gianni.morselli@erigon.tech>
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.
What
Weekly docs maintenance (w29), targeting
main(future v3.6). Documents newly-added CLI flags and fixes a stalerpcdaemon --helpline.configuring-erigon.mdx--experimental.parallel-commitmentand--experimental.streaming-commitment(both new, innode/cli/default_flags.go, previously undocumented). Streaming takes precedence over parallel per source;COMMITMENT_PARALLELis the env twin of the parallel flag (streaming has none).--commitment.plainValuesunder Database and Caching — a one-time, per-datadir fresh-start format choice (ignored onceerigondb.tomlexists).*(New in v3.6)*markers per the page convention, so v3.5 users aren't surprised by "flag not defined".modules/rpc-daemon.md--db.read.concurrencyhelp line was stale ("equal to GOMAXPROCS … (default 1408)"); cmd/utils: fix db.read.concurrency help to match the actual default #21762 corrected the source Usage (the rpcdaemon subcommand reusesutils.DBReadConcurrencyFlag.Usageviacli/config.go:134). Updated to the actualmin(max(10, GOMAXPROCS*64), 9000), including the fail-fast overload behavior on RPC paths.--helpdump is misleading; runrpcdaemon --helpfor the authoritative, host-dependent listing.database.md--db.read.concurrencytuning-knob description with the two pages above (same "ceiling on concurrent open MDBX read transactions (read-tx semaphore)" framing), so the flag is now described consistently across the whole site.Review
Adversarially reviewed by three independent passes — ChatGPT 5.5, Fable, and GitHub Copilot. All must/should-fix items folded in: verbatim-block reframing, section-scope separation,
*(New in v3.6)*markers,parallel trie(not "hasher") wording, theCOMMITMENT_PARALLELenv twin, documenting--commitment.plainValues, and Copilot's catch that RPC read paths fail fast (kv.ErrReadTxLimitExceeded/kv.WithNonBlockingAcquire) rather than always waiting.Verification
python3 docs/site/scripts/generate-llms.py --check→OK: 4 llms files match regenerated content (74 pages).docs/siteDocusaurus build green (onBrokenLinks: 'throw').cmd/utils/flags.goonorigin/main; registration confirmed innode/cli/default_flags.go; fail-fast behavior confirmed inrpc/handler.go/rpc/http.go/rpc/websocket.go.🤖 Generated with Claude Code