Welcome

The Execution Pipeline#

A transaction travels through these stages inside stateTransition.execute():

1
execute()
2
│
3
├─ preCheck()
4
│    ├─ verify nonce == state nonce
5
│    ├─ verify sender is EOA (or EIP-7702 delegation)
6
│    ├─ verify gasFeeCap ≥ baseFee
7
│    └─ buyGas()
8
│         ├─ check sender balance ≥ gasLimit × gasFeeCap + value
9
│         ├─ gp.SubGas(gasLimit)
10
│         └─ state.SubBalance(sender, gasLimit × gasPrice)
11
│
12
├─ IntrinsicGas()
13
│    └─ gasRemaining -= intrinsicGas
14
│
15
├─ state.Prepare()
16
│
17
├─ EVM dispatch
18
│    ├─ if msg.To == nil:  evm.Create()
19
│    └─ else:              evm.Call()
20
│
21
├─ gasRemaining += calcRefund()
22
│
23
├─ returnGas()
24
│    ├─ state.AddBalance(sender, gasRemaining × gasPrice)
25
│    └─ gp.AddGas(gasRemaining)
26
│
27
└─ state.AddBalance(coinbase, gasUsed × effectiveTip)

Each stage is covered in detail below.

Block-Level Processing: Process()#

Before individual transactions are executed, the block processor sets up the shared environment. The StateProcessor.Process() method orchestrates this:

1
func (p *StateProcessor) Process(block *types.Block, statedb *state.StateDB, cfg vm.Config) (*ProcessResult, error) {
2
    var (
3
        receipts    types.Receipts
4
        usedGas     = new(uint64)
5
        header      = block.Header()
6
        allLogs     []*types.Log
7
        gp          = new(GasPool).AddGas(block.GasLimit())
8
    )
9
    // ...
10
    context = NewEVMBlockContext(header, p.chain, nil)
11
    evm := vm.NewEVM(context, tracingStateDB, config, cfg)
12

13
    // Pre-execution system calls
14
    if beaconRoot := block.BeaconRoot(); beaconRoot != nil {
15
        ProcessBeaconBlockRoot(*beaconRoot, evm)
16
    }
17

18
    // Iterate over and process the individual transactions
19
    for i, tx := range block.Transactions() {
20
        msg, err := TransactionToMessage(tx, signer, header.BaseFee)
21
        // ...
22
        receipt, err := ApplyTransactionWithEVM(msg, gp, statedb, blockNumber, blockHash, context.Time, tx, usedGas, evm)
23
        receipts = append(receipts, receipt)
24
        allLogs = append(allLogs, receipt.Logs...)
25
    }
26
    // ...
27
}

Walking through the key steps:

• GasPool creation — new(GasPool).AddGas(block.GasLimit()) creates the block-level gas budget. Every transaction draws from this pool; if the pool runs dry, no more transactions can execute in this block.
• EVM creation — A single EVM instance is created for the entire block and reused across all transactions. The BlockContext (built from the header) provides block-level data: coinbase, block number, timestamp, base fee, blob base fee.
• System calls — Before user transactions, EIP-4788 stores the beacon block root and EIP-2935/7709 stores the parent block hash via system calls to predeployed contracts.
• Transaction loop — Each transaction is converted to a Message, then executed via ApplyTransactionWithEVM.

1
type Message struct {
2
    To                    *common.Address
3
    From                  common.Address
4
    Nonce                 uint64
5
    Value                 *big.Int
6
    GasLimit              uint64
7
    GasPrice              *big.Int
8
    GasFeeCap             *big.Int
9
    GasTipCap             *big.Int
10
    Data                  []byte
11
    AccessList            types.AccessList
12
    BlobGasFeeCap         *big.Int
13
    BlobHashes            []common.Hash
14
    SetCodeAuthorizations []types.SetCodeAuthorization
15
    SkipNonceChecks       bool
16
    SkipTransactionChecks bool
17
}

1
type GasPool uint64
2

3
func (gp *GasPool) AddGas(amount uint64) *GasPool {
4
    // ... overflow check ...
5
    *(*uint64)(gp) += amount
6
    return gp
7
}
8

