Skip to content
Tevm Docs
Blog

createMemoryClient

createMemoryClient<TCommon, TAccountOrAddress, TRpcSchema>(options?): object

Creates a MemoryClient which is a viem client with an in-memory Ethereum client as its transport. It comes batteries included with all wallet, test, public, and tevm actions.

Type Parameters

• TCommon extends object & object & ChainConfig<undefined | ChainFormatters, undefined | Record<string, unknown>> = object & object & ChainConfig<undefined | ChainFormatters, undefined | Record<string, unknown>>

• TAccountOrAddress extends undefined | `0x${string}` | Account = undefined

• TRpcSchema extends undefined | RpcSchema = [object, object, object, object, object]

Parameters

• options?: MemoryClientOptions<TCommon, TAccountOrAddress, TRpcSchema>

Returns

object

account

account: TAccountOrAddress extends Account ? Account : undefined

The Account of the Client.

addChain()

addChain: (args) => Promise<void>

Adds an EVM chain to the wallet.

Parameters

• args: AddChainParameters

AddChainParameters

Returns

Promise<void>

Example

import { createWalletClient, custom } from 'viem'
import { optimism } from 'viem/chains'


const client = createWalletClient({
  transport: custom(window.ethereum),
})
await client.addChain({ chain: optimism })

batch?

optional batch: object

Flags for batch settings.

batch.multicall?

optional batch.multicall: boolean | object

Toggle to enable eth_call multicall aggregation.

cacheTime

cacheTime: number

Time (in ms) that cached data will remain in memory.

call()

call: (parameters) => Promise<CallReturnType>

Executes a new message call immediately without submitting a transaction to the network.

Parameters

• parameters: CallParameters<TCommon>

Returns

Promise<CallReturnType>

The call data. CallReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const data = await client.call({
  account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
  data: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
})

ccipRead?

optional ccipRead: false | object

CCIP Read configuration.

chain

chain: TCommon

Chain for the client.

createBlockFilter()

createBlockFilter: () => Promise<object>

Creates a Filter to listen for new block hashes that can be used with getFilterChanges.

Returns

Promise<object>

Filter. CreateBlockFilterReturnType

id

id: `0x${string}`

request

request: EIP1193RequestFn<readonly [object, object, object]>

type

type: "block"

Example

import { createPublicClient, createBlockFilter, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await createBlockFilter(client)
// { id: "0x345a6572337856574a76364e457a4366", type: 'block' }

createContractEventFilter()

createContractEventFilter: <abi, eventName, args, strict, fromBlock, toBlock>(args) => Promise<CreateContractEventFilterReturnType<abi, eventName, args, strict, fromBlock, toBlock>>

Creates a Filter to retrieve event logs that can be used with getFilterChanges or getFilterLogs.

Type Parameters

• abi extends Abi | readonly unknown[]

• eventName extends undefined | string

• args extends undefined | Record<string, unknown> | readonly unknown[]

• strict extends undefined | boolean = undefined

• fromBlock extends undefined | bigint | BlockTag = undefined

• toBlock extends undefined | bigint | BlockTag = undefined

Parameters

• args: CreateContractEventFilterParameters<abi, eventName, args, strict, fromBlock, toBlock>

CreateContractEventFilterParameters

Returns

Promise<CreateContractEventFilterReturnType<abi, eventName, args, strict, fromBlock, toBlock>>

Filter. CreateContractEventFilterReturnType

Example

import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createContractEventFilter({
  abi: parseAbi(['event Transfer(address indexed, address indexed, uint256)']),
})

createEventFilter()

createEventFilter: <abiEvent, abiEvents, strict, fromBlock, toBlock, _EventName, _Args>(args?) => Promise<{ [K in string | number | symbol]: Filter<“event”, abiEvents, _EventName, _Args, strict, fromBlock, toBlock>[K] }>

Creates a Filter to listen for new events that can be used with getFilterChanges.

Type Parameters

• abiEvent extends undefined | AbiEvent = undefined

• abiEvents extends undefined | readonly unknown[] | readonly AbiEvent[] = abiEvent extends AbiEvent ? [abiEvent<abiEvent>] : undefined

• strict extends undefined | boolean = undefined

• fromBlock extends undefined | bigint | BlockTag = undefined

• toBlock extends undefined | bigint | BlockTag = undefined

• _EventName extends undefined | string = MaybeAbiEventName<abiEvent>

• _Args extends undefined | Record<string, unknown> | readonly unknown[] = undefined

Parameters

• args?: CreateEventFilterParameters<abiEvent, abiEvents, strict, fromBlock, toBlock, _EventName, _Args>

CreateEventFilterParameters

Returns

Promise<{ [K in string | number | symbol]: Filter<“event”, abiEvents, _EventName, _Args, strict, fromBlock, toBlock>[K] }>

Filter. CreateEventFilterReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createEventFilter({
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
})

createPendingTransactionFilter()

createPendingTransactionFilter: () => Promise<object>

Creates a Filter to listen for new pending transaction hashes that can be used with getFilterChanges.

Returns

Promise<object>

Filter. CreateBlockFilterReturnType

id

id: `0x${string}`

request

request: EIP1193RequestFn<readonly [object, object, object]>

type

type: "transaction"

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createPendingTransactionFilter()
// { id: "0x345a6572337856574a76364e457a4366", type: 'transaction' }

deployContract()

deployContract: <abi, chainOverride>(args) => Promise<`0x${string}`>

Deploys a contract to the network, given bytecode and constructor arguments.

Type Parameters

• abi extends Abi | readonly unknown[]

• chainOverride extends undefined | Chain

Parameters

• args: DeployContractParameters<abi, TCommon, TAccountOrAddress extends Account ? Account : undefined, chainOverride>

DeployContractParameters

Returns

Promise<`0x${string}`>

The Transaction hash. DeployContractReturnType

Example

import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  account: privateKeyToAccount('0x…'),
  chain: mainnet,
  transport: http(),
})
const hash = await client.deployContract({
  abi: [],
  account: '0x…,
  bytecode: '0x608060405260405161083e38038061083e833981016040819052610...',
})

dropTransaction()

dropTransaction: (args) => Promise<void>

Removes a transaction from the mempool.

Parameters

• args: DropTransactionParameters

DropTransactionParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.dropTransaction({
  hash: '0xe58dceb6b20b03965bb678e27d141e151d7d4efc2334c2d6a49b9fac523f7364'
})

dumpState()

dumpState: () => Promise<`0x${string}`>

Serializes the current state (including contracts code, contract’s storage, accounts properties, etc.) into a savable data blob.

Returns

Promise<`0x${string}`>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.dumpState()

estimateContractGas()

estimateContractGas: <chain, abi, functionName, args>(args) => Promise<bigint>

Estimates the gas required to successfully execute a contract write function call.

Type Parameters

• chain extends undefined | Chain

• abi extends Abi | readonly unknown[]

• functionName extends string

• args extends unknown

Parameters

• args: EstimateContractGasParameters<abi, functionName, args, chain>

EstimateContractGasParameters

Returns

Promise<bigint>

The gas estimate (in wei). EstimateContractGasReturnType

Remarks

Internally, uses a Public Client to call the estimateGas action with ABI-encoded data.

Example

import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const gas = await client.estimateContractGas({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: parseAbi(['function mint() public']),
  functionName: 'mint',
  account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
})

estimateFeesPerGas()

estimateFeesPerGas: <chainOverride, type>(args?) => Promise<EstimateFeesPerGasReturnType<type>>

Returns an estimate for the fees per gas for a transaction to be included in the next block.

Type Parameters

• chainOverride extends undefined | Chain = undefined

• type extends FeeValuesType = "eip1559"

Parameters

• args?: EstimateFeesPerGasParameters<TCommon, chainOverride, type>

Returns

Promise<EstimateFeesPerGasReturnType<type>>

An estimate (in wei) for the fees per gas. EstimateFeesPerGasReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const maxPriorityFeePerGas = await client.estimateFeesPerGas()
// { maxFeePerGas: ..., maxPriorityFeePerGas: ... }

estimateGas()

estimateGas: (args) => Promise<bigint>

Estimates the gas necessary to complete a transaction without submitting it to the network.

Parameters

• args: EstimateGasParameters<TCommon>

EstimateGasParameters

Returns

Promise<bigint>

The gas estimate (in wei). EstimateGasReturnType

Example

import { createPublicClient, http, parseEther } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const gasEstimate = await client.estimateGas({
  account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
  value: parseEther('1'),
})

estimateMaxPriorityFeePerGas()

estimateMaxPriorityFeePerGas: <chainOverride>(args?) => Promise<bigint>

Returns an estimate for the max priority fee per gas (in wei) for a transaction to be included in the next block.

Type Parameters

• chainOverride extends undefined | Chain = undefined

Parameters

• args?: GetChainParameter<TCommon, chainOverride>

Returns

Promise<bigint>

An estimate (in wei) for the max priority fee per gas. EstimateMaxPriorityFeePerGasReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const maxPriorityFeePerGas = await client.estimateMaxPriorityFeePerGas()
// 10000000n

extend()

extend: <client>(fn) => Client<TevmTransport, TCommon, TAccountOrAddress extends Account ? Account : undefined, [object, object, object, object, object], { [K in string | number | symbol]: client[K] } & TevmActions & PublicActions<TevmTransport, TCommon, TAccountOrAddress extends Account ? Account : undefined> & WalletActions<TCommon, TAccountOrAddress extends Account ? Account : undefined> & TestActions>

