Tevm

Tevm

Use tevm@1.0.0-rc.151. Do not copy 1.0.0-next.x examples or rely on npm's latest tag. Install a compatible viem peer explicitly. The rc.151 repository uses viem@2.49.3.

Mental model

Tevm is an EVM that runs inside the JavaScript or TypeScript process and exposes both Tevm-native and viem-compatible actions. Its three defining capabilities are: run a real EVM without a subprocess or JSON-RPC server, import Solidity files as typechecked contract modules, and fork mainnet or another EVM chain with remote state fetched lazily only when execution touches it. Use Tevm to make state setup, execution, mining, tracing, and assertions one program.

Start with a complete script

This script creates a synchronous memory client, funds a caller, deploys a packaged contract, mines it, sends a state-changing call, mines again, and reads the result.

import {
  createMemoryClient,
  encodeFunctionData,
  parseEther,
} from "tevm";
import { SimpleContract } from "tevm/contract";

const caller = "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
const client = createMemoryClient({
  miningConfig: { type: "manual" },
});

await client.tevmSetAccount({
  address: caller,
  balance: parseEther("10"),
  nonce: 0n,
});

const deployment = await client.tevmDeploy({
  ...SimpleContract.deploy(42n),
  from: caller,
});
if (!deployment.createdAddress) throw new Error("deployment failed");

await client.tevmMine({ blockCount: 1 });
const counter = SimpleContract.withAddress(deployment.createdAddress);

await client.tevmCall({
  from: caller,
  to: counter.address,
  data: encodeFunctionData(counter.write.set(7n)),
  addToMempool: true,
});
await client.tevmMine({ blockCount: 1 });

const read = await client.tevmContract(counter.read.get());
const value = read.data;
const account = await client.tevmGetAccount({ address: caller });
const chainId = await client.request({ method: "eth_chainId" });

console.log({
  contract: counter.address,
  value,
  funded: account.balance > 0n,
  chainId,
});

if (value !== 7n) throw new Error(`expected 7, received ${value}`);
if (account.balance <= 0n) throw new Error("caller unexpectedly depleted");

Reach for these APIs

createMemoryClient(options?: MemoryClientOptions): MemoryClient is synchronous in rc.151. Its result already includes Tevm actions plus viem public, wallet, and Anvil-mode test actions.

Import tree-shakeable forms from tevm/actions. Their signatures put the client first: tevmCall(client, params), tevmMine(client, params?), tevmSetAccount(client, params), tevmGetAccount(client, params), and tevmDeploy(client, params).

Keep parameter dialects separate. Tevm mining uses { blockCount: 1 }; viem test mining uses { blocks: 1 }. Tevm account setup uses { balance }; viem setBalance uses { value }. Viem call models eth_call; tevmCall adds tracing, access lists, state overrides, transaction creation, and direct EVM controls.

The EIP-1193 shape is client.request({ method, params }). Pass params as a positional array only for methods that take arguments; omit the key entirely for no-argument methods such as eth_chainId and eth_blockNumber. In rc.151 those method types declare params?: undefined, so params: [] runs but fails typechecking. For raw Tevm JSON-RPC, client.transport.tevm.request also accepts a full { jsonrpc: "2.0", id, method: "tevm_call", params: [callParams] } request and returns JSON-serialized quantities.

Fork lazily and pin the state

Pass a transport factory, not a URL string. Set common for OP-stack rules and fee behavior. Use a bigint blockTag or a blockHash for reproducibility.

import { createMemoryClient, http } from "tevm";
import { mainnet, optimism } from "tevm/common";

const forks = [
  {
    name: "mainnet",
    common: mainnet,
    url: "https://ethereum-rpc.publicnode.com",
    blockTag: 19_000_000n,
  },
  {
    name: "optimism",
    common: optimism,
    url: "https://optimism-rpc.publicnode.com",
    blockTag: 120_000_000n,
  },
] as const;

