debug

The debug namespace provides RPC endpoints designed for developers to inspect and debug the internal workings of the node. These endpoints offer detailed execution traces for transactions and calls, enable inspection of account storage, and allow for simulation of state changes. They are especially useful during development and troubleshooting to gain insight into the node’s processing of transactions and blocks.

---

debug_accountRange

Description: Returns a range of account-related information. This function may be used to inspect a segment of the state related to account data.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_accountRange",
  "params": ["0xstartKey", "0xendKey"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "accounts": {
      "0x1234...": { "balance": "0xde0b6b3a7640000", "nonce": "0x0" },
      "0xabcd...": { "balance": "0x5f5e100", "nonce": "0x1" }
    },
    "nextKey": "0x5678..."
  }
}

Parameters:

• startKey (string): The starting key of the account range.

• endKey (string): The ending key of the account range.

---

debug_backtraceAt

Description: Returns the execution backtrace at a specified program counter (PC) or function name, helping to diagnose where errors occur.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_backtraceAt",
  "params": ["PUSH1"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Backtrace:\n0: PUSH1 at 0x04\n1: CALL at 0x15\n..."
}

Parameters:

• location (string): The function name or PC value at which to retrieve the backtrace.

---

debug_blockProfile

Description: Starts profiling of block processing. Useful for gathering performance metrics on block execution.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_blockProfile",
  "params": [],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Block profiling started."
}

Parameters: None.

---

debug_chaindbCompact

Description: Triggers a compaction of the chain database to reclaim space and improve performance.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_chaindbCompact",
  "params": [],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Chain database compaction initiated."
}

Parameters: None.

---

debug_chaindbProperty

Description: Retrieves a specific property from the chain database.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_chaindbProperty",
  "params": ["propertyName"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Property value"
}

Parameters:

• propertyName (string): The name of the database property to retrieve.

---

debug_cpuProfile

Description: Generates a CPU profile of the node’s current execution for performance analysis.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_cpuProfile",
  "params": ["profileName"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "CPU profile 'profileName' written successfully."
}

Parameters:

• profileName (string): A name identifier for the CPU profile.

---

debug_dbAncient

Description: Accesses a specific ancient (old) data entry from the database.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_dbAncient",
  "params": ["ancientKey"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xancientdata..."
}

Parameters:

• ancientKey (string): The key or identifier for the ancient data.

---

debug_dbAncients

Description: Lists all available ancient data entries in the database.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_dbAncients",
  "params": [],
  "id": 1
}

Expected Response:

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

Parameters: None.

---

debug_dbGet

Description: Retrieves a value from the database using a given key.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_dbGet",
  "params": ["dbKey"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xvalue..."
}

Parameters:

• dbKey (string): The key for the database entry.

---

debug_dumpBlock

Description: Dumps detailed information about a block for debugging purposes.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_dumpBlock",
  "params": ["0xa966a73858f8e41c8374f6e91139a1eed9a41fc961e2588478b652c78ba1fc98"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "block": { "number": "0x10", "transactions": [ ... ], ... } }
}

Parameters:

• blockHash (string): The hash of the block to dump.

---

debug_freeOSMemory

Description: Forces the node to free unused memory back to the operating system.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_freeOSMemory",
  "params": [],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Unused memory freed."
}

Parameters: None.

---

debug_freezeClient

Description: Freezes the client’s state for debugging, preventing further state changes.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_freezeClient",
  "params": [],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Client frozen."
}

Parameters: None.

---

debug_gcStats

Description: Returns statistics about the garbage collection (GC) performance and memory usage.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_gcStats",
  "params": [],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "numGC": 15,
    "pauseTotal": "150ms",
    "heapAlloc": "0x1e8480"
  }
}

Parameters: None.

---

debug_getAccessibleState

Description: Returns information about the state that is accessible to the debugger, such as cached trie nodes.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_getAccessibleState",
  "params": [],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "stateNodes": 12345, "size": "0xabcde" }
}

Parameters: None.

---