Type Parameters

• client extends object & ExactPartial<ExtendableProtectedActions<TevmTransport, TCommon, TAccountOrAddress extends Account ? Account : undefined>>

Parameters

• fn

Returns

Client<TevmTransport, TCommon, TAccountOrAddress extends Account ? Account : undefined, [object, object, object, object, object], { [K in string | number | symbol]: client[K] } & TevmActions & PublicActions<TevmTransport, TCommon, TAccountOrAddress extends Account ? Account : undefined> & WalletActions<TCommon, TAccountOrAddress extends Account ? Account : undefined> & TestActions>

getAddresses()

getAddresses: () => Promise<GetAddressesReturnType>

Returns a list of account addresses owned by the wallet or client.

Returns

Promise<GetAddressesReturnType>

List of account addresses owned by the wallet or client. GetAddressesReturnType

Example

import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
const accounts = await client.getAddresses()

getAutomine()

getAutomine: () => Promise<boolean>

Returns the automatic mining status of the node.

Returns

Promise<boolean>

Whether or not the node is auto mining. GetAutomineReturnType

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
const isAutomining = await client.getAutomine()

getBalance()

getBalance: (args) => Promise<bigint>

Returns the balance of an address in wei.

Parameters

• args: GetBalanceParameters

GetBalanceParameters

Returns

Promise<bigint>

The balance of the address in wei. GetBalanceReturnType

Remarks

You can convert the balance to ether units with formatEther.

const balance = await getBalance(client, {
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  blockTag: 'safe'
})
const balanceAsEther = formatEther(balance)
// "6.942"

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const balance = await client.getBalance({
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
})
// 10000000000000000000000n (wei)

getBlobBaseFee()

getBlobBaseFee: () => Promise<bigint>

Returns the base fee per blob gas in wei.

Returns

Promise<bigint>

The blob base fee (in wei). GetBlobBaseFeeReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { getBlobBaseFee } from 'viem/public'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const blobBaseFee = await client.getBlobBaseFee()

getBlock()

getBlock: <includeTransactions, blockTag>(args?) => Promise<{ [K in string | number | symbol]: FormattedBlock<TCommon, includeTransactions, blockTag>[K] }>

Returns information about a block at a block number, hash, or tag.

Type Parameters

• includeTransactions extends boolean = false

• blockTag extends BlockTag = "latest"

Parameters

• args?: GetBlockParameters<includeTransactions, blockTag>

GetBlockParameters

Returns

Promise<{ [K in string | number | symbol]: FormattedBlock<TCommon, includeTransactions, blockTag>[K] }>

Information about the block. GetBlockReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const block = await client.getBlock()

getBlockNumber()

getBlockNumber: (args?) => Promise<bigint>

Returns the number of the most recent block seen.

Parameters

• args?: GetBlockNumberParameters

GetBlockNumberParameters

Returns

Promise<bigint>

The number of the block. GetBlockNumberReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const blockNumber = await client.getBlockNumber()
// 69420n

getBlockTransactionCount()

getBlockTransactionCount: (args?) => Promise<number>

Returns the number of Transactions at a block number, hash, or tag.

Parameters

• args?: GetBlockTransactionCountParameters

GetBlockTransactionCountParameters

Returns

Promise<number>

The block transaction count. GetBlockTransactionCountReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const count = await client.getBlockTransactionCount()

getBytecode()

getBytecode: (args) => Promise<GetCodeReturnType>

Parameters

• args: GetCodeParameters

Returns

Promise<GetCodeReturnType>

getChainId

getChainId: () => Promise<number> & () => Promise<number>

Returns the chain ID associated with the current network.

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const chainId = await client.getChainId()
// 1

getCode()

getCode: (args) => Promise<GetCodeReturnType>

Retrieves the bytecode at an address.

Parameters

• args: GetCodeParameters

GetBytecodeParameters

Returns

Promise<GetCodeReturnType>

The contract’s bytecode. GetBytecodeReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const code = await client.getCode({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
})

getContractEvents()

getContractEvents: <abi, eventName, strict, fromBlock, toBlock>(args) => Promise<GetContractEventsReturnType<abi, eventName, strict, fromBlock, toBlock>>

Returns a list of event logs emitted by a contract.

Type Parameters

• abi extends Abi | readonly unknown[]

• eventName extends undefined | string = undefined

• strict extends undefined | boolean = undefined

• fromBlock extends undefined | bigint | BlockTag = undefined

• toBlock extends undefined | bigint | BlockTag = undefined

Parameters

• args: GetContractEventsParameters<abi, eventName, strict, fromBlock, toBlock>

Returns

Promise<GetContractEventsReturnType<abi, eventName, strict, fromBlock, toBlock>>

A list of event logs. GetContractEventsReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { wagmiAbi } from './abi'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const logs = await client.getContractEvents(client, {
 address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
 abi: wagmiAbi,
 eventName: 'Transfer'
})

getEip712Domain()

getEip712Domain: (args) => Promise<GetEip712DomainReturnType>

Reads the EIP-712 domain from a contract, based on the ERC-5267 specification.

Parameters

• args: GetEip712DomainParameters

Returns

Promise<GetEip712DomainReturnType>

The EIP-712 domain, fields, and extensions. GetEip712DomainReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})


const domain = await client.getEip712Domain({
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
})
// {
//   domain: {
//     name: 'ExampleContract',
//     version: '1',
//     chainId: 1,
//     verifyingContract: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
//   },
//   fields: '0x0f',
//   extensions: [],
// }

getEnsAddress()

getEnsAddress: (args) => Promise<GetEnsAddressReturnType>

Gets address for ENS name.

Parameters

• args

GetEnsAddressParameters

• args.blockNumber?: bigint

The balance of the account at a block number.

• args.blockTag?: BlockTag

The balance of the account at a block tag.

Default

'latest'

• args.coinType?: number

ENSIP-9 compliant coinType used to resolve addresses for other chains

• args.gatewayUrls?: string[]

Universal Resolver gateway URLs to use for resolving CCIP-read requests.

• args.name: string

Name to get the address for.

• args.strict?: boolean

Whether or not to throw errors propagated from the ENS Universal Resolver Contract.

• args.universalResolverAddress?: `0x${string}`

Address of ENS Universal Resolver Contract.

Returns

Promise<GetEnsAddressReturnType>

Address for ENS name or null if not found. GetEnsAddressReturnType

Remarks

Calls resolve(bytes, bytes) on ENS Universal Resolver Contract.

Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to normalize ENS names with UTS-46 normalization before passing them to getEnsAddress. You can use the built-in normalize function for this.

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { normalize } from 'viem/ens'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const ensAddress = await client.getEnsAddress({
  name: normalize('wevm.eth'),
})
// '0xd2135CfB216b74109775236E36d4b433F1DF507B'

getEnsAvatar()

getEnsAvatar: (args) => Promise<GetEnsAvatarReturnType>

Gets the avatar of an ENS name.

Parameters

• args

GetEnsAvatarParameters

• args.assetGatewayUrls?: AssetGatewayUrls

Gateway urls to resolve IPFS and/or Arweave assets.

• args.blockNumber?: bigint

The balance of the account at a block number.

• args.blockTag?: BlockTag

The balance of the account at a block tag.

Default

'latest'

• args.gatewayUrls?: string[]

Universal Resolver gateway URLs to use for resolving CCIP-read requests.

• args.name: string

ENS name to get Text for.

• args.strict?: boolean

Whether or not to throw errors propagated from the ENS Universal Resolver Contract.

• args.universalResolverAddress?: `0x${string}`

Address of ENS Universal Resolver Contract.

Returns

Promise<GetEnsAvatarReturnType>

Avatar URI or null if not found. GetEnsAvatarReturnType

Remarks

Calls getEnsText with key set to 'avatar'.

Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to normalize ENS names with UTS-46 normalization before passing them to getEnsAddress. You can use the built-in normalize function for this.

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { normalize } from 'viem/ens'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const ensAvatar = await client.getEnsAvatar({
  name: normalize('wevm.eth'),
})
// 'https://ipfs.io/ipfs/Qma8mnp6xV3J2cRNf3mTth5C8nV11CAnceVinc3y8jSbio'

getEnsName()

getEnsName: (args) => Promise<GetEnsNameReturnType>

Gets primary name for specified address.

Parameters

• args

GetEnsNameParameters

• args.address: `0x${string}`

Address to get ENS name for.

• args.blockNumber?: bigint

The balance of the account at a block number.

• args.blockTag?: BlockTag

The balance of the account at a block tag.

Default

'latest'

• args.gatewayUrls?: string[]

Universal Resolver gateway URLs to use for resolving CCIP-read requests.

• args.strict?: boolean

Whether or not to throw errors propagated from the ENS Universal Resolver Contract.

• args.universalResolverAddress?: `0x${string}`

Address of ENS Universal Resolver Contract.

Returns

Promise<GetEnsNameReturnType>

Name or null if not found. GetEnsNameReturnType

Remarks

Calls reverse(bytes) on ENS Universal Resolver Contract to “reverse resolve” the address to the primary ENS name.

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const ensName = await client.getEnsName({
  address: '0xd2135CfB216b74109775236E36d4b433F1DF507B',
})
// 'wevm.eth'

getEnsResolver()

getEnsResolver: (args) => Promise<`0x${string}`>