9
func (gp *GasPool) SubGas(amount uint64) error {
10
    if uint64(*gp) < amount {
11
        return ErrGasLimitReached
12
    }
13
    *(*uint64)(gp) -= amount
14
    return nil
15
}

The stateTransition Engine#

The core of transaction execution is the stateTransition struct. ApplyMessage creates one and calls execute():

1
func ApplyMessage(evm *vm.EVM, msg *Message, gp *GasPool) (*ExecutionResult, error) {
2
    evm.SetTxContext(NewEVMTxContext(msg))
3
    return newStateTransition(evm, msg, gp).execute()
4
}

The struct itself holds the transaction context:

1
type stateTransition struct {
2
    gp           *GasPool
3
    msg          *Message
4
    gasRemaining uint64
5
    initialGas   uint64
6
    state        vm.StateDB
7
    evm          *vm.EVM
8
}

gasRemaining tracks how much gas is left for this transaction. It starts at msg.GasLimit (set during buyGas), decreases as computation proceeds, and partially recovers during refund.

preCheck()#

preCheck() validates the transaction against the current state before any gas is spent:

1
func (st *stateTransition) preCheck() error {
2
    msg := st.msg
3
    if !msg.SkipNonceChecks {
4
        stNonce := st.state.GetNonce(msg.From)
5
        if msgNonce := msg.Nonce; stNonce < msgNonce {
6
            return fmt.Errorf("%w: address %v, tx: %d state: %d", ErrNonceTooHigh, ...)
7
        } else if stNonce > msgNonce {
8
            return fmt.Errorf("%w: address %v, tx: %d state: %d", ErrNonceTooLow, ...)
9
        }
10
    }
11
    if !msg.SkipTransactionChecks {
12
        // Verify the sender is an EOA (or has a delegation)
13
        code := st.state.GetCode(msg.From)
14
        _, delegated := types.ParseDelegation(code)
15
        if len(code) > 0 && !delegated {
16
            return fmt.Errorf("%w: address %v, len(code): %d", ErrSenderNoEOA, ...)
17
        }
18
    }
19
    // Verify gasFeeCap >= baseFee (post-London)
20
    // Verify blobGasFeeCap >= blobBaseFee (post-Cancun)
21
    // Verify blob version hashes, EIP-7702 authorization list
22
    // ...
23
    return st.buyGas()
24
}

The checks in order:

1. Nonce match — The transaction’s nonce must exactly equal the sender’s state nonce. Too high means a gap; too low means a replay.
2. Sender is EOA — The sender must not have contract code, unless it has an EIP-7702 delegation (which allows EOAs to temporarily delegate to contract code).
3. Gas fee cap — Post-London, gasFeeCap >= baseFee is required; post-Cancun, blob transactions also need blobGasFeeCap >= blobBaseFee.
4. Blob validation — Blob transactions must have a To address, at least one blob hash, and valid KZG version hashes.

If all checks pass, preCheck calls buyGas() at the end.

1
func (st *stateTransition) buyGas() error {
2
    mgval := new(big.Int).SetUint64(st.msg.GasLimit)
3
    mgval.Mul(mgval, st.msg.GasPrice)
4
    balanceCheck := new(big.Int).Set(mgval)
5
    if st.msg.GasFeeCap != nil {
6
        balanceCheck.SetUint64(st.msg.GasLimit)
7
        balanceCheck = balanceCheck.Mul(balanceCheck, st.msg.GasFeeCap)
8
    }
9
    balanceCheck.Add(balanceCheck, st.msg.Value)
10
    // ... add blob fee to balanceCheck for Cancun+ ...
11

12
    if have, want := st.state.GetBalance(st.msg.From), balanceCheckU256; have.Cmp(want) < 0 {
13
        return fmt.Errorf("%w: address %v have %v want %v", ErrInsufficientFunds, ...)
14
    }
15
    if err := st.gp.SubGas(st.msg.GasLimit); err != nil {
16
        return err
17
    }
18
    st.gasRemaining = st.msg.GasLimit
19
    st.initialGas = st.msg.GasLimit
20
    mgvalU256, _ := uint256.FromBig(mgval)
21
    st.state.SubBalance(st.msg.From, mgvalU256, tracing.BalanceDecreaseGasBuy)
22
    return nil
23
}

