debug_traceTransaction | Polygon

​

Parameters

• hash — the hash identifying a transaction.
• object — (optional) an object identifying the type of tracer and its configuration:
  • 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 transaction’s calls 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.

• disableStorage — when enabled, it prevents tracing of storage changes made by the transaction being analyzed, which can reduce the resource requirements of the analysis. By default, debug_traceTransaction traces both memory and storage changes, but storage tracing can be particularly resource-intensive, especially for large transactions.
• disableStack — when enabled, it skips tracing of stack changes made by the transaction being analyzed. This can be helpful in optimizing performance and resource usage, especially when analyzing complex transactions, but may result in reduced analysis accuracy that should be considered.
• enableMemory — when false, it prevents tracing of memory changes made by the transaction being analyzed, which can reduce the resource requirements of the analysis. This can be helpful in optimizing performance and resource usage, especially when analyzing complex transactions, but may result in reduced analysis accuracy that should be considered.

• enableReturnData — when false, it prevents the method from tracing the return data produced by the transaction being analyzed. The return data tracing can be particularly resource-intensive, requiring a significant amount of time and processing power to complete.

• timeout — setting that allows developers to customize the method’s timeout period for JavaScript-based tracing calls. The default timeout is 5s, and you can find the values formats in the Go documentation.

​

Response types

​

4byteTracer response

• object — the 4byteTracer traces object:
  • result — a map of the function signature, the call data size, and how many times the function was called.

​

callTracer response

• object — the callTracer traces object:
  • from — the address of the sender who initiated the transaction.
  • gas — the units of gas included in the transaction by the sender.
  • gasused — the total used gas by the call, encoded as hexadecimal.
  • to — the address of the recipient of the transaction if it was a transaction to an address. For contract creation transactions, this field is null.
  • input — the optional input data sent with the transaction, usually used to interact with smart contracts.
  • output — the return value of the call, encoded as a hexadecimal string.
  • error — an error message in case the execution failed.
  • revertReason — the reason why the transaction was reverted, returned by the smart contract if any.
  • calls — a list of sub-calls made by the contract during the call, each represented as a nested call frame object.

​

flatCallTracer response

• array — the transaction’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.

​

prestateTracer response

• object — the prestateTracer traces object:
  • smart contract address — the address of the smart contract associated with the result.
    • balance — the balance of the contract, expressed in Wei and encoded as a hexadecimal string.
    • code — the bytecode of the contract, encoded as a hexadecimal string.
    • nonce — the nonce of the account associated with the contract, represented as an unsigned integer.
    • storage — a map of key-value pairs representing the storage slots of the contract. The keys and values are both encoded as hexadecimal strings.

​

Struct/opcode logger response

• object — the Struct/opcode logger traces object:
  • pc — the current program counter of the transaction, which represents the location of the current opcode being executed. A register that keeps track of the address of the next instruction to be executed in a program.
  • op — the current opcode being executed, such as PUSH1, ADD, or SWAP1. A code that represents a specific operation or instruction that a computer or processor can understand and execute.
  • gas — the amount of gas remaining in the transaction at the current step of execution.
  • gasCost — the amount of gas consumed by the current opcode being executed.
  • depth — the current depth of the call stack for the transaction, reflecting the number of active frames representing nested function calls.
  • stack — the contents of the EVM stack at the current step of the transaction’s execution. The stack is a data structure used by the EVM to manage and manipulate data during the execution of opcodes
  • memory — the contents of the memory at the current step of execution. A temporary data storage location that is available to smart contracts during execution.

​

debug_traceTransaction code examples

const ethers = require('ethers');
const NODE_URL = "CHAINSTACK_NODE_URL";
const provider = new ethers.JsonRpcProvider(NODE_URL);

const traceTransaction = async (txhash) => {

  // Specify the type of tracer: 4byteTracer, callTracer, flatCallTracer, or prestateTracer. Leave empty {} for Struct/opcode logger.
  const tracer = {};
  const traces = await provider.send("debug_traceTransaction", [txhash, tracer]);
  console.log(traces);
};

traceTransaction("0x6be573c85c46d02cd2d47b997d2f153583fbc959541400bc41b9f140d1216772")

from web3 import Web3  
node_url = "CHAINSTACK_NODE_URL" 
web3 = Web3.HTTPProvider(node_url)

tx_hash = "0x6be573c85c46d02cd2d47b997d2f153583fbc959541400bc41b9f140d1216772"

# Specify the type of tracer: 4byteTracer, callTracer, flatCallTracer, or prestateTracer. Leave empty {} for Struct/opcode logger.
tracer = { "tracer": '4byteTracer' }
tx_traces = web3.provider.make_request('debug_traceTransaction', [tx_hash, tracer])
print(tx_traces)

​

Use case

const ethers = require("ethers");
const NODE_URL = "CHAINSTACK_NODE_URL";
const provider = new ethers.JsonRpcProvider(NODE_URL);

// Trace a failed transaction using the callTracer
async function traceTransaction(txHash) {
  const tracer = { tracer: 'callTracer' };
  const result = await provider.send("debug_traceTransaction", [txHash, tracer]);
  return result;
}

// Get all transactions from the specified block number
async function getTransactionsFromBlock(blockNumber) {
  const block = await provider.getBlock(blockNumber, false);
  const txArray = block.transactions;
  return txArray;
}

// Main function that iterates through transactions and extracts data from failed ones
async function main() {
  try {
      const transactions = await getTransactionsFromBlock('latest');

      for (let i = 0; i < transactions.length; i++) {
          const txHash = transactions[i];
          const tx = await provider.getTransactionReceipt(txHash);
          const txStatus = tx.status;

          // If transaction failed, extract data using traceTransaction method
          if (txStatus === 0) {
              console.log(`Transaction ${txHash} failed!`);
              const traces = await traceTransaction(txHash);
              const error = traces.error;
              const reason = traces.revertReason;
              console.log(`Transaction failed with error: ${error}`);
              console.log(`Revert reason: ${reason}\n`);
          }
      }
  } catch (error) {
      console.error(`Error occurred: ${error}`);
  }
}

// Call the main function
main();