Linea · debug

debug_traceTransaction

Replays a transaction and returns its trace.

Executes the transaction identified by the given hash in the exact manner it was executed on the network, replaying all prior transactions in the same block as necessary to reconstruct the correct pre-execution state. When no tracer is specified (or the tracer field is absent), the opcode (struct) logger is used and the result conforms to OpcodeTransactionTrace. When a named tracer is specified via the tracer field in TraceConfig (e.g. "callTracer", "prestateTracer"), the result contains tracer-specific output. Defining the output schemas of named tracers is outside the scope of this specification.

Parameters

Transaction hash required

Schema

{
  "type": "string",
  "title": "32 byte hex value",
  "pattern": "^0x[0-9a-f]{64}$"
}

TraceConfig

Schema

{
  "type": "object",
  "title": "Trace configuration",
  "description": "Configuration object accepted by debug_traceBlockByNumber and debug_traceTransaction.\nWhen the tracer field is absent or empty, the opcode (struct) logger is used and the result conforms to OpcodeTransactionTrace. The fields enableMemory, disableStack, disableStorage, enableReturnData, and limit only apply to the opcode logger and are ignored when a named tracer is set.\nWhen the tracer field is set to a named tracer (e.g. \"callTracer\", \"prestateTracer\"), the result format is tracer-specific. Defining the output schemas of named tracers is outside the scope of this specification.",
  "properties": {
    "debug": {
      "type": "boolean",
      "title": "debug print",
      "description": "Opcode logger only. When true, the client may print the trace output to its internal log during execution. Has no effect on the JSON-RPC response. Ignored when tracer is set. Default: false."
    },
    "disableStack": {
      "type": "boolean",
      "title": "disable stack capture",
      "description": "Opcode logger only. Setting to true disables stack capture in structLogs. When true, the stack field is omitted from each StructLog entry. Ignored when tracer is set. Default: false."
    },
    "disableStorage": {
      "type": "boolean",
      "title": "disable storage capture",
      "description": "Opcode logger only. Setting to true disables storage capture in structLogs. When true, the storage field is omitted from each StructLog entry. Ignored when tracer is set. Default: false."
    },
    "enableMemory": {
      "type": "boolean",
      "title": "enable memory capture",
      "description": "Opcode logger only. Setting to true enables memory capture in structLogs. When false (default), the memory field is omitted from each StructLog entry. Ignored when tracer is set. Default: false."
    },
    "enableReturnData": {
      "type": "boolean",
      "title": "enable return data capture",
      "description": "Opcode logger only. Setting to true enables return data capture in structLogs. When false (default), the returnData field is omitted from each StructLog entry. Ignored when tracer is set. Default: false."
    },
    "limit": {
      "type": "integer",
      "title": "step limit",
      "description": "Opcode logger only. Maximum number of opcode steps to capture. Zero means no limit. When the limit is reached, execution continues but no further StructLog entries are recorded. Ignored when tracer is set. Default: 0 (unlimited)."
    },
    "timeout": {
      "type": "string",
      "title": "execution timeout",
      "description": "Optional duration string specifying a timeout for trace execution. Clients that do not support execution timeouts (e.g. streaming implementations) MAY ignore this field. When supported and the timeout is reached, the client MUST return an error; no partial results are returned. Accepts Go duration strings (e.g. \"5s\", \"300ms\", \"2m\")."
    },
    "tracer": {
      "type": "string",
      "title": "tracer name",
      "description": "The name of a built-in or custom tracer to use. When absent or empty, the opcode (struct) logger is used.\nExample built-in tracer names in go-ethereum include: 4byteTracer, callTracer, prestateTracer, noopTracer, bigramTracer, evmdisTracer, opcountTracer, trigramTracer, unigramTracer.\nClients may support different sets of named tracers.\nCustom JavaScript tracers may also be supplied as an expression string."
    },
    "tracerConfig": {
      "type": "object",
      "title": "tracer configuration",
      "description": "An optional tracer-specific configuration object passed to the named tracer. Only applicable when the tracer field is set. The fields accepted here depend on the named tracer in use."
    }
  }
}

Result

Transaction trace

Schema

