Tevm reference

Overview

Tevm reference docs are autogenerated from their TypeScript types and jsdoc annotations. This guide organizes the generated docs contextually.

Most runtime packages are available both as standalone packages (@tevm/actions) or conveniently in a barrel package. tevm. Most buildtime packages like the typescript or webpack plugin are similarly available both as a standalone @tevm/ts-plugin and in a barrel package @tevm/bundler

The tevm api is vast because all internal packages are made publically available. For most users they will be best off sticking to the getting-started and guides which go over the main top-level apis.

Runtime packages

Memory client and actions apis packages

The following packages are used to build MemoryClient:

@tevm/actions Implements the tevm ActionsApi along with actions for handling ethereum JSON-RPC requests.
@tevm/actions-types The typescript types for @tevm/actions
@tevm/base-client The base client extended by memory-client and used to implement @tevm/actions. It is currently built on top of the ethereumjs api
@tevm/client-types This package is deprecated and will be removed soon
@tevm/contract Implements the Contract and Scripts. These are used at runtime and also generated by the buildtime tevm compiler.
@tevm/common This package holds common blockchain information such as gas fee information by network
@tevm/decorators This package internal to memory-client creates viem-like decorators for adding functionality to BaseClient such as EIP-1193 request function and TevmActionsApi
@tevm/errors Contains the definitions for all the type-safe errors tevm can throw
@tevm/http-client Is deprecated in favor of using viem and ethers clients
@tevm/json-rpc Is an extremely simple package that makes json-rpc requests to fork url.
@tevm/logger Is the internal logger used by tevm.
@tevm/memory-client Implements the tevm MemoryClient
@tevm/precompiles Implements tevm precompile support for tevm advanced scripting
@tevm/predeploys Implements tevm predeploy support
@tevm/procedures Wraps the @tevm/actions api with JSON-RPC support.
@tevm/procedures-types Wraps the @tevm/actions-types api with JSON-RPC support. The TypeScript types for @tevm/procedures
@tevm/server Turns any tevm client with tevm.send such as MemoryClient into a http server in next.js, express, or a vanilla node http handler
@tevm/sync-storage-persister An experimental package that allows users to persist tevm state. Often used to sync tevm to local storage.
@tevm/utils Contains many low level util methods used by tevm as well as reexports important utils from viem and ethereumjs that end users may need.
@tevm/zod Contains zod validators used internally for validation

Ethereum EVM packages

The following packages are used to implement base-client and are the lowest level packages implementing the Tevm VM. They all are modified from ethereumjs either as custom implementations implementing the same interface or extending it’s functionality.

Note: many of these packages hold a MLP-2.0 license because they are adapted from ethereumjs rather than an MIT license.0

@tevm/block A simple package representing ethereum blocks. It is used by the @tevm/blockchain package
@tevm/blockchain A custom implementaton of ethereumjs/blockchain. This package is in charge of holding the cannonical chain in memory as well as forking blocks.
@tevm/common This package holds common blockchain information such as gas fee information by network
@tevm/evm Contains the EVM to execute bytecode. It lightly wraps the ethereumjs evm with custom tevm types/functionality
@tevm/receipt-manager Module involved with tracking receipts. The equivelent ethereumjs component is in @ethereumjs/client package
@tevm/rlp Wraps ethereumjs rlp. Deprecated in favor of using viem.
@tevm/state A custom implementation of the ethereumjs/state-manager package. It is in charge of both keeping the VM state as well as fetching state from fork urls.
@tevm/trie Simply reexports @ethereumjs/trie.
@tevm/tx A custom implementation of the @ethereumjs/tx package that notably has a new tx type called ImpersonatedTx for unsigned tx that are meant to impersonate signed ones in the EVM.
@tevm/txpool A mempool implementation that holds the state of transactions that have not yet bein included in @tevm/blockchain
@tevm/vm A custom implementation of the @ethereumjs/vm package

Tevm extensions

The following packages extend tevm functionality for compatability with other popular libraries and technologies.

@tevm/ethers Contains an ethers provider similar to MemoryClient as well as typesafe ethers contracts
@tevm/opstack Experimental package for running an opstack devnet
@tevm/viem Contains useful utils for extending viem with tevm functionality.

Buildtime packages

Util packages

The following package isn’t specific to the bundler per-say but still used by the bundler.

@tevm/effect The tevm compiler uses effect.ts under the hood and this package has common code for using it. In future versions the runtime might be migrated to Effect as well.

Base bundler implementation

The tevm bundler is built agnostic of any specific bundler and then reused to implement specific bundlers with a single implementation. The following packages make it up

@tevm/base-bundler is the main package implementing the tevm bundler. It generates typescript and javascript files when given a path to a solidity file.
@tevm/compiler The internal package that compiles solidity to it’s abi and bytecode artifacts as well as generating an AST
@tevm/config The internal package in charge of reading and validating a tevm.config.json file
@tevm/resolutions The internal package in charge of resolving solidity import graphs. It handles things like remappings, loading solidity from node_modules, and creating the overall build graph.
@tevm/runtime The internal package in charge of turning solidity artifacts into Typescript/JavaScript runtime code
@tevm/solc A simple typesafe wrapper around solc used by @tevm/compiler to compile solidity contracts.

Specific bundler implementations

The following bundlers use @tevm/base-bundler to implement support for specific bundlers

@tevm/bun Implements bun plugin support
@tevm/esbuild Implements an esbuild plugin
@tevm/rollup Implements an rollup plugin
@tevm/rspack Implements an rspack plugin
@tevm/unplugin Implements an unplugin
@tevm/vite Implements an vite plugin
@tevm/webpack Implements an webpack plugin

LSP

In addition to implementing bundlers the @tevm/base-bundler is also used to implement the tevm Typescript LSP plugins and wrappers to allow typescript to infer types from solidity.

@tevm/ts-plugin The current implementation of the TypeScript lsp as a ts plugin
@tevm/lsp The next generation version of the lsp built with volar. This version of the LSP will unblock future improvements, stabilize the LSP, simplify the internal code, and allow for easy debugging.
@tevm/vscode A vscode plugin for tevm built on top of @tevm/lsp volar package

CLI packages

The tevm cli is not yet publically available but implemented in the following package:

@tevm/cli Implements the tevm cli

Experimental package

Tevm is always experimenting with next generation improvements.

@tevm/revm Compiles revm to wasm. In future this will be used to implement the tevm actions api using revm as it’s backend.
@tevm/schema Implements all ethereum types as an effect schema
@tevm/solc-experimental An experimental take on the solc compiler that initializes itself at runtime
@tevm/viem-effect A code-generated library that wraps the viem api with an effect.ts based wrapper returning strongly typed errors.