Gets resolver for ENS name.

Parameters

• args

GetEnsResolverParameters

• args.blockNumber?: bigint

The balance of the account at a block number.

• args.blockTag?: BlockTag

The balance of the account at a block tag.

Default

'latest'

• args.name: string

Name to get the address for.

• args.universalResolverAddress?: `0x${string}`

Address of ENS Universal Resolver Contract.

Returns

Promise<`0x${string}`>

Address for ENS resolver. GetEnsResolverReturnType

Remarks

Calls findResolver(bytes) on ENS Universal Resolver Contract to retrieve the resolver of an ENS name.

Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to normalize ENS names with UTS-46 normalization before passing them to getEnsAddress. You can use the built-in normalize function for this.

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { normalize } from 'viem/ens'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const resolverAddress = await client.getEnsResolver({
  name: normalize('wevm.eth'),
})
// '0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41'

getEnsText()

getEnsText: (args) => Promise<GetEnsTextReturnType>

Gets a text record for specified ENS name.

Parameters

• args

GetEnsTextParameters

• args.blockNumber?: bigint

The balance of the account at a block number.

• args.blockTag?: BlockTag

The balance of the account at a block tag.

Default

'latest'

• args.gatewayUrls?: string[]

Universal Resolver gateway URLs to use for resolving CCIP-read requests.

• args.key: string

Text record to retrieve.

• args.name: string

ENS name to get Text for.

• args.strict?: boolean

Whether or not to throw errors propagated from the ENS Universal Resolver Contract.

• args.universalResolverAddress?: `0x${string}`

Address of ENS Universal Resolver Contract.

Returns

Promise<GetEnsTextReturnType>

Address for ENS resolver. GetEnsTextReturnType

Remarks

Calls resolve(bytes, bytes) on ENS Universal Resolver Contract.

Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to normalize ENS names with UTS-46 normalization before passing them to getEnsAddress. You can use the built-in normalize function for this.

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { normalize } from 'viem/ens'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const twitterRecord = await client.getEnsText({
  name: normalize('wevm.eth'),
  key: 'com.twitter',
})
// 'wevm_dev'

getFeeHistory()

getFeeHistory: (args) => Promise<GetFeeHistoryReturnType>

Returns a collection of historical gas information.

Parameters

• args: GetFeeHistoryParameters

GetFeeHistoryParameters

Returns

Promise<GetFeeHistoryReturnType>

The gas estimate (in wei). GetFeeHistoryReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const feeHistory = await client.getFeeHistory({
  blockCount: 4,
  rewardPercentiles: [25, 75],
})

getFilterChanges()

getFilterChanges: <filterType, abi, eventName, strict, fromBlock, toBlock>(args) => Promise<GetFilterChangesReturnType<filterType, abi, eventName, strict, fromBlock, toBlock>>

Returns a list of logs or hashes based on a Filter since the last time it was called.

Type Parameters

• filterType extends FilterType

• abi extends undefined | Abi | readonly unknown[]

• eventName extends undefined | string

• strict extends undefined | boolean = undefined

• fromBlock extends undefined | bigint | BlockTag = undefined

• toBlock extends undefined | bigint | BlockTag = undefined

Parameters

• args: GetFilterChangesParameters<filterType, abi, eventName, strict, fromBlock, toBlock>

GetFilterChangesParameters

Returns

Promise<GetFilterChangesReturnType<filterType, abi, eventName, strict, fromBlock, toBlock>>

Logs or hashes. GetFilterChangesReturnType

Remarks

A Filter can be created from the following actions:

Depending on the type of filter, the return value will be different:

  • If the filter was created with createContractEventFilter or createEventFilter, it returns a list of logs.
  • If the filter was created with createPendingTransactionFilter, it returns a list of transaction hashes.
  • If the filter was created with createBlockFilter, it returns a list of block hashes.

Examples

// Blocks
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createBlockFilter()
const hashes = await client.getFilterChanges({ filter })
// Contract Events
import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createContractEventFilter({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  abi: parseAbi(['event Transfer(address indexed, address indexed, uint256)']),
  eventName: 'Transfer',
})
const logs = await client.getFilterChanges({ filter })
// Raw Events
import { createPublicClient, http, parseAbiItem } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createEventFilter({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  event: parseAbiItem('event Transfer(address indexed, address indexed, uint256)'),
})
const logs = await client.getFilterChanges({ filter })
// Transactions
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createPendingTransactionFilter()
const hashes = await client.getFilterChanges({ filter })

getFilterLogs()

getFilterLogs: <abi, eventName, strict, fromBlock, toBlock>(args) => Promise<GetFilterLogsReturnType<abi, eventName, strict, fromBlock, toBlock>>

Returns a list of event logs since the filter was created.

Type Parameters

• abi extends undefined | Abi | readonly unknown[]

• eventName extends undefined | string

• strict extends undefined | boolean = undefined

• fromBlock extends undefined | bigint | BlockTag = undefined

• toBlock extends undefined | bigint | BlockTag = undefined

Parameters

• args: GetFilterLogsParameters<abi, eventName, strict, fromBlock, toBlock>

GetFilterLogsParameters

Returns

Promise<GetFilterLogsReturnType<abi, eventName, strict, fromBlock, toBlock>>

A list of event logs. GetFilterLogsReturnType

Remarks

getFilterLogs is only compatible with event filters.

Example

import { createPublicClient, http, parseAbiItem } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createEventFilter({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  event: parseAbiItem('event Transfer(address indexed, address indexed, uint256)'),
})
const logs = await client.getFilterLogs({ filter })

getGasPrice()

getGasPrice: () => Promise<bigint>

Returns the current price of gas (in wei).

Returns

Promise<bigint>

The gas price (in wei). GetGasPriceReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const gasPrice = await client.getGasPrice()

getLogs()

getLogs: <abiEvent, abiEvents, strict, fromBlock, toBlock>(args?) => Promise<GetLogsReturnType<abiEvent, abiEvents, strict, fromBlock, toBlock>>

Returns a list of event logs matching the provided parameters.

Type Parameters

• abiEvent extends undefined | AbiEvent = undefined

• abiEvents extends undefined | readonly unknown[] | readonly AbiEvent[] = abiEvent extends AbiEvent ? [abiEvent<abiEvent>] : undefined

• strict extends undefined | boolean = undefined

• fromBlock extends undefined | bigint | BlockTag = undefined

• toBlock extends undefined | bigint | BlockTag = undefined

Parameters

• args?: GetLogsParameters<abiEvent, abiEvents, strict, fromBlock, toBlock>

GetLogsParameters

Returns

Promise<GetLogsReturnType<abiEvent, abiEvents, strict, fromBlock, toBlock>>

A list of event logs. GetLogsReturnType

Example

import { createPublicClient, http, parseAbiItem } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const logs = await client.getLogs()

getPermissions()

getPermissions: () => Promise<GetPermissionsReturnType>

Gets the wallets current permissions.

Returns

Promise<GetPermissionsReturnType>

The wallet permissions. GetPermissionsReturnType

Example

import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
const permissions = await client.getPermissions()

getProof()

getProof: (args) => Promise<GetProofReturnType>

Returns the account and storage values of the specified account including the Merkle-proof.

Parameters

• args: GetProofParameters

Returns

Promise<GetProofReturnType>

Proof data. GetProofReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const block = await client.getProof({
 address: '0x...',
 storageKeys: ['0x...'],
})

getStorageAt()

getStorageAt: (args) => Promise<GetStorageAtReturnType>

Returns the value from a storage slot at a given address.

Parameters

• args: GetStorageAtParameters

GetStorageAtParameters

Returns

Promise<GetStorageAtReturnType>

The value of the storage slot. GetStorageAtReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { getStorageAt } from 'viem/contract'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const code = await client.getStorageAt({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  slot: toHex(0),
})

getTransaction()

getTransaction: <blockTag>(args) => Promise<{ [K in string | number | symbol]: FormattedTransaction<TCommon, blockTag>[K] }>

Returns information about a Transaction given a hash or block identifier.

Type Parameters

• blockTag extends BlockTag = "latest"

Parameters

• args: GetTransactionParameters<blockTag>

GetTransactionParameters

Returns

Promise<{ [K in string | number | symbol]: FormattedTransaction<TCommon, blockTag>[K] }>

The transaction information. GetTransactionReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const transaction = await client.getTransaction({
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})

getTransactionConfirmations()

getTransactionConfirmations: (args) => Promise<bigint>

Returns the number of blocks passed (confirmations) since the transaction was processed on a block.

Parameters

• args: GetTransactionConfirmationsParameters<TCommon>

GetTransactionConfirmationsParameters

Returns

Promise<bigint>

The number of blocks passed since the transaction was processed. If confirmations is 0, then the Transaction has not been confirmed & processed yet. GetTransactionConfirmationsReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const confirmations = await client.getTransactionConfirmations({
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})

getTransactionCount()

getTransactionCount: (args) => Promise<number>

Returns the number of Transactions an Account has broadcast / sent.

Parameters

• args: GetTransactionCountParameters

GetTransactionCountParameters

Returns

Promise<number>

The number of transactions an account has sent. GetTransactionCountReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const transactionCount = await client.getTransactionCount({
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
})

getTransactionReceipt()

getTransactionReceipt: (args) => Promise<ExtractChainFormatterReturnType<TCommon, "transactionReceipt", TransactionReceipt>>

