Welcome

NewEVM and Fork Selection#

NewEVM constructs the EVM for a block. Its most important job is selecting the correct instruction set for the current fork:

1
func NewEVM(blockCtx BlockContext, statedb StateDB, chainConfig *params.ChainConfig, config Config) *EVM {
2
    evm := &EVM{
3
        Context:     blockCtx,
4
        StateDB:     statedb,
5
        Config:      config,
6
        chainConfig: chainConfig,
7
        chainRules:  chainConfig.Rules(blockCtx.BlockNumber, blockCtx.Random != nil, blockCtx.Time),
8
        jumpDests:   newMapJumpDests(),
9
        hasher:      crypto.NewKeccakState(),
10
    }
11
    evm.precompiles = activePrecompiledContracts(evm.chainRules)
12

13
    switch {
14
    case evm.chainRules.IsOsaka:
15
        evm.table = &osakaInstructionSet
16
    case evm.chainRules.IsVerkle:
17
        evm.table = &verkleInstructionSet
18
    case evm.chainRules.IsPrague:
19
        evm.table = &pragueInstructionSet
20
    case evm.chainRules.IsCancun:
21
        evm.table = &cancunInstructionSet
22
    // ... Shanghai, Merge, London, Berlin, Istanbul,
23
    //     Constantinople, Byzantium, SpuriousDragon,
24
    //     TangerineWhistle, Homestead ...
25
    default:
26
        evm.table = &frontierInstructionSet
27
    }
28
    // ...
29
}

The switch statement falls through from the newest fork to the oldest. A Cancun block gets the cancunInstructionSet, which includes all opcodes from Frontier through Cancun. The chainRules struct — derived from ChainConfig at the block’s number and timestamp — drives every fork-dependent decision throughout the EVM.

Call#

Call is the most common entry point — it executes code at a target address. Here is the core logic with the tracer and Verkle code removed for clarity:

1
func (evm *EVM) Call(caller common.Address, addr common.Address, input []byte, gas uint64, value *uint256.Int) (ret []byte, leftOverGas uint64, err error) {
2
    if evm.depth > int(params.CallCreateDepth) {
3
        return nil, gas, ErrDepth
4
    }
5
    if !value.IsZero() && !evm.Context.CanTransfer(evm.StateDB, caller, value) {
6
        return nil, gas, ErrInsufficientBalance
7
    }
8
    snapshot := evm.StateDB.Snapshot()
9
    p, isPrecompile := evm.precompile(addr)
10

11
    if !evm.StateDB.Exist(addr) {
12
        // ...EIP-158: calling a non-existent account with zero value is a no-op
13
        evm.StateDB.CreateAccount(addr)
14
    }
15
    evm.Context.Transfer(evm.StateDB, caller, addr, value)
16

17
    if isPrecompile {
18
        ret, gas, err = RunPrecompiledContract(p, input, gas, evm.Config.Tracer)
19
    } else {
20
        code := evm.resolveCode(addr)
21
        if len(code) == 0 {
22
            ret, err = nil, nil
23
        } else {
24
            contract := NewContract(caller, addr, value, gas, evm.jumpDests)
25
            contract.SetCallCode(evm.resolveCodeHash(addr), code)
26
            ret, err = evm.Run(contract, input, false)
27
            gas = contract.Gas
28
        }
29
    }
30
    if err != nil {
31
        evm.StateDB.RevertToSnapshot(snapshot)
32
        if err != ErrExecutionReverted {
33
            gas = 0
34
        }
35
    }
36
    return ret, gas, err
37
}

The sequence:

1. Depth check: if evm.depth > 1024, return ErrDepth. This prevents infinite recursion between contracts.
2. Balance check: if the call transfers value, verify the caller has enough.
3. Snapshot: take a state snapshot so we can revert on error.
4. Precompile check: if the target address is a precompiled contract, run it directly via RunPrecompiledContract() and skip the interpreter.
5. Resolve code: load the target’s bytecode. Post-Prague, resolveCode follows EIP-7702 delegation designators one level deep.
6. Create contract object: NewContract packages the caller, address, value, gas allowance, and jump destination cache into a Contract struct.
7. Run: invoke evm.Run() — the interpreter loop.
8. Error handling: on error, revert state to the snapshot. If the error is ErrExecutionReverted (from the REVERT opcode), leftover gas is returned to the caller. For all other errors, gas is consumed entirely.

