> ## Documentation Index
> Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# debug Methods

> Debugging and development methods (5 methods)

<Warning>
  **This page is a placeholder.** All examples on this page are currently AI-generated and are not correct. This documentation will be completed in the future with accurate, tested examples.
</Warning>

# debug Methods

The `debug` namespace provides 5 debugging and development methods for transaction tracing and block analysis.

<Warning>
  Debug methods are not part of the standard JSON-RPC spec and may not be available on all nodes. They are typically only enabled on development and testing nodes.
</Warning>

## Overview

Access debug methods directly on the provider:

```typescript theme={null}
import { Provider } from '@tevm/voltaire/provider';
import { Keccak256 } from '@tevm/voltaire/Keccak256';

const txHash = Keccak256.from('0x...');

// Trace transaction execution
const trace = await provider.debug_traceTransaction(txHash, {
  tracer: 'callTracer'
});
```

## Transaction Tracing

### debug\_traceTransaction

Trace the execution of a transaction, returning detailed information about each step.

```typescript theme={null}
const trace = await provider.debug_traceTransaction(txHash, {
  tracer: 'callTracer',
  timeout: '10s'
});
// Response<TransactionTrace>
```

**Parameters:**

* `transactionHash: Hash` - Transaction to trace
* `options?: TraceOptions` - Tracing configuration

**Common Tracers:**

* `callTracer` - Call tree with gas and value transfers
* `prestateTracer` - State before transaction execution
* `4byteTracer` - Count of 4-byte function selectors
* `opcodeTracer` - Full opcode-level trace

**Example:**

```typescript theme={null}
import { Keccak256 } from '@tevm/voltaire/Keccak256';

const txHash = Hash('0xabc123...');

// Call tracer - see internal calls
const callTrace = await provider.debug_traceTransaction(txHash, {
  tracer: 'callTracer'
});

if (!callTrace.error) {
  console.log('Calls:', callTrace.result.calls);
  console.log('Gas used:', callTrace.result.gasUsed);
}

// Opcode tracer - detailed execution
const opcodeTrace = await provider.debug_traceTransaction(txHash, {
  tracer: 'opcodeTracer',
  enableMemory: true,
  enableReturnData: true
});
```

### debug\_traceBlockByNumber

Trace all transactions in a block by block number.

```typescript theme={null}
const traces = await provider.debug_traceBlockByNumber('latest', {
  tracer: 'callTracer'
});
// Response<TransactionTrace[]>
```

**Parameters:**

* `blockTag: BlockTag` - Block to trace
* `options?: TraceOptions` - Tracing configuration

**Example:**

```typescript theme={null}
// Trace all transactions in latest block
const traces = await provider.debug_traceBlockByNumber('latest', {
  tracer: 'callTracer'
});

if (!traces.error) {
  traces.result.forEach((trace, i) => {
    console.log(`Transaction ${i}:`, trace.result);
  });
}
```

### debug\_traceBlockByHash

Trace all transactions in a block by block hash.

```typescript theme={null}
const traces = await provider.debug_traceBlockByHash(blockHash, {
  tracer: 'prestateTracer'
});
// Response<TransactionTrace[]>
```

**Parameters:**

* `blockHash: Hash` - Block hash to trace
* `options?: TraceOptions` - Tracing configuration

**Example:**

```typescript theme={null}
import { Keccak256 } from '@tevm/voltaire/Keccak256';

const blockHash = Hash('0xdef456...');

const traces = await provider.debug_traceBlockByHash(blockHash, {
  tracer: 'prestateTracer'
});

if (!traces.error) {
  console.log('Pre-state:', traces.result[0].result);
}
```

### debug\_traceCall

Trace a call without creating a transaction (like eth\_call with tracing).

```typescript theme={null}
const trace = await provider.debug_traceCall({
  from: Address('0x...'),
  to: Address('0x...'),
  data: Hex('0x...')
}, 'latest', {
  tracer: 'callTracer'
});
// Response<TransactionTrace>
```

**Parameters:**

* `callParams: CallParams` - Transaction parameters
* `blockTag: BlockTag` - Block to execute against
* `options?: TraceOptions` - Tracing configuration

**Example:**

```typescript theme={null}
import * as Address from '@tevm/voltaire/Address';
import * as Hex from '@tevm/voltaire/Hex';

// Trace a call before submitting
const trace = await provider.debug_traceCall({
  from: Address('0x742d35...'),
  to: Address('0xcontract...'),
  data: Hex('0xa9059cbb...')  // transfer(address,uint256)
}, 'latest', {
  tracer: 'callTracer'
});

if (!trace.error) {
  // Inspect internal calls before submitting transaction
  console.log('Will make calls:', trace.result.calls);
}
```

## Block Inspection

### debug\_getRawBlock

Get the RLP-encoded raw block data.

```typescript theme={null}
const rawBlock = await provider.debug_getRawBlock('latest');
// Response<Hex>
```

**Parameters:**

* `blockTag: BlockTag` - Block to retrieve

**Example:**

```typescript theme={null}
// Get raw block bytes
const rawBlock = await provider.debug_getRawBlock('latest');

if (!rawBlock.error) {
  console.log('RLP-encoded block:', rawBlock.result);
  // Can decode with RLP module
}
```

## Trace Options

Common options for tracing methods:

```typescript theme={null}
interface TraceOptions {
  // Built-in tracer name
  tracer?: 'callTracer' | 'prestateTracer' | '4byteTracer' | 'opcodeTracer';

  // Custom JavaScript tracer code
  tracerConfig?: {
    onlyTopCall?: boolean;
    withLog?: boolean;
  };

  // Timeout for tracing operation
  timeout?: string;  // e.g., '10s', '1m'

  // Include memory in trace
  enableMemory?: boolean;

  // Include return data
  enableReturnData?: boolean;

  // Disable storage
  disableStorage?: boolean;

  // Disable stack
  disableStack?: boolean;
}
```

## Usage Patterns

### Debug Failed Transaction

```typescript theme={null}
import { Keccak256 } from '@tevm/voltaire/Keccak256';

async function debugFailedTx(txHash: Keccak256.Keccak256Hash) {
  // Get transaction receipt
  const receipt = await provider.eth_getTransactionReceipt(txHash);

  if (!receipt.error && receipt.result.status === '0x0') {
    // Transaction reverted, trace it
    const trace = await provider.debug_traceTransaction(txHash, {
      tracer: 'callTracer'
    });

    if (!trace.error) {
      console.log('Revert reason:', trace.result.error);
      console.log('Failed at:', trace.result.calls);
    }
  }
}
```

### Analyze Gas Usage

```typescript theme={null}
async function analyzeGas(txHash: Keccak256.Keccak256Hash) {
  const trace = await provider.debug_traceTransaction(txHash, {
    tracer: 'callTracer'
  });

  if (!trace.error) {
    const result = trace.result;
    console.log('Total gas:', result.gasUsed);

    // Show gas for each call
    result.calls?.forEach(call => {
      console.log(`${call.type} to ${call.to}: ${call.gasUsed} gas`);
    });
  }
}
```

### Test Before Sending

```typescript theme={null}
async function testTransaction(params: CallParams) {
  // Trace the call first
  const trace = await provider.debug_traceCall(params, 'latest', {
    tracer: 'callTracer'
  });

  if (!trace.error) {
    if (trace.result.error) {
      console.error('Transaction would fail:', trace.result.error);
      return false;
    }

    console.log('Transaction would succeed');
    console.log('Gas estimate:', trace.result.gasUsed);
    return true;
  }

  return false;
}
```

### Compare State Changes

```typescript theme={null}
async function compareStateChanges(txHash: Keccak256.Keccak256Hash) {
  // Get pre-state
  const preTrace = await provider.debug_traceTransaction(txHash, {
    tracer: 'prestateTracer'
  });

  if (!preTrace.error) {
    const preState = preTrace.result;

    // Get transaction receipt for post-state
    const receipt = await provider.eth_getTransactionReceipt(txHash);

    console.log('Accounts modified:', Object.keys(preState));
  }
}
```

## Node Requirements

Debug methods require specific node configuration:

**Geth:**

```bash theme={null}
geth --http --http.api="eth,debug,net,web3"
```

**Erigon:**

```bash theme={null}
erigon --http --http.api="eth,debug,trace,net,web3"
```

**Hardhat:**

```javascript theme={null}
// Enabled by default in Hardhat Network
```

**Anvil:**

```bash theme={null}
anvil --host 0.0.0.0
# Debug methods enabled by default
```

## Performance Considerations

* **Tracing is expensive** - Can take several seconds for complex transactions
* **Use timeouts** - Prevent hanging on long traces
* **Disable unused features** - `disableMemory`, `disableStack` for faster traces
* **Production nodes** - Usually disable debug methods for security

## Type Reference

All parameter and return types are defined in the [JSON-RPC types](/jsonrpc/debug) module.

## Next Steps

* [Method API](/provider/methods) - Learn about the method-based API
* [eth Methods](/provider/eth-methods) - Standard Ethereum methods
* [engine Methods](/provider/engine-methods) - Consensus layer methods
* [Events](/provider/events) - Subscribe to blockchain events