gen_dbg_traceTransaction

Retrieves the full execution trace for a transaction, including the return data, stdout/stderr, GenVM logs, and the exact error if execution failed.

Method: gen_dbg_traceTransaction

Parameters:

• request (object, required):
  • txID (string, required): Transaction ID (hex-encoded with 0x prefix)
  • round (integer, optional): Consensus round number (default: 0)

Returns: Transaction execution trace object

Response Fields:

Example:

{
  "jsonrpc": "2.0",
  "method": "gen_dbg_traceTransaction",
  "params": [{"txID": "0x563f046c187d711127c51213ca62e2e4fee52009a98f0989a73a0a0382d21890", "round": 0}],
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "0x563f046c187d711127c51213ca62e2e4fee52009a98f0989a73a0a0382d21890",
    "result_code": 2,
    "return_data": "0x2e0464617461b402696e76616c69645f636f6e7472616374...",
    "stdout": "",
    "stderr": "",
    "genvm_log": [
      {
        "file": "src/lib.rs:82",
        "level": "error",
        "message": "vm error",
        "error": {"causes": ["VMError(invalid_contract absent_runner_comment)"]}
      }
    ],
    "storage_proof": "0x99ff0d9125e1fc9531a11262e15aeb2c60509a078c4cc4c64cefdfb06ff68647",
    "run_time": "0s",
    "leader_public_data": "0x0e076e645f6f75747305"
  },
  "id": 1
}

Notes:

• If the trace isn't stored locally (e.g., the node restarted or data was pruned), the endpoint will replay the transaction automatically.
• Retention. Operators bound the trace store with node.trace.retention_blocks (default 1,000,000 blocks; 0 disables). A trace below the retention watermark is gone, so this endpoint falls back to a live replay — reconstructed from the latest on-chain view, and not byte-identical to the stored artifact. A single trace larger than node.trace.max_trace_bytes (default 32 MB) is never stored, which produces the same fallback.
• Field bound. The free-form execution-output fields (return_data, stdout, stderr, genvm_log) carry whatever the replayed contract emitted, so their size is contract-controlled. Each is capped at node.trace.max_debug_field_bytes (default 256 KB; 0 takes the default). When a field is cut, the truncation is marked in-band — a trailing ...[truncated: N of M bytes omitted from gen_dbg trace] on a string field, or a final {"truncated": "..."} entry on genvm_log — so the reply stays honest rather than silently short.
• This endpoint is in the genlayer_debug group, which is disabled by default. Enable it deliberately, and only on an RPC bind that untrusted callers cannot reach: it replays a transaction through GenVM and returns internal execution output, so it is debug tooling, not a public API.
• Use result_code to determine execution outcome: 0 = contract returned successfully, 1 = contract raised a user error, 2 = GenVM encountered an error, 3 = internal error.