StaticCall#

StaticCall differs from Call in several ways beyond just read-only enforcement:

• No value transfer: the value is always zero — there is no value parameter in the signature.
• No account creation: unlike Call, it has no Exist / CreateAccount logic.
• Zero-balance touch: it unconditionally calls AddBalance(addr, 0) to “touch” the account, which matters for state accounting on some networks.
• Read-only mode: it passes readOnly = true to Run(). Any state-modifying opcode (SSTORE, LOG, CREATE, SELFDESTRUCT) checks evm.readOnly and returns ErrWriteProtection.

DelegateCall#

DelegateCall executes the target address’s code but in the context of the caller:

1
contract := NewContract(originCaller, caller, value, gas, evm.jumpDests)

Notice the first argument is originCaller (the caller’s caller), not caller. Inside the delegated code, CALLER returns the original external caller and ADDRESS returns the calling contract’s address — not the library’s address. This is the mechanism behind Solidity’s proxy/library pattern.

Create and Create2#

Contract creation follows a different path through the private evm.create() method:

1. Depth check and balance check (same as Call).
2. Increment the creator’s nonce — this happens before execution, and it’s the reason nonce is incremented even if creation fails.
3. Compute the new address: CREATE uses keccak256(rlp([sender, nonce])). CREATE2 uses keccak256(0xff ++ sender ++ salt ++ keccak256(init_code)).
4. Collision check: if the target address already has a non-zero nonce, non-empty code, or non-empty storage, return ErrContractAddressCollision.
5. Create the account, transfer value, set nonce to 1 (post-EIP-158).
6. Run init code: evm.Run() executes the constructor bytecode. The returned bytes become the deployed code.
7. Post-checks: code size must not exceed params.MaxCodeSize (24576 bytes). Post-London, code must not start with 0xEF (EIP-3541, reserved for EOF).
8. Charge code storage gas: len(deployedCode) * params.CreateDataGas (200 gas per byte).

Stack#

1
type Stack struct {
2
    data []uint256.Int
3
}

The EVM stack holds 256-bit integers. The maximum depth is 1024 items — enforced not in the stack itself but by the maxStack check in the interpreter loop. The pool pre-allocates a capacity of 16 elements:

1
var stackPool = sync.Pool{
2
    New: func() interface{} {
3
        return &Stack{data: make([]uint256.Int, 0, 16)}
4
    },
5
}

Stack operations are minimal: push, pop, peek (return a pointer to the top without removing it), swap1–swap16, dup, and Back(n) (access the nth item from top). A common pattern in opcode implementations is pop + peek:

1
func opAdd(pc *uint64, evm *EVM, scope *ScopeContext) ([]byte, error) {
2
    x, y := scope.Stack.pop(), scope.Stack.peek()
3
    y.Add(&x, y)
4
    return nil, nil
5
}

Here opAdd pops the first operand and peeks at the second (leaving it in place), then writes the result directly into y. This avoids an extra push — a micro-optimization that appears throughout instructions.go.

Memory#

1
type Memory struct {
2
    store       []byte
3
    lastGasCost uint64
4
}

EVM memory is a byte-addressable, word-aligned buffer that grows on demand. The lastGasCost field tracks cumulative gas already paid for memory expansion, so that memoryGasCost() only charges the delta when memory grows further.

Memory expansion follows a quadratic cost model from the Yellow Paper:

