`debug_traceTransaction` returns `[]` for Bor state-sync transactions although the documented result is an Object

[BenWhite713]

Summary

The documentation says:

Returns Geth style transaction trace.

and documents the return value as:

Object — Transaction trace object

For a recognized Bor state-sync transaction, however, an omitted or empty
trace config returns a successful empty array:

{"jsonrpc":"2.0","id":1,"result":[]}

Affected revision

• Erigon commit: 993149925e454e7f15113a11e78f48af4f23a7a9
• Endpoint: debug_traceTransaction
• Scope: Bor/Polygon state-sync transactions when Bor tracing is not explicitly enabled
• Documentation: https://docs.erigon.tech/interacting-with-erigon/debug#debug_tracetransaction

Reproduction

Use a Bor-enabled node and a known state-sync transaction hash. In the
deterministic fixture, the recognized state-sync hash is
0x1ce3791a4ceb3a037e5c860d86adf3fbefb70707cd1bf5057359d5d5d9699f97:

RPC_URL="${RPC_URL:-http://127.0.0.1:8545}"
TX_HASH="0x1ce3791a4ceb3a037e5c860d86adf3fbefb70707cd1bf5057359d5d5d9699f97"

curl -s -H 'Content-Type: application/json' --data \
  '{"jsonrpc":"2.0","id":1,"method":"debug_traceTransaction","params":["'"$TX_HASH"'"]}' \
  "$RPC_URL"

curl -s -H 'Content-Type: application/json' --data \
  '{"jsonrpc":"2.0","id":2,"method":"debug_traceTransaction","params":["'"$TX_HASH"'",{}]}' \
  "$RPC_URL"

For another Bor node, replace TX_HASH with one of that node's state-sync
transaction hashes. The exact fixture used for this report is reproducible in
the research checkout with:

cd path_to/erigon
go test \
  -overlay="path_to/overlay.json" \
  ./rpc/jsonrpc \
  -run '^TestValidationDebugTraceTransactionBorDisabledReturnsEmptyArray$' \
  -count=1 -v

A deterministic Bor lookup fixture produced result: [] for both requests.
It recorded two successful state-sync lookups and zero event-load calls,
confirming that the state-sync early-return branch was reached rather than a
transaction-not-found path.

Relevant code

rpc/jsonrpc/tracing.go:258-268 contains the special case:

if isBorStateSyncTxn && (config == nil || config.BorTraceEnabled == nil || !*config.BorTraceEnabled) {
    stream.WriteEmptyArray()
    return nil
}

The code comment says this matches maticnetwork/bor behavior, so the response
appears intentional.

Expected behavior / documentation change

Please document the Bor state-sync special case, including:

• that the default response can be an empty array rather than an Object;
• how callers enable Bor tracing for these transactions;
• the result shape when BorTraceEnabled=true.

Alternatively, return a consistent trace-object schema if that is the intended
cross-network contract.

Impact

Strict clients generated from the documented Object schema can fail to decode a
successful response. An empty array is also ambiguous to callers unless the
state-sync exception is documented.

[VBulikov]

yperbasis added Imp3 as Importance