Skip to content

@tevm/vm

The @tevm/vm package provides a high-performance Ethereum Virtual Machine (EVM) implementation specifically designed for Tevm. It extends the functionality of the base EVM with additional features for testing, debugging, and development purposes.

Installation

npm install @tevm/vm

Overview

The VM package is a core component of Tevm that handles the execution of EVM bytecode, transaction processing, and block building. It provides a robust set of tools for:

  • Executing EVM bytecode and smart contracts
  • Processing transactions and blocks
  • Managing state transitions
  • Supporting various hardforks and EIPs
  • Debugging and profiling execution

API Reference

Core Types

Vm

The main VM type that extends the base VM with Tevm-specific functionality:

  • Vm - Core VM type with methods for block building, transaction execution, and state management

Block Building

Transaction Processing

  • RunTx - Function type for transaction execution
  • RunTxOpts - Options for transaction execution
  • RunTxResult - Result of transaction execution

Block Processing

Events

Core Functions

VM Creation and Management

  • createVm - Creates a new VM instance
  • deepCopy - Creates a deep copy of a VM instance

Block Operations

  • applyBlock - Applies a block to the current state
  • buildBlock - Creates a new block builder instance
  • genTxTrie - Generates transaction trie for a block

Transaction Operations

  • validateRunTx - Validates transaction parameters before execution

State Management

Usage Examples

Creating a VM Instance

import { createVm } from '@tevm/vm'
import { Common } from '@tevm/common'
 
const common = new Common({ chain: 'mainnet' })
const vm = createVm({ common })

Building and Executing a Block

import { createVm, BlockBuilder } from '@tevm/vm'
 
const vm = createVm({ /* options */ })
const blockBuilder = await vm.buildBlock({
  parentBlock: block,
  blockOpts: { /* options */ }
})
 
// Add transactions to the block
await blockBuilder.addTransaction(tx)
 
// Build and execute the block
const block = await blockBuilder.build()
const result = await vm.runBlock({ block })

Executing a Transaction

import { createVm } from '@tevm/vm'
 
const vm = createVm({ /* options */ })
const txResult = await vm.runTx({ tx })
 
console.log('Gas used:', txResult.gasUsed.toString())
console.log('Return value:', txResult.execResult.returnValue)

Error Handling

The VM package throws specific error types for different failure scenarios:

  • Transaction execution errors (invalid nonce, insufficient balance, etc.)
  • Block validation errors (invalid state root, gas limit, etc.)
  • VM execution errors (out of gas, invalid opcode, etc.)

Example error handling:

try {
  await vm.runTx({ tx })
} catch (error) {
  if (error.code === 'INVALID_OPCODE') {
    console.error('Invalid operation in contract code')
  } else if (error.code === 'OUT_OF_GAS') {
    console.error('Transaction ran out of gas')
  }
}

Configuration

The VM can be configured with various options through the VMOpts interface:

const vm = createVm({
  common, // Chain configuration
  stateManager, // Custom state manager
  blockchain, // Custom blockchain
  activatePrecompiles: true, // Activate precompiled contracts
  // ... other options
})

Related Packages

License

MIT