HyperTraceX SDK

A comprehensive TypeScript SDK for HyperEVM transaction simulation, gas profiling, and advanced transaction analysis. Built for the HyperLiquid ecosystem with powerful plugins for execution tracing, event decoding, and access list generation.

🚀 Features

• Transaction Simulation: Simulate single, multi, and batch transactions on HyperEVM
• Gas Profiling: Detailed gas usage breakdown with optimization recommendations
• Execution Tracing: Step-by-step transaction execution analysis
• Event Decoding: Human-readable event logs and state changes
• Access List Generation: Optimized access lists for gas efficiency
• Plugin System: Modular architecture for extensible analysis

🚀 Quick Start

npm install hypertracex

import { HyperEVMSimulationEngine } from 'hypertracex';

// Initialize with HyperLiquid defaults
const engine = new HyperEVMSimulationEngine({
  defaultRpcUrl: 'https://rpc.hyperliquid.xyz/evm',
});

// Simulate a transaction
const transaction = {
  from: '0xE5B542211DEcf6fe258185e4EaD53ee2ad04c17d',
  to: '0xd878229c9c3575f224784de610911b5607a3ad15',
  value: '100000000000000000', // 0.1 HYPE
  data: '0x',
};

const result = await engine.simulateTransaction(transaction, { withTrace: true });
console.log('Simulation result:', result);

🔍 Gas Profiling

HyperTraceX provides comprehensive gas analysis with detailed breakdowns:

// Analyze gas usage for a single transaction
const gasProfile = engine.analyzeGasUsage(result);
const gasReport = engine.generateGasReport(result);
console.log(gasReport);

// Multi-transaction gas analysis
const multiResult = await engine.simulateMultiTransaction(transactions, { withTrace: true });
const multiGasReport = engine.generateMultiTransactionGasReport(multiResult);
console.log(multiGasReport);

Gas Profile Features

• Storage Operations: Cold vs warm slot access analysis
• Call Operations: External, internal, delegate, and static call breakdown
• Optimization Suggestions: AI-powered recommendations for gas savings
• Efficiency Scoring: 0-100 efficiency score with detailed metrics
• Cost Breakdown: Per-operation gas cost analysis

🔌 Plugin System

HyperTraceX now features a plugin architecture that automatically runs gas profiling when enabled:

Available Plugins

1. Gas Profiling Plugin

// Enable gas profiling plugin
engine.enableGasProfiling();

// Run simulation - gas profiling runs automatically
const result = await engine.simulateTransaction(transaction, { withTrace: true });

// Access gas profiling results in JSON format
if ('pluginResults' in result && result.pluginResults) {
  const gasProfiling = result.pluginResults.GasProfiling;
  console.log('Gas Profile:', JSON.stringify(gasProfiling, null, 2));
}

// Disable when not needed
engine.disableGasProfiling();

2. Access List Generator Plugin

// Enable access list generation plugin
engine.enableAccessListGeneration();

// Run simulation - access lists generated automatically
const result = await engine.simulateTransaction(transaction, { withTrace: true });

// Access list generation results
if ('pluginResults' in result && result.pluginResults) {
  const accessList = result.pluginResults.AccessListGenerator;
  console.log('Access List:', JSON.stringify(accessList, null, 2));
}

// Disable when not needed
engine.disableAccessListGeneration();

3. Execution Trace Plugin

// Enable execution trace plugin
engine.enableExecutionTrace();

// Run simulation - execution traces generated automatically
const result = await engine.simulateTransaction(transaction, { withTrace: true });

// Execution trace results
if ('pluginResults' in result && result.pluginResults) {
  const executionTrace = result.pluginResults.ExecutionTrace;
  console.log('Execution Trace:', JSON.stringify(executionTrace, null, 2));
}

// Disable when not needed
engine.disableExecutionTrace();

4. Event Decoder Plugin

// Enable event decoder plugin
engine.enableEventDecoder();

