debug Namespace

The debug namespace provides powerful introspection capabilities that can be resource-intensive. These methods should be used carefully and are typically only available on trusted nodes with debugging enabled.

Overview

The debug namespace offers methods for debugging transactions, tracing execution, inspecting state, and diagnosing blockchain issues.

Transaction Tracing

debug_traceTransaction

Returns a detailed trace of a transaction’s execution.

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":["0x1234...",{}],"id":1}' \
  http://localhost:8545

params[0]

string

required

Transaction hash (32 bytes, hex encoded)

params[1]

object

Trace configuration options

Show properties

tracer

string

Tracer type: “callTracer”, “prestateTracer”, or custom JavaScript

timeout

string

Timeout in seconds (default: “5s”)

disableStorage

boolean

Disable storage capture (default: false)

disableMemory

boolean

Disable memory capture (default: false)

disableStack

boolean

Disable stack capture (default: false)

result

object

Execution trace with opcode-level details

Show properties

gas

number

Gas used

failed

boolean

Whether execution failed

returnValue

string

Return data (hex)

structLogs

array

Array of execution steps

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "gas": 21000,
    "failed": false,
    "returnValue": "",
    "structLogs": [
      {
        "pc": 0,
        "op": "PUSH1",
        "gas": 79000,
        "gasCost": 3,
        "depth": 1,
        "stack": [],
        "memory": []
      }
    ]
  }
}

debug_traceBlockByNumber

Traces all transactions in a block by block number.

params[0]

string

required

Block number (hex) or “latest”

params[1]

object

Trace configuration (same as debug_traceTransaction)

result

array

Array of transaction traces for all transactions in the block

debug_traceBlockByHash

Traces all transactions in a block by block hash.

params[0]

string

required

Block hash (32 bytes, hex encoded)

params[1]

object

Trace configuration (same as debug_traceTransaction)

debug_traceBlock

Traces all transactions in a raw block.

params[0]

string

required

RLP-encoded block data (hex)

params[1]

object

Trace configuration

Block Inspection

debug_dumpBlock

Returns the state of all accounts at a given block.

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"debug_dumpBlock","params":["latest"],"id":1}' \
  http://localhost:8545

params[0]

string

required

Block number (hex) or “latest”, “earliest”, “pending”

result

object

State dump containing all account data

Show properties

root

string

State root hash

accounts

object

Map of address to account state

debug_printBlock

Returns a human-readable representation of a block.

params[0]

number

required

Block number (decimal)

result

string

Pretty-printed block information

debug_getBlockRlp

Returns RLP-encoded block data.

params[0]

number

required

Block number (decimal)

result

string

RLP-encoded block (hex)

State Inspection

debug_storageRangeAt

Returns storage entries for a contract at a specific transaction.

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"debug_storageRangeAt","params":["0xblockHash",0,"0xcontractAddress","0x0",100],"id":1}' \
  http://localhost:8545

params[0]

string

required

Block hash

params[1]

number

required

Transaction index in block

params[2]

string

required

Contract address

params[3]

string

required

Starting storage key (hex)

params[4]

number

required

Maximum number of entries to return

result

object

Storage range result

Show properties

storage

object

Map of storage keys to values

nextKey

string

Next key for pagination (null if complete)

debug_preimage

Returns the preimage of a hash stored in the database.

params[0]

string

required

Hash (32 bytes, hex)

result

string

Preimage data (hex) or null if not found

debug_getModifiedAccountsByNumber

Returns accounts modified between two blocks.

params[0]

number

required

Start block number (decimal)

params[1]

number

End block number (decimal, optional)

result

array

Array of addresses that were modified

debug_getModifiedAccountsByHash

Returns accounts modified between two blocks (by hash).

params[0]

string

required

Start block hash

params[1]

string

End block hash (optional)

Bad Blocks

debug_getBadBlocks

Returns a list of recently rejected bad blocks.

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"debug_getBadBlocks","params":[],"id":1}' \
  http://localhost:8545

result

array

Array of bad block objects with rejection reasons

Chain Management

debug_setHead

Rewinds the blockchain to a specific block number.

This is a destructive operation that removes blocks from the chain. Use with extreme caution.

params[0]

string

required

Block number to rewind to (hex)

debug_seedHash

Returns the seed hash used for PoW at a given block.

params[0]

number

required

Block number (decimal)

result

string

Seed hash (hex)

Database Operations

debug_chaindbProperty

Returns LevelDB properties.

params[0]

string

required

Property name (e.g., “leveldb.stats”)

result

string

Property value

debug_chaindbCompact

Triggers a database compaction.

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"debug_chaindbCompact","params":[],"id":1}' \
  http://localhost:8545

result

null

null on success

Database compaction can take significant time and resources. Run during low-traffic periods.

Usage Examples

JavaScript - Transaction Tracing

const Web3 = require('web3');
const web3 = new Web3('http://localhost:8545');

// Trace a transaction
async function traceTransaction(txHash) {
  const trace = await web3.currentProvider.send({
    jsonrpc: '2.0',
    method: 'debug_traceTransaction',
    params: [txHash, {
      tracer: 'callTracer',
      timeout: '10s'
    }],
    id: 1
  });
  
  console.log('Gas used:', trace.result.gas);
  console.log('Failed:', trace.result.failed);
  return trace.result;
}

