Skip to content

@tevm/memory-client

The @tevm/memory-client package provides a powerful in-memory Ethereum client implementation for Tevm. It combines the capabilities of viem with Tevm's custom EVM implementation to offer a complete testing and development environment.

Installation

npm install @tevm/memory-client

API Reference

Type Aliases

Actions

Overview

The memory client package provides:

  • A complete in-memory Ethereum client implementation
  • Support for forking existing networks
  • Automatic and manual mining modes
  • Full compatibility with viem's actions
  • Extended functionality through Tevm-specific actions

Core Components

MemoryClient

The main client class that provides Ethereum client functionality with in-memory state management.

import { createMemoryClient } from '@tevm/memory-client'
 
const client = createMemoryClient({
  fork: {
    transport: http("https://mainnet.optimism.io")
  }
})

Client Options

interface MemoryClientOptions<TCommon, TAccountOrAddress, TRpcSchema> {
  // Chain configuration
  common?: TCommon
  // Fork configuration
  fork?: {
    transport: Transport
    blockTag?: string | number
  }
  // Client configuration
  name?: string
  account?: TAccountOrAddress
  pollingInterval?: number
  cacheTime?: number
}

Features

Mining Modes

The client supports two mining modes:

// Auto mining (default)
const client = createMemoryClient()
 
// Manual mining
const client = createMemoryClient({
  mining: {
    mode: 'manual'
  }
})
 
// Mine blocks manually
await client.mine()

Network Forking

Fork any EVM-compatible network:

import { createMemoryClient, http } from '@tevm/memory-client'
import { optimism } from '@tevm/common'
 
const client = createMemoryClient({
  fork: {
    transport: http("https://mainnet.optimism.io"),
    blockTag: '0xa6a63cd70fbbe396321ca6fe79e1b6735760c03538208b50d7e3a5dac5226435'
  },
  common: optimism
})

State Management

// Set account state
await client.setAccount({
  address: '0x...',
  balance: 100n,
  nonce: 1n,
  deployedBytecode: '0x...',
  state: {
    '0x...': '0x...'
  }
})
 
// Get account state
const account = await client.getAccount({
  address: '0x...',
  returnStorage: true
})

Contract Interactions

// Deploy contract
const deployResult = await client.tevmDeploy({
  abi: contractAbi,
  bytecode: contractBytecode,
  args: ['Constructor', 'Args']
})
 
// Call contract
const result = await client.tevmCall({
  to: contractAddress,
  data: encodeFunctionData(...)
})
 
// Contract interaction with high-level API
const contractResult = await client.tevmContract({
  contract: myContract,
  method: 'myMethod',
  args: [arg1, arg2]
})

Transaction Management

// Send transaction
const hash = await client.writeContract({
  address: contractAddress,
  abi: contractAbi,
  functionName: 'myFunction',
  args: [arg1, arg2]
})
 
// Wait for receipt
const receipt = await client.waitForTransactionReceipt({ hash })

Actions API

The client includes several sets of actions:

Tevm Actions

  • tevmCall: Low-level EVM call execution
  • tevmContract: High-level contract interaction
  • tevmDeploy: Contract deployment
  • tevmGetAccount: Account state retrieval
  • tevmSetAccount: Account state modification
  • tevmDeal: Add native ETH or ERC20 tokens to an account
  • tevmMine: Manual block mining
  • tevmDumpState: State export
  • tevmLoadState: State import

Viem Actions

  • Public actions (e.g., getBlockNumber, getBalance)
  • Wallet actions (e.g., sendTransaction, signMessage)
  • Test actions (e.g., setBalance, impersonateAccount)

Advanced Features

State Persistence

import { createMemoryClient, createSyncPersister } from '@tevm/memory-client'
 
const client = createMemoryClient({
  persister: createSyncPersister({
    storage: localStorage
  })
})

HTTP Server Integration

import { createServer } from '@tevm/server'
import { createMemoryClient } from '@tevm/memory-client'
 
const client = createMemoryClient()
const server = createServer({
  request: client.request
})
 
server.listen(8545)

Network Support

Officially supported networks:

  • Ethereum mainnet
  • Standard OP Stack chains

Other EVM-compatible chains may work but are not officially supported.

EIP Support

Always-enabled EIPs:

  • EIP-1559 (Fee Market)
  • EIP-4895
  • EIP-4844 (Blob Transactions)
  • EIP-4788

Types

The package exports several important types:

type MemoryClient<TChain, TAccountOrAddress>
type MemoryClientOptions<TCommon, TAccountOrAddress, TRpcSchema>
type TevmActions
type TevmContract
type TevmRpcSchema
type TevmTransport

License

This package is licensed under the MIT License.

See Also