docs: Polygon Bor consistency — document flatCallTracer, drop stale Erigon claims#583
Conversation
…rigon claims 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).
|
📝 WalkthroughSummary by CodeRabbit
WalkthroughPolygon documentation now states that Bor exposes ChangesPolygon tracing documentation
Estimated code review effort: 2 (Simple) | ~10 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: 4
🤖 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/debug-and-trace-apis.mdx`:
- Line 46: Update the opening sentence in the dedicated Polygon node
documentation to say “debug APIs” instead of “debug and trace APIs.” Keep the
remaining Bor and trace_* migration explanation unchanged.
In `@reference/polygon-getblockreceipts.mdx`:
- Line 7: Revise the Polygon API method description to distinguish transaction
receipt status from transfer verification: describe status as indicating
transaction execution outcome, and refer to receipt logs or the to/value fields
when discussing transfer or event monitoring.
In `@reference/polygon-traceblockbyhash.mdx`:
- Around line 53-62: The flatCallTracer documentation is missing the
per-transaction wrapper returned by both block trace methods. In
reference/polygon-traceblockbyhash.mdx lines 53-62 and
reference/polygon-traceblockbynumber.mdx lines 63-72, document the flat entries
under a transaction/result/response envelope containing txHash, rather than
presenting the call fields as the top-level response.
In `@reference/polygon-tracecall.mdx`:
- Line 49: Update the built-in-tracer note in reference/polygon-tracecall.mdx
(line 49) and reference/polygon-tracetransaction.mdx (line 31) to remove the
stale reference to “one of the three built-in tracers,” reflecting that
flatCallTracer is now included as a fourth documented tracer.
🪄 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: 7d94a5ce-cc50-4564-9f10-447bd94aea06
📒 Files selected for processing (7)
docs/debug-and-trace-apis.mdxreference/polygon-debug-trace-rpc-methods.mdxreference/polygon-getblockreceipts.mdxreference/polygon-traceblockbyhash.mdxreference/polygon-traceblockbynumber.mdxreference/polygon-tracecall.mdxreference/polygon-tracetransaction.mdx
| * With a node running on Erigon, both `debug_*` and `trace_*`namespaces are exposed. | ||
|
|
||
| For the full list of the available debug and trace API methods, see: [Erigon: RPC implementation status](https://github.com/ledgerwatch/erigon/blob/stable/cmd/rpcdaemon/README.md#rpc-implementation-status) | ||
| To enable debug and trace APIs on your dedicated Polygon node, you must have a [paid plan](https://chainstack.com/pricing/). Dedicated Polygon nodes run the Bor client, which exposes the `debug_*` namespace. Bor does not implement the Erigon-only Parity `trace_*` namespace — see [Polygon methods](/docs/polygon-methods) for the `trace_*` → `debug_*` migration. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Say “debug APIs,” not “debug and trace APIs.”
The paragraph says Bor exposes only debug_* and does not implement trace_*, so the opening currently implies unsupported trace APIs are available on dedicated Polygon nodes.
🤖 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/debug-and-trace-apis.mdx` at line 46, Update the opening sentence in the
dedicated Polygon node documentation to say “debug APIs” instead of “debug and
trace APIs.” Keep the remaining Bor and trace_* migration explanation unchanged.
| --- | ||
|
|
||
| Polygon API method that retrieves all transaction receipts for a given block. Transaction receipts contain information about the execution status of a transaction and can be useful for monitoring the status of transfers or contract execution on the blockchain. This method is available on Erigon only. | ||
| Polygon API method that retrieves all transaction receipts for a given block. Transaction receipts contain information about the execution status of a transaction and can be useful for monitoring the status of transfers or contract execution on the blockchain. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== locate file =="
git ls-files | grep -F 'reference/polygon-getblockreceipts.mdx' || true
echo "== file excerpt =="
if [ -f reference/polygon-getblockreceipts.mdx ]; then
nl -ba reference/polygon-getblockreceipts.mdx | sed -n '1,120p'
fi
echo "== search for getblockreceipt-related wording =="
rg -n "getblockreceipt|block receipt|transaction receipt|transfer|monitoring" reference -g '*.mdx' -g '*.md' | head -200
echo "== external docs check =="
python3 - <<'PY'
# Read-only semantic check against local file and common Ethereum RPC docs via web if needed.
from pathlib import Path
p = Path('reference/polygon-getblockreceipts.mdx')
text = p.read_text() if p.exists() else ''
print("mentions_transfer_on_same_sentence_as_receipt_or_monitoring:", any(s in text for s in ["receipts for a given block", "monitoring the status of transfers", "contract execution", "transaction receipts"]))
PYRepository: chainstack/dev-portal
Length of output: 275
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== file excerpt =="
if [ -f reference/polygon-getblockreceipts.mdx ]; then
awk '{printf "%6d\t%s\n", NR, $0}' reference/polygon-getblockreceipts.mdx | sed -n '1,140p'
fi
echo "== search for getblockreceipt-related wording =="
rg -n "getblockreceipt|block receipt|transaction receipt|transfer|monitoring" reference -g '*.mdx' -g '*.md' | head -200 || trueRepository: chainstack/dev-portal
Length of output: 46661
Distinguish receipt status from transfer verification.
status reports whether the transaction executed successfully; transfer details come from the to/value fields for native transfers or from emitted logs for contract transfers. Reword this as monitoring the transaction outcome or use receipt logs for transfer/event monitoring.
🤖 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 `@reference/polygon-getblockreceipts.mdx` at line 7, Revise the Polygon API
method description to distinguish transaction receipt status from transfer
verification: describe status as indicating transaction execution outcome, and
refer to receipt logs or the to/value fields when discussing transfer or event
monitoring.
Source: MCP tools
| ### `flatCallTracer` response | ||
|
|
||
| * `array` — the block's calls as a flat list in the Parity trace format, one object per call: | ||
| + `action` — the call details: `from`, `to`, `value`, `gas`, `input`, and `callType` (for example, `call`, `delegatecall`, or `staticcall`). Contract creations and self-destructs carry the corresponding Parity `create` and `suicide` fields instead. | ||
| + `result` — the call outcome: `gasUsed` and `output`. Contract creations return the new contract `address` and its `code`. | ||
| + `subtraces` — the number of child calls made directly by this call. | ||
| + `traceAddress` — the position of this call in the call tree, as an array of child indices. | ||
| + `type` — the call type: `call`, `create`, or `suicide`. | ||
| + `error` — present only when the call failed, with the failure reason. | ||
|
|
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Repository files matching trace MDX:"
git ls-files 'reference/*trace*.mdx' | sed -n '1,120p'
echo
echo "Relevant reference sections:"
for f in reference/polygon-traceblockbyhash.mdx reference/polygon-traceblockbynumber.mdx reference/polygon-tracecall.mdx reference/polygon-tracetransaction.mdx; do
if [ -f "$f" ]; then
echo "--- $f"
wc -l "$f"
sed -n '1,110p' "$f" | nl -ba
else
echo "MISSING $f"
fi
done
echo
echo "Search for flatCallTracer/tracer terminology:"
rg -n "flatCallTracer|tracer|txHash|result" reference -g '*.mdx' | sed -n '1,200p'
echo
echo "Changed files/stat (if available):"
git diff --stat HEAD~1..HEAD 2>/dev/null || git diff --stat 2>/dev/null || trueRepository: chainstack/dev-portal
Length of output: 5161
🏁 Script executed:
#!/bin/bash
set - eu
for f in reference/polygon-traceblockbyhash.mdx reference/polygon-traceblockbynumber.mdx reference/polygon-tracecall.mdx reference/polygon-tracetransaction.mdx; do
if [ -f "$f" ]; then
echo "--- $f"
wc -l "$f"
cat -n "$f" | sed -n '1,130p'
else
echo "MISSING $f"
fi
done
echo
echo "Search relevant docs terms:"
rg -n "flatCallTracer|tracer|txHash|result|three built-in|built-in tracers" reference -g '*.mdx' | sed -n '1,240p'
echo
echo "Changed files/stat:"
git diff --stat 2>/dev/null || trueRepository: chainstack/dev-portal
Length of output: 50379
🌐 Web query:
Bor debug_traceBlockByHash flatCallTracer response envelope txHash result
💡 Result:
When using the debug_traceBlockByHash RPC method on a Bor (Polygon) or Ethereum node with the flatCallTracer option, the response is typically an array of transaction trace objects [1][2]. Each object within this array represents a transaction from the block and contains a txHash field identifying the transaction, followed by a result field that provides the flattened execution trace [1][2]. The result field for flatCallTracer consists of an array of call frame objects [1][2]. Unlike the standard callTracer, which returns a hierarchical, tree-like structure of nested calls, the flatCallTracer provides a flattened list of these execution frames [2][3]. Each call frame within the result array typically includes the following fields [1][2]: - action: An object containing details about the call, such as: - callType: The type of operation (e.g., 'call', 'delegatecall', 'staticcall') [1][2]. - from: The address initiating the call [1][2]. - to: The recipient address [1][2]. - gas: The gas provided for the call [1][2]. - input: The input data (hexadecimal) [1][2]. - value: The amount of value transferred (hexadecimal) [1][2]. - result: An object containing execution results: - gasUsed: The gas consumed by this specific call [1][2]. - output: The return data from the call [1][2]. - type: The type of call [1][2]. - traceAddress: An array representing the position of the call in the overall trace (e.g., empty for top-level, or indices for nested calls) [1][2]. - subtraces: An integer indicating the number of internal sub-calls [1][2]. - blockHash and blockNumber: Metadata about the block [1][2]. - transactionHash and transactionPosition: Metadata identifying the specific transaction and its order in the block [1][2]. Because flatCallTracer is designed to provide a simplified, non-nested view, it is particularly useful for performance-sensitive analysis where the tree structure of a standard callTracer is not required [2][3].
Citations:
- 1: https://docs.validationcloud.io/v1/bsc/debug-api/debug_traceblockbyhash.md
- 2: https://docs.validationcloud.io/v1/opbnb/debug-api/debug_traceblockbyhash
- 3: https://docs.chainstack.com/reference/ethereum-traceblockbynumber
🌐 Web query:
Erigon flatCallTracer traceBlockByHash response txHash result structure
💡 Result:
When using the flatCallTracer with Erigon's debug_traceBlockByHash RPC method, the response structure differs significantly from the tree-based callTracer [1][2]. Instead of a nested structure, it returns a flattened list of call frames in a format compatible with OpenEthereum/Parity-style traces [3][2]. For a block trace, the top-level response is typically a JSON-RPC result object containing an array [4]. Each element in this array corresponds to a transaction within the block, often keyed by txHash [4]. The result for each transaction is an array of flat call frame objects [4]. Each flat call frame object typically includes the following fields [5]: - action: An object containing details such as callType, from, to, input, value, and gas [6][4]. - result: An object containing execution results such as gasUsed and output [6][4]. - subtraces: An integer representing the count of sub-calls [3][6]. - traceAddress: An array of integers representing the position of the call within the execution tree [6][5]. - type: A string indicating the type of call (e.g., call, delegatecall, staticcall, create) [6][4]. Unlike the Geth-style output where traces are often nested under a result field, the flatCallTracer organizes all call frames from the execution into a single, linear list [3][2]. Note that Erigon may return these results within a JSON-RPC envelope [4], and users should be aware that discrepancies may exist between Erigon and Geth output formats, such as the inclusion of specific result keys or handling of errors [7][8]. For example, if a method handler crashes or an error occurs during tracing, the response structure might be incomplete or contain error-specific fields [7][5].
Citations:
- 1: https://docs.chainstack.com/reference/ethereum-traceblockbyhash
- 2: https://chainstack.mintlify.app/reference/ethereum-debug-trace-rpc-methods
- 3: https://docs.erigon.tech/interacting-with-erigon/trace
- 4: https://docs.validationcloud.io/v1/bsc/debug-api/debug_traceblockbyhash.md
- 5: bobanetwork/op-geth@2ad150d
- 6: https://docs.erigon.tech/erigon/v3.2/interacting-with-erigon/interacting-with-erigon/trace
- 7: Slight difference in debug_traceBlockByHash output from Geth erigontech/erigon#4935
- 8: eth/tracers: add native flatCallTracer (aka parity style tracer) ethereum/go-ethereum#26377
🌐 Web query:
"flatCallTracer" "debug_traceBlockByHash" "txHash" "result"
💡 Result:
The flatCallTracer is a native tracer available in Geth and other Ethereum clients that provides a flattened, Parity-style list of call frames, rather than the nested tree structure produced by the default callTracer [1][2][3]. When using flatCallTracer with the debug_traceBlockByHash method, you provide it within the tracer configuration object [4][5][6]. Below is an example of the request structure: curl -X POST <RPC_URL> \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "debug_traceBlockByHash", "params": [ "<BLOCK_HASH>", { "tracer": "flatCallTracer" } ], "id": 1 }' Key characteristics and notes for flatCallTracer: 1. Output Format: It outputs call traces as a flattened list of frames [2][3]. 2. Compatibility: It was implemented in Geth to provide compatibility with Parity/OpenEthereum-style tracing [1]. 3. Implementation Differences: While it mimics Parity-style output, there are known differences, such as how Geth handles errors, gas usage (Geth includes intrinsic gas and refunds, while Parity did not), and how it handles whole-block tracing (Geth typically nests transaction results within a result field) [1]. 4. Block Tracing: When tracing an entire block, the RPC response returns a list of results for all transactions contained within that block [7][1]. 5. Versioning/Bugs: Users should be aware that implementation details may vary between client versions, and specific bugs (such as incorrect hash returns or timeout handling) have been documented in various client implementations [8][9]. Because the debug_traceBlockByHash method expects a block hash as the first parameter and a configuration object (which can include the tracer type) as the second, the txHash is not a direct parameter of this specific RPC call [4][5][6]. If you need a trace for a specific transaction, you should use the debug_traceTransaction method instead [4].
Citations:
- 1: eth/tracers: add native flatCallTracer (aka parity style tracer) ethereum/go-ethereum#26377
- 2: https://docs.chainstack.com/reference/ethereum-traceblockbynumber
- 3: https://docs.validationcloud.io/v1/opbnb/debug-api/debug_traceblockbynumber.md
- 4: https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug
- 5: https://www.quicknode.com/docs/ethereum/debug_traceBlockByHash
- 6: https://docs.validationcloud.io/v1/bsc/debug-api/debug_traceblockbyhash.md
- 7: https://www.chainnodes.org/docs/ethereum/debug_traceBlockByHash
- 8: debug_traceBlockByNumber using flatCallTracer incorrectly returns parentHash instead of blockHash paradigmxyz/reth#12415
- 9: flatCallTracer returns wrong result instead of error at timeout ethereum/go-ethereum#29622
🌐 Web query:
Bor flatCallTracer block trace result txHash source
💡 Result:
The flatCallTracer is a transaction tracing tool designed to provide a flattened, Parity-style list of call frames, rather than the nested tree structure produced by the standard callTracer [1][2][3]. This format is primarily used for compatibility with tooling built for the OpenEthereum/Parity trace format [1][3]. On networks like Polygon (Bor), tracing support—including the availability of specific tracers—can vary based on the node configuration and the specific implementation of the trace API [4][5]. Key Technical Details: - Format: It returns a flattened list of call frames [2][6][3]. - Purpose: It offers a simplified output for complex transactions [7][8][9] and ensures compatibility with legacy OpenEthereum/Parity tooling [1][3]. - Implementation: In go-ethereum (which Bor is based on), the flatCallTracer is implemented as a wrapper that uses the standard callTracer to collect callstack information and then reformats the output into the flat structure [1]. - Bor/Polygon Context: Bor has integrated support for various tracing methods, often backported or adapted from go-ethereum and OpenEthereum implementations [4]. If you are experiencing issues tracing transactions (e.g., state-sync transactions failing) [10][11], it is often due to how the node handles specific transaction types, such as system transactions with zero gas or intrinsic gas issues [10]. Enabling specific flags like borTraceEnabled in the tracer configuration is sometimes required for successful tracing on Bor [5]. If you are attempting to locate a transaction by its hash in a trace result, the flatCallTracer output includes the transactionHash field for each entry [7]. When tracing blocks, the structure typically returns a result containing transaction results, which may vary slightly between implementations regarding how errors are nested [1].
Citations:
- 1: eth/tracers: add native flatCallTracer (aka parity style tracer) ethereum/go-ethereum#26377
- 2: https://docs.chainstack.com/reference/ethereum-tracecall
- 3: https://chainstack.mintlify.app/reference/ethereum-debug-trace-rpc-methods
- 4: Enable trace methods 0xPolygon/bor#2294
- 5: https://www.quicknode.com/docs/polygon/debug_traceBlockByNumber
- 6: https://docs.chainstack.com/reference/ethereum-tracetransaction
- 7: https://docs.validationcloud.io/v1/bsc/debug-api/debug_traceblockbyhash.md
- 8: https://docs.validationcloud.io/v1/bsc/debug-api/debug_traceblockbynumber
- 9: https://docs.validationcloud.io/v1/opbnb/debug-api/debug_tracetransaction
- 10: debug_traceTransaction fails on state-sync transactions with "intrinsic gas too low" 0xPolygon/bor#2250
- 11: Bor client not able to trace blocks by number 0xPolygon/bor#1920
🌐 Web query:
site:geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug traceBlockByHash txHash result flatCallTracer
💡 Result:
The flatCallTracer is a native tracer available in Geth (go-ethereum) designed to provide Parity-style transaction tracing output [1]. It functions as a proxy that utilizes the callTracer to collect call stack information, which is then formatted to align with compatibility requirements for users transitioning from or integrating with systems that expect Parity-style traces [1]. You can use the flatCallTracer with Geth's debug RPC methods, such as debug_traceBlockByHash or debug_traceBlockByNumber, by specifying it in the tracer configuration [2][3]. Example RPC request: { "method": "debug_traceBlockByHash", "params": [ "0xYourBlockHash", { "tracer": "flatCallTracer", "tracerConfig": { "includePrecompiles": false, "convertParityErrors": false } } ], "id": 1, "jsonrpc": "2.0" } Key characteristics and compatibility notes include: 1. Compatibility Options: You can enable includePrecompiles: true to report precompile calls, which are excluded by default [1]. If you require Parity-style error messages, you can set convertParityErrors: true [1]. 2. Output Differences: Unlike Parity, Geth's implementation accounts for intrinsic gas and refunds in the gasUsed field, and it nests transaction results within a result field when tracing an entire block [1]. 3. Maintenance: It is an actively maintained native tracer within the Geth codebase, with bug fixes and updates (such as blob base fee support) integrated to ensure reliability and performance [4][5].
Citations:
- 1: eth/tracers: add native flatCallTracer (aka parity style tracer) ethereum/go-ethereum#26377
- 2: https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug
- 3: flatCallTracer returns wrong result instead of error at timeout ethereum/go-ethereum#29622
- 4: eth/tracers/native: fix flatCallTracer Stop() bug ethereum/go-ethereum#29623
- 5: eth/tracers: set blob base fee for callTracer,flatCallTracer ethereum/go-ethereum#29376
🏁 Script executed:
#!/bin/bash
set -eu
echo "OpenAPI response schemas for Polygon debug_traceBlock methods:"
fd -a 'debug_traceBlock.*\.(yaml|json|yml|md)' . | sed -n '1,40p'
for f in $(fd 'debug_traceBlock.*\.(json|yaml|yml)$' .); do
echo "--- $f"
# Print lines that mention flatCallTracer/response schema if present
rg -n "flatCallTracer|result|array|object|properties|type" "$f" | sed -n '1,220p'
doneRepository: chainstack/dev-portal
Length of output: 19171
🏁 Script executed:
#!/bin/bash
set -eu
python3 - <<'PY'
import json
from pathlib import Path
for name in ["debug_traceBlockByHash", "debug_traceBlockByNumber"]:
path = Path("openapi/polygon_node_api/debug_and_trace") / f"{name}.json"
data = json.loads(path.read_text())
result = None
schema = data.get("content", {}).get("application/json", {}).get("schema", {})
def walk(cur):
nonlocal result
if isinstance(cur, dict):
if cur.get("type") == "object" and cur.get("properties"):
if "result" in cur["properties"]:
result = cur["properties"]["result"]
for v in cur.values():
walk(v)
schema.get("properties", {}).get("result", {}).get("items", {})
walk(schema)
print(f"--- {name}")
print(json.dumps(result, indent=2, sort_keys=True, ensure_ascii=False)[:2000])
PYRepository: chainstack/dev-portal
Length of output: 236
🏁 Script executed:
#!/bin/bash
set -eu
python3 - <<'PY'
import json
from pathlib import Path
for name in ["debug_traceBlockByHash", "debug_traceBlockByNumber"]:
path = Path("openapi/polygon_node_api/debug_and_trace") / f"{name}.json"
data = json.loads(path.read_text())
def find_result_schema(node, depth=0):
if not isinstance(node, dict):
return None
if node.get("type") == "object" and node.get("properties") and "result" in node["properties"]:
return node["properties"]["result"]
for v in node.values():
r = find_result_schema(v, depth + 1)
if r is not None:
return r
return None
result = find_result_schema(data)
print(f"--- {name}: type={result.get('type')}, title={result.get('title')}, description={result.get('description')}")
print(json.dumps(result, indent=2)[:2400])
PY
echo
echo "Top-level API docs around flatCallTracer:"
for f in reference/polygon-debug-trace-rpc-methods.mdx; do
[ -f "$f" ] && cat -n "$f" | sed -n '1,260p'
doneRepository: chainstack/dev-portal
Length of output: 3638
Document the flatCallTracer transaction wrapper for both block methods.
debug_traceBlockByHash/debug_traceBlockByNumber return per-transaction trace objects for each transaction in the block, so the flat entries should be documented under result in a transaction/result/response envelope that includes txHash, rather than listing the flat call fields as the top-level response.
reference/polygon-traceblockbyhash.mdx#L53-L62reference/polygon-traceblockbynumber.mdx#L63-L72
📍 Affects 2 files
reference/polygon-traceblockbyhash.mdx#L53-L62(this comment)reference/polygon-traceblockbynumber.mdx#L63-L72
🤖 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 `@reference/polygon-traceblockbyhash.mdx` around lines 53 - 62, The
flatCallTracer documentation is missing the per-transaction wrapper returned by
both block trace methods. In reference/polygon-traceblockbyhash.mdx lines 53-62
and reference/polygon-traceblockbynumber.mdx lines 63-72, document the flat
entries under a transaction/result/response envelope containing txHash, rather
than presenting the call fields as the top-level response.
Source: MCP tools
| + `4byteTracer` — tracer that captures the function signatures and call data sizes for all functions executed during a transaction, creating a map that links each selector and size combination to the number of times it occurred. This provides valuable information about the frequency and usage of each function within the transaction. | ||
| + `callTracer` — tracer that captures information on all call frames executed during a transaction. The resulting nested list of call frames is organized into a tree structure that reflects the way the Ethereum Virtual Machine works and can be used for debugging and analysis purposes. | ||
| + `prestateTracer` — tracer with two modes: `prestate` and `diff`, where the former returns the accounts needed to execute a transaction, and the latter returns the differences between the pre and post-states of the transaction. The tracer operates by re-executing the transaction and tracking every state change made, resulting in an object with the account addresses as keys and the corresponding trie leaves as values. | ||
| + `flatCallTracer` — tracer that returns the call's execution as a flat array in the Parity-style trace format, with each entry's position given by its `traceAddress`. This is the drop-in replacement for the Erigon `trace_*` methods, which Bor does not implement. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Remove the stale tracer count.
Adding flatCallTracer creates a fourth documented built-in tracer, but both pages still refer to “one of the three built-in tracers.”
reference/polygon-tracecall.mdx#L49-L49: update the later built-in-tracer note to avoid the stale count.reference/polygon-tracetransaction.mdx#L31-L31: update the matching note to avoid the stale count.
📍 Affects 2 files
reference/polygon-tracecall.mdx#L49-L49(this comment)reference/polygon-tracetransaction.mdx#L31-L31
🤖 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 `@reference/polygon-tracecall.mdx` at line 49, Update the built-in-tracer note
in reference/polygon-tracecall.mdx (line 49) and
reference/polygon-tracetransaction.mdx (line 31) to remove the stale reference
to “one of the three built-in tracers,” reflecting that flatCallTracer is now
included as a fourth documented tracer.
1 participant
Follow-up to #578. Now that Polygon runs fully on Bor with
flatCallTracerenabled, this propagates the change across the debug/trace reference pages and fixes leftover Erigon-era drift.Fixes stale Erigon claims
docs/debug-and-trace-apis.mdx(Polygon → Dedicated Nodes) — still said dedicated Polygon nodes could run Bor or Erigon, and that Erigon exposestrace_*. Polygon is Bor-only now, so this dropped the obsolete choice, thetrace_*claim, and the outdated "Erigon: RPC implementation status" link; it now points to thetrace_*→debug_*migration on Polygon methods.reference/polygon-getblockreceipts.mdx— dropped the false "This method is available on Erigon only".eth_getBlockReceiptsis served on Bor and is marked available in the Polygon methods table.Documents flatCallTracer as a selectable tracer
flatCallTraceris the Parity-flat drop-in #578 recommends fortrace_*, but it wasn't described on the reference pages. Added it to:reference/polygon-debug-trace-rpc-methods.mdx— the pre-built native tracer catalog.reference/polygon-tracetransaction.mdx,polygon-traceblockbynumber.mdx,polygon-traceblockbyhash.mdx,polygon-tracecall.mdx— the tracer parameter list, aflatCallTracerresponse section, and the tracer-selection code comments.The response fields (
action,result,subtraces,traceAddress,type) were verified against a liveflatCallTracertrace. ExistingcallTracerexamples are unchanged —callTracerremains fully supported; this only addsflatCallTraceras a documented option.mint broken-linksclean.