debug_getBadBlocks

Description: Returns a list of blocks that have been marked as bad (i.e. invalid or corrupt).

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_getBadBlocks",
  "params": [],
  "id": 1
}

Expected Response:

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

Parameters: None.

---

debug_getModifiedAccountsByHash

Description: Returns a list of accounts modified in a specific state trie, identified by its state root hash.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_getModifiedAccountsByHash",
  "params": ["0xstateRootHash"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "0xaccount1": { "balance": "0x...", "nonce": "0x..." },
    "0xaccount2": { "balance": "0x...", "nonce": "0x..." }
  }
}

Parameters:

• stateRootHash (string)

---

debug_getModifiedAccountsByNumber

Description: Returns modified accounts for a given block number.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_getModifiedAccountsByNumber",
  "params": ["0xa"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "0xaccount1": {...}, "0xaccount2": {...} }
}

Parameters:

• block (string): Block number or tag.

---

debug_getRawBlock

Description: Retrieves the raw block data in RLP-encoded format for a given block hash.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_getRawBlock",
  "params": ["0xblockhash"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xRLPencodedBlockData..."
}

Parameters:

• blockHash (string)

---

debug_getRawHeader

Description: Retrieves the raw RLP-encoded block header for a given block hash.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_getRawHeader",
  "params": ["0xblockhash"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xRLPencodedHeader..."
}

Parameters:

• blockHash (string)

---

debug_getRawReceipts

Description: Returns the raw, RLP-encoded receipts for a given block hash.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_getRawReceipts",
  "params": ["0xblockhash"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xRLPencodedReceipts..."
}

Parameters:

• blockHash (string)

---

debug_getRawTransaction

Description: Retrieves the raw, RLP-encoded transaction data for a given transaction hash.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_getRawTransaction",
  "params": ["0xtransactionHash"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xRLPencodedTransaction..."
}

Parameters:

• transactionHash (string)

---

debug_goTrace

Description: Returns a trace of Go runtime events that occurred during execution. This can help diagnose performance issues at the language runtime level.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_goTrace",
  "params": [],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Go runtime trace data..."
}

Parameters: None.

---

debug_intermediateRoots

Description: Returns a list of intermediate state roots computed during block processing.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_intermediateRoots",
  "params": ["0xblockhash"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": ["0xroot1", "0xroot2", "..."]
}

Parameters:

• blockHash (string)

---

debug_memStats

Description: Returns memory statistics of the node, including heap usage and GC metrics.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_memStats",
  "params": [],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "heapAlloc": "0x1e8480",
    "heapSys": "0x2dc6c0",
    "gcPause": "150ms"
  }
}

Parameters: None.

---

debug_mutexProfile

Description: Returns a profile of mutex contention in the node, useful for debugging concurrency issues.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_mutexProfile",
  "params": [],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Mutex profile data..."
}

Parameters: None.

---

debug_preimage

Description: Retrieves the preimage (original input) for a given hash, if available. This is used for state debugging and verification.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_preimage",
  "params": ["0xhash"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xoriginalData..."
}

Parameters:

• hash (string): The hash whose preimage is to be retrieved.

---

debug_printBlock

Description: Prints a human-readable representation of a block for debugging purposes.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_printBlock",
  "params": ["0xblockhash"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Block details: number, timestamp, transactions, etc."
}

Parameters:

• blockHash (string)

---

debug_seedHash

Description: Returns the seed hash used for generating the cache and dataset in Ethash. This is useful for verifying the current mining epoch parameters.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_seedHash",
  "params": [60000],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xseedhash..."
}

Parameters:

• blockNumber (number): The block number for which to compute the seed hash.

---

debug_setBlockProfileRate

Description: Sets the rate at which block profiling data is collected.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_setBlockProfileRate",
  "params": [1],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Block profile rate set to 1."
}

Parameters:

• rate (number): The sampling rate.

---

debug_setGCPercent

Description: Sets the target percentage of heap in use before triggering garbage collection.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_setGCPercent",
  "params": [100],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "GC percent set to 100."
}

