docs: document erigondb domain merge cap flag [main] by bloxster · Pull Request #21130 · erigontech/erigon

bloxster · 2026-05-12T07:29:00Z

Summary

Current main has migrated away from GitBook to Docusaurus. This PR now resolves the previous GitBook conflict by accepting the GitBook removal from main and carrying the surviving docs fix into the current Docusaurus page.

Change

Adds --erigondb.domain.steps-in-frozen-file to docs/site/docs/fundamentals/configuring-erigon/index.mdx.

Source-of-truth check

This PR targets main, so the flag was verified against origin/main:

cmd/utils/flags.go defines ErigondbDomainStepsInFrozenFileFlag with name erigondb.domain.steps-in-frozen-file.
node/cli/default_flags.go registers it for the main erigon binary.

Conflict resolution

docs/gitbook/src/fundamentals/configuring-erigon/README.md was deleted on current main; the PR accepts that deletion and does not reintroduce GitBook.
The prior RPC default and Caplin docs updates are already present in the Docusaurus configuring page on current main.

Local checks

git diff --check origin/main...HEAD passes.
npm --prefix docs/site run typecheck could not run locally because docs/site dependencies are not installed in this worktree (tsc missing); CI should run the docs-site checks.

🤖 Generated by weekly docs maintenance routine

bloxster · 2026-05-12T09:02:33Z

