ethereumjs-monorepo

Class: EVM

The EVM (Ethereum Virtual Machine) is responsible for executing EVM bytecode, processing transactions, and managing state changes. It handles both contract calls and contract creation operations.

An EVM instance can be created with the constructor method:

createEVM

Implements

EVMInterface

Constructors

Constructor

new EVM(opts): EVM

Defined in: evm.ts:355

Creates new EVM object

Parameters

opts

EVMOpts

The EVM options

Returns

EVM

Deprecated

The direct usage of this constructor is replaced since non-finalized async initialization lead to side effects. Please use the async createEVM constructor instead (same API).

Properties

allowUnlimitedContractSize

readonly allowUnlimitedContractSize: boolean

Defined in: evm.ts:219

allowUnlimitedInitCodeSize

readonly allowUnlimitedInitCodeSize: boolean

Defined in: evm.ts:220

binaryAccessWitness?

optional binaryAccessWitness?: BinaryTreeAccessWitness

Defined in: evm.ts:212

blockchain

blockchain: EVMMockBlockchainInterface

Defined in: evm.ts:210

blockLevelAccessList?

readonly optional blockLevelAccessList?: BlockLevelAccessList

Defined in: evm.ts:227

Accumulated block access list when EIP-7928 is active.

Remarks

Experimental (Amsterdam): may change on patch releases.

Implementation of

EVMInterface.blockLevelAccessList

common

readonly common: Common

Defined in: evm.ts:206

Implementation of

EVMInterface.common

createdAccountIntrinsicStateGas

createdAccountIntrinsicStateGas: Map<`0x${string}`, bigint>

Defined in: evm.ts:304

EIP-8037 (v7): previously tracked intrinsic new-account state gas for depth=0 creation txs. New-account state gas is now charged at access (same map as inner CREATE: createdAccountStateGas). Kept for API compatibility; reset per tx, not written on the v7 path.

createdAccountStateGas

createdAccountStateGas: Map<`0x${string}`, bigint>

Defined in: evm.ts:297

EIP-8037 SELFDESTRUCT deferred refund support. Per-address record of the state-gas charged for account creation (stateBytesPerNewAccount × costPerStateByte) plus code deposit (L × costPerStateByte) at successful CREATE/CREATE2 frame exit. Reset at the start of each tx and consulted by runTx to refund state-gas for accounts that were both created and SELFDESTRUCTed in the same tx (per EIP-6780 + EIP-8037). Storage-slot state-gas is not tracked here yet; that is a separate follow-up.

createTxTargetAlive

createTxTargetAlive: boolean = false

Defined in: evm.ts:269

EIP-8037: whether the target account of a top-level creation transaction was already alive (EIP-161 non-empty) before creation. runTx refunds the intrinsic new-account state gas when this is true or the creation failed.

Remarks

Experimental (Amsterdam): may change on patch releases.

Implementation of

EVMInterface.createTxTargetAlive

eip2780PrepOog

eip2780PrepOog: boolean = false

Defined in: evm.ts:261

EIP-2780 / EIP-8037: set when a top-frame access charge (new-account state or 7702 delegation resolution) OOGs before opcodes run. runTx uses this to revert 7702 delegations applied in the prepare region.

Remarks

Experimental (Amsterdam): may change on patch releases.

Implementation of

EVMInterface.eip2780PrepOog

eip7928CallPostTargetOog

eip7928CallPostTargetOog: boolean = false

Defined in: evm.ts:253

EIP-7928 CALL post-state OOG: set while handling post-target access failure so runTx drains the state-gas reservoir and the sender pays the full tx gas limit.

Remarks

Experimental (Amsterdam): may change on patch releases.

Implementation of

EVMInterface.eip7928CallPostTargetOog

events

readonly events: EventEmitter<EVMEvent>

Defined in: evm.ts:207

Implementation of

EVMInterface.events

executionStateGasUsed

executionStateGasUsed: bigint = BIGINT_0

Defined in: evm.ts:246

EIP-8037 cumulative state-gas used by the current transaction.

Remarks

Experimental (Amsterdam): may change on patch releases.

Implementation of

EVMInterface.executionStateGasUsed

journal

journal: Journal

Defined in: evm.ts:211

Implementation of

EVMInterface.journal

stateGasReservoir

stateGasReservoir: bigint = BIGINT_0

Defined in: evm.ts:240

EIP-8037 transaction-level state-gas reservoir. Holds gas paid by the user that exceeds the EIP-7825 regular-gas budget and is reserved exclusively for state-creation charges. State-gas charges draw from stateGasReservoir first; once exhausted, they fall through to the regular gasLeft. Refunds (revert / exceptional halt / SELFDESTRUCT of same-tx-created accounts) refill it. Initialized by runTx at the start of each transaction; 0 when EIP-8037 is inactive.

Remarks

Experimental (Amsterdam): may change on patch releases.

Implementation of

EVMInterface.stateGasReservoir

stateManager

stateManager: StateManagerInterface

Defined in: evm.ts:209

Implementation of

EVMInterface.stateManager

systemBinaryAccessWitness?

optional systemBinaryAccessWitness?: BinaryTreeAccessWitness

Defined in: evm.ts:213

transientStorage

readonly transientStorage: TransientStorage

Defined in: evm.ts:215

Accessors

opcodes

Get Signature

get opcodes(): OpcodeList

Defined in: evm.ts:325

Returns

OpcodeList

precompiles

Get Signature

get precompiles(): Map<string, PrecompileFunc>

Defined in: evm.ts:321

Returns

Map<string, PrecompileFunc>

Implementation of

EVMInterface.precompiles

Methods

clearPerformanceLogs()

clearPerformanceLogs(): void

Defined in: evm.ts:1739

Returns

void

getActiveOpcodes()

getActiveOpcodes(): OpcodeList

Defined in: evm.ts:449

Returns a list with the currently activated opcodes available for EVM execution

Returns

OpcodeList

getPerformanceLogs()

getPerformanceLogs(): object

Defined in: evm.ts:1735

Returns

object

opcodes

opcodes: EVMPerformanceLogOutput[]

precompiles

precompiles: EVMPerformanceLogOutput[]

getPrecompile()

getPrecompile(address): PrecompileFunc | undefined

Defined in: evm.ts:1582

Returns the precompile function registered at the given address, or undefined if no precompile is active there.

Accepts either an Address instance or a 0x-prefixed hex string.

const evm = await createEVM({
  customPrecompiles: [{ address: '0x000000000000000000000000000000000000ff01', function: myFn }],
})
const fn = evm.getPrecompile('0x000000000000000000000000000000000000ff01')

Parameters

address

`0x${string}` | Address

Returns

PrecompileFunc | undefined

Implementation of

EVMInterface.getPrecompile

runCall()

runCall(opts): Promise<EVMResult>

Defined in: evm.ts:1327

Executes an EVM message, determining whether it’s a call or create based on the to address. It checkpoints the state and reverts changes if an exception happens during the message execution.