// Usage
traceTransaction('0x1234...');

Python - State Inspection

from web3 import Web3

w3 = Web3(Web3.HTTPProvider('http://localhost:8545'))

# Get modified accounts
def get_modified_accounts(start_block, end_block):
    result = w3.provider.make_request(
        'debug_getModifiedAccountsByNumber',
        [start_block, end_block]
    )
    return result['result']

# Get storage range
def get_storage_range(block_hash, tx_index, contract_addr):
    result = w3.provider.make_request(
        'debug_storageRangeAt',
        [block_hash, tx_index, contract_addr, '0x0', 100]
    )
    return result['result']

Call Tracer Example

// Trace with call tracer for high-level view
const callTrace = await web3.currentProvider.send({
  jsonrpc: '2.0',
  method: 'debug_traceTransaction',
  params: ['0xtxHash', {
    tracer: 'callTracer'
  }],
  id: 1
});

// Result shows call hierarchy
console.log(JSON.stringify(callTrace.result, null, 2));
/*
{
  "type": "CALL",
  "from": "0x...",
  "to": "0x...",
  "value": "0x0",
  "gas": "0x...",
  "gasUsed": "0x...",
  "input": "0x...",
  "output": "0x...",
  "calls": [
    {
      "type": "DELEGATECALL",
      "from": "0x...",
      "to": "0x..."
    }
  ]
}
*/

Performance Considerations

Resource UsageDebug methods can be extremely resource-intensive:

debug_traceTransaction: Can take seconds to minutes for complex transactions
debug_traceBlockByNumber: Multiplies trace time by number of transactions
debug_dumpBlock: Can return very large responses for blocks with many accounts
Storage operations: May require scanning large portions of the state trie

Best Practices

Use timeouts: Always set reasonable timeouts for trace operations
Disable unnecessary data: Use disableStorage, disableMemory, disableStack to reduce overhead
Limit scope: Trace specific transactions rather than entire blocks when possible
Cache results: Store trace results to avoid recomputation
Use dedicated nodes: Run debug operations on separate nodes from production RPC

Enabling Debug APIs

To enable debug APIs on a Viction node:

tomo --http --http.api "eth,net,web3,debug" \
     --http.corsdomain "*" \
     --http.vhosts "*"

Never expose debug APIs on public endpoints. They can:

Consume significant resources
Reveal sensitive state information
Be used for DoS attacks
Impact node performance

Common Use Cases

Transaction Debugging

Trace failed transactions to identify revert reasons and execution flow

Gas Optimization

Analyze opcode execution to optimize gas usage in smart contracts

State Analysis

Inspect contract storage and account states at specific blocks

Security Auditing

Trace contract interactions to verify security properties

RPC APIs

CLI Reference

debug Namespace

Overview

Transaction Tracing

debug_traceTransaction

debug_traceBlockByNumber

debug_traceBlockByHash

debug_traceBlock

Block Inspection

debug_dumpBlock

debug_printBlock

debug_getBlockRlp

State Inspection

debug_storageRangeAt

debug_preimage

debug_getModifiedAccountsByNumber

debug_getModifiedAccountsByHash

Bad Blocks

debug_getBadBlocks

Chain Management

debug_setHead

debug_seedHash

Database Operations

debug_chaindbProperty

debug_chaindbCompact

Usage Examples

JavaScript - Transaction Tracing

Python - State Inspection

Call Tracer Example

Performance Considerations

Best Practices

Enabling Debug APIs

Common Use Cases

Transaction Debugging

Gas Optimization

State Analysis

Security Auditing

Build docs developers (and LLMs) love

RPC APIs

CLI Reference

​Overview

​Transaction Tracing

​debug_traceTransaction

​debug_traceBlockByNumber

​debug_traceBlockByHash

​debug_traceBlock

​Block Inspection

​debug_dumpBlock

​debug_printBlock

​debug_getBlockRlp

​State Inspection

​debug_storageRangeAt

​debug_preimage

​debug_getModifiedAccountsByNumber

​debug_getModifiedAccountsByHash

​Bad Blocks

​debug_getBadBlocks

​Chain Management

​debug_setHead

​debug_seedHash

​Database Operations

​debug_chaindbProperty

​debug_chaindbCompact

​Usage Examples

​JavaScript - Transaction Tracing

​Python - State Inspection

​Call Tracer Example

​Performance Considerations

​Best Practices

​Enabling Debug APIs

​Common Use Cases

Transaction Debugging

Gas Optimization

State Analysis

Security Auditing

Build docs developers (and LLMs) love

Overview

Transaction Tracing

debug_traceTransaction

debug_traceBlockByNumber

debug_traceBlockByHash

debug_traceBlock

Block Inspection

debug_dumpBlock

debug_printBlock

debug_getBlockRlp

State Inspection

debug_storageRangeAt

debug_preimage

debug_getModifiedAccountsByNumber

debug_getModifiedAccountsByHash

Bad Blocks

debug_getBadBlocks

Chain Management

debug_setHead

debug_seedHash

Database Operations

debug_chaindbProperty

debug_chaindbCompact

Usage Examples

JavaScript - Transaction Tracing

Python - State Inspection

Call Tracer Example

Performance Considerations

Best Practices

Enabling Debug APIs

Common Use Cases