Returns the Transaction Receipt given a Transaction hash.

Parameters

• args: GetTransactionReceiptParameters

GetTransactionReceiptParameters

Returns

Promise<ExtractChainFormatterReturnType<TCommon, "transactionReceipt", TransactionReceipt>>

The transaction receipt. GetTransactionReceiptReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const transactionReceipt = await client.getTransactionReceipt({
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})

getTxpoolContent()

getTxpoolContent: () => Promise<GetTxpoolContentReturnType>

Returns the details of all transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only.

Returns

Promise<GetTxpoolContentReturnType>

Transaction pool content. GetTxpoolContentReturnType

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
const content = await client.getTxpoolContent()

getTxpoolStatus()

getTxpoolStatus: () => Promise<GetTxpoolStatusReturnType>

Returns a summary of all the transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only.

Returns

Promise<GetTxpoolStatusReturnType>

Transaction pool status. GetTxpoolStatusReturnType

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
const status = await client.getTxpoolStatus()

impersonateAccount()

impersonateAccount: (args) => Promise<void>

Impersonate an account or contract address. This lets you send transactions from that account even if you don’t have access to its private key.

Parameters

• args: ImpersonateAccountParameters

ImpersonateAccountParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.impersonateAccount({
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
})

increaseTime()

increaseTime: (args) => Promise<`0x${string}`>

Jump forward in time by the given amount of time, in seconds.

Parameters

• args: IncreaseTimeParameters

– IncreaseTimeParameters

Returns

Promise<`0x${string}`>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.increaseTime({
  seconds: 420,
})

inspectTxpool()

inspectTxpool: () => Promise<InspectTxpoolReturnType>

Returns a summary of all the transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only.

Returns

Promise<InspectTxpoolReturnType>

Transaction pool inspection data. InspectTxpoolReturnType

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
const data = await client.inspectTxpool()

key

key: string

A key for the client.

loadState()

loadState: (args) => Promise<void>

Adds state previously dumped with dumpState to the current chain.

Parameters

• args: LoadStateParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.loadState({ state: '0x...' })

mine()

mine: (args) => Promise<void>

Mine a specified number of blocks.

Parameters

• args: MineParameters

– MineParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.mine({ blocks: 1 })

multicall()

multicall: <contracts, allowFailure>(args) => Promise<MulticallReturnType<contracts, allowFailure>>

Similar to readContract, but batches up multiple functions on a contract in a single RPC call via the multicall3 contract.

Type Parameters

• contracts extends readonly unknown[]

• allowFailure extends boolean = true

Parameters

• args: MulticallParameters<contracts, allowFailure>

MulticallParameters

Returns

Promise<MulticallReturnType<contracts, allowFailure>>

An array of results with accompanying status. MulticallReturnType

Example

import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const abi = parseAbi([
  'function balanceOf(address) view returns (uint256)',
  'function totalSupply() view returns (uint256)',
])
const result = await client.multicall({
  contracts: [
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
      abi,
      functionName: 'balanceOf',
      args: ['0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'],
    },
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
      abi,
      functionName: 'totalSupply',
    },
  ],
})
// [{ result: 424122n, status: 'success' }, { result: 1000000n, status: 'success' }]

name

name: string

A name for the client.

pollingInterval

pollingInterval: number

Frequency (in ms) for polling enabled actions & events. Defaults to 4_000 milliseconds.

prepareTransactionRequest

prepareTransactionRequest: <request, chainOverride, accountOverride>(args) => Promise<{ [K in string | number | symbol]: (UnionRequiredBy<Extract<(…) & (…) & (…), (…) extends (…) ? (…) : (…)> & Object, ParameterTypeToParameters<(…)[(…)] extends readonly (…)[] ? (…)[(…)] : (…) | (…) | (…) | (…) | (…) | (…)>> & (unknown extends request[“kzg”] ? Object : Pick<request, “kzg”>))[K] }> & <request, chainOverride, accountOverride>(args) => Promise<{ [K in string | number | symbol]: (UnionRequiredBy<Extract<(…) & (…) & (…), (…) extends (…) ? (…) : (…)> & Object, ParameterTypeToParameters<(…)[(…)] extends readonly (…)[] ? (…)[(…)] : (…) | (…) | (…) | (…) | (…) | (…)>> & (unknown extends request[“kzg”] ? Object : Pick<request, “kzg”>))[K] }>

Prepares a transaction request for signing.

Param

PrepareTransactionRequestParameters

Examples

import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
const request = await client.prepareTransactionRequest({
  account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  to: '0x0000000000000000000000000000000000000000',
  value: 1n,
})
// Account Hoisting
import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  account: privateKeyToAccount('0x…'),
  chain: mainnet,
  transport: custom(window.ethereum),
})
const request = await client.prepareTransactionRequest({
  to: '0x0000000000000000000000000000000000000000',
  value: 1n,
})

readContract()

readContract: <abi, functionName, args>(args) => Promise<ReadContractReturnType<abi, functionName, args>>

Calls a read-only function on a contract, and returns the response.

Type Parameters

• abi extends Abi | readonly unknown[]

• functionName extends string

• args extends unknown

Parameters

• args: ReadContractParameters<abi, functionName, args>

ReadContractParameters

Returns

Promise<ReadContractReturnType<abi, functionName, args>>

The response from the contract. Type is inferred. ReadContractReturnType

Remarks

A “read-only” function (constant function) on a Solidity contract is denoted by a view or pure keyword. They can only read the state of the contract, and cannot make any changes to it. Since read-only methods do not change the state of the contract, they do not require any gas to be executed, and can be called by any user without the need to pay for gas.

Internally, uses a Public Client to call the call action with ABI-encoded data.

Example

import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'
import { readContract } from 'viem/contract'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const result = await client.readContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: parseAbi(['function balanceOf(address) view returns (uint256)']),
  functionName: 'balanceOf',
  args: ['0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'],
})
// 424122n

removeBlockTimestampInterval()

removeBlockTimestampInterval: () => Promise<void>

Removes setBlockTimestampInterval if it exists.

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'
import { removeBlockTimestampInterval } from 'viem/test'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.removeBlockTimestampInterval()

request

request: EIP1193RequestFn<[object, object, object, object, object]>

Request function wrapped with friendly error handling

requestAddresses()

requestAddresses: () => Promise<RequestAddressesReturnType>

Requests a list of accounts managed by a wallet.

Sends a request to the wallet, asking for permission to access the user’s accounts. After the user accepts the request, it will return a list of accounts (addresses).

This API can be useful for dapps that need to access the user’s accounts in order to execute transactions or interact with smart contracts.

Returns

Promise<RequestAddressesReturnType>

List of accounts managed by a wallet RequestAddressesReturnType

Example

import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
const accounts = await client.requestAddresses()

requestPermissions()

requestPermissions: (args) => Promise<RequestPermissionsReturnType>

Requests permissions for a wallet.

Parameters

• args

RequestPermissionsParameters

• args.eth_accounts: Record<string, any>

Returns

Promise<RequestPermissionsReturnType>

The wallet permissions. RequestPermissionsReturnType

Example

import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
const permissions = await client.requestPermissions({
  eth_accounts: {}
})

reset()

reset: (args?) => Promise<void>

Resets fork back to its original state.

Parameters

• args?: ResetParameters

– ResetParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.reset({ blockNumber: 69420n })

revert()

revert: (args) => Promise<void>

Revert the state of the blockchain at the current block.

Parameters

• args: RevertParameters

– RevertParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.revert({ id: '0x…' })

sendRawTransaction

sendRawTransaction: (args) => Promise<`0x${string}`> & (args) => Promise<`0x${string}`>

Sends a signed transaction to the network

Param

Client to use

Param

SendRawTransactionParameters

Example

import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'
import { sendRawTransaction } from 'viem/wallet'


const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})


const hash = await client.sendRawTransaction({
  serializedTransaction: '0x02f850018203118080825208808080c080a04012522854168b27e5dc3d5839bab5e6b39e1a0ffd343901ce1622e3d64b48f1a04e00902ae0502c4728cbf12156290df99c3ed7de85b1dbfe20b5c36931733a33'
})

sendTransaction()

sendTransaction: <request, chainOverride>(args) => Promise<`0x${string}`>

Creates, signs, and sends a new transaction to the network.

Type Parameters

• request extends Omit<object, "from"> | Omit<object, "from"> | Omit<object, "from"> | Omit<object, "from"> | Omit<object, "from"> & object

• chainOverride extends undefined | Chain = undefined

Parameters

• args: SendTransactionParameters<TCommon, TAccountOrAddress extends Account ? Account : undefined, chainOverride, request>

SendTransactionParameters

Returns

Promise<`0x${string}`>

The Transaction hash. SendTransactionReturnType

Examples

import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
const hash = await client.sendTransaction({
  account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
  value: 1000000000000000000n,
})
// Account Hoisting
import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  account: privateKeyToAccount('0x…'),
  chain: mainnet,
  transport: http(),
})
const hash = await client.sendTransaction({
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
  value: 1000000000000000000n,
})

sendUnsignedTransaction()

sendUnsignedTransaction: <chain>(args) => Promise<`0x${string}`>

Returns the details of all transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only.

Type Parameters

• chain extends undefined | Chain

Parameters

• args: SendUnsignedTransactionParameters<chain>

– SendUnsignedTransactionParameters

Returns

Promise<`0x${string}`>