⚠️ Fix needed before merging: --erigondb.domain.steps-in-frozen-file was incorrectly removed from this PR. The flag exists on main (registered in node/cli/default_flags.go, added via PR #20705 on 2026-04-21). The removal is correct for release/3.4 (#21129) but must be reverted here.

Lines to restore in docs/gitbook/src/fundamentals/configuring-erigon/README.md after --sync.parallel-state-flushing:

* `--erigondb.domain.steps-in-frozen-file value`: Overrides the `steps_in_frozen_file` setting from `erigondb.toml` for the domain merge cap only (history and inverted-index merges are unaffected). Pass a positive integer to set an explicit cap, or `Inf` to leave the domain merge unbounded.
  * Default: unset (uses the value from `erigondb.toml`)
  * Use with care — an incorrect value may affect database structure.

yperbasis

TL;DR: One factual error to fix before merge — the rest of the diff is correct. The PR was regenerated from a v3.4.1 binary on release/3.4, so it drops a flag (--erigondb.domain.steps-in-frozen-file) that exists on main's target binary.

Verification against current `main`

Claim in PR	Source	Status
`--rpc.subscription.filters.maxlogs` default → `10000`	`rpc/rpchelper/config.go:35`	✅ correct
`--rpc.subscription.filters.maxheaders` default → `10000`	`rpc/rpchelper/config.go:36`	✅ correct
`--rpc.subscription.filters.maxtxs` default → `10000`	`rpc/rpchelper/config.go:37`	✅ correct
`--log.dir.verbosity` default → `dbug`	`node/logging/flags.go:69` + `common/log/v3/logger.go:36`	✅ correct
`--caplin.nat` exists, accepted values	`cmd/utils/flags.go:880` + `p2p/nat/nat.go:69`	✅ correct
`--caplin.columns-keep-slots` default `131072` (~18 days)	`cmd/utils/flags.go:1030-1034`	✅ correct
`--erigondb.domain.steps-in-frozen-file` removed as stale	`cmd/utils/flags.go:1149` + `node/cli/default_flags.go:268`	❌ wrong on `main`

Critical issue — `erigondb.domain.steps-in-frozen-file` is not stale on `main`

The PR description says the flag was "removed in v3.4 source." That's apparently true on release/3.4 — the v3.4.1 commit 6fdfdb7b has no ErigondbDomainStepsInFrozenFile symbol. But this PR targets main, where:

cmd/utils/flags.go:1149 defines the flag.
node/cli/default_flags.go:268 registers it on the main erigon binary.
PR #21025 (merged 2026-05-07, five days before this PR) actively extended the flag into integration stage_exec and erigon seg retire.
PR #20730 originally added its documentation block — which this PR now reverses.

The regenerated #Options block was produced from a v3.4.1 binary, so it understandably doesn't list the flag. The result is documentation on main that contradicts main's source.

Options to fix:

Preferred: regenerate the #Options block from a main-built erigon binary so all of main's flags are documented, and restore the erigondb.domain.steps-in-frozen-file entry. The bot should source its dump from HEAD, not the latest tag.
Acknowledge in the PR title/description that this gitbook docs update on main intentionally mirrors v3.4.1 (since gitbook is slated for removal in #21013) and the flag-set divergence is accepted. I'd recommend against this — gitbook is still the published docs for main until #21013 lands.

Smaller observations

caplin.nat accepted-values list: the PR enumerates \"\", extip:1.2.3.4, stun, stun:<host>, upnp, pmp, pmp:192.168.0.1. The upstream p2p/nat.Parse also accepts the aliases none/off/any/auto/on/natpmp/nat-pmp. The source-level Usage string at cmd/utils/flags.go:880 doesn't list them either, so this is consistent — but worth a thought for completeness.
Overlap with --caplin.enable-upnp: the doc still lists both --caplin.enable-upnp (bool) and --caplin.nat (which itself accepts upnp/pmp). Setting both is confusing; not introduced by this PR, but a one-line note in the caplin.nat blurb pointing users at the preferred form would help.
r3.4 PR includes a nat.md smart-quote fix that this PR doesn't carry. Probably because gitbook doesn't have the equivalent file, so this is fine.
Style: the new caplin.nat entry is one dense sentence followed by inline backticks. A short bullet list of accepted values (matching the gitbook style of the other long blurbs in this file) would render more clearly. Not a blocker.

Risks

If merged as-is, operators reading docs.erigon.tech (which serves gitbook from main) won't see the --erigondb.domain.steps-in-frozen-file override knob even though main's binary supports it. That's a performance-tuning flag with a "use with care" advisory — losing it from the docs is a real regression for ops.

Recommendation

Don't merge until the #Options block is regenerated from a main-built erigon binary (so the live flag set on main is documented). The rest of the inline edits are correct and can stand once the dump is refreshed.

bloxster · 2026-05-13T09:28:02Z

Addressed the blocking review point in 5d7164b:

Restored the curated --erigondb.domain.steps-in-frozen-file documentation entry because the flag exists on main.
Verified the current diff against origin/main no longer removes that flag; it now only updates the RPC subscription defaults and adds the two Caplin entries.
Updated the PR body to remove the stale claim that the verbatim # Options block was regenerated from v3.4.1.

Local check: git diff --check.

# Conflicts: # docs/gitbook/src/fundamentals/configuring-erigon/README.md

bloxster · 2026-05-13T09:56:17Z

Resolved the current main conflicts in 937b379.

Resolution details:

Accepted the GitBook deletion from current main; the PR no longer reintroduces docs/gitbook/src/fundamentals/configuring-erigon/README.md.
Ported the surviving docs fix to Docusaurus: docs/site/docs/fundamentals/configuring-erigon/index.mdx now documents --erigondb.domain.steps-in-frozen-file.
Verified the flag still exists and is registered on origin/main (cmd/utils/flags.go + node/cli/default_flags.go).
The final diff against origin/main is one docs file, 3 added lines.

Local check: git diff --check origin/main...HEAD passes. npm --prefix docs/site run typecheck could not run locally because docs/site dependencies are not installed in this worktree (tsc missing); CI should cover docs-site validation.

Copilot

Pull request overview

Updates the Docusaurus CLI reference to document the --erigondb.domain.steps-in-frozen-file flag, which overrides the steps_in_frozen_file value from erigondb.toml specifically for the domain merge cap (leaving history and inverted-index merges unchanged).

Changes:

Adds documentation for --erigondb.domain.steps-in-frozen-file, including semantics and default behavior.
Notes safe-usage guidance and that the default is unset (falls back to erigondb.toml).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

bloxster added 2 commits May 12, 2026 09:28

docs: May 2026 w20 — v3.4.1 update [main]

056837c

docs: May 2026 w20 — v3.4.1 update [main]

f20de8b

bloxster requested review from AskAlexSharov and yperbasis as code owners May 12, 2026 07:29

bloxster added the docs label May 12, 2026

docs: remove #Options verbatim block update (keep flag doc changes only)

933f425

bloxster added 2 commits May 12, 2026 11:38

Merge branch 'main' into docs/may-2026-w20-v341-update-main

c867fa0

Merge branch 'main' into docs/may-2026-w20-v341-update-main

3e35d24

bloxster marked this pull request as draft May 12, 2026 10:52

yperbasis requested changes May 12, 2026

View reviewed changes

docs: restore main erigondb flag

5d7164b

bloxster marked this pull request as ready for review May 13, 2026 09:28

bloxster changed the title ~~docs: May 2026 w20 — v3.4.1 update [main/gitbook]~~ docs: May 2026 w20 update [main/gitbook] May 13, 2026

Merge remote-tracking branch 'origin/main' into pr-21130

937b379

# Conflicts: # docs/gitbook/src/fundamentals/configuring-erigon/README.md

bloxster changed the title ~~docs: May 2026 w20 update [main/gitbook]~~ docs: document erigondb domain merge cap flag [main] May 13, 2026

yperbasis requested a review from Copilot May 13, 2026 11:25

Copilot started reviewing on behalf of yperbasis May 13, 2026 11:25 View session

Copilot AI reviewed May 13, 2026

View reviewed changes

yperbasis approved these changes May 13, 2026

View reviewed changes

AskAlexSharov added this pull request to the merge queue May 13, 2026

Merged via the queue into main with commit 3df4579 May 13, 2026
65 checks passed

AskAlexSharov deleted the docs/may-2026-w20-v341-update-main branch May 13, 2026 13:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: document erigondb domain merge cap flag [main]#21130

docs: document erigondb domain merge cap flag [main]#21130
AskAlexSharov merged 7 commits into
mainfrom
docs/may-2026-w20-v341-update-main

bloxster commented May 12, 2026 •

edited

Loading

Uh oh!

bloxster commented May 12, 2026

Uh oh!

yperbasis left a comment

Uh oh!

bloxster commented May 13, 2026

Uh oh!

bloxster commented May 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

bloxster commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Change

Source-of-truth check

Conflict resolution

Local checks

Uh oh!

bloxster commented May 12, 2026

Uh oh!

yperbasis left a comment

Choose a reason for hiding this comment

Verification against current main

Critical issue — erigondb.domain.steps-in-frozen-file is not stale on main

Smaller observations

Risks

Recommendation

Uh oh!

bloxster commented May 13, 2026

Uh oh!

bloxster commented May 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bloxster commented May 12, 2026 •

edited

Loading

Verification against current `main`

Critical issue — `erigondb.domain.steps-in-frozen-file` is not stale on `main`