IntrinsicGas()#

After preCheck succeeds, execute() computes the intrinsic gas — the minimum gas any transaction must pay before the EVM even starts:

1
gas, err := IntrinsicGas(msg.Data, msg.AccessList, msg.SetCodeAuthorizations,
2
    contractCreation, rules.IsHomestead, rules.IsIstanbul, rules.IsShanghai)

The IntrinsicGas function computes the sum of:

1
func IntrinsicGas(data []byte, accessList types.AccessList, authList []types.SetCodeAuthorization,
2
    isContractCreation, isHomestead, isEIP2028, isEIP3860 bool) (uint64, error) {
3
    var gas uint64
4
    if isContractCreation && isHomestead {
5
        gas = params.TxGasContractCreation   // 53,000
6
    } else {
7
        gas = params.TxGas                   // 21,000
8
    }
9
    // Zero and non-zero bytes are priced differently
10
    z := uint64(bytes.Count(data, []byte{0}))
11
    nz := uint64(len(data)) - z
12

13
    nonZeroGas := params.TxDataNonZeroGasFrontier   // 68
14
    if isEIP2028 {
15
        nonZeroGas = params.TxDataNonZeroGasEIP2028 // 16
16
    }
17
    gas += nz * nonZeroGas
18
    gas += z * params.TxDataZeroGas                 // 4
19

20
    if accessList != nil {
21
        gas += uint64(len(accessList)) * params.TxAccessListAddressGas      // 2,400
22
        gas += uint64(accessList.StorageKeys()) * params.TxAccessListStorageKeyGas // 1,900
23
    }
24
    if authList != nil {
25
        gas += uint64(len(authList)) * params.CallNewAccountGas             // 25,000
26
    }
27
    return gas, nil
28
}

If gasRemaining < intrinsicGas, the transaction fails immediately with ErrIntrinsicGas. Otherwise, intrinsic gas is subtracted from gasRemaining and the rest is available for EVM execution.

1
func FloorDataGas(data []byte) (uint64, error) {
2
    var (
3
        z      = uint64(bytes.Count(data, []byte{0}))
4
        nz     = uint64(len(data)) - z
5
        tokens = nz*params.TxTokenPerNonZeroByte + z
6
    )
7
    return params.TxGas + tokens*params.TxCostFloorPerToken, nil
8
}

EVM Dispatch#

After intrinsic gas is deducted, the access list is prepared and the EVM is dispatched:

1
// core/state_transition.go (inside execute)
2

3
st.state.Prepare(rules, msg.From, st.evm.Context.Coinbase, msg.To, vm.ActivePrecompiles(rules), msg.AccessList)
4

5
var (
6
    ret   []byte
7
    vmerr error
8
)
9
if contractCreation {
10
    ret, _, st.gasRemaining, vmerr = st.evm.Create(msg.From, msg.Data, st.gasRemaining, value)
11
} else {
12
    st.state.SetNonce(msg.From, st.state.GetNonce(msg.From)+1, tracing.NonceChangeEoACall)
13
    // ... apply EIP-7702 authorizations ...
14
    ret, st.gasRemaining, vmerr = st.evm.Call(msg.From, st.to(), msg.Data, st.gasRemaining, value)
15
}

Key observations:

• Prepare() warms the access list — the sender, recipient, coinbase, and all precompile addresses are added to the EIP-2929 access list. Any addresses and storage keys from the transaction’s EIP-2930 access list are also added. This means subsequent SLOAD/CALL to these addresses pay the “warm” gas cost instead of the “cold” cost.
• Contract creation — If msg.To == nil, evm.Create() is called. The Data field is treated as init code, executed to produce the deployed bytecode.
• Regular call — Otherwise, the nonce is incremented first (before the call, not after), then evm.Call() executes the contract at the destination address. EIP-7702 authorizations are applied between the nonce increment and the call.
• vmerr vs err — EVM errors (vmerr) like ErrOutOfGas or ErrExecutionReverted are not consensus errors. They don’t prevent the transaction from being included in the block — the transaction is included, gas is consumed, but the state changes from the reverted call are rolled back. Consensus errors (returned as err from execute()) mean the transaction is invalid and must not be included.