The transaction hash. SendUnsignedTransactionReturnType

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
const hash = await client.sendUnsignedTransaction({
  from: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
  value: 1000000000000000000n,
})

setAutomine()

setAutomine: (args) => Promise<void>

Enables or disables the automatic mining of new blocks with each new transaction submitted to the network.

Parameters

• args: boolean

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.setAutomine()

setBalance()

setBalance: (args) => Promise<void>

Modifies the balance of an account.

Parameters

• args: SetBalanceParameters

– SetBalanceParameters

Returns

Promise<void>

Example

import { createTestClient, http, parseEther } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.setBalance({
  address: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  value: parseEther('1'),
})

setBlockGasLimit()

setBlockGasLimit: (args) => Promise<void>

Sets the block’s gas limit.

Parameters

• args: SetBlockGasLimitParameters

– SetBlockGasLimitParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.setBlockGasLimit({ gasLimit: 420_000n })

setBlockTimestampInterval()

setBlockTimestampInterval: (args) => Promise<void>

Similar to increaseTime, but sets a block timestamp interval. The timestamp of future blocks will be computed as lastBlock_timestamp + interval.

Parameters

• args: SetBlockTimestampIntervalParameters

– SetBlockTimestampIntervalParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.setBlockTimestampInterval({ interval: 5 })

setCode()

setCode: (args) => Promise<void>

Modifies the bytecode stored at an account’s address.

Parameters

• args: SetCodeParameters

– SetCodeParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.setCode({
  address: '0xe846c6fcf817734ca4527b28ccb4aea2b6663c79',
  bytecode: '0x60806040526000600355600019600955600c80546001600160a01b031916737a250d5630b4cf539739df…',
})

setCoinbase()

setCoinbase: (args) => Promise<void>

Sets the coinbase address to be used in new blocks.

Parameters

• args: SetCoinbaseParameters

– SetCoinbaseParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.setCoinbase({
  address: '0xe846c6fcf817734ca4527b28ccb4aea2b6663c79',
})

setIntervalMining()

setIntervalMining: (args) => Promise<void>

Sets the automatic mining interval (in seconds) of blocks. Setting the interval to 0 will disable automatic mining.

Parameters

• args: SetIntervalMiningParameters

– SetIntervalMiningParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.setIntervalMining({ interval: 5 })

setLoggingEnabled()

setLoggingEnabled: (args) => Promise<void>

Enable or disable logging on the test node network.

Parameters

• args: boolean

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.setLoggingEnabled()

setMinGasPrice()

setMinGasPrice: (args) => Promise<void>

Change the minimum gas price accepted by the network (in wei).

Note: setMinGasPrice can only be used on clients that do not have EIP-1559 enabled.

Parameters

• args: SetMinGasPriceParameters

– SetBlockGasLimitParameters

Returns

Promise<void>

Example

import { createTestClient, http, parseGwei } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.setMinGasPrice({
  gasPrice: parseGwei('20'),
})

setNextBlockBaseFeePerGas()

setNextBlockBaseFeePerGas: (args) => Promise<void>

Sets the next block’s base fee per gas.

Parameters

• args: SetNextBlockBaseFeePerGasParameters

– SetNextBlockBaseFeePerGasParameters

Returns

Promise<void>

Example

import { createTestClient, http, parseGwei } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.setNextBlockBaseFeePerGas({
  baseFeePerGas: parseGwei('20'),
})

setNextBlockTimestamp()

setNextBlockTimestamp: (args) => Promise<void>

Sets the next block’s timestamp.

Parameters

• args: SetNextBlockTimestampParameters

– SetNextBlockTimestampParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.setNextBlockTimestamp({ timestamp: 1671744314n })

setNonce()

setNonce: (args) => Promise<void>

Modifies (overrides) the nonce of an account.

Parameters

• args: SetNonceParameters

– SetNonceParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.setNonce({
  address: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  nonce: 420,
})

setRpcUrl()

setRpcUrl: (args) => Promise<void>

Sets the backend RPC URL.

Parameters

• args: string

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.setRpcUrl('https://eth-mainnet.g.alchemy.com/v2')

setStorageAt()

setStorageAt: (args) => Promise<void>

Writes to a slot of an account’s storage.

Parameters

• args: SetStorageAtParameters

– SetStorageAtParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.setStorageAt({
  address: '0xe846c6fcf817734ca4527b28ccb4aea2b6663c79',
  index: 2,
  value: '0x0000000000000000000000000000000000000000000000000000000000000069',
})

signMessage()

signMessage: (args) => Promise<`0x${string}`>

Calculates an Ethereum-specific signature in EIP-191 format: keccak256("\x19Ethereum Signed Message:\n" + len(message) + message)).

With the calculated signature, you can:

Parameters

• args: SignMessageParameters<TAccountOrAddress extends Account ? Account : undefined>

SignMessageParameters

Returns

Promise<`0x${string}`>

The signed message. SignMessageReturnType

Examples

import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
const signature = await client.signMessage({
  account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  message: 'hello world',
})
// Account Hoisting
import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  account: privateKeyToAccount('0x…'),
  chain: mainnet,
  transport: http(),
})
const signature = await client.signMessage({
  message: 'hello world',
})

signTransaction()

signTransaction: <chainOverride>(args) => Promise<`0x02${string}` | `0x01${string}` | `0x03${string}` | `0x04${string}` | TransactionSerializedLegacy>

Signs a transaction.

Type Parameters

• chainOverride extends undefined | Chain

Parameters

• args: SignTransactionParameters<TCommon, TAccountOrAddress extends Account ? Account : undefined, chainOverride>

SignTransactionParameters

Returns

Promise<`0x02${string}` | `0x01${string}` | `0x03${string}` | `0x04${string}` | TransactionSerializedLegacy>

The signed message. SignTransactionReturnType

Examples

import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
const request = await client.prepareTransactionRequest({
  account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  to: '0x0000000000000000000000000000000000000000',
  value: 1n,
})
const signature = await client.signTransaction(request)
// Account Hoisting
import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  account: privateKeyToAccount('0x…'),
  chain: mainnet,
  transport: custom(window.ethereum),
})
const request = await client.prepareTransactionRequest({
  to: '0x0000000000000000000000000000000000000000',
  value: 1n,
})
const signature = await client.signTransaction(request)

signTypedData()

signTypedData: <typedData, primaryType>(args) => Promise<`0x${string}`>

Signs typed data and calculates an Ethereum-specific signature in EIP-191 format: keccak256("\x19Ethereum Signed Message:\n" + len(message) + message)).

Type Parameters

• typedData extends object | object

• primaryType extends string

Parameters

• args: SignTypedDataParameters<typedData, primaryType, TAccountOrAddress extends Account ? Account : undefined>

SignTypedDataParameters

Returns

Promise<`0x${string}`>

The signed data. SignTypedDataReturnType

Examples

import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
const signature = await client.signTypedData({
  account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  domain: {
    name: 'Ether Mail',
    version: '1',
    chainId: 1,
    verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC',
  },
  types: {
    Person: [
      { name: 'name', type: 'string' },
      { name: 'wallet', type: 'address' },
    ],
    Mail: [
      { name: 'from', type: 'Person' },
      { name: 'to', type: 'Person' },
      { name: 'contents', type: 'string' },
    ],
  },
  primaryType: 'Mail',
  message: {
    from: {
      name: 'Cow',
      wallet: '0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826',
    },
    to: {
      name: 'Bob',
      wallet: '0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB',
    },
    contents: 'Hello, Bob!',
  },
})
// Account Hoisting
import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  account: privateKeyToAccount('0x…'),
  chain: mainnet,
  transport: http(),
})
const signature = await client.signTypedData({
  domain: {
    name: 'Ether Mail',
    version: '1',
    chainId: 1,
    verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC',
  },
  types: {
    Person: [
      { name: 'name', type: 'string' },
      { name: 'wallet', type: 'address' },
    ],
    Mail: [
      { name: 'from', type: 'Person' },
      { name: 'to', type: 'Person' },
      { name: 'contents', type: 'string' },
    ],
  },
  primaryType: 'Mail',
  message: {
    from: {
      name: 'Cow',
      wallet: '0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826',
    },
    to: {
      name: 'Bob',
      wallet: '0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB',
    },
    contents: 'Hello, Bob!',
  },
})

simulateContract()

simulateContract: <abi, functionName, args, chainOverride, accountOverride>(args) => Promise<SimulateContractReturnType<abi, functionName, args, TCommon, TAccountOrAddress extends Account ? Account : undefined, chainOverride, accountOverride>>

Simulates/validates a contract interaction. This is useful for retrieving return data and revert reasons of contract write functions.

Type Parameters

• abi extends Abi | readonly unknown[]

• functionName extends string

• args extends unknown

• chainOverride extends undefined | Chain

• accountOverride extends undefined | `0x${string}` | Account = undefined

Parameters

• args: SimulateContractParameters<abi, functionName, args, TCommon, chainOverride, accountOverride>

SimulateContractParameters

Returns

Promise<SimulateContractReturnType<abi, functionName, args, TCommon, TAccountOrAddress extends Account ? Account : undefined, chainOverride, accountOverride>>

The simulation result and write request. SimulateContractReturnType

Remarks

This function does not require gas to execute and does not change the state of the blockchain. It is almost identical to readContract, but also supports contract write functions.

