Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Account Management

Two actions manage account state: getAccountHandler and setAccountHandler.

getAccountHandler

Retrieve the current state of an account.

Parameters

type GetAccountParams = {
  address: Address
  blockTag?: 'latest' | 'pending' | 'earliest' | number
  returnStorage?: boolean // expensive
  throwOnFail?: boolean // defaults to true
}

Return Type

type GetAccountResult = {
  address: Address
  nonce: bigint
  balance: bigint
  deployedBytecode: Hex
  storageRoot: Hex
  codeHash: Hex
  isContract: boolean
  isEmpty: boolean
  storage?: { [key: Hex]: Hex } // when returnStorage=true
  errors?: TevmGetAccountError[]
}

Example

import { createTevmNode } from 'tevm'
import { getAccountHandler, setAccountHandler } from 'tevm/actions'
import { parseEther } from 'viem'
 
const node = createTevmNode()
const address = '0x1234567890123456789012345678901234567890'
 
await setAccountHandler(node)({
  address,
  balance: parseEther('1')
})
 
const account = await getAccountHandler(node)({
  address,
  blockTag: 'latest',
  returnStorage: true
})
 
console.log('Balance:', account.balance)
console.log('Nonce:', account.nonce)
if (account.isContract) {
  console.log('Code:', account.deployedBytecode)
  console.log('Storage:', account.storage)
}

setAccountHandler

Modify account state directly.

Parameters

type SetAccountParams = {
  address: Address
  nonce?: bigint
  balance?: bigint
  deployedBytecode?: Hex
  state?: { [key: Hex]: Hex }
  stateDiff?: { [key: Hex]: Hex }
  throwOnFail?: boolean // defaults to true
}

Return Type

type SetAccountResult = {
  errors?: TevmSetAccountError[]
}

Examples

Setting Balance

import { setAccountHandler } from 'tevm/actions'
 
await setAccountHandler(node)({
  address: '0x...',
  balance: parseEther('100')
})

Deploying Contract Code

await setAccountHandler(node)({
  address: contractAddress,
  deployedBytecode: '0x...',
  state: {
    '0x0000...': '0x0000...'
  }
})

Modifying Multiple Properties

await setAccountHandler(node)({
  address: '0x...',
  nonce: 5n,
  balance: parseEther('10'),
  state: {
    [slot1]: value1,
    [slot2]: value2
  }
})

Best Practices

Skip storage fetches unless needed:

const account = await getAccountHandler(node)({
  address: '0x...',
  returnStorage: false // default
})

Check existence before modifying:

const account = await getAccountHandler(node)({
  address,
  throwOnFail: false
})
 
if (account.errors) {
  await setAccountHandler(node)({
    address,
    balance: amount
  })
} else if (!account.isEmpty) {
  await setAccountHandler(node)({
    address,
    balance: account.balance + amount
  })
}

By default, getAccountHandler throws when an account is missing. Use throwOnFail: false when probing for existence.

Error handling:

const result = await setAccountHandler(node)({
  address: '0x...',
  balance: newBalance,
  throwOnFail: false
})
 
if (result.errors) {
  console.error('Failed to set account:', result.errors)
}

Related Topics