The EVM internals are covered in Chapter 07 — The EVM Deep Dive.

calcRefund()#

After EVM execution, unused gas and refund counters are reconciled:

1
func (st *stateTransition) calcRefund() uint64 {
2
    var refund uint64
3
    if !st.evm.ChainConfig().IsLondon(st.evm.Context.BlockNumber) {
4
        refund = st.gasUsed() / params.RefundQuotient        // gasUsed / 2
5
    } else {
6
        refund = st.gasUsed() / params.RefundQuotientEIP3529  // gasUsed / 5
7
    }
8
    if refund > st.state.GetRefund() {
9
        refund = st.state.GetRefund()
10
    }
11
    return refund
12
}

The refund counter is incremented during EVM execution by operations like SSTORE (clearing a storage slot to zero). But the refund is capped:

• Pre-London: capped at gasUsed / 2
• Post-London (EIP-3529): capped at gasUsed / 5

The cap was tightened in EIP-3529 to prevent “gas token” exploits where users would create and destroy storage slots specifically to harvest refunds.

The computed refund is added back to gasRemaining:

1
// inside execute()
2
st.gasRemaining += st.calcRefund()

returnGas()#

After refunds are applied, the remaining gas is converted back to ETH and returned to the sender:

1
func (st *stateTransition) returnGas() {
2
    remaining := uint256.NewInt(st.gasRemaining)
3
    remaining.Mul(remaining, uint256.MustFromBig(st.msg.GasPrice))
4
    st.state.AddBalance(st.msg.From, remaining, tracing.BalanceIncreaseGasReturn)
5

6
    // Return remaining gas to the block gas counter
7
    st.gp.AddGas(st.gasRemaining)
8
}

This reverses part of what buyGas() did. The sender originally paid gasLimit × gasPrice. Now they get back gasRemaining × gasPrice. The gas pool is also replenished, making this gas available for subsequent transactions in the block.

Fee Distribution#

After returning gas to the sender, the tip is paid to the coinbase (the block producer):

1
// core/state_transition.go (inside execute)
2

3
effectiveTip := msg.GasPrice
4
if rules.IsLondon {
5
    effectiveTip = new(big.Int).Sub(msg.GasPrice, st.evm.Context.BaseFee)
6
}
7
effectiveTipU256, _ := uint256.FromBig(effectiveTip)
8

9
fee := new(uint256.Int).SetUint64(st.gasUsed())
10
fee.Mul(fee, effectiveTipU256)
11
st.state.AddBalance(st.evm.Context.Coinbase, fee, tracing.BalanceIncreaseRewardTransactionFee)

Post-London (EIP-1559), the gas price splits into two parts:

• Base fee (msg.GasPrice - effectiveTip): This ETH was already deducted from the sender during buyGas(), but it is not added to the coinbase. It is effectively burned — removed from circulation.
• Tip (effectiveTip = msg.GasPrice - baseFee): This goes to the coinbase as the block producer’s reward for including the transaction.

The gasUsed() helper computes initialGas - gasRemaining — the total gas actually consumed (including intrinsic gas but after refunds).

Receipt Creation#

After execution completes, ApplyTransactionWithEVM calls MakeReceipt to build the receipt:

1
func MakeReceipt(evm *vm.EVM, result *ExecutionResult, statedb *state.StateDB,
2
    blockNumber *big.Int, blockHash common.Hash, blockTime uint64,
3
    tx *types.Transaction, usedGas uint64, root []byte) *types.Receipt {
4

5
    receipt := &types.Receipt{Type: tx.Type(), PostState: root, CumulativeGasUsed: usedGas}
6
    if result.Failed() {
7
        receipt.Status = types.ReceiptStatusFailed
8
    } else {
9
        receipt.Status = types.ReceiptStatusSuccessful
10
    }
11
    receipt.TxHash = tx.Hash()
12
    receipt.GasUsed = result.UsedGas
13

14
    if tx.Type() == types.BlobTxType {
15
        receipt.BlobGasUsed = uint64(len(tx.BlobHashes()) * params.BlobTxBlobGasPerBlob)
16
        receipt.BlobGasPrice = evm.Context.BlobBaseFee
17
    }
18

19
    if tx.To() == nil {
20
        receipt.ContractAddress = crypto.CreateAddress(evm.TxContext.Origin, tx.Nonce())
21
    }
22

23
    receipt.Logs = statedb.GetLogs(tx.Hash(), blockNumber.Uint64(), blockHash, blockTime)
24
    receipt.Bloom = types.CreateBloom(receipt)
25
    return receipt
26
}