Internally, uses a Public Client to call the call action with ABI-encoded data.

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const result = await client.simulateContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: parseAbi(['function mint(uint32) view returns (uint32)']),
  functionName: 'mint',
  args: ['69420'],
  account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
})

snapshot()

snapshot: () => Promise<`0x${string}`>

Snapshot the state of the blockchain at the current block.

Returns

Promise<`0x${string}`>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'
import { snapshot } from 'viem/test'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.snapshot()

stopImpersonatingAccount()

stopImpersonatingAccount: (args) => Promise<void>

Stop impersonating an account after having previously used impersonateAccount.

Parameters

• args: StopImpersonatingAccountParameters

– StopImpersonatingAccountParameters

Returns

Promise<void>

Example

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'
import { stopImpersonatingAccount } from 'viem/test'


const client = createTestClient({
  mode: 'anvil',
  chain: 'foundry',
  transport: http(),
})
await client.stopImpersonatingAccount({
  address: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
})

switchChain()

switchChain: (args) => Promise<void>

Switch the target chain in a wallet.

Parameters

• args: SwitchChainParameters

SwitchChainParameters

Returns

Promise<void>

Example

import { createWalletClient, custom } from 'viem'
import { mainnet, optimism } from 'viem/chains'


const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
await client.switchChain({ id: optimism.id })

tevm

tevm: object & EIP1193Events & object & Eip1193RequestProvider

Low level access to TEVM can be accessed via tevm. These APIs are not guaranteed to be stable.

Type declaration

deepCopy()

readonly deepCopy: () => Promise<TevmNode<"fork" | "normal", object>>

Copies the current client state into a new client

Returns

Promise<TevmNode<"fork" | "normal", object>>

extend()

readonly extend: <TExtension>(decorator) => TevmNode<"fork" | "normal", object & TExtension>

Extends the base client with additional functionality. This enables optimal code splitting and extensibility

Type Parameters

• TExtension extends Record<string, any>

Parameters

• decorator

Returns

TevmNode<"fork" | "normal", object & TExtension>

forkTransport?

readonly optional forkTransport: object

Client to make json rpc requests to a forked node

Example
const client = createMemoryClient({ request: eip1193RequestFn })
forkTransport.request

forkTransport.request: EIP1193RequestFn

getFilters()

readonly getFilters: () => Map<`0x${string}`, Filter>

Gets all registered filters mapped by id

Returns

Map<`0x${string}`, Filter>

getImpersonatedAccount()

readonly getImpersonatedAccount: () => undefined | `0x${string}`

The currently impersonated account. This is only used in fork mode

Returns

undefined | `0x${string}`

getReceiptsManager()

readonly getReceiptsManager: () => Promise<ReceiptsManager>

Interface for querying receipts and historical state

Returns

Promise<ReceiptsManager>

getTxPool()

readonly getTxPool: () => Promise<TxPool>

Gets the pool of pending transactions to be included in next block

Returns

Promise<TxPool>

getVm()

readonly getVm: () => Promise<Vm>

Internal instance of the VM. Can be used for lower level operations. Normally not recomended to use unless building libraries or extensions on top of Tevm.

Returns

Promise<Vm>

logger

readonly logger: Logger

The logger instance

miningConfig

readonly miningConfig: MiningConfig

The configuration for mining. Defaults to ‘auto’

  • ‘auto’ will mine a block on every transaction
  • ‘interval’ will mine a block every interval milliseconds
  • ‘manual’ will not mine a block automatically and requires a manual call to mineBlock
mode

readonly mode: "fork" | "normal"

The mode the current client is running in fork mode will fetch and cache all state from the block forked from the provided URL normal mode will not fetch any state and will only run the EVM in memory

Example
let client = createMemoryClient()
console.log(client.mode) // 'normal'
client = createMemoryClient({ forkUrl: 'https://mainnet.infura.io/v3/your-api-key' })
console.log(client.mode) // 'fork'
ready()

readonly ready: () => Promise<true>

Returns promise that resulves when the client is ready The client is usable without calling this method but may have extra latency on the first call from initialization

Returns

Promise<true>

Example
const client = createMemoryClient()
await client.ready()
removeFilter()

readonly removeFilter: (id) => void

Removes a filter by id

Parameters

• id: `0x${string}`

Returns

void

setFilter()

readonly setFilter: (filter) => void

Creates a new filter to watch for logs events and blocks

Parameters

• filter: Filter

Returns

void

setImpersonatedAccount()

readonly setImpersonatedAccount: (address) => void

Sets the account to impersonate. This will allow the client to act as if it is that account On Ethereum JSON_RPC endpoints. Pass in undefined to stop impersonating

Parameters

• address: undefined | `0x${string}`

Returns

void

status

status: "INITIALIZING" | "READY" | "SYNCING" | "MINING" | "STOPPED"

Returns status of the client

  • INITIALIZING: The client is initializing
  • READY: The client is ready to be used
  • SYNCING: The client is syncing with the forked node
  • MINING: The client is mining a block

Type declaration

emit()

Emit an event.

Parameters

• eventName: keyof EIP1193EventMap

The event name.

• …args: any[]

Arguments to pass to the event listeners.

Returns

boolean

True if the event was emitted, false otherwise.

See

TevmNode

Example

import { createMemoryClient } from 'tevm'


const memoryClient = createMemoryClient()


// low level access to the TEVM VM, blockchain, EVM, stateManager, mempool, receiptsManager and more are available
const vm = await memoryClient.tevm.getVm()
vm.runBlock(...)
const { blockchain, evm, stateManager } = vm
blockchain.addBlock(...)
evm.runCall(...)
stateManager.putAccount(...)


const mempool = await memoryClient.tevm.getTxPool()
const receiptsManager = await memoryClient.tevm.getReceiptsManager()

tevmCall

tevmCall: CallHandler

A powerful low level API for executing calls and sending transactions. See CallParams for options reference. See CallResult for return values reference. Remember, you must set createTransaction: true to send a transaction. Otherwise, it will be a call. You must also mine the transaction before it updates the canonical head state. This can be avoided by setting mining mode to auto when using createMemoryClient.

Example

import { createMemoryClient } from 'tevm'
import { ERC20 } from 'tevm/contract'


const client = createMemoryClient()


const token = ERC20.withAddress(`0x${'0721'.repeat(10)}`)


await client.setAccount(token)


const balance = await client.tevmCall({
  to: token.address,
  data: encodeFunctionData(token.read.balanceOf, [token.address]),
})

In addition to making basic calls, you can also do advanced things like:

  • Impersonate accounts via passing in from, caller, or origin
  • Set the call depth via depth
  • Create a trace or access list using createTrace: true or createAccessList: true
  • Send as a transaction with createTransaction: true For all options see CallParams

tevmContract

tevmContract: ContractHandler

A powerful low level API for calling contracts. Similar to tevmCall but takes care of encoding and decoding data, revert messages, etc. See ContractParams for options reference. See ContractResult for return values reference. Remember, you must set createTransaction: true to send a transaction. Otherwise, it will be a call. You must also mine the transaction before it updates the canonical head state. This can be avoided by setting mining mode to auto when using createMemoryClient.

Example

import { createMemoryClient } from 'tevm'
import { ERC20 } from './MyERC721.sol'


const client = createMemoryClient()
const token = ERC20.withAddress(`0x${'0721'.repeat(10)}`)
await client.setAccount(token)
const balance = await client.tevmContract({
  contract: token,
  method: token.read.balanceOf,
  args: [token.address],
})

In addition to making basic calls, you can also do advanced things like:

  • Impersonate accounts via passing in from, caller, or origin
  • Set the call depth via depth
  • Create a trace or access list using createTrace: true or createAccessList: true
  • Send as a transaction with createTransaction: true For all options see ContractParams

tevmDeploy

tevmDeploy: DeployHandler

Deploys a contract to the EVM with encoded constructor arguments. Extends tevmCall so it supports all advanced options.

See

  • DeployParams for options reference.
  • DeployResult for return values reference. Remember, you must set createTransaction: true to send a transaction. Otherwise, it will be a call. You must also mine the transaction before it updates the canonical head state. This can be avoided by setting mining mode to auto when using createMemoryClient.

Example

import { createMemoryClient } from 'tevm'
import { ERC20 } from './MyERC721.sol'


const client = createMemoryClient()
const token = ERC20.withAddress(`0x${'0721'.repeat(10)}`)


const deploymentResult = await client.tevmDeploy({
  abi: token.abi,
  bytecode: token.bytecode,
  args: ['TokenName', 18, 'SYMBOL'],
})


console.log(deploymentResult.createdAddress)

tevmDumpState

tevmDumpState: DumpStateHandler

Dumps a JSON serializable state from the EVM. This can be useful for persisting and restoring state between processes.

Example

import { createMemoryClient } from 'tevm'
import fs from 'fs'
const client = createMemoryClient()
const state = await client.tevmDumpState()
fs.writeFileSync('state.json', JSON.stringify(state))

tevmGetAccount

tevmGetAccount: GetAccountHandler

Gets the account state of an account. It does not return the storage state by default but can if returnStorage is set to true. In forked mode, the storage is only the storage TEVM has cached and may not represent all the on-chain storage.

See

Example

import { createMemoryClient } from 'tevm'


const client = createMemoryClient()


const account = await client.tevmGetAccount({
  address: `0x${'0000'.repeat(10)}`,
  returnStorage: true,
})

tevmLoadState

tevmLoadState: LoadStateHandler

