HyperEVM Simulation Engine

A high-performance Rust-based transaction simulation engine for HyperEVM, built on REVM with advanced tracing capabilities.

🔧 Core Features

• REVM Integration: Built on REVM 24.0.1 with full EVM opcode coverage and future-proof compatibility.
• HyperLiquid RPC: Optimized execution against https://rpc.hyperliquid.xyz/evm for maximum performance.
• Historical Simulation: Run simulations at any historical block height for accurate replay and debugging.
• Advanced Tracing: Capture full execution traces, including function calls, slot accesses, and storage diffs.
• Gas Profiling: Fine-grained gas usage breakdown per opcode, function, and transaction stage for optimization insights.
• Event Decoding: Automatic parsing of logs and events into human-readable form, with ABI support.
• Error Analysis: Detailed failure diagnostics with reasons for reverts, invalid opcodes, and out-of-gas issues.
• State Diffs & Overrides: Compare pre- and post-execution state changes, with custom overrides for advanced what-if scenarios.
• Multi-threaded Runtime: Powered by Tokio async, enabling parallel simulation at scale.
• Performance Monitoring: Built-in metrics for latency, throughput, and memory usage.
• Production Ready: Auto-scaling deployment on Railway, with robust logging and monitoring.
• Developer Tools: JSON-RPC compatible API endpoints for simulation, trace analysis, and gas insights.

---

🚀 API Endpoints

Health Check

GET /health

Single Transaction Simulation

POST /simulate

Multi-Transaction Simulation (Independent)

POST /simulate/multi

Independent Transaction Simulation - Simulate multiple transactions without state propagation. Perfect for comparing different scenarios from the same starting state.

Request Body:

{
  "rpc_url": "https://rpc.hyperliquid.xyz/evm",
  "transactions": [
    {
      "from": "0xC255fC198eEdAC7AF8aF0f6e0ca781794B094A61",
      "to": "0xd878229c9c3575F224784DE610911B5607a3ad15",
      "value": "100000000000000000",
      "data": "0x"
    },
    {
      "from": "0xC255fC198eEdAC7AF8aF0f6e0ca781794B094A61",
      "to": "0xd878229c9c3575F224784DE610911B5607a3ad15",
      "value": "200000000000000000",
      "data": "0x"
    }
  ],
  "with_trace": false,
  "block_number": null,
  "overrides": null
}

Batch Transaction Simulation (Stateful)

POST /simulate/batch

Stateful Transaction Simulation - Simulate multiple transactions where each transaction can affect the state of subsequent transactions. Perfect for contract deployment followed by interaction.

Request Body: (Same structure as above)

{
  "rpc_url": "https://rpc.hyperliquid.xyz/evm",
  "transactions": [
    {
      "from": "0xC255fC198eEdAC7AF8aF0f6e0ca781794B094A61",
      "to": "0xd878229c9c3575F224784DE610911B5607a3ad15",
      "value": "100000000000000000",
      "data": "0x"
    },
    {
      "from": "0xC255fC198eEdAC7AF8aF0f6e0ca781794B094A61",
      "to": "0xd878229c9c3575F224784DE610911B5607a3ad15",
      "value": "200000000000000000",
      "data": "0x"
    }
  ],
  "with_trace": false,
  "block_number": null,
  "overrides": null
}

Response:

{
  "success": true,
  "results": [
    {
      "index": 0,
      "success": true,
      "gas_used": 21000,
      "error": null,
      "traces": null
    },
    {
      "index": 1,
      "success": true,
      "gas_used": 21000,
      "error": null,
      "traces": null
    }
  ],
  "block_number": 1847392,
  "error": null
}

Benefits of Multi-Transaction Simulation:

Independent Simulation (/simulate/multi):

• ✅ Compare Different Scenarios: Test various transaction parameters from same starting state
• ✅ Parallel Analysis: Analyze multiple independent transactions simultaneously
• ✅ Performance: Faster simulation (no state propagation overhead)
• ✅ Isolated Testing: Each transaction runs in isolation

Batch Simulation (/simulate/batch):

