Skip to content

Correct fundamentals docs facts and regenerate llms artifacts#21559

Merged
bloxster merged 2 commits into
docs/architecture-database-main-2026-05-28from
copilot/update-docs-factual-corrections
Jun 1, 2026
Merged

Correct fundamentals docs facts and regenerate llms artifacts#21559
bloxster merged 2 commits into
docs/architecture-database-main-2026-05-28from
copilot/update-docs-factual-corrections

Conversation

Copilot AI commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

This updates the two new fundamentals pages to resolve the remaining factual review comments on PR #21500. It corrects inaccurate descriptions in the architecture/database docs and brings the generated llms-full.txt artifacts back in sync with the source pages.

  • Architecture diagram

    • Remove the incorrect private gRPC edge between TxPool and Caplin
    • Keep the existing TxPool -> Datadir relationship unchanged
  • Database tuning guidance

    • Rewrite --batchSize to describe what it actually controls: the Execution stage in-memory buffer flushed to MDBX
    • State the actual default (512M)
    • Make the example direction consistent by describing --batchSize 1G as an increase, not a decrease
  • Snapshot sizing breakdown

    • Clarify that the listed subdirectories are only the state/history portion of snapshots/
    • Explain that the missing ~1.2 TB is primarily block/transaction .seg data so the 2.3 TB total is internally consistent
  • MDBX reference

    • Replace the dead external MDBX link with Erigon’s maintained erigontech/mdbx-go repository
  • Generated artifacts

    • Regenerate llms-full.txt and docs/site/static/llms-full.txt so the committed artifacts reflect the corrected page text

Example of the corrected tuning guidance:

- **`--batchSize`** — size of the Execution stage's in-memory buffer before it is flushed to MDBX. Default: `512M`. Raising it (for example `--batchSize 1G` or higher) can speed up execution-heavy sync at the cost of more RAM.
Original prompt

Address the unresolved factual corrections from yperbasis's review (CHANGES_REQUESTED) on PR #21500. The two new docs pages live at docs/site/docs/fundamentals/architecture.md and docs/site/docs/fundamentals/database.md. Two of his six points are already fixed; the FOUR below remain and must be corrected. These are text-only edits — do NOT restructure the pages.

  1. --batchSize example is backwards and mis-framed (docs/site/docs/fundamentals/database.md, "Tuning knobs" section). The current text says: "controls how much state Erigon buffers in RAM before flushing to MDBX. Default is balanced; lower it (e.g. --batchSize 1G) if chaindata/ grows unexpectedly." This is wrong on two counts:

    • The default --batchSize is 512M (see node/cli/flags.go:48), so --batchSize 1G raises it, it does not "lower it".
    • --batchSize is the execution-stage RAM buffer; it has nothing to do with chaindata/ growing. That rationale is dubious and should be dropped.
      Reword to accurately describe --batchSize as the execution-stage in-memory buffer (default 512M) that is flushed to the DB, e.g. raising it (--batchSize 1G or higher) can speed up execution-heavy sync at the cost of more RAM. Make the example direction consistent with the description.
  2. Mermaid diagram has a factually wrong edge (docs/site/docs/fundamentals/architecture.md, the mermaid block in "At a glance"). The line TxPool <-- private gRPC --> Caplin is incorrect: the TxPool does NOT talk to Caplin (the consensus layer). Its gRPC relationship is with the core/Sentry, not the CL. Remove this Caplin↔TxPool edge. (Note: an earlier Copilot review suggested ADDING such an edge — that suggestion was wrong; follow yperbasis here and remove it.) Keep TxPool -.reads.-> Datadir. Ensure the diagram still renders and no dangling/duplicate node definitions remain.

  3. Snapshot sizing does not add up (docs/site/docs/fundamentals/database.md, "What does it cost on disk?" code block). The listed directories sum to ~1.13 TB (accessor 120 + domain 300 + history 280 + idx 430 GB) but the block says snapshots TOTAL 2.3 TB. The gap is the unlisted block/transaction .seg files. Either add the missing rows (e.g. blocks/transactions segment files) so the numbers reconcile to ~2.3 TB, or add a short note that the breakdown is partial and the remainder is block/transaction .seg data. Keep it honest and consistent.

  4. Likely dead link (docs/site/docs/fundamentals/database.md, "Storage engine: MDBX" section). The MDBX link https://github.com/erthink/libmdbx points to a repo that was taken down. Erigon vendors github.com/erigontech/mdbx-go. Replace the link target with https://github.com/erigontech/mdbx-go (keep the visible link text "MDBX"). Note onBrokenLinks only validates internal links, so the build won't catch external dead links.

After editing, regenerate the llms artifacts if the build requires it and ensure npm run build (run from docs/site/) passes with onBrokenLinks/onBrokenAnchors: 'throw'. The llms.txt, llms-full.txt, and their docs/site/static/ copies should reflect the corrected page text.

Copilot AI changed the title [WIP] Address unresolved factual corrections from review on PR #21500 Correct fundamentals docs facts and regenerate llms artifacts Jun 1, 2026
Copilot AI requested a review from bloxster June 1, 2026 12:30
@bloxster bloxster marked this pull request as ready for review June 1, 2026 12:35
@bloxster bloxster merged commit 57242bd into docs/architecture-database-main-2026-05-28 Jun 1, 2026
@bloxster bloxster deleted the copilot/update-docs-factual-corrections branch June 1, 2026 12:35
@yperbasis

Copy link
Copy Markdown
Member

@bloxster this was merged not into main, but some other branch.

@bloxster

bloxster commented Jun 1, 2026

Copy link
Copy Markdown
Collaborator

@bloxster this was merged not into main, but some other branch.

It's ok, it was meant to update #21500

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants