Debug Operations

/**
 * Trace transaction execution with detailed call information
 * @param transactionHash - Hash of transaction to trace
 * @param options - Tracing options and configuration
 * @returns Promise resolving to detailed transaction trace
 */
traceTransaction(
  transactionHash: string,
  options?: DebugTracingOptions
): Promise<DebugTransaction>;

/**
 * Trace a call without executing it on-chain
 * @param request - Transaction request to trace
 * @param blockTag - Block number or tag to execute at
 * @param options - Tracing options
 * @returns Promise resolving to call trace
 */
traceCall(
  request: TransactionRequest,
  blockTag?: string | number,
  options?: DebugTracingOptions
): Promise<DebugCallTrace>;

interface DebugTracingOptions {
  disableStorage?: boolean;
  disableMemory?: boolean;
  disableStack?: boolean;
  tracer?: string;
  tracerConfig?: DebugTracerConfig;
  timeout?: string;
}

interface DebugTransaction {
  gas: number;
  failed: boolean;
  returnValue: string;
  structLogs: DebugStructLog[];
}

interface DebugCallTrace {
  type: string;
  from: string;
  to: string;
  value: string;
  gas: string;
  gasUsed: string;
  input: string;
  output: string;
  error?: string;
  revertReason?: string;
  calls?: DebugCallTrace[];
}

interface DebugStructLog {
  pc: number;
  op: string;
  gas: number;
  gasCost: number;
  depth: number;
  error?: string;
  stack?: string[];
  memory?: string[];
  storage?: { [key: string]: string };
}

interface DebugTracerConfig {
  onlyTopCall?: boolean;
  withLog?: boolean;
}

/**
 * Trace all transactions in a block
 * @param blockNumber - Block number to trace
 * @param options - Tracing options
 * @returns Promise resolving to array of transaction traces
 */
traceBlock(
  blockNumber: number,
  options?: DebugTracingOptions
): Promise<DebugTransaction[]>;

/**
 * Trace block by hash
 * @param blockHash - Block hash to trace
 * @param options - Tracing options
 * @returns Promise resolving to array of transaction traces
 */
traceBlockByHash(
  blockHash: string,
  options?: DebugTracingOptions
): Promise<DebugTransaction[]>;

/**
 * Trace a range of blocks
 * @param fromBlock - Starting block number
 * @param toBlock - Ending block number
 * @param options - Tracing options
 * @returns Promise resolving to traces for all blocks in range
 */
traceBlockRange(
  fromBlock: number,
  toBlock: number,
  options?: DebugTracingOptions
): Promise<DebugBlockTrace[]>;

interface DebugBlockTrace {
  blockNumber: number;
  blockHash: string;
  transactions: DebugTransaction[];
}

/**
 * Trace transaction with custom tracer
 * @param transactionHash - Transaction to trace
 * @param tracer - Custom tracer code or name
 * @param tracerConfig - Tracer configuration
 * @returns Promise resolving to custom trace result
 */
traceTransactionWithTracer(
  transactionHash: string,
  tracer: string,
  tracerConfig?: DebugTracerConfig
): Promise<any>;

/**
 * Trace call with custom tracer
 * @param request - Call to trace
 * @param blockTag - Block to execute at
 * @param tracer - Custom tracer code or name
 * @returns Promise resolving to custom trace result
 */
traceCallWithTracer(
  request: TransactionRequest,
  blockTag: string | number,
  tracer: string
): Promise<any>;

/**
 * Get storage at specific address and key
 * @param address - Contract address
 * @param key - Storage key
 * @param blockTag - Block number or tag
 * @returns Promise resolving to storage value
 */
getStorageAt(
  address: string,
  key: string,
  blockTag?: string | number
): Promise<string>;

/**
 * Get code at address
 * @param address - Address to get code for
 * @param blockTag - Block number or tag
 * @returns Promise resolving to contract bytecode
 */
getCode(address: string, blockTag?: string | number): Promise<string>;

/**
 * Analyze gas usage patterns in a transaction
 * @param transactionHash - Transaction to analyze
 * @returns Promise resolving to gas analysis
 */
analyzeGasUsage(transactionHash: string): Promise<GasAnalysis>;

/**
 * Get detailed gas breakdown for a transaction
 * @param transactionHash - Transaction to analyze
 * @returns Promise resolving to gas breakdown
 */
