eth_simulateV1

POST

Simulates the execution of multiple transactions across one or more blocks without broadcasting them to the network. Similar to eth_call, but lets you run a sequence of calls with the block context (block number, timestamp, base fee, and so on) and account state overridden with arbitrary values. Use it to debug smart contract interactions, estimate gas usage, or validate bundled transactions.

🚧 Taking a long time to respond? Response time depends on the size of the simulation!

The more blocks and calls included in blockStateCalls, the longer the response takes. Keep the number of simulated blocks and calls to a minimum if you need a fast response.

param[0]

simulationPayloadobjectrequired

An object containing the simulation configuration. It can contain the following fields.

blockStateCalls: Array of block definitions to simulate. (required, up to 256) Each item can contain blockOverrides, stateOverrides, and calls.
traceTransfers: Whether to include native token transfers in the logs as ERC-20 Transfer events.
validation: Whether to apply EVM validation rules except for signature checks.
returnFullTransactions: Whether to include full transaction objects in the response.

blockStateCallsarrayrequired

Array of block definitions to simulate. Up to 256 blocks can be specified, and each block is executed sequentially.

blockOverridesobject

Overrides the block context used for the simulation.

numberstring

The block number to simulate, as a hex string. Block numbers must increase; skipped block numbers are included in the response as empty blocks.

timestring

The block timestamp as a hex string.

gasLimitstring

The block gas limit as a hex string.

feeRecipientstring

The address that receives the fees, as a string.

prevRandaostring

The PREVRANDAO value of the block, as a hex string.

baseFeePerGasstring

The base fee per gas of the block, as a hex string.

blobBaseFeestring

The blob base fee of the block, as a hex string.

withdrawalsarray

List of validator withdrawals to include in the block. (EIP-4895)

indexstring

Withdrawal index (hex)

validatorIndexstring

Validator index (hex)

addressstring

Withdrawal recipient address

amountstring

Withdrawal amount in Gwei (hex)

stateOverridesobject

Overrides account state with arbitrary values for the duration of the simulation only, without changing on-chain state. Each key is a target address, and its value can contain the following fields.

balance: A hex string that overrides the account balance.
nonce: A hex string that overrides the account nonce.
code: Fake EVM bytecode to inject into the account, as a hex string.
state: A set of key-value pairs that replaces the entire account storage. Each key and value is a hex string.
stateDiff: A set of key-value pairs that overrides individual account storage slots. Similar to state, but used when only specific slots should be changed.
movePrecompileToAddress: Moves the precompile at this address to another address. It is applied before the code override, and the behavior is client-specific when the target is not a precompile.

state and stateDiff are mutually exclusive — specify only one of them per account.

addressstring

balancestring

Account balance to override (hex)

noncestring

Account nonce to override (hex)

codestring

EVM bytecode to inject into the account (hex)

stateobject

Key-value pairs that replace the entire account storage

stateDiffobject

Key-value pairs that override individual account storage slots

movePrecompileToAddressstring

Target address to move the precompile to

callsarray

Array of call objects to execute sequentially in this block.

typestring

The transaction type as a hex string. Defaults to 0x2 (EIP-1559).

fromstring

The transaction sender (from) address as a string.

tostring

The transaction recipient (to) address as a string. Can be omitted when deploying a contract.

gasstring

The gas limit allocated to this call, as a hex string.

gasPricestring

The price per gas unit, as a hex string. (Legacy transactions)

maxFeePerGasstring

The maximum fee per gas you are willing to pay, as a hex string. (EIP-1559)

maxPriorityFeePerGasstring

The maximum priority fee per gas paid to the validator, as a hex string. (EIP-1559)

maxFeePerBlobGasstring

The maximum fee per blob gas you are willing to pay, as a hex string. Defaults to 0x0. (EIP-4844)

blobVersionedHashesarray

Versioned hashes of the blobs. Defaults to an empty array. (EIP-4844)

noncestring

The transaction nonce as a hex string.

valuestring

The value of the transaction.

inputstring

The hashed method signature of the transaction to execute. You can find it in the ABI. It can also be provided in the data field.

accessListarray

List of addresses and storage keys the transaction accesses during execution. (EIP-2930)

addressstring

Contract address to be accessed

storageKeysarray

Storage keys to be accessed

traceTransfersboolean

When set to true, native token transfers are included in the response logs as ERC-20 Transfer events. Defaults to false.

validationboolean

When set to true, EVM validation rules (balance, nonce, fees, and so on) are applied except for signature checks, making the simulation closer to a real transaction. Defaults to false.

returnFullTransactionsboolean

When set to true, the transactions field in the response returns full transaction objects instead of transaction hashes. Defaults to false.

param[1]

blockNumberOrHashOrTagstringrequired

