debug Namespace

Debugging and diagnostic RPC methods for transaction tracing and state inspection

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 Usage

Debug 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

1. Use timeouts: Always set reasonable timeouts for trace operations
2. Disable unnecessary data: Use disableStorage, disableMemory, disableStack to reduce overhead
3. Limit scope: Trace specific transactions rather than entire blocks when possible
4. Cache results: Store trace results to avoid recomputation
5. 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