Loads a JSON serializable state into the EVM. This can be useful for persisting and restoring state between processes.

Example

import { createMemoryClient } from 'tevm'
import fs from 'fs'


const client = createMemoryClient()


const state = fs.readFileSync('state.json', 'utf8')


await client.tevmLoadState(state)

tevmMine

tevmMine: MineHandler

Mines a new block with all pending transactions. In manual mode you must call this manually before the canonical head state is updated.

Example

import { createMemoryClient } from 'tevm'


const client = createMemoryClient()


await client.tevmMine()

tevmReady()

tevmReady: () => Promise<true>

Returns a promise that resolves when the TEVM is ready. This is not needed to explicitly be called as all actions will wait for the TEVM to be ready.

Returns

Promise<true>

Example

import { createMemoryClient } from 'tevm'


const client = createMemoryClient()


await client.tevmReady()

Same as calling client.tevm.ready()

tevmSetAccount

tevmSetAccount: SetAccountHandler

Sets any property of an account including its balance, nonce, contract deployedBytecode, contract state, and more.

See

Example

import { createMemoryClient, numberToHex } from 'tevm'
import { SimpleContract } from 'tevm/contract'


const client = createMemoryClient()


await client.tevmSetAccount({
  address: `0x${'0123'.repeat(10)}`,
  balance: 100n,
  nonce: 1n,
  deployedBytecode: SimpleContract.deployedBytecode,
  state: {
    [`0x${'0'.repeat(64)}`]: numberToHex(420n),
  }
})

transport

transport: TransportConfig<string> & object

The RPC transport

Type declaration

tevm

tevm: object & EIP1193Events & object & object

Type declaration
deepCopy()

readonly deepCopy: () => Promise<TevmNode<"fork" | "normal", object>>

Copies the current client state into a new client

Returns

Promise<TevmNode<"fork" | "normal", object>>

extend()

readonly extend: <TExtension>(decorator) => TevmNode<"fork" | "normal", object & TExtension>

Extends the base client with additional functionality. This enables optimal code splitting and extensibility

Type Parameters

• TExtension extends Record<string, any>

Parameters

• decorator

Returns

TevmNode<"fork" | "normal", object & TExtension>

forkTransport?

readonly optional forkTransport: object

Client to make json rpc requests to a forked node

Example
const client = createMemoryClient({ request: eip1193RequestFn })
forkTransport.request

forkTransport.request: EIP1193RequestFn

getFilters()

readonly getFilters: () => Map<`0x${string}`, Filter>

Gets all registered filters mapped by id

Returns

Map<`0x${string}`, Filter>

getImpersonatedAccount()

readonly getImpersonatedAccount: () => undefined | `0x${string}`

The currently impersonated account. This is only used in fork mode

Returns

undefined | `0x${string}`

getReceiptsManager()

readonly getReceiptsManager: () => Promise<ReceiptsManager>

Interface for querying receipts and historical state

Returns

Promise<ReceiptsManager>

getTxPool()

readonly getTxPool: () => Promise<TxPool>

Gets the pool of pending transactions to be included in next block

Returns

Promise<TxPool>

getVm()

readonly getVm: () => Promise<Vm>

Internal instance of the VM. Can be used for lower level operations. Normally not recomended to use unless building libraries or extensions on top of Tevm.

Returns

Promise<Vm>

logger

readonly logger: Logger

The logger instance

miningConfig

readonly miningConfig: MiningConfig

The configuration for mining. Defaults to ‘auto’

  • ‘auto’ will mine a block on every transaction
  • ‘interval’ will mine a block every interval milliseconds
  • ‘manual’ will not mine a block automatically and requires a manual call to mineBlock
mode

readonly mode: "fork" | "normal"

The mode the current client is running in fork mode will fetch and cache all state from the block forked from the provided URL normal mode will not fetch any state and will only run the EVM in memory

Example
let client = createMemoryClient()
console.log(client.mode) // 'normal'
client = createMemoryClient({ forkUrl: 'https://mainnet.infura.io/v3/your-api-key' })
console.log(client.mode) // 'fork'
ready()

readonly ready: () => Promise<true>

Returns promise that resulves when the client is ready The client is usable without calling this method but may have extra latency on the first call from initialization

Returns

Promise<true>

Example
const client = createMemoryClient()
await client.ready()
removeFilter()

readonly removeFilter: (id) => void

Removes a filter by id

Parameters

• id: `0x${string}`

Returns

void

setFilter()

readonly setFilter: (filter) => void

Creates a new filter to watch for logs events and blocks

Parameters

• filter: Filter

Returns

void

setImpersonatedAccount()

readonly setImpersonatedAccount: (address) => void

Sets the account to impersonate. This will allow the client to act as if it is that account On Ethereum JSON_RPC endpoints. Pass in undefined to stop impersonating

Parameters

• address: undefined | `0x${string}`

Returns

void

status

status: "INITIALIZING" | "READY" | "SYNCING" | "MINING" | "STOPPED"

Returns status of the client

  • INITIALIZING: The client is initializing
  • READY: The client is ready to be used
  • SYNCING: The client is syncing with the forked node
  • MINING: The client is mining a block
Type declaration
emit()

Emit an event.

Parameters

• eventName: keyof EIP1193EventMap

The event name.

• …args: any[]

Arguments to pass to the event listeners.

Returns

boolean

True if the event was emitted, false otherwise.

Type declaration
request

request: EIP1193RequestFn

type

type: string

The type of client.

uid

uid: string

A unique ID for the client.

uninstallFilter()

uninstallFilter: (args) => Promise<boolean>

Destroys a Filter that was created from one of the following Actions:

Parameters

• args: UninstallFilterParameters

UninstallFilterParameters

Returns

Promise<boolean>

A boolean indicating if the Filter was successfully uninstalled. UninstallFilterReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { createPendingTransactionFilter, uninstallFilter } from 'viem/public'


const filter = await client.createPendingTransactionFilter()
const uninstalled = await client.uninstallFilter({ filter })
// true

verifyMessage()

verifyMessage: (args) => Promise<boolean>

Verify that a message was signed by the provided address.

Compatible with Smart Contract Accounts & Externally Owned Accounts via ERC-6492.

Parameters

• args

• args.address: `0x${string}`

The address that signed the original message.

• args.blockNumber?: bigint

The balance of the account at a block number.

• args.blockTag?: BlockTag

The balance of the account at a block tag.

Default

'latest'

• args.factory?: `0x${string}`

• args.factoryData?: `0x${string}`

• args.message: SignableMessage

The message to be verified.

• args.signature: `0x${string}` | Uint8Array | Signature

The signature that was generated by signing the message with the address’s private key.

Returns

Promise<boolean>

Whether or not the signature is valid. VerifyMessageReturnType

verifySiweMessage()

verifySiweMessage: (args) => Promise<boolean>

Verifies EIP-4361 formatted message was signed.

Compatible with Smart Contract Accounts & Externally Owned Accounts via ERC-6492.

Parameters

• args

• args.address?: `0x${string}`

Ethereum address to check against.

• args.blockNumber?: bigint

The balance of the account at a block number.

• args.blockTag?: BlockTag

The balance of the account at a block tag.

Default

'latest'

• args.domain?: string

RFC 3986 authority to check against.

• args.message: string

EIP-4361 formatted message.

• args.nonce?: string

Random string to check against.

• args.scheme?: string

RFC 3986 URI scheme to check against.

• args.signature: `0x${string}`

Signature to check against.

• args.time?: Date

Current time to check optional expirationTime and notBefore fields.

Default

new Date()

Returns

Promise<boolean>

Whether or not the signature is valid. VerifySiweMessageReturnType

verifyTypedData()

verifyTypedData: (args) => Promise<boolean>

Verify that typed data was signed by the provided address.

Parameters

• args: VerifyTypedDataParameters

Returns

Promise<boolean>

Whether or not the signature is valid. VerifyTypedDataReturnType

waitForTransactionReceipt()

waitForTransactionReceipt: (args) => Promise<ExtractChainFormatterReturnType<TCommon, "transactionReceipt", TransactionReceipt>>

Waits for the Transaction to be included on a Block (one confirmation), and then returns the Transaction Receipt. If the Transaction reverts, then the action will throw an error.

Parameters

• args: WaitForTransactionReceiptParameters<TCommon>

WaitForTransactionReceiptParameters

Returns

Promise<ExtractChainFormatterReturnType<TCommon, "transactionReceipt", TransactionReceipt>>

The transaction receipt. WaitForTransactionReceiptReturnType

Remarks

The waitForTransactionReceipt action additionally supports Replacement detection (e.g. sped up Transactions).

Transactions can be replaced when a user modifies their transaction in their wallet (to speed up or cancel). Transactions are replaced when they are sent from the same nonce.

There are 3 types of Transaction Replacement reasons:

  • repriced: The gas price has been modified (e.g. different maxFeePerGas)
  • cancelled: The Transaction has been cancelled (e.g. value === 0n)
  • replaced: The Transaction has been replaced (e.g. different value or data)

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const transactionReceipt = await client.waitForTransactionReceipt({
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})

watchAsset()

watchAsset: (args) => Promise<boolean>

Adds an EVM chain to the wallet.

Parameters

• args: WatchAssetParams

WatchAssetParameters

Returns

Promise<boolean>

Boolean indicating if the token was successfully added. WatchAssetReturnType

Example

