Package Exports

hypertracex
hypertracex/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (hypertracex) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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.