{
  "title": "Transaction trace result",
  "anyOf": [
    {
      "type": "object",
      "title": "Opcode tracer result",
      "description": "Returned when no named tracer is specified.",
      "properties": {
        "failed": {
          "type": "boolean",
          "title": "failed",
          "description": "Whether the transaction execution failed (reverted or ran out of gas)."
        },
        "gas": {
          "type": "integer",
          "title": "gas used",
          "description": "Total amount of gas consumed by the transaction."
        },
        "returnValue": {
          "type": "string",
          "title": "return value",
          "description": "The data returned by the transaction. 0x-prefixed hex-encoded bytes. MUST be \"0x\" (not an empty string) when no data was returned.",
          "pattern": "^0x[0-9a-f]*$"
        },
        "structLogs": {
          "type": "array",
          "title": "opcode execution logs",
          "description": "The ordered sequence of opcode execution steps. Will be empty for simple ETH transfers between externally owned accounts that execute no EVM code.",
          "items": {
            "type": "object",
            "title": "Opcode execution log entry",
            "description": "A single step in the EVM execution trace produced by the opcode (struct) logger. One entry is emitted per opcode executed.",
            "properties": {
              "depth": {
                "type": "integer",
                "title": "call depth",
                "description": "The call stack depth at this execution step. Starts at 1 for the outermost call."
              },
              "error": {
                "type": "string",
                "title": "execution error",
                "description": "The error encountered during execution of this opcode, if any. This field MUST be absent when no error occurred. Clients MUST NOT include this field as null or as an empty string when there is no error."
              },
              "gas": {
                "type": "integer",
                "title": "remaining gas",
                "description": "The amount of gas remaining before executing this opcode."
              },
              "gasCost": {
                "type": "integer",
                "title": "gas cost",
                "description": "The gas cost computed for this opcode step — the amount that will be deducted from the remaining gas assuming successful execution. Includes dynamic costs such as memory expansion and storage access charges (e.g. cold vs. warm SLOAD/SSTORE)."
              },
              "memory": {
                "type": "array",
                "title": "EVM memory",
                "description": "The contents of EVM memory at this step, divided into 32-byte chunks. Each element is a 0x-prefixed, zero-padded 32-byte hex word representing a consecutive 32-byte memory slot starting at offset (index * 32). This field is absent (not null) when enableMemory is false.",
                "items": {
                  "type": "string",
                  "title": "32 hex encoded bytes",
                  "pattern": "^0x[0-9a-f]{64}$"
                }
              },
              "op": {
                "type": "string",
                "title": "opcode name",
                "description": "The name of the EVM opcode executed at this step (e.g. \"PUSH1\", \"SSTORE\")."
              },
              "pc": {
                "type": "integer",
                "title": "program counter",
                "description": "The program counter position of this opcode in the contract bytecode."
              },
              "refund": {
                "type": "integer",
                "title": "gas refund counter",
                "description": "The accumulated gas refund counter at this execution step. Clients MUST include this field at every step when it is non-zero. Clients SHOULD include this field at every step even when zero."
              },
              "returnData": {
                "type": "string",
                "title": "return data",
                "description": "The return data from the most recent call at this step. This field is absent when enableReturnData is false.",
                "pattern": "^0x[0-9a-f]*$"
              },
              "stack": {
                "type": "array",
                "title": "EVM stack",
                "description": "The contents of the EVM stack at this step, ordered from bottom (index 0) to top (last element). Each value is a 0x-prefixed uint256 quantity. This field is absent when disableStack is true.",
                "items": {
                  "type": "string",
                  "title": "hex encoded 256 bit unsigned integer",
                  "pattern": "^0x(0|[1-9a-f][0-9a-f]{0,63})$"
                }
              },
              "storage": {
                "type": "object",
                "title": "contract storage",
                "description": "A cumulative snapshot of all storage slots accessed or modified by the current contract up to and including this step. Keys are 0x-prefixed, zero-padded 32-byte storage slot indices; values are the 32-byte stored values reflecting the post-execution state of the opcode at this step (i.e., for SSTORE, the value reflects the new value just written).\nThis field is only populated at SLOAD and SSTORE opcodes. At all other opcodes, this field MUST be absent (not an empty object). This field is absent when disableStorage is true."
              }
            },
            "required": [
              "pc",
              "op",
              "gas",
              "gasCost",
              "depth"
            ]
          }
        }
      },
      "required": [
        "gas",
        "failed",
        "returnValue",
        "structLogs"
      ]
    },
    {
      "title": "Named tracer result",
      "description": "Returned when a named tracer is specified via the tracer field. The format is tracer-specific and not defined by this specification. Named tracers may return any JSON value (object, array, integer, etc.)."
    }
  ]
}

Example request

Endpoint: https://your-linea-node.azxa.io

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "debug_traceTransaction",
  "params": [
    "0xdd8cf045113754c306ba9ac8ac8786235e33bc5c087678084ef260a2a583f127",
    {
      "disableStack": false,
      "disableStorage": false,
      "enableMemory": false,
      "enableReturnData": false
    }
  ]
}

Example response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "failed": false,
    "gas": 26916,
    "returnValue": "0x",
    "structLogs": [
      {
        "depth": 1,
        "gas": 68612,
        "gasCost": 3,
        "op": "PUSH1",
        "pc": 0,
        "stack": [
          "0x60"
        ]
      },
      {
        "depth": 1,
        "gas": 68609,
        "gasCost": 3,
        "op": "PUSH1",
        "pc": 2,
        "stack": [
          "0x60",
          "0x40"
        ]
      },
      {
        "depth": 1,
        "gas": 68606,
        "gasCost": 12,
        "op": "MSTORE",
        "pc": 4,
        "stack": []
      }
    ]
  }
}

Test fixture

Fixture: trace-contract-call

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "debug_traceTransaction",
  "params": [
    "0xc1d605c6612a5fe84dc95810030bfe5b1d327652b381bc695e28f50d13b2b09e"
  ]
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "gas": 66259,
    "failed": false,
    "returnValue": "0x60004381526020014681526020014181526020014881526020014481526020013281526020013481526020016000f3",
    "structLogs": [
      {
        "pc": 0,
        "op": "PUSH1",
        "gas": 23644,
        "gasCost": 3,
        "depth": 1,
        "stack": []
      },
      {
        "pc": 2,
        "op": "CODESIZE",
        "gas": 23641,
        "gasCost": 2,
        "depth": 1,
        "stack": [
          "…"
        ]
      },
      {
        "pc": 3,
        "op": "SUB",
        "gas": 23639,
        "gasCost": 3,
        "depth": 1,
        "stack": [
          "…",
          "…"
        ]
      },
      {
        "pc": 4,
        "op": "DUP1",
        "gas": 23636,
        "gasCost": 3,
        "depth": 1,
        "stack": [
          "…"
        ]
      },
      "…",
      {
        "pc": 12,
        "op": "RETURN",
        "gas": 23609,
        "gasCost": 0,
        "depth": 1,
        "stack": [
          "…",
          "…"
        ]
      }
    ]
  }
}

cURL

curl -X POST https://your-linea-node.azxa.io \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"debug_traceTransaction","params":["0xdd8cf045113754c306ba9ac8ac8786235e33bc5c087678084ef260a2a583f127",{"disableStack":false,"disableStorage":false,"enableMemory":false,"enableReturnData":false}]}'