Use one of block hash, block number, or block tag to specify a block.

Block number: hex string (ex. "0x1")
Block hash: 64-character hex string (ex. "0x39008d07edf93c03bb9d1cfc80598fcf63f441ec86e9de3733fa6a484980ca48")]
Block tag: enum string (ex. "latest", "earliest", "pending")
- earliest: The oldest available block on the chain.
- finalized: A recently finalized block that can no longer be changed. Primarily used in proof-of-stake (PoS) blockchains.
- safe: A recent block considered safe by the network (immune to reorgs).
- latest: The most recent block on the chain (may be subject to reorgs).
- pending: The next block to be mined, including pending transactions in the mempool.

Responses

baseFeePerGasstring

Base fee per gas of the simulated block (EIP-1559, hex wei)

blobGasUsedstring

Amount of blob gas used in the block (EIP-4844, hex)

difficultystring

Block difficulty (hex)

excessBlobGasstring

Amount of blob gas used above the target (EIP-4844, hex)

extraDatastring

Arbitrary data included in the block (hex)

gasLimitstring

Maximum total gas allowed in the block (hex)

gasUsedstring

Total gas used in the block (hex)

hashstring

Hash of the simulated block

logsBloomstring

Bloom filter for searching event logs (2048 bits, hex)

minerstring

Block miner address. Can be changed with blockOverrides.feeRecipient.

mixHashstring

Mix hash of the block

noncestring

Block nonce (hex)

numberstring

Simulated block number (hex)

parentBeaconBlockRootstring

Root hash of the parent beacon block (EIP-4788)

parentHashstring

Parent block hash

receiptsRootstring

Root hash of the transaction receipts trie

sha3Unclesstring

SHA3 hash of the uncle blocks list

sizestring

Block size in bytes (hex)

stateRootstring

Root hash of the state trie

timestampstring

Block creation time (Unix timestamp, hex). Can be changed with blockOverrides.time.

transactionsoneOf

List of transactions included in the block. Returns an array of full transaction objects when returnFullTransactions is set to true, and an array of transaction hashes otherwise.

Array of transaction hashes (returnFullTransactions=false)

transactionsRootstring

Root hash of the transactions trie

unclesarray

Array of uncle block hashes

List of validator withdrawals (EIP-4895)

indexstring

Withdrawal index (hex)

validatorIndexstring

Validator index (hex)

addressstring

Withdrawal recipient address

amountstring

Withdrawal amount in Gwei (hex)

withdrawalsRootstring

Root hash of the withdrawals trie (EIP-4895)

Results of the calls executed in this block. Returned in the same order as the calls array in the request.

statusstring

Execution status of the call. Returns 0x1 on success and 0x0 on failure (including reverts).

returnDatastring

Data returned by the call (hex). Contains the revert data when the call fails.

gasUsedstring

Amount of gas used to execute the call (hex)

maxUsedGasstring

Maximum gas used during execution before refunds are applied (hex)

Event logs emitted during the call. When traceTransfers is set to true, native token transfers are also included as ERC-20 Transfer events (address 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee).

addressstring

The address of the contract that emitted this log

topicsarray

Array of event signature hash and indexed parameters (up to 4 entries)

datastring

Non-indexed event parameter data (hex encoded)

blockNumberstring

Block number containing this log (hex)

transactionHashstring

Hash of the transaction that created this log

transactionIndexstring

Transaction position index within the block (hex)

blockHashstring

Hash of the block containing this log

logIndexstring

Log position index within the block (hex)

removedboolean

True if the log was removed due to a chain reorganization

Error object returned only when the call fails.

codeinteger

Error code. Returns 3 when the call reverted, or -32015 on a VM execution error.

messagestring

Error message

datastring

Additional error data such as the revert reason (hex). May not be provided depending on the client.

codestringrequired

Code identifying the cause of the failed request.

messagestringrequired

Detailed message including the name and value of the invalid parameter.

{
  "code": "ERROR_CODE",
  "message": "Unauthorized"
}

X-API-KEY

cURL

curl -X POST 'https://metal-mainnet.nodit.io' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: nodit-demo' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_simulateV1",
    "params": [
      {
        "blockStateCalls": [
          {
            "blockOverrides": {
              "baseFeePerGas": "0x9"
            },
            "stateOverrides": {
              "0xc000000000000000000000000000000000000000": {
                "balance": "0x4a817c420"
              }
            },
            "calls": [
              {
                "from": "0xc000000000000000000000000000000000000000",
                "to": "0xc000000000000000000000000000000000000001",
                "maxFeePerGas": "0xf",
                "value": "0x1"
              }
            ]
          }
        ],
        "traceTransfers": true,
        "validation": true
      },
      "latest"
    ]
  }'