// Run simulation - events decoded automatically
const result = await engine.simulateTransaction(transaction, { withTrace: true });

// Event decoding results
if ('pluginResults' in result && result.pluginResults) {
  const eventDecoder = result.pluginResults.EventDecoder;
  console.log('Event Decoder:', JSON.stringify(eventDecoder, null, 2));
}

// Disable when not needed
engine.disableEventDecoder();

Plugin Management

// Check plugin status
const status = engine.getPluginStatus();
console.log('Plugins:', status);

// Check if gas profiling is enabled
const isEnabled = engine.isGasProfilingEnabled();

// Register custom plugins
engine.registerPlugin(customPlugin);

JSON Gas Profiling Output

When the gas profiling plugin is enabled, you get structured JSON results:

{
  "GasProfiling": {
    "pluginName": "GasProfiling",
    "success": true,
    "data": {
      "type": "single_transaction_gas_analysis",
      "success": true,
      "data": {
        "gas_profile": {
          "total_gas_used": 60912,
          "base_transaction_cost": 21000,
          "execution_gas": 39912,
          "storage_operations": { ... },
          "call_operations": { ... },
          "optimization_suggestions": [ ... ]
        },
        "efficiency_score": 85,
        "optimization_suggestions": [ ... ],
        "metadata": { ... }
      }
    },
    "metadata": {
      "timestamp": 1703123456789,
      "processingTime": 45,
      "version": "1.0.0"
    }
  }
}

📋 Access List Generation

The Access List Generator Plugin automatically creates optimized access lists for gas efficiency:

Key Features

• Automatic Detection: Identifies all storage slots accessed during transaction execution
• Priority Ranking: Ranks addresses and slots by access frequency and importance
• Gas Savings Estimation: Calculates potential gas savings from cold vs warm access
• State Propagation Analysis: Analyzes how state flows through batch transactions
• Optimization Recommendations: Provides actionable suggestions for gas optimization

Access List Output Structure

{
  "AccessListGenerator": {
    "pluginName": "AccessListGenerator",
    "success": true,
    "data": {
      "type": "single_transaction_access_list",
      "success": true,
      "data": {
        "access_list": [
          {
            "address": "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb",
            "storage_keys": ["0x...", "0x..."],
            "access_count": 5,
            "priority": 125
          }
        ],
        "gas_savings_estimate": {
          "estimated_gas_savings": 10000,
          "cold_access_cost": 2100,
          "warm_access_cost": 100,
          "savings_per_access": 2000
        },
        "optimization_recommendations": [
          "High gas savings potential: 10,000 gas units",
          "Prioritize 2 high-priority addresses for access list"
        ],
        "metadata": {
          "total_addresses": 2,
          "total_storage_slots": 8,
          "cold_access_count": 8
        }
      }
    },
    "metadata": {
      "timestamp": 1703123456789,
      "processingTime": 23,
      "version": "1.0.0"
    }
  }
}

🔍 Execution Trace Analysis

The Execution Trace Plugin provides complete step-by-step transaction execution details:

Key Features

• Step-by-Step Execution: Detailed breakdown of every execution step
• Call Hierarchy: Complete call tree with depth analysis
• Storage Operations: Track all storage reads and writes
• Gas Flow Analysis: Monitor gas consumption throughout execution
• Execution Patterns: Detect recursive calls, delegate calls, and contract creation
• Performance Metrics: Gas, call, and storage efficiency scores

Execution Trace Output Structure

