doc: add full node operator guide - #87
Conversation
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
- Summary: Doc-only PR adding
docs/node/full-node.md(414 lines) and onedocs/SUMMARY.mdentry. Coverage, tone, and cross-links all read well. - Inline comments: 4 anchorable findings — one Major (quickstart RPC bind exposes privileged namespaces on
0.0.0.0), two Minor (metric type inconsistency; likely--target_block_numbertypo), one Nit (placeholder convention).
Pre-mortem (unverified):
docs/node/full-node.md:241— Verify thatmega_*methods really are merged into every enabled transport regardless of--http.apion the actualmega-rethbuild. If not, monitoring against the recommended--http.apiset (which does not listmega) silently returns-32601and validator-halt alerts never fire.docs/node/full-node.md:132,320— Verifymega-rethbehavior when--datadiris explicitly set and opened against a different--chain. The current wording ("used as-is when set") could invite cross-chain reuse; if the binary does not refuse, add a warning.
Verification reminder: the PR description acknowledges that flags, defaults, metric names, and log strings from the permissioned mega-reth repo are unverified. Please record the mega-reth commit SHA the tables were compared against before merging — a stale metric name silently kills Prometheus alerts, and a stale flag name breaks the copy-pasteable quickstart.
Still open from earlier reviews: none.
- Bind the quickstart JSON-RPC example to loopback with eth,net,web3 and warn about exposing admin/debug/trace/txpool on a public interface - Label the validator duration metrics as Prometheus summaries and explain that histogram_quantile() does not apply to them - Add replay-full and verifier to the node types table - Note that index_db is created for full-node, rpc-node, and replay-full - Use an angle-bracket placeholder for the reth_db_table_size label
There was a problem hiding this comment.
- Summary: Reviewed the added full-node operator guide and its
docs/SUMMARY.mdentry. - Inline comments: 1 anchorable finding.
- Prior thread on the
reth_db_table_sizelabel placeholder has been addressed and was resolved.
Pre-mortem (unverified):
docs/node/full-node.md:83and:250— Verify against the currentmega-rethbuild thatmega_*methods really are merged into every enabled RPC transport regardless of--http.api. The quick-start--http.api eth,net,web3and themega_getValidatedChainmonitoring recipe both depend on this. If the current build gatesmega_*on the namespace list, the monitoring probe will silently return-32601and alerting recipes built from this page will not detect a stalled validator.docs/node/full-node.md:397— Verify the exact wording of the startup error. The doc quotes--node-type full requires at least one --validator.rpc-urls, but the documented--node-typevalues arefull-node/rpc-node/etc. — there is nofull. If the real error string usesfull-node, operators grepping the exact string will miss this troubleshooting entry.
The replayer, replay-full and verifier roles are internal and not open to external operators, so drop them from the table and say plainly that it lists the roles operators can actually run. Also stop claiming index_db is exclusive to full-node and rpc-node, and apply prettier formatting.
Re-verified the page against mega-reth ba30a29a6
(liquan/perf/fullnode-state-sync-validator). Flags, defaults, log lines and
anchor resolution are unchanged; the metrics surface and delta-mode
fallbacks grew.
- Document the metrics added on the branch: validation_salt_update_seconds,
anchor_fallback_full_total, failures_panic_total, canonical_lag_seconds,
and the report-to pair publisher_active / publish_failures_total{peer}
- Delta mode has two fallback causes now (missing changeset row, missing
parent anchor), each with its own counter; note it never runs unanchored
- Split the fallback troubleshooting entry to say which counter means what
- Note that mega_getValidatedChain reports anchor=null on an rpc-node and
tip=null until the first attestation lands
- Fix the initial-sync anchor sentence, which claimed the validator anchors
at the first synced head rather than the last finalized block
"latest" resolved to 0.24.2 on CI and 0.23.0 locally, and include_fragments changed type in 0.24 (bool -> string), so lychee.toml could only parse on one of them. Pin 0.23.0: it is the newest release whose macOS assets still match the aqua registry, so it installs on both CI and Apple Silicon.
There was a problem hiding this comment.
🧭 Re-review update
- Reviewed incremental changes since 12b9243 (metrics additions, delta-mode fallback split, node-types table trim, systemd
MEGARETH_BOOTSTRAP_POLICY=required,.mise.tomllychee pin +lychee.tomlfragments type flip). - No new actionable findings on this pass. Cross-links resolve, terminology is consistent, and the anchor-resolution / delta-fallback rewrites read cleanly.
Still open from earlier reviews:
--target_block_numbershould be kebab-case — the snake_case spelling is still present atdocs/node/full-node.md:432, and every other flag on the page is kebab-case. If the binary rejects the unknown token, the operator hits it onmega-reth recovery, which the warning right below flags as destructive. Verify againstmega-reth recovery --helpand update.
Pre-mortem (unverified):
docs/node/full-node.md:377,383— verify the sampleTimeoutStopSec=120still bounds the worst-case flush window on a large Mainnet datadir. The same paragraph notesMEGARETH_CRITICAL_WAIT_SECS=Nextends the critical-task budget to5 + Nseconds, so an operator raisingNpast ~115 for a heavy datadir would silently overshootTimeoutStopSec, triggering systemd SIGKILL escalation mid-flush while the doc separately states RocksDB runs with the WAL disabled.tables-heighton the copy catches the resulting inconsistency, but the sample unit itself does not tie the two knobs together. Consider recommendingTimeoutStopSec=infinity(or wiring it toMEGARETH_CRITICAL_WAIT_SECS) in the example.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
❓ Review complete — 2 open question(s)
Reviewed head 17f186a4.
Doc PR adds docs/node/full-node.md, one SUMMARY.md entry, pins lychee to 0.23.0, and reverts include_fragments to the 0.23-era bool syntax.
Open questions:
❓ Open question · Medium confidence
- Do
mega_*RPC methods really surface on every enabled transport regardless of the--http.apinamespace list on the currentmega-rethbuild? - Why it matters: The quick-start uses
--http.api eth,net,web3and the monitoring section instructs operators to callmega_getValidatedChainover that same transport. If the current build gatesmega_*behind the--http.apilist (as vanilla reth does for other namespaces), the documented monitoring recipe and validator-halt alerting silently return-32601and operators never see a stalled validator. - How to verify: In the
mega-rethsource, check where themega_*RPC module is registered on the HTTP/WS server (look forRpcModule::merge/server_buildercalls around themeganamespace) and confirm it is added unconditionally, not gated on theSelectionderived from--http.api. Alternatively, start a node with--http.api eth,net,web3and confirm a curl ofmega_getValidatedChainreturns a result rather than method-not-found.
❓ Open question · Low confidence
- Does
mega-reth noderefuse to open an existing data directory when--chainpoints at a different network than the one that populated it? - Why it matters: docs/node/full-node.md:174 says an explicitly passed
--datadiris used as-is (only the OS default appends the chain ID), and the systemd example hard-codes/var/lib/megaeth/full-node. If the binary does not refuse cross-chain reuse, an operator who reruns the same unit against a different--chain(e.g. swapping Testnet genesis for Mainnet) could silently corrupt or misinterpret the on-disk database. The Data directory section warns about node-type reuse but not chain reuse. - How to verify: Check the
mega-rethstartup sequence for a chain-ID/genesis-hash comparison between the loaded chain spec and the on-disk state (look for something likeexpected_chain_id != stored_chain_idbail in the datadir open path). If no such guard exists, the doc should add a warning that an explicit--datadirmust be scoped per chain (e.g./var/lib/megaeth/<chain>/full-node).
|
Answers to the two open questions from the last review round. Verified against mega-reth 1. Source: Empirical, on a node started with
The namespace list gates ordinary namespaces but not 2. Cross-chain reuse of an existing Source: genesis init bails with Empirical: opening a datadir initialized with chain ID 424242 using The page now documents this in the Data directory section: "It is also bound to its chain: opening it with a different |
Claude review status
✅ Review clean Last reviewed: head New this round: 0 finding(s), 0 question(s) · Resolved this round: 0 · Open questions: 0 |
1 participant
Summary
Adds
docs/node/full-node.md, an operator guide for runningmega-rethas a full node — a replica node plus an embedded asynchronous stateless validator that re-executes every committed block against a SALT witness and halts on mismatch. Registered indocs/SUMMARY.mdunder Node Operation, before Debug Trace Server.Contents
--node-type full-nodeis versusrpc-nodeandsequencer, and how a full node publishes its validated range (mega_getValidatedChain,--validator.report-to).--bootstrap-policy nevervsrequired, and the 1,800-block resume limit for an interrupted bootstrap.MEGARETH_*environment variables and defaults.deltavsfullvalidation modes, and mismatch/reorg handling.mega_getValidatedChain, and the metrics and log lines worth alerting on.MEGARETH_*names), data directory layout, graceful shutdown and backup rules, andtables-heightbackup verification.Verification
Flag names, env vars, defaults, metric names, log lines, and error strings are verified against mega-reth
develop@ab60376(stateless-validator library v2.0.15). Additionally verified empirically with a release build:mega_*methods are served on every enabled transport regardless of the--http.apilist, an existing datadir opened with a different--chainis refused at startup (GenesisHashMismatch), and the log directory gains the chain-ID suffix in both env-only and argv configurations. The quoted startup error--node-type full requires at least one --validator.rpc-urlsis intentional — the stalefullspelling is what the current build emits (crates/megaeth/validator/src/args.rs:221).Notes
mega-rethsource and binaries are permissioned; the page states this up front and points readers at the access-request path, so publishing commits to that path being in place.