Parameters:

• percent (number): The desired GC percentage.

---

debug_setHead

Description: Manually sets the head (latest block) of the chain. This is primarily for debugging purposes.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_setHead",
  "params": ["0xblockhash"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Head set to 0xblockhash."
}

Parameters:

• blockHash (string): The hash to set as the new head.

---

debug_setMutexProfileFraction

Description: Adjusts the fraction of mutex events that are profiled. This can help in diagnosing lock contention issues.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_setMutexProfileFraction",
  "params": [1],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Mutex profile fraction set to 1."
}

Parameters:

• fraction (number): The profile fraction.

---

debug_setTrieFlushInterval

Description: Sets the interval at which the state trie is flushed to disk.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_setTrieFlushInterval",
  "params": [1000],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Trie flush interval set to 1000."
}

Parameters:

• interval (number): The flush interval in number of operations or time units.

---

debug_stacks

Description: Returns the current stack traces for all goroutines. This is useful for diagnosing deadlocks and performance issues.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_stacks",
  "params": [],
  "id": 1
}

Expected Response: A long string containing stack traces.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "goroutine 1 [running]:\nmain.main()\n\t/path/to/main.go:42 +0x123\n..."
}

Parameters: None.

---

debug_standardTraceBadBlockToFile

Description: Writes a standard trace of a bad block to a file for later analysis.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_standardTraceBadBlockToFile",
  "params": ["0xbadblockhash", "badblocktrace.log"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Trace written to badblocktrace.log."
}

Parameters:

• blockHash (string)

• filename (string)

---

debug_standardTraceBlockToFile

Description: Writes a standard trace of a block to a file.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_standardTraceBlockToFile",
  "params": ["0xblockhash", "blocktrace.log"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Trace written to blocktrace.log."
}

Parameters:

• blockHash (string)

• filename (string)

---

debug_startCPUProfile

Description: Starts CPU profiling and writes the profile data to a specified file.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_startCPUProfile",
  "params": ["cpuProfile.out"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "CPU profiling started."
}

Parameters:

• filename (string): The output file name for the CPU profile.

---

debug_startGoTrace

Description: Starts Go runtime tracing and writes the trace data to a specified file.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_startGoTrace",
  "params": ["goTrace.out"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Go tracing started."
}

Parameters:

• filename (string): The output file for the trace.

---

debug_stopCPUProfile

Description: Stops the CPU profiling that was previously started.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_stopCPUProfile",
  "params": [],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "CPU profiling stopped."
}

Parameters: None.

---

debug_stopGoTrace

Description: Stops the Go runtime tracing.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_stopGoTrace",
  "params": [],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Go tracing stopped."
}

Parameters: None.

---

debug_storageRangeAt

Description: Returns a range of storage entries for a given contract at a specified block and transaction index.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_storageRangeAt",
  "params": [
    "0xblockNumber", 
    "0xtransactionIndex", 
    "0xcontractAddress", 
    "0xstartKey", 
    10
  ],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "storage": {
      "0x0": "0xvalue...",
      "0x1": "0xvalue..."
    },
    "nextKey": "0x2"
  }
}

Parameters:

• blockNumber (string): The block number in hex.

• transactionIndex (string): The index of the transaction in hex.

• contractAddress (string): The address of the contract.

• startKey (string): The storage key to start from.

• maxResults (number): Maximum number of entries to return.

---

debug_traceBadBlock

Description: Traces the execution of a block that is known to be bad (invalid or corrupt) and returns detailed trace data.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_traceBadBlock",
  "params": ["0xbadblockhash"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "trace": "Detailed trace data of bad block." }
}

Parameters:

• blockHash (string): The hash of the bad block.

---

debug_traceBlock

Description: Traces the execution of a block and returns detailed execution traces including opcode level logs.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_traceBlock",
  "params": ["0xblockhash"],
  "id": 1
}

Expected Response: An object containing detailed trace logs.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "structLogs": [ /* log entries */ ] }
}