Key fields in the receipt:

• Status: 1 (success) or 0 (failure). Post-Byzantium, this replaced the post-state root.
• CumulativeGasUsed: Running total of gas used by all transactions in the block up to and including this one.
• GasUsed: Gas consumed by this individual transaction.
• ContractAddress: If the transaction created a contract, the new contract’s address (derived from sender + nonce).
• Logs: Events emitted during EVM execution.
• Bloom: A 2048-bit bloom filter over the logs, used for efficient log filtering.

Before receipt creation, ApplyTransactionWithEVM also calls statedb.Finalise(true) (post-Byzantium) to promote dirty state into the pending trie, preparing the state for the next transaction.

The ExecutionResult#

The execute() method returns an ExecutionResult that captures the outcome:

1
type ExecutionResult struct {
2
    UsedGas    uint64 // Total gas used (after refunds)
3
    MaxUsedGas uint64 // Peak gas consumed during execution (before refunds)
4
    Err        error  // EVM error (nil = success, non-nil = reverted/OOG/etc.)
5
    ReturnData []byte // Data returned by the EVM
6
}
7

8
func (result *ExecutionResult) Failed() bool { return result.Err != nil }

Failed() returns true for any EVM error. Even when Failed() is true, the transaction is included in the block — gas is consumed, the nonce is incremented, but the EVM’s state changes are reverted. The receipt’s status will be 0 (failed).

The EVM Context#

The EVM needs two kinds of context — block-level and transaction-level. Both are constructed in core/evm.go:

1
func NewEVMBlockContext(header *types.Header, chain ChainContext, author *common.Address) vm.BlockContext {
2
    // ...
3
    return vm.BlockContext{
4
        CanTransfer: CanTransfer,
5
        Transfer:    Transfer,
6
        GetHash:     GetHashFn(header, chain),
7
        Coinbase:    beneficiary,
8
        BlockNumber: new(big.Int).Set(header.Number),
9
        Time:        header.Time,
10
        Difficulty:  new(big.Int).Set(header.Difficulty),
11
        BaseFee:     baseFee,
12
        BlobBaseFee: blobBaseFee,
13
        GasLimit:    header.GasLimit,
14
        Random:      random,
15
    }
16
}

• CanTransfer and Transfer are function values that check balances and move ETH. By injecting them as functions, the EVM doesn’t need to know about StateDB specifics.
• GetHash returns a closure that looks up ancestor block hashes by number (needed for the BLOCKHASH opcode). It uses a cache that lazily fills from the chain.
• Random is the post-Merge RANDAO mix (the MixDigest header field when Difficulty == 0), exposed to the EVM via the PREVRANDAO opcode.

The transaction context is simpler:

1
func NewEVMTxContext(msg *Message) vm.TxContext {
2
    ctx := vm.TxContext{
3
        Origin:     msg.From,
4
        GasPrice:   new(big.Int).Set(msg.GasPrice),
5
        BlobHashes: msg.BlobHashes,
6
    }
7
    if msg.BlobGasFeeCap != nil {
8
        ctx.BlobFeeCap = new(big.Int).Set(msg.BlobGasFeeCap)
9
    }
10
    return ctx
11
}

Origin is the transaction sender (used by the ORIGIN opcode) and GasPrice is the effective gas price (used by GASPRICE).

What’s Next#

This chapter traced the execution pipeline from Process() down to the EVM dispatch and back. The EVM itself — the bytecode interpreter, opcode dispatch, gas metering, memory/stack management, and nested calls — is covered in Chapter 07 — The EVM Deep Dive.