HyperTrace

KO | EN

gitlite — search

#javascript #python #react #typescript #android #machine-learning #linux #docker #nodejs #kubernetes #vue #pytorch #security #mcp

(★ 27)

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

HyperTrace Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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
```bash
GET /health
```

### Single Transaction Simulation
```bash
POST /simulate
```

### Multi-Transaction Simulation (Independent)
```bash
POST /simulate/multi
```

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

**Request Body:**
```json
{
  "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)
```bash
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)
```json
{
  "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:**
```json
{
  "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
```bash
# 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:

```json
{
  "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
```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
```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)

```bash
# 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
  }'
```

HyperTrace

HyperTrace Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

HyperTrace

HyperTrace Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README