1
func memoryGasCost(mem *Memory, newMemSize uint64) (uint64, error) {
2
    // ...
3
    newMemSizeWords := toWordSize(newMemSize)
4
    newMemSize = newMemSizeWords * 32
5

6
    if newMemSize > uint64(mem.Len()) {
7
        square := newMemSizeWords * newMemSizeWords
8
        linCoef := newMemSizeWords * params.MemoryGas
9
        quadCoef := square / params.QuadCoeffDiv
10
        newTotalFee := linCoef + quadCoef
11

12
        fee := newTotalFee - mem.lastGasCost
13
        mem.lastGasCost = newTotalFee
14
        return fee, nil
15
    }
16
    return 0, nil
17
}

The formula is memory_cost = (words * 3) + (words^2 / 512). The linear term keeps small reads cheap; the quadratic term makes large memory allocations progressively more expensive. The function calculates the total fee for the new size and subtracts the already-paid lastGasCost to get the incremental charge.

The operation Struct#

1
type operation struct {
2
    execute     executionFunc
3
    constantGas uint64
4
    dynamicGas  gasFunc
5
    minStack    int
6
    maxStack    int
7
    memorySize  memorySizeFunc
8
    undefined   bool
9
}

• execute: the function that performs the operation (e.g., opAdd, opSstore).
• constantGas: the fixed gas cost charged on every execution.
• dynamicGas: an optional function that computes additional gas based on arguments (e.g., memory expansion, cold/warm storage access).
• minStack / maxStack: the minimum items required on the stack and the maximum allowed after execution.
• memorySize: an optional function that computes how much memory the operation needs. If set, dynamicGas must also be set.

Fork Inheritance#

The JumpTable is a 256-element array — one slot per possible opcode byte:

1
type JumpTable [256]*operation

Each fork builds on the previous one by copying and patching:

1
func newCancunInstructionSet() JumpTable {
2
    instructionSet := newShanghaiInstructionSet()
3
    enable4844(&instructionSet) // BLOBHASH opcode
4
    enable7516(&instructionSet) // BLOBBASEFEE opcode
5
    enable1153(&instructionSet) // Transient storage (TLOAD/TSTORE)
6
    enable5656(&instructionSet) // MCOPY opcode
7
    enable6780(&instructionSet) // Neutered SELFDESTRUCT
8
    return validate(instructionSet)
9
}

newShanghaiInstructionSet() calls newMergeInstructionSet(), which calls newLondonInstructionSet(), and so on back to newFrontierInstructionSet(). Each enable* function overwrites specific slots in the table. The validate function panics if any slot is nil or if memorySize is set without dynamicGas.

This chain of inheritance means you can trace every opcode back to the fork that introduced it. For example, PUSH0 was added by enable3855 (EIP-3855) in the Shanghai set.

Example: How ADD Is Registered#

In newFrontierInstructionSet():

1
ADD: {
2
    execute:     opAdd,
3
    constantGas: GasFastestStep,
4
    minStack:    minStack(2, 1),
5
    maxStack:    maxStack(2, 1),
6
},

GasFastestStep is 3 gas. minStack(2, 1) means “requires 2 items, will produce 1” — so the stack must have at least 2 items. maxStack(2, 1) computes the maximum stack size where adding 1 (net: -1) won’t overflow.

Arithmetic: opAdd#

1
func opAdd(pc *uint64, evm *EVM, scope *ScopeContext) ([]byte, error) {
2
    x, y := scope.Stack.pop(), scope.Stack.peek()
3
    y.Add(&x, y)
4
    return nil, nil
5
}

Pop one operand, peek at the second, write the result in-place. All arithmetic uses uint256.Int from the holiman/uint256 library — 256-bit math that maps directly to EVM word size. The return nil, nil pattern means “no return data, no error” — the interpreter increments pc by 1 and continues.

Storage Read: opSload#

1
func opSload(pc *uint64, evm *EVM, scope *ScopeContext) ([]byte, error) {
2
    loc := scope.Stack.peek()
3
    hash := common.Hash(loc.Bytes32())
4
    val := evm.StateDB.GetState(scope.Contract.Address(), hash)
5
    loc.SetBytes(val.Bytes())
6
    return nil, nil
7
}

Peek at the top of stack (the storage key), call StateDB.GetState() to read the value, then overwrite the top of stack with the result. The gas cost for SLOAD is handled entirely in the dynamic gas function (not shown here) — either 2100 for a cold slot or 100 for a warm slot under EIP-2929.

