docs(node): add debug-trace-server guide

[vincent-k2026]

Summary

Adds docs/node/debug-trace-server.md — operator guide for self-hosting a standalone debug_* / trace_* RPC server backed by SALT stateless execution.

• When to use this: explains when to self-host vs. using the public RPC trace methods.
• Quick start: Mainnet/Testnet commands with parameter explanations; clarifies that --witness-endpoint can point at the public RPC for teams without their own witness generator.
• Production setup: local cache mode with --data-dir, block pruning, response cache, metrics.
• Supported RPC methods: Geth-style (debug_traceBlockByNumber, debug_traceBlockByHash, debug_traceTransaction) and Parity-style (trace_block, trace_transaction) with full tracer table.
• Command-line reference: all flags with env vars, defaults, and descriptions — grouped by core, local cache, timeout/concurrency, response cache, monitoring.
• Deployment examples: systemd unit and env-var file for containers.
• Troubleshooting: database reset, upstream failures, memory, latency.

Updates docs/SUMMARY.md to list the new page under Node Operation.

Verification

• All CLI flags, env vars, and defaults verified against upstream bin/debug-trace-server/src/main.rs and crates/stateless-common/src/logging.rs.
• All metric names verified against bin/debug-trace-server/src/metrics.rs.
• Cross-links to stateless-validation.md, witness.md, and ../dev/send-tx/debugging.md use relative paths.
• Style follows docs/node/AGENTS.md rules: one sentence per line, reference tone, copy-pasteable commands, angle-bracket placeholders, GitBook hint blocks.

[claude]

Good addition — the flag/env-var/default tables appear accurate against the upstream source, copy-pasteable examples are clean, and cross-links are correct. Three issues inline; the metric-name one is the most important to fix before merge.

[claude]

All four prior review threads are resolved in this revision — metric names, debug_getCacheStatus, hint style, and title case are all correct.

One minor item to verify: lychee.toml changes include_fragments from true to "full". Lychee's documented values for that field are boolean (true/false); if the installed version doesn't recognise the string, local link-check runs will fail with a config parse error. Worth confirming against the lychee version you're running (lychee --version) before merging.

Everything else looks good — content is accurate, flags are verified against source, deployment examples are copy-pasteable, and the page fits naturally into the Node Operation section.

[claude]

All four previous review threads are addressed in the current diff — resolved above.

One new item: the "MuxTracer" tracer name (see inline comment). Every other tracer in the table uses lowercase-first camelCase, and Geth registers the mux tracer as "muxTracer". If the MegaETH implementation follows the same convention this is a copy-paste error that will silently break any caller who uses it. Easy to verify against the source before merging.

Everything else looks solid — the flag table, env vars, defaults, and metric names all cross-check cleanly. Structure and tone match the node layer conventions.

[claude]

Review

Overall the guide is solid — well-structured, follows docs/node/AGENTS.md rules (reference tone, one-sentence-per-line, copy-pasteable commands, angle-bracket placeholders, correct hint styles), and the CLI flag/env-var/metric tables appear accurate per the upstream source references in the PR description.

All six previously raised threads have now been addressed:

• Page title → sentence case ✓
• debug_getCacheStatus added to the RPC table ✓
• muxTracer lowercase ✓
• --start-block hint upgraded to warning ✓
• Metrics table uses full debug_trace_* names ✓
• Troubleshooting section updated to full metric names ✓ (thread just resolved)

One remaining item: the lychee.toml change (true → "full") — see inline comment. Everything else looks good to merge once that's confirmed.

[claude]

All six prior review threads are resolved in the current diff. The lychee.toml thread (seventh) was stale — that file was never changed in this PR — so I've resolved it.

The guide is in good shape:

• Accuracy: all flag names, env vars, defaults, and metric names verified and correct; full debug_trace_ prefixes in the metrics table and troubleshooting section.
• Completeness: debug_getCacheStatus present, --start-block warning uses {% hint style="warning" %}, muxTracer casing is lowercase, heading is sentence case.
• Style: one sentence per line throughout, angle-bracket placeholders, copy-pasteable commands, GitBook hint blocks used appropriately.
• Navigation: SUMMARY.md entry is correctly placed as a top-level Node Operation item (not nested under Stateless Validation, which is right — the server is an independent tool).

No new issues. Ready to merge.

[claude]

All 7 prior threads are resolved and the current diff looks clean.

lychee.toml — include_fragments = "full" is safe: CI uses lychee = "latest" (via mise), and the lint check already passes on this branch.

debug-trace-server.md — content is comprehensive and well-structured:

• Metric names carry the full debug_trace_ prefix throughout (table and troubleshooting section).
• debug_getCacheStatus is in the Geth-style methods table.
• --start-block hint is correctly warning style.
• "muxTracer" casing matches the standard Geth registration.
• Page heading uses sentence case; SUMMARY entry uses Title Case consistent with every other node-layer entry.

One thing to be aware of before merging: the Quick Start table lists eth_getHeaderByHash and eth_getCodeByHash as methods called by --rpc-endpoint. Neither is in the standard Ethereum JSON-RPC spec; both are MegaETH-specific extensions. The table description already says "A MegaETH JSON-RPC node", so this is accurate — but an operator who tries to substitute Infura/Alchemy will see cryptic errors. A brief parenthetical like "(MegaETH-specific extension)" on each would make the requirement unmissable. Not a blocker, just a readability note.

Otherwise LGTM.

[claude]

The key (block_number, tracer_type) omits tracer options. Callers can vary tracerConfig independently of tracer — for example, prestateTracer with "diffMode": false vs "diffMode": true produce different output but would map to the same cache key, so the first response would be served for both.

Please verify whether the actual implementation key includes the full request options (tracer + config), and update this sentence to match. If only the tracer name is included, that's a correctness bug worth surfacing to users.

[claude]

This claim is not scoped to local cache mode. In stateless mode (no --data-dir) there is no background sync pipeline — so the server has no mechanism to detect chain reorganizations and invalidate entries. Either scope this to local cache mode, or explain how reorg detection works without --data-dir.

[claude]

All 7 previous review threads are resolved. The document is comprehensive, well-structured, and follows the node layer conventions.

Two issues in the response cache section need clarification before merge:

1. Cache key granularity (line 196): The stated key (block_number, tracer_type) omits tracerConfig. Requests like prestateTracer with diffMode: true vs false produce different output — if the key doesn't include options, the cache returns the wrong result. Please verify the actual key against source and update the description to match.

2. Reorg invalidation scope (line 198): "Invalidated automatically on chain reorganization" is stated unconditionally, but in stateless mode (no --data-dir) there is no sync pipeline that could detect reorgs. This should be scoped to local cache mode or explained for stateless mode.

Everything else looks good — metrics table is correct with full debug_trace_ prefixes, debug_getCacheStatus is in the methods table, hint styles match AGENTS.md rules, heading uses sentence case, and the testnet endpoint is corrected.