Parameters:

• blockHash (string): The hash of the block to trace.

---

debug_traceBlockByHash

Description: Traces the execution of a block identified by its hash.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_traceBlockByHash",
  "params": ["0xblockhash"],
  "id": 1
}

Expected Response: Same as debug_traceBlock.

Parameters:

• blockHash (string)

---

debug_traceBlockByNumber

Description: Traces the execution of a block by its number (or tag).

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_traceBlockByNumber",
  "params": ["latest"],
  "id": 1
}

Expected Response: Returns detailed trace logs for the block.

Parameters:

• block (string): Block number in hex or tag (e.g., "latest").

---

debug_traceBlockFromFile

Description: Traces a block using data read from a file, which contains a previously exported block trace.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_traceBlockFromFile",
  "params": ["blocktrace.dat"],
  "id": 1
}

Expected Response: Returns the trace data extracted from the file.

Parameters:

• filename (string): The file containing the block trace.

---

debug_traceCall

Description: Simulates a transaction call and returns an execution trace, including opcode steps, gas usage, and state changes.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_traceCall",
  "params": [
    {
      "from": "0x1234567890abcdef1234567890abcdef12345678",
      "to": "0xabcdef1234567890abcdef1234567890abcdef12",
      "gas": "0x76c0",
      "gasPrice": "0x9184e72a000",
      "value": "0x0",
      "data": "0xabcdef"
    },
    "latest",
    { "disableMemory": false, "disableStack": false, "disableStorage": true }
  ],
  "id": 1
}

Expected Response: Returns a trace object similar to:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "failed": false,
    "gas": 80000,
    "returnValue": "0x123456",
    "structLogs": [ /* array of opcode logs */ ]
  }
}

Parameters:

• callObject (object): Contains transaction call details.

• blockIdentifier (string): Block number/tag.

• traceConfig (object): Optional config to disable memory, stack, or storage traces.

---

debug_traceTransaction

Description: Returns a detailed execution trace for a given transaction, showing all opcodes executed, gas used per step, and state changes.

Sample Request:

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

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "failed": false,
    "gas": 21000,
    "returnValue": "0x",
    "structLogs": [
      {
        "pc": 0,
        "op": "PUSH1",
        "gas": 21000,
        "gasCost": 3,
        "depth": 1,
        "stack": ["0x80"],
        "memory": [],
        "storage": {}
      }
      // ... additional logs ...
    ]
  }
}

Parameters:

• transactionHash (string)

---

debug_verbosity

Description: Sets or retrieves the current logging verbosity level of the node for debugging purposes.

Sample Request (Set Verbosity):

{
  "jsonrpc": "2.0",
  "method": "debug_verbosity",
  "params": [4],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Verbosity level set to 4."
}

Parameters:

• level (number): The verbosity level (e.g., 0 for minimal logging, higher numbers for more detailed logs).

---

debug_vmodule

Description: Sets the logging module-specific verbosity. This allows fine-grained control over logging output for specific components.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_vmodule",
  "params": ["module=2"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "vmodule set to module=2."
}

Parameters:

• vmodule (string): A string defining module-specific verbosity settings.

---

debug_writeBlockProfile

Description: Writes the current block profile data to a specified file for offline analysis.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_writeBlockProfile",
  "params": ["blockProfile.out"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Block profile written to blockProfile.out."
}

Parameters:

• filename (string): The target file name.

---

debug_writeMemProfile

Description: Writes the current memory profile to a file.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_writeMemProfile",
  "params": ["memProfile.out"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Memory profile written to memProfile.out."
}

Parameters:

• filename (string)

---

debug_writeMutexProfile

Description: Writes the current mutex contention profile to a file.

Sample Request:

{
  "jsonrpc": "2.0",
  "method": "debug_writeMutexProfile",
  "params": ["mutexProfile.out"],
  "id": 1
}

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Mutex profile written to mutexProfile.out."
}

Parameters:

• filename (string)