import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
const success = await client.watchAsset({
  type: 'ERC20',
  options: {
    address: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
    decimals: 18,
    symbol: 'WETH',
  },
})

watchBlockNumber()

watchBlockNumber: (args) => WatchBlockNumberReturnType

Watches and returns incoming block numbers.

Parameters

• args: WatchBlockNumberParameters

WatchBlockNumberParameters

Returns

WatchBlockNumberReturnType

A function that can be invoked to stop watching for new block numbers. WatchBlockNumberReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = await client.watchBlockNumber({
  onBlockNumber: (blockNumber) => console.log(blockNumber),
})

watchBlocks()

watchBlocks: <includeTransactions, blockTag>(args) => WatchBlocksReturnType

Watches and returns information for incoming blocks.

Type Parameters

• includeTransactions extends boolean = false

• blockTag extends BlockTag = "latest"

Parameters

• args: WatchBlocksParameters<TevmTransport, TCommon, includeTransactions, blockTag>

WatchBlocksParameters

Returns

WatchBlocksReturnType

A function that can be invoked to stop watching for new block numbers. WatchBlocksReturnType

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = await client.watchBlocks({
  onBlock: (block) => console.log(block),
})

watchContractEvent()

watchContractEvent: <abi, eventName, strict>(args) => WatchContractEventReturnType

Watches and returns emitted contract event logs.

Type Parameters

• abi extends Abi | readonly unknown[]

• eventName extends string

• strict extends undefined | boolean = undefined

Parameters

• args: WatchContractEventParameters<abi, eventName, strict, TevmTransport>

WatchContractEventParameters

Returns

WatchContractEventReturnType

A function that can be invoked to stop watching for new event logs. WatchContractEventReturnType

Remarks

This Action will batch up all the event logs found within the pollingInterval, and invoke them via onLogs.

watchContractEvent will attempt to create an Event Filter and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (e.g. eth_newFilter), then watchContractEvent will fall back to using getLogs instead.

Example

import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = client.watchContractEvent({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: parseAbi(['event Transfer(address indexed from, address indexed to, uint256 value)']),
  eventName: 'Transfer',
  args: { from: '0xc961145a54C96E3aE9bAA048c4F4D6b04C13916b' },
  onLogs: (logs) => console.log(logs),
})

watchEvent()

watchEvent: <abiEvent, abiEvents, strict>(args) => WatchEventReturnType

Watches and returns emitted Event Logs.

Type Parameters

• abiEvent extends undefined | AbiEvent = undefined

• abiEvents extends undefined | readonly unknown[] | readonly AbiEvent[] = abiEvent extends AbiEvent ? [abiEvent<abiEvent>] : undefined

• strict extends undefined | boolean = undefined

Parameters

• args: WatchEventParameters<abiEvent, abiEvents, strict, TevmTransport>

WatchEventParameters

Returns

WatchEventReturnType

A function that can be invoked to stop watching for new Event Logs. WatchEventReturnType

Remarks

This Action will batch up all the Event Logs found within the pollingInterval, and invoke them via onLogs.

watchEvent will attempt to create an Event Filter and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (e.g. eth_newFilter), then watchEvent will fall back to using getLogs instead.

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = client.watchEvent({
  onLogs: (logs) => console.log(logs),
})

watchPendingTransactions()

watchPendingTransactions: (args) => WatchPendingTransactionsReturnType

Watches and returns pending transaction hashes.

Parameters

• args: WatchPendingTransactionsParameters<TevmTransport>

WatchPendingTransactionsParameters

Returns

WatchPendingTransactionsReturnType

A function that can be invoked to stop watching for new pending transaction hashes. WatchPendingTransactionsReturnType

Remarks

This Action will batch up all the pending transactions found within the pollingInterval, and invoke them via onTransactions.

Example

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'


const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = await client.watchPendingTransactions({
  onTransactions: (hashes) => console.log(hashes),
})

writeContract()

writeContract: <abi, functionName, args, chainOverride>(args) => Promise<`0x${string}`>

Executes a write function on a contract.

A “write” function on a Solidity contract modifies the state of the blockchain. These types of functions require gas to be executed, and hence a Transaction is needed to be broadcast in order to change the state.

Internally, uses a Wallet Client to call the sendTransaction action with ABI-encoded data.

Warning: The write internally sends a transaction – it does not validate if the contract write will succeed (the contract may throw an error). It is highly recommended to simulate the contract write with contract.simulate before you execute it.

Type Parameters

• abi extends Abi | readonly unknown[]

• functionName extends string

• args extends unknown

• chainOverride extends undefined | Chain = undefined

Parameters

• args: WriteContractParameters<abi, functionName, args, TCommon, TAccountOrAddress extends Account ? Account : undefined, chainOverride>

WriteContractParameters

Returns

Promise<`0x${string}`>

A Transaction Hash. WriteContractReturnType

Examples

import { createWalletClient, custom, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
const hash = await client.writeContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: parseAbi(['function mint(uint32 tokenId) nonpayable']),
  functionName: 'mint',
  args: [69420],
})
// With Validation
import { createWalletClient, custom, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'


const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
const { request } = await client.simulateContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: parseAbi(['function mint(uint32 tokenId) nonpayable']),
  functionName: 'mint',
  args: [69420],
}
const hash = await client.writeContract(request)

Example

import { createMemoryClient } from "tevm";


const client = createMemoryClient({
  fork: {
    transport: http("https://mainnet.optimism.io")({}),
  },
});


const blockNumber = await client.getBlockNumber();
console.log(blockNumber);

See

Actions API

MemoryClient supports the following viem actions:

import { createMemoryClient } from "tevm";


const tevm = createMemoryClient();
await tevm.setAccount({ address: `0x${'01'.repeat(20)}`, balance: 100n });
import { createMemoryClient } from "tevm";


const tevm = createMemoryClient();
const bn = await tevm.getBlockNumber();
import { createMemoryClient } from "tevm";


const tevm = createMemoryClient();
await tevm.setBalance({ address: `0x${'01'.repeat(20)}`, balance: 100n });

Forking

To fork an existing network, pass an EIP-1193 transport to the fork.transport option with an optional block tag. When you fork, TEVM will pin the block tag and lazily cache state from the fork transport. It’s highly recommended to pass in a common object that matches the chain. This will increase the performance of forking with known values.

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


const forkedClient = createMemoryClient({
  fork: {
    transport: http("https://mainnet.optimism.io")({}),
    blockTag: '0xa6a63cd70fbbe396321ca6fe79e1b6735760c03538208b50d7e3a5dac5226435',
  },
  common: optimism,
});

The common object extends the viem chain interface with EVM-specific information. When using TEVM, you should also use tevm/common rather than viem/chains or use createCommon and pass in a viem chain.

Viem clients, including MemoryClient, are themselves EIP-1193 transports. This means you can fork a client with another client.

Mining Modes

TEVM supports two mining modes:

  • Manual: Using tevm.mine()
  • Auto: Automatically mines a block after every transaction.

TEVM state does not update until blocks are mined.

Using TEVM over HTTP

TEVM can be run as an HTTP server using @tevm/server to handle JSON-RPC requests.

import { createServer } from "tevm/server";
import { createMemoryClient } from "tevm";


const memoryClient = createMemoryClient();


const server = createServer({
  request: memoryClient.request,
});


server.listen(8545, () => console.log("listening on 8545"));

This allows you to use any Ethereum client to communicate with it, including a viem public client.

import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";


const publicClient = createPublicClient({
  chain: mainnet,
  transport: http("https://localhost:8545"),
});


console.log(await publicClient.getChainId());

State Persistence (Experimental)

It is possible to persist the TEVM client to a synchronous source using the persister option.

import { createMemoryClient, createSyncPersister } from "tevm";
import { createMemoryClient } from "tevm/sync-storage-persister";


// Client state will be hydrated and persisted from/to local storage
const clientWithLocalStoragePersistence = createMemoryClient({
  persister: createSyncPersister({
    storage: localStorage,
  }),
});

Network Support

TEVM guarantees support for the following networks:

  • Ethereum mainnet
  • Standard OP Stack chains

Other EVM chains are likely to work but do not officially carry support. More official chain support will be added in the near future.

Note: Optimism deposit transactions are not currently supported but will be in a future release. TEVM filters out these transactions from blocks.

Network and Hardfork Support

TEVM supports enabling and disabling different EIPs, but the following EIPs are always turned on:

  • 1559
  • 4895
  • 4844
  • 4788

Currently, only EIP-1559 Fee Market transactions are supported.

Tree Shakeable Actions

TEVM supports tree-shakeable actions using createTevmNode() and the tevm/actions package. If you are building a UI, you should use tree-shakeable actions to optimize bundle size. These are described in detail in the actions API guide.

Composing with TEVM Contracts and Bundler

MemoryClient can compose with TEVM contracts and the TEVM bundler. For more information, see the TEVM contracts guide and the TEVM Solidity imports guide.

import { createMemoryClient } from "tevm";
import { MyERC721 } from './MyERC721.sol';


const tevm = createMemoryClient({
  fork: {
    transport: http("https://mainnet.optimism.io")({}),
  },
});


const address = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045';


await tevm.runContractCall(
  MyERC721.write.mint({
    caller: address,
  }),
);


const balance = await tevm.runContractCall(
  MyERC721.read.balanceOf({
    caller: address,
  }),
);
console.log(balance); // 1n

Defined in

packages/memory-client/src/createMemoryClient.js:189