Bundle Simulation

The MEV engine provides simulation endpoints that execute bundles and transactions against the current chain state without submitting them on-chain. Use simulation to validate profitability, estimate gas, and detect reverts before committing to an auction bid.

Simulate a Bundle

`POST /simulateBundle`

Simulates an entire bundle atomically against the latest block state.

Request body:

{
  "txs": [
    "0xf86c0a8502540be400...",
    "0xf86c0b8502540be400..."
  ],
  "block_number": "0x129A3E1",
  "state_overrides": {
    "0x1234...abcd": {
      "balance": "0xDE0B6B3A7640000"
    }
  }
}

`POST /simulateTransaction`

Simulates a single transaction in isolation.

Request body:

{
  "tx": "0xf86c0a8502540be400...",
  "block_number": "0x129A3E1"
}

Response Fields

Both endpoints return the same response structure:

{
  "success": true,
  "gas_used": 243800,
  "effective_value": "1250000000000000",
  "state_changes": [
    {
      "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "key": "0x03",
      "before": "0x1000",
      "after": "0x2000"
    }
  ],
  "revert_reason": null,
  "logs": [
    {
      "address": "0xC02aaA39...",
      "topics": ["0xddf252ad..."],
      "data": "0x00000000..."
    }
  ]
}

Field	Type	Description
`success`	bool	Whether the bundle/transaction executed without reverting.
`gas_used`	int	Total gas consumed by the simulation.
`effective_value`	string	Net ETH value extracted by the bundle (in wei).
`state_changes`	[]object	Storage slot changes produced by execution.
`revert_reason`	string	ABI-decoded revert reason if the simulation failed. Null on success.
`logs`	[]object	EVM event logs emitted during execution.

EVM Simulation Methods

The engine supports two underlying EVM simulation methods:

`eth_callBundle` (Flashbots)

Executes the bundle as a single atomic unit at the top of the specified block. This is the standard Flashbots simulation method and is the default.

Transactions execute sequentially; state carries forward between them.
The bundle either fully succeeds or fully reverts.
Supported by Flashbots, MEV-Boost relays, and most builder APIs.

`debug_traceCall` (Geth)

Traces a single transaction call with full EVM step-level detail. Used for deep inspection of individual transactions.

Returns opcode-level traces, memory, and stack snapshots.
Higher computational cost; use sparingly.
Requires a Geth-compatible RPC endpoint with debug namespace enabled.

State Overrides / stateDiff

State overrides allow you to modify account balances, nonces, code, and storage slots before simulation. This is essential for testing bundles that depend on specific on-chain conditions.

{
  "state_overrides": {
    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48": {
      "stateDiff": {
        "0x09": "0x00000000000000000000000000000000000000000000d3c21bcecceda1000000"
      }
    }
  }
}

Common storage slot mappings:

Token	`balanceOf` slot	`allowance` slot
WETH9	3	4
USDC	9	10

Code Examples

Simulate a bundle

curl -X POST https://rpc.yoorquezt.com/simulateBundle \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SEARCHER_KEY" \
  -d '{
    "txs": [
      "0xf86c0a8502540be400..."
    ],
    "block_number": "0x129A3E1"
  }'

Simulate with state overrides

curl -X POST https://rpc.yoorquezt.com/simulateBundle \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SEARCHER_KEY" \
  -d '{
    "txs": ["0xf86c..."],
    "block_number": "0x129A3E1",
    "state_overrides": {
      "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": {
        "balance": "0x56BC75E2D63100000"
      }
    }
  }'

Simulate a single transaction

curl -X POST https://rpc.yoorquezt.com/simulateTransaction \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SEARCHER_KEY" \
  -d '{
    "tx": "0xf86c0a8502540be400...",
    "block_number": "0x129A3E1"
  }'