{
  "ExecutionTrace": {
    "pluginName": "ExecutionTrace",
    "success": true,
    "data": {
      "type": "single_transaction_execution_trace",
      "success": true,
      "data": {
        "execution_summary": {
          "execution_overview": {
            "total_execution_steps": 15,
            "total_function_calls": 8,
            "storage_operations": 12,
            "maximum_call_depth": 3,
            "execution_complexity": "MEDIUM"
          },
          "performance_metrics": {
            "gas_efficiency": 85,
            "call_efficiency": 90,
            "storage_efficiency": 88
          },
          "execution_patterns": {
            "has_recursive_calls": false,
            "has_delegate_calls": true,
            "has_static_calls": false,
            "has_contract_creation": false
          }
        },
        "step_by_step_trace": [
          {
            "step_id": 0,
            "depth": 0,
            "type": "call_execution",
            "call_details": {
              "from": "0xE5B542...",
              "to": "0xB8CE59...",
              "call_scheme": "Call",
              "gas_used": "0x9994",
              "status": "Success"
            },
            "storage_operations": [...],
            "subtraces": [...]
          }
        ],
        "call_hierarchy": {
          "root_call": {
            "address": "0xB8CE59...",
            "method_signature": "transfer(address,uint256)",
            "gas_consumed": 39316,
            "success": true
          },
          "call_tree": {...}
        },
        "storage_changes": {
          "total_changes": 12,
          "read_operations": 8,
          "write_operations": 4,
          "value_changes": 4
        },
        "gas_flow": {
          "total_gas_consumed": 39316,
          "gas_distribution": {...},
          "gas_efficiency_analysis": {...}
        },
        "execution_path": {
          "execution_path": [...],
          "path_summary": {
            "total_steps": 15,
            "successful_steps": 15,
            "failed_steps": 0,
            "average_gas_per_step": 2621
          }
        }
      }
    }
  }
}

📊 Event Decoder Plugin

The Event Decoder Plugin provides human-readable event logs and state changes:

Key Features

• Event Decoding: Automatic decoding of common ERC20/ERC721 events
• Human-Readable Output: Convert raw logs to understandable descriptions
• State Change Analysis: Track all storage modifications
• Method Call Decoding: Decode function calls and parameters
• Value Formatting: Format addresses, amounts, and data for readability
• Cross-Transaction Analysis: Analyze events across multiple transactions

Event Decoder Output Structure

{
  "EventDecoder": {
    "pluginName": "EventDecoder",
    "success": true,
    "data": {
      "type": "single_transaction_event_decoding",
      "success": true,
      "data": {
        "event_summary": {
          "total_events": 2,
          "event_type_distribution": {
            "Transfer(address,address,uint256)": 2
          },
          "contract_interactions": {
            "0xB8CE59...": 2
          },
          "most_frequent_event": "Transfer(address,address,uint256)",
          "most_active_contract": "0xB8CE59..."
        },
        "decoded_events": [
          {
            "contract_address": "0xB8CE59...",
            "event_name": "Transfer(address,address,uint256)",
            "event_signature": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
            "indexed_parameters": [
              {
                "name": "from",
                "value": "0xE5B542...",
                "type": "address",
                "is_address": true
              },
              {
                "name": "to",
                "value": "0x1720F2...",
                "type": "address",
                "is_address": true
              },
              {
                "name": "value",
                "value": "1,000,000 USDT",
                "type": "uint256",
                "is_value": true
              }
            ],
            "human_readable": "Transfer: 1,000,000 USDT tokens from 0xE5B542... to 0x1720F2... on contract 0xB8CE59..."
          }
        ],
        "state_changes": {
          "total_changes": 8,
          "changes": [
            {
              "contract_address": "0xB8CE59...",
              "storage_slot": "0x3976c95...",
              "operation_type": "write",
              "old_value": "0x467be4",
              "new_value": "0x3739a4",
              "value_changed": true,
              "human_readable": "Storage slot 0x3976c95... changed from 0x467be4 to 0x3739a4"
            }
          ],
          "read_operations": 5,
          "write_operations": 3,
          "value_changes": 3
        },
        "method_calls": [
          {
            "contract_address": "0xB8CE59...",
            "method_name": "transfer(address,uint256)",
            "method_signature": "0xa9059cbb",
            "decoded_parameters": [
              {
                "value": "0x1720F2...",
                "type": "address"
              },
              {
                "value": "1,000,000",
                "type": "uint256"
              }
            ],
            "success": true,
            "human_readable": "Called transfer(address,uint256) on contract 0xB8CE59..."
          }
        ],
        "human_readable_summary": [
          "📋 Transaction emitted 2 events",
          "💰 2 transfer events detected",
          "💾 3 storage writes, 5 reads",
          "🔄 3 storage values were modified",
          "📞 1 method calls executed",
          "✅ 1 successful method calls"
        ]
      }
    }
  }
}