for (const fork of forks) {
  const client = createMemoryClient({
    common: fork.common,
    fork: {
      transport: http(fork.url),
      blockTag: fork.blockTag,
    },
  });
  await client.tevmReady();
  const block = await client.getBlock({ blockTag: "latest" });
  console.log(fork.name, block.number);
  if (block.number !== fork.blockTag) {
    throw new Error(`${fork.name}: expected ${fork.blockTag}, got ${block.number}`);
  }
}

At initialization Tevm resolves the chain ID and fork anchor. It does not download chain state. Account records, code, storage slots, proofs, and blocks are requested from the fork transport when an action first touches them, then cached locally. Local writes overlay the fork.

If blockTag is omitted or set to latest, tevmReady() resolves it to a concrete anchor. Pin a bigint in tests. Use fork.chainId only to override the exposed chain ID. It does not change the remote chain.

rc.151 limitations matter:

• Mainnet fork block reconstruction can fail on blocks containing EIP-4844 transactions if common.customCrypto.kzg is not initialized. The verified example uses a pre-4844 block.
• OP-stack deposit transaction types are filtered during block reconstruction. State-backed execution works, but a reconstructed block hash can differ from the remote block.

Import Solidity as typed modules

Install the plugin matching the runtime:

The plugin resolves Solidity imports, compiles the dependency graph, and emits Tevm Contract exports with literal ABI types and helpers such as .read, .write, .deploy, and .withAddress.

Use .sol for ABI and type helpers. Name a deployable module .s.sol; rc.151 emits creation and deployed bytecode only for .s.sol.

Install @tevm/ts-plugin@1.0.0-rc.151 and add { "name": "@tevm/ts-plugin" } to compilerOptions.plugins. It gives the TypeScript language service editor types, completion, diagnostics, and navigation for Solidity imports. It does not transform runtime imports; the bundler plugin does that. Configure the editor to use the workspace TypeScript version.

tsc on the command line does not load language-service plugins, so a plain tsc --noEmit reports TS2307: Cannot find module './Counter.s.sol'. Typecheck Solidity-importing files in the editor, or exclude them from the tsc project and rely on the bundler plugin plus tests. In rc.151 the bundled tevm-gen declaration generator fails with solc.compile is not a function, so it is not a working substitute.

Test inside Vitest

Use a deployable Solidity source:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract Counter {
    uint256 public number;

    constructor(uint256 initialNumber) {
        number = initialNumber;
    }

    function setNumber(uint256 nextNumber) external {
        number = nextNumber;
    }
}

Save it as Counter.s.sol, then configure Vitest:

import { defineConfig } from "vitest/config";
import { vitePluginTevm } from "@tevm/vite-plugin";

export default defineConfig({
  plugins: [vitePluginTevm()],
  test: { environment: "node" },
});

Run the EVM in the test process:

import { describe, expect, it } from "vitest";
import { createMemoryClient } from "tevm";
import { Counter } from "./Counter.s.sol";

describe("Counter", () => {
  it("deploys and reads in process", async () => {
    const client = createMemoryClient();
    const deployed = await client.tevmDeploy(Counter.deploy(3n));
    if (!deployed.createdAddress) throw new Error("deployment failed");

    await client.tevmMine();
    const counter = Counter.withAddress(deployed.createdAddress);

    await expect(client.readContract(counter.read.number())).resolves.toBe(3n);
  });
});

Compared with Anvil, Tevm needs no process lifecycle or RPC port, keeps ABI types from Solidity import through the assertion, permits direct account and storage mutation without RPC serialization, and exposes EVM traces, access lists, state dumps, snapshots, and custom precompiles inside the test process.

Avoid these first-run failures

Do not use Tevm when

• A production service needs a durable full or archive node, peer-to-peer sync, consensus participation, or an externally reachable RPC service.
• A simple remote read needs only viem and no local execution, fork overlay, trace, or state mutation.
• Exact remote block reconstruction is required for post-4844 mainnet blocks or OP-stack blocks containing deposit transactions under rc.151.
• Independent validation is security critical. Compare against another execution client or a real node.
• The EVM must survive process restarts without explicitly dumping and restoring state.