simulate

Simulates a set of calls on block(s) with optional block and state overrides. Internally uses the eth_simulateV1 JSON-RPC method.

Usage

example.ts

import { parseEther } from 'viem'
import { client } from './config'
 
const result = await client.simulate({
  blocks: [{
    blockOverrides: {
      number: 69420n,
    },
    calls: [
      {
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
        to: '0xcb98643b8786950F0461f3B0edf99D88F274574D',
        value: parseEther('2'),
      },
      {
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
        value: parseEther('1'),
      },
    ],
    stateOverrides: [{
      address: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
      balance: parseEther('10'),
    }],
  }]
})

Contract Calls

The calls property also accepts Contract Calls, and can be used via the abi, functionName, and args properties.

example.ts

import { parseEther } from 'viem'
import { client } from './config'
 
const abi = parseAbi([
  'function approve(address, uint256) returns (bool)',
  'function transferFrom(address, address, uint256) returns (bool)',
])
 
const result = await client.simulate({ 
  blocks: [{
    calls: [
      {
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
        value: parseEther('1')
      },
      {
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
        to: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
        abi,
        functionName: 'approve',
        args: [
          '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC', 
          100n
        ],
      },
      {
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
        to: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
        abi,
        functionName: 'transferFrom',
        args: [
          '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
          '0x0000000000000000000000000000000000000000',
          100n
        ],
      },
    ],
  }]
})

Return Value

simulateReturnType

Simulation results.

Parameters

blocks

Blocks to simulate.

blocks.calls

Type: TransactionRequest[]

Calls to simulate. Each call can consist of transaction request properties.

const result = await client.simulate({
  blocks: [{
    blockOverrides: {
      number: 69420n,
    },
    calls: [ 
      { 
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929', 
        data: '0xdeadbeef', 
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 
      }, 
      { 
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929', 
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 
        value: parseEther('1'), 
      }, 
    ], 
    stateOverrides: [{
      address: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
      balance: parseEther('10'),
    }],
  }]
})

blocks.blockOverrides

Type: BlockOverrides

Values to override on the block.

const result = await client.simulate({
  blocks: [{
    blockOverrides: { 
      number: 69420n, 
    }, 
    calls: [ 
      { 
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929', 
        data: '0xdeadbeef', 
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 
      }, 
      { 
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929', 
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 
        value: parseEther('1'), 
      }, 
    ], 
    stateOverrides: [{
      address: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
      balance: parseEther('10'),
    }],
  }]
})

blocks.stateOverrides

Type: StateOverride

State overrides.

const result = await client.simulate({
  blocks: [{
    blockOverrides: {
      number: 69420n,
    },
    calls: [ 
      { 
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929', 
        data: '0xdeadbeef', 
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 
      }, 
      { 
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929', 
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 
        value: parseEther('1'), 
      }, 
    ], 
    stateOverrides: [{ 
      address: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929', 
      balance: parseEther('10'), 
    }], 
  }]
})

returnFullTransactions

Type: boolean

Whether to return the full transactions.

const result = await client.simulate({
  blocks: [{
    blockOverrides: {
      number: 69420n,
    },
    calls: [ 
      { 
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929', 
        data: '0xdeadbeef', 
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 
      }, 
      { 
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929', 
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 
        value: parseEther('1'), 
      }, 
    ], 
    stateOverrides: [{
      address: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
      balance: parseEther('10'),
    }],
  }],
  returnFullTransactions: true, 
})

traceTransfers

Type: boolean

Whether to trace transfers.

const result = await client.simulate({
  blocks: [{
    blockOverrides: {
      number: 69420n,
    },
    calls: [ 
      { 
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929', 
        data: '0xdeadbeef', 
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 
      }, 
      { 
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929', 
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 
        value: parseEther('1'), 
      }, 
    ], 
    stateOverrides: [{
      address: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
      balance: parseEther('10'),
    }],
  }],
  traceTransfers: true, 
})

validation

Type: boolean

Whether to enable validation mode.

const result = await client.simulate({
  blocks: [{
    blockOverrides: {
      number: 69420n,
    },
    calls: [ 
      { 
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929', 
        data: '0xdeadbeef', 
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 
      }, 
      { 
        from: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929', 
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 
        value: parseEther('1'), 
      }, 
    ], 
    stateOverrides: [{
      address: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
      balance: parseEther('10'),
    }],
  }],
  validation: true, 
})