Storage Write: opSstore#

1
func opSstore(pc *uint64, evm *EVM, scope *ScopeContext) ([]byte, error) {
2
    if evm.readOnly {
3
        return nil, ErrWriteProtection
4
    }
5
    loc := scope.Stack.pop()
6
    val := scope.Stack.pop()
7
    evm.StateDB.SetState(scope.Contract.Address(), loc.Bytes32(), val.Bytes32())
8
    return nil, nil
9
}

The execute function is simple — pop key, pop value, write to state. The complexity of SSTORE is entirely in its dynamic gas function (covered below).

Control Flow: opJump#

1
func opJump(pc *uint64, evm *EVM, scope *ScopeContext) ([]byte, error) {
2
    if evm.abort.Load() {
3
        return nil, errStopToken
4
    }
5
    pos := scope.Stack.pop()
6
    if !scope.Contract.validJumpdest(&pos) {
7
        return nil, ErrInvalidJump
8
    }
9
    *pc = pos.Uint64() - 1
10
    return nil, nil
11
}

Pop the destination from the stack. Validate that the destination byte is actually a JUMPDEST opcode (not data embedded in a PUSH). Set *pc to dest - 1 because the interpreter loop will pc++ after this returns.

The validJumpdest check prevents jumping into the middle of a PUSH instruction’s data bytes. It uses a bitmap (analysis BitVec) that marks which byte positions are actual opcodes vs. push data. This bitmap is computed once and cached in the JumpDestCache.

Inter-Contract Calls: opCall#

1
func opCall(pc *uint64, evm *EVM, scope *ScopeContext) ([]byte, error) {
2
    stack := scope.Stack
3
    temp := stack.pop()
4
    gas := evm.callGasTemp
5
    addr, value, inOffset, inSize, retOffset, retSize := stack.pop(), stack.pop(), stack.pop(), stack.pop(), stack.pop(), stack.pop()
6
    toAddr := common.Address(addr.Bytes20())
7
    args := scope.Memory.GetPtr(inOffset.Uint64(), inSize.Uint64())
8

9
    if evm.readOnly && !value.IsZero() {
10
        return nil, ErrWriteProtection
11
    }
12
    if !value.IsZero() {
13
        gas += params.CallStipend
14
    }
15
    ret, returnGas, err := evm.Call(scope.Contract.Address(), toAddr, args, gas, &value)
16

17
    if err != nil {
18
        temp.Clear()
19
    } else {
20
        temp.SetOne()
21
    }
22
    stack.push(&temp)
23
    if err == nil || err == ErrExecutionReverted {
24
        scope.Memory.Set(retOffset.Uint64(), retSize.Uint64(), ret)
25
    }
26

27
    scope.Contract.RefundGas(returnGas, evm.Config.Tracer, tracing.GasChangeCallLeftOverRefunded)
28
    evm.returnData = ret
29
    return ret, nil
30
}

Walking through:

• The first pop discards the gas argument from the stack — the actual gas to forward was already computed by gasCall (the dynamic gas function) and stored in evm.callGasTemp. This split exists because the 63/64 rule (EIP-150) must be applied during gas calculation, not during execution.
• Pop the remaining 6 arguments: target address, value, input offset/size, return offset/size.
• If the call transfers value, add CallStipend (2300 gas) — a free allowance so the receiver can emit a LOG.
• Recursively call evm.Call(). This increments evm.depth, creates a new Contract and ScopeContext, and enters Run() again.
• Push 1 (success) or 0 (failure) onto the stack.
• Copy return data into memory at the specified offset.
• Refund unused gas back to the current contract.

Note that opCall always returns nil, nil to the interpreter loop — sub-call errors are reported via the stack value, not by breaking the parent’s execution. This is the distinction between EVM-level errors (which revert the sub-call) and consensus errors (which abort the entire transaction).

Memory Expansion#