🏗️ Analysis Module Architecture

The SDK now features a modular analysis architecture for easy extensibility:

Core Analysis Classes

• GasAnalyzer - Comprehensive gas usage analysis
• TransactionAnalyzer - Transaction pattern and behavior analysis
• ReportGenerator - Multi-format report generation (Text, JSON, Markdown)

Analysis Types

import { GasAnalyzer, TransactionAnalyzer, ReportGenerator } from 'hypertracex';

// Gas analysis
const gasAnalysis = GasAnalyzer.analyzeTransaction(simulationResult);
const gasReport = ReportGenerator.generateGasReport(gasAnalysis, { 
  outputFormat: 'json' 
});

// Transaction pattern analysis
const patternAnalysis = TransactionAnalyzer.analyzeTransactionPatterns(simulationResult);

// Multi-transaction analysis
const multiAnalysis = GasAnalyzer.analyzeMultiTransaction(multiResult);
const multiReport = ReportGenerator.generateMultiTransactionReport(multiAnalysis);

Report Formats

• Text: Human-readable console output
• JSON: Structured data for programmatic use
• Markdown: Formatted documentation (coming soon)

📚 API Reference

Core Methods

• simulateTransaction(transaction, options) - Single transaction simulation
• simulateMultiTransaction(transactions, options) - Independent multi-transaction simulation
• simulateBatchTransaction(transactions, options) - Stateful batch simulation
• analyzeGasUsage(result) - Generate detailed gas profile
• generateGasReport(result) - Human-readable gas analysis report

Gas Profiling Methods

• analyzeGasUsage(simulationResult) - Analyze gas usage for single transaction
• analyzeMultiTransactionGasUsage(multiResult) - Analyze gas usage for multi-transactions
• analyzeBatchTransactionGasUsage(batchResult) - Analyze gas usage for batch transactions
• generateGasReport(simulationResult) - Generate comprehensive gas report
• generateMultiTransactionGasReport(multiResult) - Generate multi-transaction gas report
• generateBatchTransactionGasReport(batchResult) - Generate batch transaction gas report

🧪 Examples

Check out the examples/ directory for comprehensive usage examples:

• basic-usage.ts - Basic transaction simulation
• simple-demo.ts - Complete demo with gas profiling
• gas-profiling-demo.ts - Advanced gas analysis demonstration

🔧 Configuration

const engine = new HyperEVMSimulationEngine({
  defaultRpcUrl: 'https://rpc.hyperliquid.xyz/evm',
  timeout: 30000,
  retries: 3,
  headers: {
    'Custom-Header': 'value'
  }
});

📊 Gas Analysis Output

The gas profiler provides detailed insights:

Gas Profile Analysis:
====================
Total Gas Used: 60,912
Base Transaction Cost: 21,000
Execution Gas: 39,912

Storage Operations:
- Cold Reads: 2 (4,200 gas)
- Warm Reads: 0 (0 gas)
- Cold Writes: 2 (4,200 gas)
- Warm Writes: 0 (0 gas)

Call Operations:
- External Calls: 1
- Delegate Calls: 1
- Static Calls: 0
- Total Call Cost: 2,600 gas

Efficiency Score: 85/100

Optimization Suggestions:
- [MEDIUM] 2 cold storage writes detected: Consider batching storage operations to reduce cold access costs
- [MEDIUM] 1 delegate calls detected: Consider inlining simple delegate calls or using libraries

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.