Tevm Node Methods

This reference documents the main API methods available on a Tevm Node instance. These methods allow you to interact with the Ethereum Virtual Machine, manage state, and control execution at various levels of abstraction.

Core Methods

🚀 Initialization

Create and set up a Tevm Node instance

⚙️ Virtual Machine

Access the low-level EVM interface

📥 Transaction Pool

Manage pending transactions

📃 Receipts & Logs

Access transaction receipts and event logs

Initialization

import { createTevmNode, http } from 'tevm'
 
const node = createTevmNode({ 
  fork: { 
    transport: http('https://mainnet.infura.io/v3/YOUR-KEY') 
  } 
}) 
 
await node.ready() // Wait for initialization

State Management

👤 Account Impersonation

Act as another account in fork mode

🔍 Event Filtering

Create and manage event filters

Account Impersonation

// Impersonate an account (fork mode only)
node.setImpersonatedAccount('0x1234...') 
 
// Get current impersonated account
const impersonated = node.getImpersonatedAccount() 
 
// Stop impersonating
node.setImpersonatedAccount(undefined) 
 
// Now you can send transactions as this account
// without having its private key

Node Properties

🚦 Status

Current state of the node

🔄 Mode

Fork or normal operation mode

📝 Logger

Built-in logging capabilities

Status

The status property indicates the current state of the node:

console.log(node.status) 
// One of: 'INITIALIZING' | 'READY' | 'SYNCING' | 'MINING' | 'STOPPED'
 
// Example: Wait until node is ready
const waitForReady = async () => {
  while (node.status !== 'READY') {
    await new Promise(resolve => setTimeout(resolve, 100))
  }
  console.log('Node is ready!')
}

Mode

The mode property indicates whether the node is running in fork or normal mode:

console.log(node.mode) // 'fork' or 'normal'
 
// Use mode to adapt behavior
if (node.mode === 'fork') {
  console.log('Node is forking from a remote provider')
  // Use fork-specific features like impersonation
} else {
  console.log('Node is running in standalone mode')
  // Use local-only features
}

Logger

Built-in logging capabilities with multiple levels:

// Different log levels
node.logger.trace('Extremely detailed information')
node.logger.debug('Detailed debugging information')
node.logger.info('General information')
node.logger.warn('Warning messages')
node.logger.error('Error information')
node.logger.fatal('Critical errors that stop execution')
 
// Log with context
node.logger.info('Transaction processed', {
  hash: '0x1234...',
  from: '0x5678...',
  to: '0x9abc...',
  value: '1 ETH'
})

Advanced Actions

tevmCall

Execute low-level EVM calls with detailed execution tracing:

import { tevmCall } from 'tevm/actions'
import { encodeFunctionData } from 'viem'
import { createMemoryClient } from 'tevm'
 
const client = createMemoryClient()
 
const result = await tevmCall(client, {
  to: '0x1234...',
  data: encodeFunctionData({
    abi,
    functionName: 'myFunction',
    args: [arg1, arg2]
  }),
  // Monitor EVM execution steps
  onStep: (step, next) => {
    console.log(`Opcode: ${step.opcode.name}, PC: ${step.pc}`)
    next?.()
  },
  // Monitor contract creation
  onNewContract: (data, next) => {
    console.log(`New contract at: ${data.address.toString()}`)
    next?.()
  },
  // Monitor call execution
  onBeforeMessage: (message, next) => {
    console.log(`Call to: ${message.to?.toString()}`)
    next?.()
  },
  onAfterMessage: (result, next) => {
    console.log(`Return: ${result.execResult.returnValue.toString('hex')}`)
    next?.()
  }
})

tevmContract

High-level contract interaction with EVM event monitoring:

import { tevmContract } from 'tevm/actions'
import { createMemoryClient } from 'tevm'
 
const client = createMemoryClient()
 
const result = await tevmContract(client, {
  abi,
  address: '0x1234...',
  functionName: 'myFunction',
  args: [arg1, arg2],
  // Monitor EVM execution
  onStep: (step, next) => {
    console.log(`Opcode: ${step.opcode.name}, Stack: ${step.stack.length}`)
    next?.()
  },
  onNewContract: (data, next) => {
    console.log(`New contract created: ${data.address.toString()}`)
    next?.()
  }
})
 
console.log('Function result:', result)

tevmDeploy

Contract deployment with execution monitoring:

import { tevmDeploy } from 'tevm/actions'
import { createMemoryClient } from 'tevm'
 
const client = createMemoryClient()
 
const deployResult = await tevmDeploy(client, {
  abi,
  bytecode,
  args: [constructorArg1, constructorArg2],
  // Monitor deployment execution
  onStep: (step, next) => {
    console.log(`Executing: ${step.opcode.name}`)
    next?.()
  },
  onNewContract: (data, next) => {
    console.log(`Deployed at: ${data.address.toString()}`)
    next?.()
  }
})
 
console.log('Contract deployed at:', deployResult.address)
console.log('Deployment gas used:', deployResult.gasUsed)

Debug Use Cases

⛽ Gas Profiling

Track gas consumption of specific operations

🧪 Smart Contract Testing

Trace execution to debug test failures

🔒 Security Auditing

Analyze EVM execution paths for vulnerabilities

🎓 Educational Tools

Create EVM instruction visualizers

Extensibility

Custom Methods

const enhancedNode = node.extend((baseNode) => ({
  async getBalance(address: string) {
    const vm = await baseNode.getVm()
    const account = await vm.stateManager.getAccount(address)
    return account.balance
  },
}))
 
// Use the new method
const balance = await enhancedNode.getBalance('0x1234...')

JSON-RPC Support

EIP-1193 Interface

import { requestEip1193 } from 'tevm/decorators'
 
const node = createTevmNode().extend(requestEip1193())
 
// Standard JSON-RPC calls
const blockNumber = await node.request({ 
  method: 'eth_blockNumber', 
  params: [] 
}) 
 
// Get balance
const balance = await node.request({
  method: 'eth_getBalance',
  params: ['0x1234...', 'latest']
})

Supported Methods

JSON-RPC Methods

State Access

📄 eth_getBalance
📄 eth_getCode
📄 eth_getStorageAt
📄 eth_getTransactionCount

Block Methods

📄 eth_blockNumber
📄 eth_getBlockByHash
📄 eth_getBlockByNumber

Transaction Methods

📄 eth_sendTransaction
📄 eth_sendRawTransaction
📄 eth_getTransactionByHash
📄 eth_getTransactionReceipt

Anvil Methods

📄 anvil_impersonateAccount
📄 anvil_stopImpersonatingAccount
📄 anvil_mine
📄 anvil_setBalance

Tevm Methods

📄 tevm_snapshot
📄 tevm_revert
📄 tevm_mine
📄 tevm_setAccount

View Complete JSON-RPC API →