• ✅ Contract Deployment + Interaction: Deploy contract then interact with it
• ✅ Dependent Sequences: Test transaction sequences where state matters
• ✅ Realistic Behavior: Simulate actual blockchain transaction ordering
• ✅ State Propagation: Changes from one transaction affect subsequent ones

General Benefits:

• Batch Processing: Simulate multiple transactions in one API call
• Gas Optimization: Understand total gas costs for complex operations
• Performance: Faster than multiple individual simulation calls
• Consistency: All transactions simulated in the same blockchain state

Testing Examples

Historical Simulation

# Simulate at specific block number
curl -X POST http://localhost:3000/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "rpc_url": "https://rpc.hyperliquid.xyz/evm",
    "from": "0xC255fC198eEdAC7AF8aF0f6e0ca781794B094A61",
    "to": "0xd878229c9c3575F224784DE610911B5607a3ad15",
    "value": "120000000000000000",
    "data": "0x",
    "with_trace": true,
    "block_number": 12345678,
    "overrides": null
  }'

Note: Historical simulation allows you to test transactions at specific block states. Omit block_number to use the latest block.

Block Number Response Values:

• Specific block: Returns the exact block number you specified
• Latest block: Returns the actual current block number from HyperEVM blockchain
• Historical simulation: Returns the specific historical block number used on HyperEVM

Custom EVM Overrides

The overrides field allows you to customize the EVM simulation environment:

{
  "overrides": {
    "0x1234567890123456789012345678901234567890": {
      "balance": "1000000000000000000",
      "state": {
        "0x0000000000000000000000000000000000000000000000000000000000000000": "0x1234567890123456789012345678901234567890123456789012345678901234",
        "0x0000000000000000000000000000000000000000000000000000000000000001": "0x0000000000000000000000000000000000000000000000000000000000000001"
      }
    },
    "0x0987654321098765432109876543210987654321": {
      "balance": "500000000000000000"
    }
  }
}

Supported override types:

• Balance overrides: Set custom account balances (in wei as hex string)
• Storage overrides: Modify contract storage values (slot-value pairs as hex strings)
• Address format: Must be valid Ethereum addresses (0x...)
• Value format: All values must be hex strings (0x...)

Example use cases:

• Test transactions with custom account balances
• Simulate contract interactions with modified storage states
• Debug contract behavior with specific state conditions

JavaScript

const API_BASE = 'http://localhost:3000';

const response = await fetch(`${API_BASE}/simulate`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    rpc_url: 'https://rpc.hyperliquid.xyz/evm',
    from: '0xC255fC198eEdAC7AF8aF0f6e0ca781794B094A61',
    to: '0xd878229c9c3575F224784DE610911B5607a3ad15',
    value: '120000000000000000',
    data: '0x',
    with_trace: true,
    block_number: 12345678, // Optional: for historical simulation
    overrides: null // Optional: custom EVM overrides
  })
});

console.log(await response.json());

Python

import requests

response = requests.post('http://localhost:3000/simulate', json={
    "rpc_url": "https://rpc.hyperliquid.xyz/evm",
    "from": "0xC255fC198eEdAC7AF8aF0f6e0ca781794B094A61",
    "to": "0xd878229c9c3575F224784DE610911B5607a3ad15",
    "value": "120000000000000000",
    "data": "0x",
    "with_trace": True,
    "block_number": 12345678,  # Optional: for historical simulation
    "overrides": None  # Optional: custom EVM overrides
})

print(response.json())

🏗️ Local Development (Optional)

# Quick setup
git clone <repository-url>
cd hyperevm-simulation-engine
cargo build --release
cargo run --release

# Test locally
curl http://localhost:3000/health

# Test local simulation with historical block
curl -X POST http://localhost:3000/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "rpc_url": "https://rpc.hyperliquid.xyz/evm",
    "from": "0xC255fC198eEdAC7AF8aF0f6e0ca781794B094A61",
    "to": "0xd878229c9c3575F224784DE610911B5607a3ad15",
    "value": "120000000000000000",
    "data": "0x",
    "with_trace": false,
    "block_number": 12345678,
    "overrides": null
  }'