docs: Polygon — recommend flatCallTracer for trace_* migration#578
Conversation
flatCallTracer returns Parity-style flat traces (same shape as the old Erigon trace_* output), so developers migrating off trace_* can reuse existing trace-parsing logic. callTracer returns Geth nested format, which would force a rewrite. Now enabled on Polygon Bor nodes. Scope: migration mapping only (polygon-methods table + protocols-clients warning). The reference/polygon-*trace* pages keep documenting callTracer with its nested-format examples — callTracer stays fully supported.
|
📝 WalkthroughSummary by CodeRabbit
WalkthroughPolygon documentation updates Bor tracing guidance to use ChangesPolygon tracing guidance
Estimated code review effort: 2 (Simple) | ~5 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/polygon-methods.mdx`:
- Line 17: Update the migration mapping table entry to separate trace semantics:
map trace_replayTransaction to debug_traceTransaction,
trace_replayBlockTransactions to debug_traceBlockByNumber, and trace_filter to
targeted tracing with client-side filtering. Retain eth_getLogs only as an
alternative for emitted-event use cases.
In `@docs/protocols-clients.mdx`:
- Line 33: Update the prose in the Chainstack Polygon client note so the em dash
has no surrounding spaces, changing the phrasing from “client — the” to
“client—the” while preserving the remaining text.
- Line 33: Update the Bor migration guidance in the Chainstack client
documentation to qualify the `trace_*` limitation as Chainstack-specific only
when Chainstack does not expose or enable those methods. Preserve the
distinction that Bor supports Parity-compatible `trace_*` and `flatCallTracer`,
and retain `debug_*` guidance only for environments where the trace namespace is
unavailable.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: f0b8f1d4-e6e2-4fef-9395-99937f4ad067
📒 Files selected for processing (2)
docs/polygon-methods.mdxdocs/protocols-clients.mdx
| | `trace_transaction` | [`debug_traceTransaction`](/reference/polygon-tracetransaction) with `flatCallTracer` | | ||
| | `trace_block` | [`debug_traceBlockByNumber`](/reference/polygon-traceblockbynumber) with `flatCallTracer` | | ||
| | `trace_call` | [`debug_traceCall`](/reference/polygon-tracecall) with `flatCallTracer` | | ||
| | `trace_filter`, `trace_replayBlockTransactions`, `trace_replayTransaction` | [`debug_traceBlockByNumber`](/reference/polygon-traceblockbynumber) with `flatCallTracer` per block, or [`eth_getLogs`](/docs/understanding-eth-getlogs-limitations) for event ranges | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Repo files matching target:"
git ls-files | grep -E '(^|/)docs/polygon-methods\.mdx$|reference/polygon-traceblockbynumber\.mdx|understanding-eth-getlogs-limitations\.mdx' || true
echo
echo "Target excerpt:"
if [ -f docs/polygon-methods.mdx ]; then
nl -ba docs/polygon-methods.mdx | sed -n '1,80p'
fi
echo
echo "Related docs targets excerpts:"
for f in reference/polygon-traceblockbynumber.mdx docs/understanding-eth-getlogs-limitations.mdx; do
if [ -f "$f" ]; then
echo "--- $f ---"
nl -ba "$f" | sed -n '1,120p'
fi
done
echo
echo "Search trace method docs references:"
rg -n "trace_(filter|replay|replayBlockTransactions|replayTransaction)|debug_trace(AllCalls|BlockByNumber|Transaction)|eth_getLogs|flatCallTracer" docs reference 2>/dev/null | head -200Repository: chainstack/dev-portal
Length of output: 358
🌐 Web query:
Open Ethereum tracing JSON-RPC trace_filter trace_replayTransaction debug_traceBlockByNumber flatCallTracer
💡 Result:
The JSON-RPC methods you mentioned belong to two distinct categories of Ethereum tracing: the OpenEthereum-style trace_* namespace and the debug_* namespace (commonly associated with Geth). 1. trace_filter: This is a method within the OpenEthereum trace module that allows you to query a subset of transaction traces across blocks [1][2]. It accepts a filter object (with parameters like fromBlock, toBlock, fromAddress, and toAddress) and returns an array of matching traces [1][3]. 2. trace_replayTransaction: This method is used to re-execute a previously mined transaction (by its hash) to generate a full trace [1][4]. The node must have access to the transaction data, typically requiring archive mode or the transaction to be within the most recent 1000 blocks [1]. 3. debug_traceBlockByNumber: This is a method from the debug namespace that traces all transactions in a specific block [2][5]. Unlike trace_* methods, this usually requires specifying a tracer type in the request parameters, such as callTracer or flatCallTracer [5][6]. 4. flatCallTracer: This is a specific tracer type used with debug_* methods (like debug_traceBlockByNumber or debug_traceTransaction) [5][7][8]. Its purpose is to provide call traces in a flattened (non-nested) list format, mimicking the output style of the original OpenEthereum/Parity trace_* methods [4][9][7]. It is particularly useful for developers who want the performance of modern debug_* tracers while maintaining compatibility with the flat, linear trace structure of older clients [5][9]. In summary, while trace_filter and trace_replayTransaction are native trace module methods [1], flatCallTracer is an optional configuration for debug methods that enables users to receive trace-like output [9][7].
Citations:
- 1: https://openethereum.github.io/JSONRPC-trace-module.html
- 2: https://github.com/paradigmxyz/ultimate_evm_tracing_reference
- 3: https://openethereum.github.io/JSONRPC-trace-module
- 4: https://docs.erigon.tech/interacting-with-erigon/trace
- 5: https://docs.validationcloud.io/v1/opbnb/debug-api/debug_traceblockbynumber.md
- 6: https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers
- 7: https://docs.chainstack.com/reference/ethereum-tracecall
- 8: https://docs.chainstack.com/reference/ethereum-traceblockbynumber
- 9: eth/tracers: add native flatCallTracer (aka parity style tracer) ethereum/go-ethereum#26377
🌐 Web query:
Open Ethereum trace_replayBlockTransactions trace_filter semantics event logs internal calls
💡 Result:
In OpenEthereum, the trace module provides specialized JSON-RPC methods for analyzing transaction execution, including internal contract calls and state changes [1][2][3]. trace_replayBlockTransactions This method replays all transactions within a specified block to provide comprehensive execution data [1][4]. - Semantics: It executes every transaction in the block and returns a list of detailed trace objects [1][5]. - Scope: It can return different levels of detail depending on the requested trace types, which include "trace" (standard execution traces), "vmTrace" (instruction-level execution data), and "stateDiff" (changes to the state tree) [1][4]. - Response: Each entry in the resulting array represents a transaction and contains the execution results, including subtraces (nested internal calls), output data, and any errors (e.g., reverts) [1][2]. trace_filter This method retrieves a flat list of traces that match specific filtering criteria [6][7]. - Semantics: Unlike replay methods that process entire blocks, trace_filter allows you to query for traces across a range of blocks based on address-specific criteria [6][7]. - Filter Parameters: You can filter by: - Block range: fromBlock and toBlock (limited to a 100-block window in some implementations) [8][7]. - Addresses: fromAddress and toAddress [6][7]. - Pagination: after (the offset trace number) and count (the number of traces to return) [6][8]. - Internal Calls & Event Logs: While trace_filter returns internal call structures (such as CALL, CREATE, and SUICIDE operations), it is distinct from the eth_getLogs API [6][9]. The trace module focuses on the execution flow (internal calls, gas usage, output) rather than the event logs emitted by smart contracts [6][9]. To retrieve event logs, you must use the standard eth_getLogs or eth_getFilterLogs methods [10]. In summary, trace_replayBlockTransactions is designed for complete block-level analysis [1], whereas trace_filter is designed for targeted searching of execution traces across blocks [6][7]. Neither method directly returns event logs, which are handled by the separate eth log-filtering API [6][10].
Citations:
- 1: https://openethereum.github.io/JSONRPC-trace-module.html
- 2: https://openethereum.github.io/JSONRPC-trace-module
- 3: https://openethereum.github.io/JSONRPC
- 4: https://drpc.org/docs/ethereum-api/debugandtrace/trace_replayBlockTransactions
- 5: https://www.quicknode.com/docs/ethereum/trace_replayBlockTransactions
- 6: https://docs.erigon.tech/interacting-with-erigon/trace
- 7: https://www.alchemy.com/docs/reference/what-is-trace_filter
- 8: https://docs.metamask.io/services/reference/ethereum/json-rpc-methods/trace-methods/trace_filter/
- 9: https://docs.metamask.io/services/reference/ethereum/json-rpc-methods/trace-methods/
- 10: https://openethereum.github.io/JSONRPC-eth-module.html
🌐 Web query:
Open Ethereum JSONRPC trace module trace_replayTransaction trace_replayBlockTransactions trace_filter
💡 Result:
The trace module in OpenEthereum provides JSON-RPC methods to gain deep insights into transaction execution and state changes [1][2]. Below is an overview of the requested methods. trace_replayTransaction This method replays a previously mined transaction and returns its execution traces [1][3]. It is primarily used for historical transactions [4]. Because it requires re-executing the transaction, the node must generally be in archive mode, or the transaction must be within the most recent 1000 blocks [1][5]. trace_replayBlockTransactions This method replays all transactions within a specified block and returns the requested traces for each transaction [1][3]. Parameters include: 1. Block identifier (Quantity, Tag such as 'latest', 'earliest', or 'pending') [1]. 2. Array of trace types (e.g., 'vmTrace', 'trace', 'stateDiff') to specify what information to return [1][4]. trace_filter This method returns a list of traces that match a provided filter object [1][3]. It allows for querying traces across a range of blocks or by specific addresses [1][3]. Common filter parameters include: - fromBlock / toBlock: The range of blocks to search [1][3]. - fromAddress / toAddress: Filtering by sender or recipient addresses [1][3]. - after: Offset trace number [1][3]. - count: Maximum number of traces to display in a batch [1][3]. These trace methods are distinct from the standard Ethereum JSON-RPC API and are often used for diagnostics, debugging, or analyzing historical contract interactions [6][2][7]. Note that support for these methods varies across different Ethereum clients (e.g., Erigon and Besu also support this module for compatibility) [4][7][8].
Citations:
- 1: https://openethereum.github.io/JSONRPC-trace-module.html
- 2: https://www.alchemy.com/docs/reference/trace-api-vs-debug-api
- 3: https://books.botanixlabs.dev/jsonrpc/trace.html
- 4: https://docs.erigon.tech/interacting-with-erigon/trace
- 5: https://openethereum.github.io/JSONRPC-trace-module
- 6: https://www.alchemy.com/docs/reference/trace-api-vs-debug-api.md
- 7: https://etclabscore.github.io/core-geth/JSON-RPC-API/trace-module-overview/
- 8: https://docs.besu-eth.org/public-networks/reference/api/trace
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Target excerpt:"
if [ -f docs/polygon-methods.mdx ]; then
awk '{printf "%5d: %s\n", NR, $0}' docs/polygon-methods.mdx | sed -n '1,90p'
fi
echo
echo "Related docs target excerpts:"
for f in reference/polygon-traceblockbynumber.mdx docs/understanding-eth-getlogs-limitations.mdx; do
if [ -f "$f" ]; then
echo "--- $f ---"
awk '{printf "%5d: %s\n", NR, $0}' "$f" | sed -n '1,140p'
fi
done
echo
echo "Search trace method docs references:"
rg -n "trace_(filter|replay|replayBlockTransactions|replayTransaction)|debug_trace(AllCalls|BlockByNumber|Transaction)|eth_getLogs|flatCallTracer|trace_replayBlockTransactions" docs reference 2>/dev/null | head -200Repository: chainstack/dev-portal
Length of output: 50379
Split the migration mappings by trace semantics.
trace_replayTransaction, trace_replayBlockTransactions, and trace_filter are execution traces with overlapping but not equivalent target semantics. Map transaction replay to debug_traceTransaction, block replay to debug_traceBlockByNumber, and handle trace_filter with targeted tracing plus client-side filtering; keep eth_getLogs only for emitted-event use cases.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/polygon-methods.mdx` at line 17, Update the migration mapping table
entry to separate trace semantics: map trace_replayTransaction to
debug_traceTransaction, trace_replayBlockTransactions to
debug_traceBlockByNumber, and trace_filter to targeted tracing with client-side
filtering. Retain eth_getLogs only as an alternative for emitted-event use
cases.
Source: MCP tools
|
|
||
| <Warning> | ||
| Chainstack has **retired the Erigon client for Polygon** — archive nodes now run Bor. Because Bor does not implement the Erigon-only Parity `trace_*` or `erigon_*` namespaces, use the `debug_*` methods (with `callTracer`) instead. See [Polygon methods](/docs/polygon-methods) and [Debug and trace APIs](/docs/debug-and-trace-apis). | ||
| Chainstack has **retired the Erigon client for Polygon** — archive nodes now run Bor. Because Bor does not implement the Erigon-only Parity `trace_*` or `erigon_*` namespaces, use the `debug_*` methods (with `flatCallTracer`) instead. See [Polygon methods](/docs/polygon-methods) and [Debug and trace APIs](/docs/debug-and-trace-apis). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Remove spaces around the em dash.
Change client — the to client—the.
As per coding guidelines, use em dashes without spaces in prose.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/protocols-clients.mdx` at line 33, Update the prose in the Chainstack
Polygon client note so the em dash has no surrounding spaces, changing the
phrasing from “client — the” to “client—the” while preserving the remaining
text.
Source: Coding guidelines
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "## Locate relevant docs"
git ls-files | rg '(^|/)docs/(protocols-clients|polygon-methods|debug-and-trace-apis)\.mdx$|docs\.json$' || true
echo
echo "## Relevant snippets"
for f in docs/protocols-clients.mdx docs/polygon-methods.mdx docs/debug-and-trace-apis.mdx; do
if [ -f "$f" ]; then
echo "--- $f"
nl -ba "$f" | sed -n '1,120p'
else
echo "MISSING $f"
fi
done
echo
echo "## Search Bor/Erigon trace/debug mentions in docs"
rg -n "Bor|Erigon|trace_\*|erigon_\*|debug_\*|flatCallTracer|Polygon methods|Debug and trace" docs docs.json || trueRepository: chainstack/dev-portal
Length of output: 369
🌐 Web query:
0xPolygon bor trace namespace Parity trace_* README flatCallTracer
💡 Result:
The Polygon Bor client recently introduced a Parity/OpenEthereum-compatible trace_* RPC namespace, which allows users to perform execution traces using a flat, Parity-style format [1][2]. This implementation includes a native flatCallTracer that outputs trace data as a flattened list of call frames, rather than the nested tree structure produced by Geth's standard callTracer [3][4]. This feature is designed to support archive-node operators who require Parity-style execution traces for indexing, debugging, and MEV tooling [1]. Key implementation details include: * Availability: The trace_* namespace (including trace_block, trace_transaction, trace_replayTransaction, trace_replayBlockTransactions, trace_call, and trace_callMany) is disabled by default [1][2]. It can be enabled on an archive node by setting the --rpc.enabletrace flag or configuring enabletrace = true under the [jsonrpc] section in the node's config.toml file [2][5]. * Compatibility: The flatCallTracer is implemented to provide Parity-style output with specific options available to maintain compatibility, such as includePrecompiles: true and convertParityErrors: true [3]. * Important Context: While some historical documentation or third-party providers may state that Bor does not support the trace_* namespace [6][7], this refers to the previous state of the client prior to recent upstream merges and updates that integrated this parity-style tracing functionality into Bor [1][8]. Operators should verify their specific Bor version to confirm support [1][9]. When using these methods, ensure your node is running in archive mode (--gcmode archive) and consider adjusting HTTP write timeouts to accommodate complex trace requests [2][5].
Citations:
- 1: Enable trace methods 0xPolygon/bor#2294
- 2: https://github.com/maticnetwork/bor/
- 3: eth/tracers: add native flatCallTracer (aka parity style tracer) ethereum/go-ethereum#26377
- 4: https://docs.chainstack.com/reference/ethereum-tracetransaction
- 5: https://github.com/0xPolygon/bor
- 6: https://docs.tatum.io/changelog/polygon-erigon-eol-migration-to-bor
- 7: https://docs.chainstack.com/docs/protocols-clients
- 8: 0xPolygon/bor@523198e
- 9: 0xPolygon/bor@v2.0.3...v2.0.4-beta
Qualify the Bor trace_* capability claim.
Bor supports the Parity-compatible trace_* namespace and flatCallTracer when enabled, so reword this to a Chainstack-specific limitation only if Chainstack disables or does not expose trace_*; otherwise this makes the Bor migration guidance misleading.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/protocols-clients.mdx` at line 33, Update the Bor migration guidance in
the Chainstack client documentation to qualify the `trace_*` limitation as
Chainstack-specific only when Chainstack does not expose or enable those
methods. Preserve the distinction that Bor supports Parity-compatible `trace_*`
and `flatCallTracer`, and retain `debug_*` guidance only for environments where
the trace namespace is unavailable.
Source: MCP tools
…rigon claims (#583) Follows #578. Now that Polygon runs fully on Bor with flatCallTracer enabled, propagate the change across the debug/trace references and fix leftover Erigon-era drift: - debug-and-trace-apis: Polygon Dedicated Nodes run Bor (debug_* only); dropped the stale Bor-or-Erigon choice, the trace_* claim, and the Erigon README link; point to the migration on Polygon methods. - polygon-getblockreceipts: dropped the false 'available on Erigon only' (eth_getBlockReceipts is served on Bor and is in the availability table). - debug/trace overview + the 4 debug_trace* reference pages: added flatCallTracer to the tracer catalog, parameter lists, response sections, and code comments. Response fields verified against a live flatCallTracer trace. callTracer examples kept as-is (still supported).
1 participant
What
Switch the Polygon
trace_*→debug_*migration mapping to recommendflatCallTracerinstead ofcallTracer:docs/polygon-methods.mdx— the migration table, plus a note on the output formatdocs/protocols-clients.mdx— the Polygon Bor retirement warningWhy
Polygon archive nodes run Bor, which doesn't implement the Erigon-only Parity
trace_*namespace.flatCallTracer(a native Bor/go-ethereum tracer,eth/tracers/native/call_flat.go) returns traces in the Parity-style flat format — the same shape as the oldtrace_*output — so developers migrating offtrace_*can reuse their existing trace-parsing logic.callTracerreturns Geth's nested format, which would force a rewrite.flatCallTraceris enabled on Chainstack's Polygon Bor nodes and verified working.Scope
Only the migration mapping changes. The
reference/polygon-*trace*pages continue to documentcallTracerwith its nested-format response examples —callTracerremains fully supported; this only changes which tracer we recommend as the drop-in replacement fortrace_*.Follows up #577 (which shipped the post-Bor reference coverage with
callTracer).