Skip to content

@tevm/evm

The @tevm/evm package provides a custom implementation of the Ethereum Virtual Machine (EVM), extending the functionality of ethereumjs/evm. It's responsible for executing Ethereum bytecode and managing the execution environment.

Generated API Documentation: View the full API documentation in the evmts/tevm-monorepo/packages/evm/docs folder.

Installation

npm install @tevm/evm

API Reference

Enumerations

Core Classes

Interfaces

Type Aliases

Variables

  • Eof - EOF-related constants

Functions

Usage Examples

Creating an EVM Instance

import { createEvm } from '@tevm/evm'
import { mainnet } from '@tevm/common'
import { createStateManager } from '@tevm/state'
import { createChain } from '@tevm/chain'
 
const evm = await createEvm({
  common: mainnet,
  stateManager: createStateManager,
  blockchain: await createChain({ common: mainnet }),
  customPrecompiles: [], // Optional custom precompiles
  profiler: false, // Enable/disable profiling
  loggingLevel: 'warn', // Logging configuration
})

Running EVM Calls

const result = await evm.runCall({
  to: '0x1234...',
  caller: '0x5678...',
  data: new Uint8Array([/* bytecode */]),
  value: 1000n,
  gasLimit: 100000n
})
 
console.log(result.execResult.returnValue)
console.log(result.execResult.executionGasUsed)

Custom Precompiles

import { definePrecompile, defineCall, createContract, parseAbi } from '@tevm/evm'
import { createAddress } from '@tevm/utils'
 
const MyContract = createContract({
  address: createAddress(2424).toString(),
  abi: parseAbi([
    'function addTwo(uint256) returns (uint256)',
  ])
})
 
const customPrecompile = definePrecompile({
  contract: MyContract,
  call: defineCall(MyContract.abi, {
    addTwo: async ({ args }) => {
      return {
        returnValue: args[0] + 5n,
        executionGasUsed: 0n
      }
    }
  })
})
 
evm.addCustomPrecompile(customPrecompile.precompile())

Error Handling

try {
  const result = await evm.runCall({
    to: '0x1234...',
    gasLimit: 100n // Very low gas limit
  })
} catch (error) {
  if (error instanceof EvmError) {
    console.log(error.error) // e.g. EvmErrorMessage.OUT_OF_GAS
  }
}

Debugging and Performance

// Enable debug logging
const evm = await createEvm({
  loggingLevel: 'trace'
})
 
// Get performance logs
const logs = evm.getPerformanceLogs()
console.log(logs.opcodes) // Opcode execution stats
console.log(logs.precompiles) // Precompile execution stats

See Also