Memory expansion gas is the most common dynamic cost — it applies to any opcode that accesses memory (MLOAD, MSTORE, CALLDATACOPY, CALL, etc.). We already saw the formula in the Memory section: cost = 3*words + words^2/512, charged incrementally.

SSTORE: The Most Complex Gas Rule#

SSTORE gas depends on three values: the original value (at the start of the transaction), the current value (possibly modified earlier in this transaction), and the new value being written. This three-way comparison implements the net gas metering rules from EIP-2200 and EIP-2929.

The post-Berlin SSTORE gas function in operations_acl.go handles all modern cases:

1
func makeGasSStoreFunc(clearingRefund uint64) gasFunc {
2
    return func(evm *EVM, contract *Contract, stack *Stack, mem *Memory, memorySize uint64) (uint64, error) {
3
        if contract.Gas <= params.SstoreSentryGasEIP2200 {
4
            return 0, errors.New("not enough gas for reentrancy sentry")
5
        }
6
        var (
7
            y, x              = stack.Back(1), stack.peek()
8
            slot              = common.Hash(x.Bytes32())
9
            current, original = evm.StateDB.GetStateAndCommittedState(contract.Address(), slot)
10
            cost              = uint64(0)
11
        )
12
        if _, slotPresent := evm.StateDB.SlotInAccessList(contract.Address(), slot); !slotPresent {
13
            cost = params.ColdSloadCostEIP2929
14
            evm.StateDB.AddSlotToAccessList(contract.Address(), slot)
15
        }
16
        value := common.Hash(y.Bytes32())
17

18
        if current == value {  // no-op
19
            return cost + params.WarmStorageReadCostEIP2929, nil
20
        }
21
        if original == current {
22
            if original == (common.Hash{}) {  // 0 → non-zero
23
                return cost + params.SstoreSetGasEIP2200, nil
24
            }
25
            if value == (common.Hash{}) {  // non-zero → 0
26
                evm.StateDB.AddRefund(clearingRefund)
27
            }
28
            return cost + (params.SstoreResetGasEIP2200 - params.ColdSloadCostEIP2929), nil
29
        }
30
        // Slot is "dirty" — already modified in this transaction
31
        // ... (refund adjustments for various reset scenarios)
32
        return cost + params.WarmStorageReadCostEIP2929, nil
33
    }
34
}

The key cost tiers:

The function also manages the refund counter: clearing a storage slot (setting to zero) adds to the refund, while recreating a cleared slot subtracts from it. The clearingRefund parameter differs between EIP-2200 and EIP-3529.

EIP-2929: Warm vs. Cold Access#

EIP-2929 (Berlin fork) introduced the warm/cold distinction for all state access opcodes. The first time a transaction touches an address or storage slot, it pays a “cold” cost. Subsequent accesses pay only a “warm” cost.

For SLOAD, this is implemented in gasSLoadEIP2929:

1
func gasSLoadEIP2929(evm *EVM, contract *Contract, stack *Stack, mem *Memory, memorySize uint64) (uint64, error) {
2
    loc := stack.peek()
3
    slot := common.Hash(loc.Bytes32())
4
    if _, slotPresent := evm.StateDB.SlotInAccessList(contract.Address(), slot); !slotPresent {
5
        evm.StateDB.AddSlotToAccessList(contract.Address(), slot)
6
        return params.ColdSloadCostEIP2929, nil   // 2100
7
    }
8
    return params.WarmStorageReadCostEIP2929, nil  // 100
9
}

For CALL and its variants, makeCallVariantGasCallEIP2929 wraps the pre-Berlin gas calculator to add cold access charges:

1
gasCallEIP2929         = makeCallVariantGasCallEIP2929(gasCall, 1)
2
gasDelegateCallEIP2929 = makeCallVariantGasCallEIP2929(gasDelegateCall, 1)
3
gasStaticCallEIP2929   = makeCallVariantGasCallEIP2929(gasStaticCall, 1)

The wrapper checks if the target address is in the access list. If not, it charges ColdAccountAccessCostEIP2929 - WarmStorageReadCostEIP2929 (2500) and adds the address.