Nice structural improvement — the previous one-line * Object - Block traces placeholders were unhelpful, and the new Response Fields Reference is much better. Conventions ([r3.4] title, base release/3.4, versioned_docs/ untouched) all look correct. However, several factual claims do not match the code on release/3.4 and should be fixed before merge.

Accuracy (must fix)

1. Stage-prefix examples are wrong ([3/12 Bodies] / [12/12 Finish])

The prefix is built in execution/stagedsync/sync.go:230 (release/3.4):

logPrefixes[i] = fmt.Sprintf("%d/%d %s", i+1, len(stagesList), stagesList[i].ID)

On release/3.4, DefaultStages (execution/stagedsync/default_stages.go) has 8 stages, not 12: Snapshots, Headers, BlockHashes, Bodies, Senders, Execution, TxLookup, Finish. So Bodies is the 4th of 8 — the actual prefix is [4/8 Bodies], and finish is [8/8 Finish].

Wrong instances introduced by this PR:

• basic-usage.mdx example block — [3/12 Bodies]
• basic-usage.mdx — [4/12 Senders], [5/12 Execution], [12/12 Finish]
• frequently-asked-questions-faqs.md (FAQ #16) — [3/12 Bodies] and [12/12 Finish]

(The pre-existing logs.md already says "1/10 Headers" — also wrong, but out of scope here. Worth a follow-up.)

2. "reward" is not "only in trace_block"

The TraceEntry fields table says:

type | String | … "reward" (block/uncle reward, only in trace_block).

But rpc/jsonrpc/trace_filtering.go emits reward traces inside the Filter method too (block reward around line 504, uncle rewards around line 544). When a filter matches block coinbases or uncle authors, reward entries appear in trace_filter results.

Suggested wording: "only in trace_block and trace_filter".

3. creationMethod is missing from the type: "create" action variant

The PR's Action variants table for type: "create" lists only from, value, gas, init. But CreateTraceAction has:

// rpc/jsonrpc/trace_types.go:97
type CreateTraceAction struct {
    From           common.Address `json:"from"`
    CreationMethod string         `json:"creationMethod"`
    Gas            hexutil.Big    `json:"gas"`
    Init           hexutil.Bytes  `json:"init"`
    Value          hexutil.Big    `json:"value"`
}

It is set in trace_adhoc.go:428 to strings.ToLower(typ.String()) — so "create", "create2", "eofcreate". Confirmed in actual JSON via gen_traces_test.go ("creationMethod": "create2"). The flat tracer (call_flat.go) emits it too. Should be added to the table.

4. error description is misleading (claims "instead of result")

PR says:

error | String | (Optional) Present instead of result when the call frame reverted, e.g. "Reverted", "Out of gas", "Bad instruction".

But in trace_adhoc.go:489-505, when err == ErrExecutionReverted (the most common case — "Reverted"), both error: "Reverted" AND result (with gasUsed and output/code) are set. Only for non-revert errors does the code do topTrace.Result = nil.

Suggested wording: "Present when the call frame errored. For "Reverted", result is still populated with gasUsed and output (or code/address for create); for other errors, result is null."

Completeness (nice-to-fix)

5. eth_syncing response shape is incomplete

Actual response in rpc/jsonrpc/eth_system.go:81-86:

return map[string]any{
    "startingBlock": "0x0", // 0x0 is a placeholder, I do not think it matters what we return here
    "currentBlock":  hexutil.Uint64(currentBlock),
    "highestBlock":  hexutil.Uint64(highestBlock),
    "stages":        stagesMap, // []{StageName string, BlockNumber hexutil.Uint64}
}

Two things the doc omits:

• stages: the per-stage progress array. Arguably the most useful field for "what stage am I in?" — it ties this section directly to the staged-sync log-prefix discussion.
• startingBlock is hardcoded to "0x0" (per the source comment). The doc currently presents it as if it carries meaningful info. The highestBlock - currentBlock math suggested is fine; just don't imply startingBlock is meaningful.

6. Error-string list is partial (e.g. is defensible)

e.g. "Reverted", "Out of gas", "Bad instruction" is fine as illustrative. For completeness, the full mapping in execution/tracing/tracers/native/call_flat.go:49-65 also includes "Bad jump destination", "Out of bounds", "Out of stack", "Built-in failed", "Stack underflow". Optional to expand.

Style (minor)

• The :::tip callout in basic-usage.mdx links to /help-center/frequently-asked-questions-faqs without an anchor. Anchoring to the new FAQ (e.g. #how-do-i-monitor-my-nodes-sync-progress) would land the reader directly on the relevant entry.
• The TraceEntry fields table marks transactionHash/transactionPosition as absent for "reward" entries — verified against the reward branches in trace_filtering.go. ✓

Recommendation

Request changes for issues 1–4 (factual). 5–6 are nice-to-have and could be a follow-up. The unchecked test-plan item "Visual review of trace fields tables for accuracy before merge" is exactly the gap above — the details here can drive that pass. Once the log-prefix examples match the actual 8-stage list and the trace-field gaps are closed, this is a solid backport.

Overview

Docs-only PR addressing two items from the docs feedback widget:

1. trace.md: a single Response Fields Reference section (top-level shapes, TraceEntry, action variants for call/create/suicide/reward, result variants). All 9 trace_* "Returns" subsections are updated to point at it.
2. Sync-monitoring guidance: a "How do I know it's syncing?" section in basic-usage.mdx, a closing pointer from the install page, and a new FAQ #16 (with #17–#25 renumbered).

Title prefix [r3.4], scope, and not touching versioned_docs/version-v3.3/ all follow the project's backport conventions.

What's good

• Strong information architecture. A single canonical reference replaces nine identical placeholder lines (* Object - Block traces). Each method's Returns now states the top-level shape and links to the reference. This is the right structure.
• Top-level shapes table, TraceEntry table, call/suicide/reward action variants, and result variants are all consistent with rpc/jsonrpc/trace_types.go and trace_adhoc.go on release/3.4 (verified ParityTrace, CallTraceAction, SuicideTraceAction, RewardTraceAction, TraceResult, CreateTraceResult).
• Stage-prefix description matches the actual format from execution/stagedsync/sync.go:230 ([%d/%d %s]); [4/8 Bodies] and [8/8 Finish] correctly match DefaultStages on release/3.4 (8 active stages: Snapshots, Headers, BlockHashes, Bodies, Senders, Execution, TxLookup, Finish; CustomTrace is commented out).
• The note that startingBlock is hardcoded to "0x0" matches rpc/jsonrpc/eth_system.go:81 exactly — useful detail to surface.
• Renumbering of FAQs #16–#25 looks clean.

Factual issues to fix

These are concrete inaccuracies verified against release/3.4 source.

1. (HIGH) creationMethod: "eofcreate" is not a real value

The new type: "create" action table claims:

creationMethod … How the contract was created: "create", "create2", or "eofcreate".

But on release/3.4 (and on main), execution/vm/opcodes.go only defines CREATE and CREATE2 — there's no EOFCREATE opcode. CreationMethod = strings.ToLower(typ.String()) (rpc/jsonrpc/trace_adhoc.go:428) can therefore only produce "create" or "create2". EOF is not on release/3.4.

Fix: drop the "eofcreate" value (or note as a footnote that EOF creation methods may appear in future hardforks, but don't list it as a current value).

2. (MEDIUM) stages array element keys are documented in wrong case

Both basic-usage.mdx and FAQ #16 describe the eth_syncing stages array as:

a stages array (one entry per stage, with {StageName, BlockNumber})

The actual JSON keys (rpc/jsonrpc/eth_system.go:70-72 on release/3.4) are snake_case:

```go
type S struct {
StageName string `json:"stage_name"`
BlockNumber hexutil.Uint64 `json:"block_number"`
}
```

A user copying this into client code (stages[i].StageName) will silently read undefined. Two locations need updating.

Fix: {stage_name, block_number} in both basic-usage.mdx and the FAQ entry.

3. (MEDIUM) error string casing is misleading for trace_*

The TraceEntry table gives examples:

e.g. "Reverted", "Out of gas", "Bad instruction".

In trace_adhoc.go:499-514, only vm.ErrExecutionReverted is mapped to the title-cased "Reverted". Every other error falls through to err.Error() as-is, so trace_* actually emits the lowercase Go-style strings: "out of gas", "invalid opcode: PUSH...", "stack underflow", etc.

The title-cased Parity-style strings ("Out of gas", "Bad instruction", "Stack underflow") are produced by a different code path — the flat call tracer in execution/tracing/tracers/native/call_flat.go:50-65 (used by debug_traceTransaction with callTracer in flat mode), not by trace_*. Documenting them under trace_* will mislead users writing string comparisons.

Fix: either replace the examples with what trace_* actually produces ("Reverted", "out of gas", "invalid opcode: …") or note explicitly that "Reverted" is the only title-cased value and other errors come through verbatim from the EVM.

Smaller things

• rewardType value list is incomplete. Docs say "block" or "uncle". rpc/jsonrpc/trace_filtering.go:172-184 (rewardKindToString) can also return "emptyStep", "external", or "unknown". Probably acceptable to leave as-is given the audience targets PoW-style chains, but a short note ("on PoA chains, additional values may appear") would be more accurate.
• PR description vs. doc text mismatch (cosmetic). The PR body lists [3/12 Bodies] → [12/12 Finish], but the actual added text correctly uses [4/8 Bodies] → [8/8 Finish]. The doc is right; just the PR description is stale. No action needed in the diff itself.
• code on revert. The result-variants table says code: "Deployed runtime bytecode of the new contract." On a reverted create, the code field actually carries the revert output, not deployed bytecode. Worth a parenthetical, but optional.

Risk

Minimal — docs-only on a release branch, no runtime impact, no test changes needed. The reader-facing risk is items 1–3 above: they will mislead anyone using the doc as a copy-paste reference for client code, which is precisely the use case the PR was opened to address.

Recommendation

Request changes for items 1–3 (small textual fixes), then this is good to go. Everything else is solid and the structural improvement is genuinely useful.