getGasBreakdown(transactionHash: string): Promise<GasBreakdown>;

/**
 * Analyze contract call costs
 * @param request - Call to analyze
 * @param blockTag - Block to analyze at
 * @returns Promise resolving to cost analysis
 */
analyzeCallCosts(
  request: TransactionRequest,
  blockTag?: string | number
): Promise<CallCostAnalysis>;

interface GasAnalysis {
  totalGas: number;
  gasUsed: number;
  gasEfficiency: number;
  expensiveOperations: ExpensiveOperation[];
  optimizationSuggestions: string[];
}

interface GasBreakdown {
  intrinsicGas: number;
  executionGas: number;
  storageGas: number;
  memoryGas: number;
  callGas: number;
  refundGas: number;
}

interface CallCostAnalysis {
  estimatedGas: number;
  actualGas: number;
  costInWei: string;
  costInUsd?: number;
  gasPrice: string;
  efficiency: number;
}

interface ExpensiveOperation {
  opcode: string;
  gasUsed: number;
  frequency: number;
  totalCost: number;
  optimization?: string;
}

/**
 * Get detailed error information for a failed transaction
 * @param transactionHash - Failed transaction hash
 * @returns Promise resolving to error details
 */
getTransactionError(transactionHash: string): Promise<TransactionError>;

/**
 * Decode revert reason from transaction data
 * @param data - Transaction data or error data
 * @returns Promise resolving to decoded revert reason
 */
decodeRevertReason(data: string): Promise<RevertReason>;

/**
 * Replay transaction to identify failure point
 * @param transactionHash - Transaction to replay
 * @returns Promise resolving to failure analysis
 */
replayTransaction(transactionHash: string): Promise<TransactionReplay>;

interface TransactionError {
  error: string;
  revertReason?: string;
  failurePoint: FailurePoint;
  gasUsedBeforeFailure: number;
  stackTrace: string[];
}

interface RevertReason {
  reason: string;
  signature?: string;
  args?: any[];
  raw: string;
}

interface TransactionReplay {
  success: boolean;
  failureStep?: number;
  errorMessage?: string;
  gasUsed: number;
  trace: DebugCallTrace;
}

interface FailurePoint {
  contract: string;
  function?: string;
  line?: number;
  opcode: string;
}

import { Alchemy, Network } from "alchemy-sdk";

const alchemy = new Alchemy({
  apiKey: "your-api-key",
  network: Network.ETH_MAINNET,
});

// Trace a transaction to understand its execution
const trace = await alchemy.debug.traceTransaction("0x...", {
  disableStorage: false,
  disableMemory: true,
  disableStack: false,
});

console.log("Gas used:", trace.gas);
console.log("Failed:", trace.failed);
console.log("Return value:", trace.returnValue);

// Trace a call before executing it
const callTrace = await alchemy.debug.traceCall({
  to: "0x...",
  data: "0x...", // function call data
}, "latest");

console.log("Call trace:", callTrace);

// Trace all transactions in a block
const blockTraces = await alchemy.debug.traceBlock(18000000);
console.log(`Traced ${blockTraces.length} transactions`);

// Analyze gas usage for optimization
const gasAnalysis = await alchemy.debug.analyzeGasUsage("0x...");
console.log("Gas efficiency:", gasAnalysis.gasEfficiency);
console.log("Optimization suggestions:", gasAnalysis.optimizationSuggestions);

// Get detailed error information for failed transaction
const errorInfo = await alchemy.debug.getTransactionError("0x...");
console.log("Failure reason:", errorInfo.revertReason);
console.log("Failure point:", errorInfo.failurePoint);

// Custom tracer example - track all SSTORE operations
const customTrace = await alchemy.debug.traceTransactionWithTracer(
  "0x...",
  `{
    data: [],
    step: function(log) {
      if (log.op.toString() === "SSTORE") {
        this.data.push({
          gas: log.gas,
          stack: log.stack.peek(0).toString(16)
        });
      }
    },
    result: function() { return this.data; }
  }`
);

// Decode revert reason from failed transaction
const revertReason = await alchemy.debug.decodeRevertReason("0x08c379a0...");
console.log("Decoded reason:", revertReason.reason);

// Get contract code for analysis
const contractCode = await alchemy.debug.getCode("0x...", "latest");
console.log("Contract bytecode length:", contractCode.length);