# Module debug The `debug` API gives you access to several non-standard RPC methods, which will allow you to inspect, debug and set certain debugging flags during runtime. ## Method debug_blockProfile The `blockProfile` method turns on block profiling for the given duration and writes profile data to disk. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually using debug_writeBlockProfile. Parameters: - file: string, required, file name - nsec: uint, required, number of seconds Returns: result: error Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_blockProfile", "params": [ "block-profile.bin", 10 ] }' | jq ``` ## Method debug_chaindbCompact The `chaindbCompact` method flattens the entire key-value database into a single level, removing all unused slots and merging all keys. Parameters: None Returns: result: error Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_chaindbCompact" }' | jq ``` ## Method debug_chaindbProperty The `chaindbProperty` method returns leveldb properties of the key-value database. Parameters: - property: string, required Returns: result: string Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_chaindbProperty", "params": [ "" ] }' | jq ``` ## Method debug_cpuProfile The `cpuProfile` method turns on CPU profiling for the given duration and writes profile data to disk. Parameters: - file: string, required, file name - nsec: uint, required, number of seconds Returns: result: error Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_cpuProfile", "params": [ "cpu-profile.bin", 10 ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": null } ``` ## Method debug_dbGet The `dbGet` method returns the raw value of a key stored in the database. Parameters: - key: string, required Returns: result: array of byte Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_dbGet", "params": [ "key" ] }' | jq ``` ## Method debug_dumpBlock The `dumpBlock` method retrieves the entire state of the database at a given block. Parameters: - number: BlockNumber, required, block number Returns: result: object Dump Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_dumpBlock", "params": [ "earliest" ] }' | jq ``` Response: See [debug_dumpBlock.json](./debug_dumpBlock_response.json) ## Method debug_getBadBlocks The `getBadBlocks` method returns a list of the last 'bad blocks' that the client has seen on the network and returns them as a JSON list of block-hashes. Parameters: None Returns: result: array of BadBlockArgs Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_getBadBlocks" }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": [] } ``` ## Method debug_gcStats The `gcStats` method returns garbage collection statistics. Parameters: None Returns: result: ojbect GCStats See for information about the fields of the returned object. Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_gcStats" }' | jq ``` Response: See [debug_gcStats.json](./debug_gcStats_response.json) ## Method debug_getBlockRlp The `getBlockRlp` retrieves the RLP encoded for of a single block. Parameters: - number: uint64, required, block number Returns: result: string Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_getBlockRlp", "params": [ 0 ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": "f9029af90295a00000000000000000000000000000000000000000000000000000000000000000a01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347940000000000000000000000000000000000000000a049be235b0098b048f9805aed38a279d8c189b469ff9ba307b39c7ad3a3bc55aea056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421a056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421b901000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001808347b76080845cefae27b89d000000000000000000000000000000000000000000000000000000000000000025c65b4b379ac37cf78357c4915f73677022eaffc7d49d0a2cf198deebd6ce581af465944ec8b2bbcfccdea1006a5cfa7d9484b5b293b46964c265c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000000880000000000000000808080c0c0" } ``` ## Method debug_getModifiedAccountsByHash The `getModifiedAccountsByHash` method returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash, or storage hash. With one parameter, returns the list of accounts modified in the specified block. Parameters: - startHash: hash, required, start block hash - endHash: hash optional, end block hash Returns: result: array of address Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_getModifiedAccountsByNumber", "params": [ "start-hash", "end-hash" ] }' | jq ``` ## Method debug_getModifiedAccountsByNumber The `getModifiedAccountsByNumber` method returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash or storage hash. Parameters: - startNum: uint64, required, start block number - endNum: uint64, optional, end block number Returns: result: array of address Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_getModifiedAccountsByNumber", "params": [ 1 ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": null } ``` ## Method debug_goTrace The `goTrace` method turns on Go runtime tracing for the given duration and writes trace data to disk. Parameters: - file: string, required, file name - nsec: uint, required, number of seconds Returns: result: error Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_goTrace", "params": [ "go-trace.bin", 10 ] }' | jq ``` ## Method debug_freeOSMemory The debug `freeOSMemory` forces garbage collection. Parameters: None Returns: result: null Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_freeOSMemory" }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": null } ``` ## Method debug_memStats The `memStats` method returns detailed runtime memory statistics. Parameters: None Returns: result: object MemStats Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_memStats" }' | jq ``` Response: See [debug_memStats_response.json](./debug_memStats_response.json) ## Method debug_mutexProfile The `mutexProfile` method turns on mutex profiling for nsec seconds and writes profile data to file. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually. Parameters: - file: string, required, file name - nsec: uint, required, number of seconds Returns: result: error Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_mutexProfile", "params": [ "mutex-profile.bin", 10 ] }' | jq ``` ## Method debug_preimage The `preimage` method returns the preimage for a sha3 hash, if known. Parameters: - hash: hash, required Returns: result: array of bytes Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_preimage", "params": [ "hash", ] }' | jq ``` ## Method debug_printBlock The `printBlock` method retrieves a block and returns its pretty printed form. Parameters: - number: uint64, required, block number Returns: result: string Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_printBlock", "params": [ 0 ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": "Block(#0): Size: 669.00 B {\nMinerHash: 5b1ad24d49ce2360509d0c13fd05358abbab323bf6021d8e85ebcc2b2ec7841f\nHeader(4a9d748bd78a8d0385b67788c2435dcdb914f98a96250b68863a1f8b7642d6b1):\n[\n\tParentHash:\t 0000000000000000000000000000000000000000000000000000000000000000\n\tUncleHash:\t 1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347\n\tCoinbase:\t 0000000000000000000000000000000000000000\n\tRoot:\t\t 49be235b0098b048f9805aed38a279d8c189b469ff9ba307b39c7ad3a3bc55ae\n\tTxSha\t\t 56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421\n\tReceiptSha:\t 56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421\n\tBloom:\t\t 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000\n\tDifficulty:\t 1\n\tNumber:\t\t 0\n\tGasLimit:\t 4700000\n\tGasUsed:\t 0\n\tTime:\t\t 1559211559\n\tExtra:\t\t \u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000%ĸ[K7ĸĸ|ĸĸWsŐ_sgp\"ĸĸĸĸԝ\n,ĸĸĸĸĸĸX\u001aĸeĸNȲĸĸĸޡ\u0000j\\ĸ}ĸĸĸĸĸĸidbĸe\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\n\tMixDigest: 0000000000000000000000000000000000000000000000000000000000000000\n\tNonce:\t\t 0000000000000000\n]\nTransactions:\n[]\nUncles:\n[]\n}\n" } ``` ## Method debug_seedHash The `seedHash` method retrieves the seed hash of a block. Parameters: - number: uint64, required, block number Returns: result: string Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_seedHash", "params": [ 0 ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": "0x0000000000000000000000000000000000000000000000000000000000000000" } ``` ## Method debug_setBlockProfileRate The `setBlockProfileRate` method sets the rate (in samples/sec) of goroutine block profile data collection. A non-zero rate enables block profiling, setting it to zero stops the profile. Collected profile data can be written using `debug_writeBlockProfile`. Parameters: - rate: int, required Returns: result: null Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_setBlockProfileRate", "params": [ 0 ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": null } ``` ## Method debug_setGCPercent The `setGCPercent` method sets the garbage collection target percentage. A negative value disables garbage collection. Parameters: - v: int, required Returns: result: int Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_setGCPercent", "params": [ 80 ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": 100 } ``` ## Method debug_setHead The `setHead` method sets the current head of the local chain by block number. Note, this is a destructive action and may severely damage your chain. Use with extreme caution. Parameters: - number: uint64, required, block number Returns: result: string Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_setHead", "params": [ "0x544b420" ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": null } ``` ## Method debug_stacks The `stacks` method returns a printed representation of the stacks of all goroutines. Note that the web3 wrapper for this method takes care of the printing and does not return the string. Parameters: None Returns: result: string Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_stacks" }' | jq ``` Response: See [debug_stacks_response.json](./debug_stacks_response.json) ## Method debug_startCPUProfile The `startCPUProfile` method turns on CPU profiling indefinitely, writing to the given file. Parameters: - file: string, required, file name Returns: result: error Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_startCPUProfile", "params": [ "cpu-profile.bin" ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": null } ``` ## Method debug_stopCPUProfile The `stopCPUProfile` method stops an ongoing CPU profile. Parameters: None Returns: result: error Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_stopCPUProfile" }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": null } ``` ## Method debug_startGoTrace The `startGoTrace` starts writing a Go runtime trace to the given file. Parameters: - file: string, required, file name Returns: result: error Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_startGoTrace", "params": [ "go-trace.bin" ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": null } ``` ## Method debug_stopGoTrace The `stopGoTrace` method stops writing the Go runtime trace. Parameters: None Returns: result: error Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_stopGoTrace" }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": null } ``` ## Method debug_storageRangeAt The `storageRangeAt` method returns the storage at the given block height and transaction index. The result can be paged by providing a maxResult to cap the number of storage slots returned as well as specifying the offset via keyStart (hash of storage key). Parameters: - blockHash: Hash, required - txIndex: int, required - contractAddress: address, required - keyStart: array of bytes, required - maxResult: int, required Returns: result: object StorageRangeResult Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_storageRangeAt" }' | jq ``` ## Method debug_traceBlock The `debug_traceBlock` method will return a full stack trace of all invoked opcodes of all transaction that were included in this block. Note, the parent of this block must be present or it will fail. For the second parameter see TraceConfig reference. Parameters: - blob: array of byte, required, the RLP encoded block - config: object of TraceConfig, optional Returns: result: array of object txTraceResult Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_traceBlock", "params": [ "RLP_ENCODED_BLOCK" ] }' | jq ``` ## Method debug_traceBlockByHash The `traceBlockByHash` method accepts a block hash and will replay the block that is already present in the database. Parameters: - hash: Hash, required, block hash - config: TraceConfig, optional Returns: result: array of object txTraceResult Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_traceBlockByHash", "params": [ "block-hash" ] }' | jq ``` ## Method debug_traceBlockByNumber The `debug_traceBlockByNumber` method accepts a block number and will replay the block that is already present in the database. Parameters: - number: BlockNumber, required, block number - config: TraceConfig, optional Returns: result: array of object txTraceResult Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_traceBlockByNumber", "params": [ "latest" ] }' | jq ``` Response: See [debug_traceBlockByNumber_response.json](./debug_traceBlockByNumber_response.json) ## Method debug_traceBlockFromFile The `traceBlockFromFile` meothod accepts a file containing the RLP of the block. Parameters: - file: string, required, file name - config: object of TraceConfig, optional Returns: result: array of object txTraceResult Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_traceBlockFromFile", "params": [ "filename" ] }' | jq ``` ## Method debug_traceCall The `traceCall` method lets you run an eth_call within the context of the given block execution using the final state of parent block as the base. Parameters: - args: TransactionArgs, required - blockNrOrHash: BlockNumberOrHash, required, hash or number - config: TraceCallConfig, optional Returns: same as debug_traceTransaction Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_traceCall", "params": [ { "to": "0x46eda75e7ca73cb1c2f83c3927211655420dbc44", "data": "0x3fb5c1cb00000000000000000000000000000000000000000000000000000000000003e7" }, "latest", ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": { "gas": 21528, "failed": false, "returnValue": "", "structLogs": [] } } ``` ## Method debug_traceTransaction The `traceTransaction` method debugging method will attempt to run the transaction in the exact same manner as it was executed on the network. It will replay any transaction that may have been executed prior to this one before it will finally attempt to execute the transaction that corresponds to the given hash. Parameters: - hash: Hash, required, transaction hash - config: TraceConfig, optional Returns: result: object Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_traceTransaction", "params": [ "tx-hash" ] }' | jq ``` ## Method debug_verbosity The `verbosity` method sets the logging verbosity ceiling. Log messages with level up to and including the given level will be printed. Parameters: - level: int, required Returns: result: null Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_verbosity", "params": [ 3 ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": null } ``` ## Method debug_vmodule The `vmodule` method sets the logging verbosity pattern. Parameters: - pattern: string, required Returns: result: error Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_vmodule", "params": [ "eth/*=3,p2p=4" ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": null } ``` ## Method debug_writeBlockProfile The `writeBlockProfile` method writes a goroutine blocking profile to the given file. Parameters: - file: string, required Returns: result: error Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_writeBlockProfile", "params": [ "block-profile.bin" ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": null } ``` ## Method debug_writeMemProfile The `writeMemProfile` method writes an allocation profile to the given file. Note that the profiling rate cannot be set through the API, it must be set on the command line using the `--pprof-memprofilerate` flag. Parameters: - file: string, required, file name Returns: result: error Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_writeMemProfile", "params": [ "memory-profile.bin", ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": null } ``` ## Method debug_writeMutexProfile The `writeMutexProfile` method writes a goroutine blocking profile to the given file. Parameters: - file: string, required, file name Returns: result: error Example: ```shell curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{ "jsonrpc": "2.0", "id": 1001, "method": "debug_writeMutexProfile", "params": [ "mutex-profile.bin", ] }' | jq ``` Response: ```json { "jsonrpc": "2.0", "id": 1001, "result": null } ```