Section 01: RLP Types

Source Files

• specs/execution-specs/src/ethereum/forks/amsterdam/block_access_lists/rlp_types.py (121 lines)

Overview

This file defines the canonical RLP data structures for Block-Level Access Lists. Every BAL transmitted over the network or validated during block processing uses these exact types. The file is 121 lines—small but foundational.

Module Docstring (lines 1-8)

"""
Defines the RLP data structures for Block-Level Access Lists
as specified in EIP-7928. These structures enable efficient encoding and
decoding of all accounts and storage locations accessed during block execution.

The encoding follows the pattern:
address -> field -> block_access_index -> change.
"""

• Top level: list of accounts (by address)
• Per account: grouped by field type (storage, balance, nonce, code)
• Per field: ordered by block_access_index
• Leaf: the actual change value

• Efficient compression (addresses deduplicated)
• Parallel prefetching (all slots for an address together)
• Clear change attribution (which tx caused what)

Imports (lines 9-15)

from dataclasses import dataclass
from typing import List, Tuple

from ethereum_types.bytes import Bytes, Bytes20
from ethereum_types.frozen import slotted_freezable
from ethereum_types.numeric import U64, U256, Uint

• Slotted: Uses __slots__ for memory efficiency (no __dict__)
• Freezable: Instances are immutable after creation

Type Aliases (lines 17-23)

# Type aliases for clarity (matching EIP-7928 specification)
Address = Bytes20
StorageKey = U256
StorageValue = U256
CodeData = Bytes
BlockAccessIndex = Uint  # uint16 in the spec, but using Uint for compatibility
Balance = U256  # Post-transaction balance in wei
Nonce = U64

Why these specific types?

BlockAccessIndex: uint16 vs Uint

The comment is important:

BlockAccessIndex = Uint  # uint16 in the spec, but using Uint for compatibility

# Constants chosen to support a 630m block gas limit
MAX_TXS = 30_000

At 630M gas with ~21,000 gas per simple transfer, you get ~30,000 transactions max. The uint16 limit (65,535) provides headroom.

• 0 = pre-execution phase (system contracts before tx 1)
• 1 to n = transaction indices (1-indexed, not 0-indexed!)
• n+1 = post-execution phase (withdrawals, post-block system calls)

Constants (lines 25-30)

# Constants chosen to support a 630m block gas limit
MAX_TXS = 30_000
# MAX_SLOTS = 300_000
# MAX_ACCOUNTS = 300_000
MAX_CODE_SIZE = 24_576
MAX_CODE_CHANGES = 1

MAX_TXS = 30,000

Derived from: 630M gas ÷ 21,000 gas/transfer ≈ 30,000.

This caps BlockAccessIndex values. Any BAL with an index > MAX_TXS + 1 is invalid.

MAX_CODE_SIZE = 24,576

From EIP-170. Contract bytecode cannot exceed 24 KiB. This bounds the size of CodeData in CodeChange.

MAX_CODE_CHANGES = 1

• CREATE/CREATE2 deploys code once
• SELFDESTRUCT (in same tx) clears it once
• EIP-7702 sets delegation once

Commented-out constants

# MAX_SLOTS = 300_000
# MAX_ACCOUNTS = 300_000

These were considered but not enforced. In practice, gas limits bound these implicitly.

StorageChange (lines 32-42)

@slotted_freezable
@dataclass
class StorageChange:
    """
    Storage change: [block_access_index, new_value].
    RLP encoded as a list.
    """

    block_access_index: BlockAccessIndex
    new_value: StorageValue

# TX 3 sets storage to 0x42
change = StorageChange(block_access_index=Uint(3), new_value=U256(0x42))
# RLP: [0x03, 0x42] → 0xc20342

Recording the post-value (not the change amount) enables state reconstruction without knowing the pre-state. This is essential for executionless sync.

BalanceChange (lines 44-54)

@slotted_freezable
@dataclass
class BalanceChange:
    """
    Balance change: [block_access_index, post_balance].
    RLP encoded as a list.
    """

    block_access_index: BlockAccessIndex
    post_balance: Balance

NonceChange (lines 56-66)

@slotted_freezable
@dataclass
class NonceChange:
    """
    Nonce change: [block_access_index, new_nonce].
    RLP encoded as a list.
    """

    block_access_index: BlockAccessIndex
    new_nonce: Nonce

• Transaction sender: nonce increments
• Contract using CREATE/CREATE2: nonce increments
• Newly deployed contract: nonce set to 1 (EIP-161)

CodeChange (lines 68-78)

@slotted_freezable
@dataclass
class CodeChange:
    """
    Code change: [block_access_index, new_code].
    RLP encoded as a list.
    """

    block_access_index: BlockAccessIndex
    new_code: CodeData

• Contract deployment: the deployed bytecode (after initcode runs)
• EIP-7702 delegation: 0xef0100 + 20-byte target address (23 bytes total)
• SELFDESTRUCT (same-tx): empty bytes b''

SlotChanges (lines 80-90)

@slotted_freezable
@dataclass
class SlotChanges:
    """
    All changes to a single storage slot: [slot, [changes]].
    RLP encoded as a list.
    """

    slot: StorageKey
    changes: Tuple[StorageChange, ...]

# Slot 0x01 modified by TX 2 (→0x100) and TX 5 (→0x200)
slot_changes = SlotChanges(
    slot=U256(0x01),
    changes=(
        StorageChange(Uint(2), U256(0x100)),
        StorageChange(Uint(5), U256(0x200)),
    )
)
# RLP: [0x01, [[0x02, 0x820100], [0x05, 0x820200]]]

AccountChanges (lines 92-115)

@slotted_freezable
@dataclass
class AccountChanges:
    """
    All changes for a single account, grouped by field type.
    RLP encoded as: [address, storage_changes, storage_reads,
    balance_changes, nonce_changes, code_changes].
    """

    address: Address

    # slot -> [block_access_index -> new_value]
    storage_changes: Tuple[SlotChanges, ...]

    # read-only storage keys
    storage_reads: Tuple[StorageKey, ...]

    # [block_access_index -> post_balance]
    balance_changes: Tuple[BalanceChange, ...]

    # [block_access_index -> new_nonce]
    nonce_changes: Tuple[NonceChange, ...]

    # [block_access_index -> new_code]
    code_changes: Tuple[CodeChange, ...]

• address (20 bytes)
• storage_changes (list of SlotChanges)
• storage_reads (list of StorageKey)
• balance_changes (list of BalanceChange)
• nonce_changes (list of NonceChange)
• code_changes (list of CodeChange)

Storage reads don't need post-values (there's nothing to reconstruct). Separating them:

• Reduces BAL size (~1/3 smaller per read vs write)
• Makes intent clear (read vs write)
• Enables different handling in clients (reads for prefetch, writes for state update)

BlockAccessList (line 118-121)

BlockAccessList = List[AccountChanges]

block_access_list_hash = keccak256(rlp.encode(block_access_list))

Cross-References

• Section 02 (RLP Utilities): Encoding/decoding functions for these types
• Section 06-07 (Builder): How these structures are constructed during execution
• Section 03-05 (State Tracker): The recording layer that feeds the builder
• EIP-7928: Canonical specification text

Gotchas

1. BlockAccessIndex is 1-indexed for transactions

# Transaction 1 has block_access_index = 1, NOT 0
# Index 0 is reserved for pre-execution
# Index n+1 is post-execution

2. Tuples, not Lists

All collection fields use Tuple[..., ...] (immutable) not List[...]. This ensures BAL structures can't be modified after creation.

3. storage_reads contains ONLY reads

A slot that was both read AND written goes in storage_changes, not storage_reads. The "read" is implicit in the write.

4. Empty code means cleared, not absent

CodeChange(block_access_index=Uint(3), new_code=b'')  # Code was CLEARED
# vs
code_changes=()  # No code change occurred

5. U256(0) RLP encoding

Zero encodes as empty RLP string 0x80, not 0x00:

rlp.encode(U256(0)) == b'\x80'  # Correct
rlp.encode(U256(0)) != b'\x00'  # Wrong

Section 02: RLP Utilities

Source

Imports (lines 16-24)

from typing import cast

from ethereum_rlp import Extended, rlp
from ethereum_types.bytes import Bytes
from ethereum_types.numeric import Uint

from ethereum.crypto.hash import Hash32, keccak256

from .rlp_types import BlockAccessList

compute_block_access_list_hash (lines 27-47)

def compute_block_access_list_hash(
    block_access_list: BlockAccessList,
) -> Hash32:
    block_access_list_bytes = rlp_encode_block_access_list(block_access_list)
    return keccak256(block_access_list_bytes)

• Builder produces BAL during execution
• compute_block_access_list_hash(bal) → hash in header
• Validator re-executes, builds BAL, computes hash
• Hash mismatch → block invalid

rlp_encode_block_access_list (lines 50-113)

def rlp_encode_block_access_list(block_access_list: BlockAccessList) -> Bytes:
    account_changes_list = []
    for account in block_access_list:
        storage_changes_list = [
            [
                slot_changes.slot,
                [
                    [Uint(c.block_access_index), c.new_value]
                    for c in slot_changes.changes
                ],
            ]
            for slot_changes in account.storage_changes
        ]

        storage_reads_list = list(account.storage_reads)

        balance_changes_list = [
            [Uint(bc.block_access_index), Uint(bc.post_balance)]
            for bc in account.balance_changes
        ]

        nonce_changes_list = [
            [Uint(nc.block_access_index), Uint(nc.new_nonce)]
            for nc in account.nonce_changes
        ]

        code_changes_list = [
            [Uint(cc.block_access_index), cc.new_code]
            for cc in account.code_changes
        ]

        account_changes_list.append(
            [
                account.address,
                storage_changes_list,
                storage_reads_list,
                balance_changes_list,
                nonce_changes_list,
                code_changes_list,
            ]
        )

    encoded = rlp.encode(cast(Extended, account_changes_list))
    return Bytes(encoded)

Encoding Structure

BlockAccessList = [
  AccountChanges_0,
  AccountChanges_1,
  ...
]

AccountChanges = [
  address,                    # Bytes20
  storage_changes,            # [[slot, [[idx, val], ...]], ...]
  storage_reads,              # [slot, ...]
  balance_changes,            # [[idx, balance], ...]
  nonce_changes,              # [[idx, nonce], ...]
  code_changes                # [[idx, code], ...]
]

Uint() Wrapping

Notice explicit Uint() conversions:

[Uint(c.block_access_index), c.new_value]
[Uint(bc.block_access_index), Uint(bc.post_balance)]

This ensures RLP integer encoding (minimal big-endian, no leading zeros). Without wrapping, Python ints might encode incorrectly.

No Validation

This function does NOT validate:

• Ordering (addresses sorted, slots sorted, indices ascending)
• Bounds (MAX_TXS, MAX_CODE_SIZE)
• Semantic correctness (valid indices)

What's Missing

The file is minimal—only encoding, no decoding. This is intentional:

• Block producers encode BALs they build
• Validators don't decode received BALs—they rebuild from execution and compare hashes
• Sync nodes using executionless sync would need decoding, but that's not in EELS yet

RLP Output Example

For a simple transfer (Alice → Bob, TX 1):

bal = [
    AccountChanges(
        address=ALICE,
        storage_changes=(),
        storage_reads=(),
        balance_changes=(BalanceChange(1, 4_000_000_000_000_000_000),),
        nonce_changes=(NonceChange(1, 43),),
        code_changes=(),
    ),
    AccountChanges(
        address=BOB,
        storage_changes=(),
        storage_reads=(),
        balance_changes=(BalanceChange(1, 2_000_000_000_000_000_000),),
        nonce_changes=(),
        code_changes=(),
    ),
]

# Encodes to (simplified):
# [
#   [alice_addr, [], [], [[1, 4e18]], [[1, 43]], []],
#   [bob_addr, [], [], [[1, 2e18]], [], []]
# ]

Cross-References

• Section 01: Type definitions being encoded
• Section 07: Where ordering/validation happens before encoding
• Section 08: blocks.py calls compute_block_access_list_hash

Section 03: State Tracker - Data Structures

Source

Module Docstring (lines 1-11)

"""
EIP-7928 Block Access Lists: Hierarchical State Change Tracking.

Frame hierarchy mirrors EVM execution: Block -> Transaction -> Call frames.
Each frame tracks state accesses and merges to parent on completion.

On success, changes merge upward with net-zero filtering (pre-state vs final).
On failure, only reads merge (writes discarded). Pre-state captures use
first-write-wins semantics and are stored at the transaction frame level.
"""

Three key concepts:

• Frame hierarchy: Block → Transaction → Call (nested arbitrarily deep)
• Merge semantics: Success = merge all; Failure = merge reads only
• First-write-wins: Pre-values captured on first access, not overwritten

StateChanges Dataclass (lines 24-56)

@dataclass
class StateChanges:
    parent: Optional["StateChanges"] = None
    block_access_index: BlockAccessIndex = BlockAccessIndex(0)

    touched_addresses: Set[Address] = field(default_factory=set)
    storage_reads: Set[Tuple[Address, Bytes32]] = field(default_factory=set)
    storage_writes: Dict[Tuple[Address, Bytes32, BlockAccessIndex], U256] = (
        field(default_factory=dict)
    )

    balance_changes: Dict[Tuple[Address, BlockAccessIndex], U256] = field(
        default_factory=dict
    )
    nonce_changes: Set[Tuple[Address, BlockAccessIndex, U64]] = field(
        default_factory=set
    )
    code_changes: Dict[Tuple[Address, BlockAccessIndex], Bytes] = field(
        default_factory=dict
    )

    # Pre-state captures (transaction-scoped)
    pre_balances: Dict[Address, U256] = field(default_factory=dict)
    pre_storage: Dict[Tuple[Address, Bytes32], U256] = field(default_factory=dict)
    pre_code: Dict[Address, Bytes] = field(default_factory=dict)

Field Breakdown

Why nonce_changes is a Set, not Dict

nonce_changes: Set[Tuple[Address, BlockAccessIndex, U64]]

Nonces only increment. Multiple nonce changes per address/tx can occur (CREATE inside a tx), but only the final nonce matters. Using a Set with the nonce value as part of the tuple allows deduplication during merge (keep highest).

Why storage_writes includes BlockAccessIndex in key

storage_writes: Dict[Tuple[Address, Bytes32, BlockAccessIndex], U256]

A single slot can be written by multiple transactions. The index in the key allows tracking each write separately, which is needed for the BAL's SlotChanges.changes list.

get_block_frame (lines 59-74)

def get_block_frame(state_changes: StateChanges) -> StateChanges:
    block_frame = state_changes
    while block_frame.parent is not None:
        block_frame = block_frame.parent
    return block_frame

Walks to root. Block frame has parent = None.

increment_block_access_index (lines 77-88)

def increment_block_access_index(root_frame: StateChanges) -> None:
    root_frame.block_access_index = BlockAccessIndex(
        root_frame.block_access_index + Uint(1)
    )

Called between transactions. Index 0 → 1 before tx 1, index 1 → 2 before tx 2, etc.

get_transaction_frame (lines 91-108)

def get_transaction_frame(state_changes: StateChanges) -> StateChanges:
    tx_frame = state_changes
    while tx_frame.parent is not None and tx_frame.parent.parent is not None:
        tx_frame = tx_frame.parent
    return tx_frame

Walks up until parent.parent is None. The tx frame is the direct child of the block frame.

• parent is None → block frame
• parent.parent is None → transaction frame
• parent.parent.parent is None → first call frame
• etc.

capture_pre_balance (lines 111-130)

def capture_pre_balance(
    tx_frame: StateChanges, address: Address, balance: U256
) -> None:
    assert tx_frame.parent is None or tx_frame.parent.parent is None
    if address not in tx_frame.pre_balances:
        tx_frame.pre_balances[address] = balance

capture_pre_storage (lines 133-156)

def capture_pre_storage(
    tx_frame: StateChanges, address: Address, key: Bytes32, value: U256
) -> None:
    assert tx_frame.parent is None or tx_frame.parent.parent is None
    slot = (address, key)
    if slot not in tx_frame.pre_storage:
        tx_frame.pre_storage[slot] = value

Same pattern. Pre-storage is used for net-zero filtering:

• If storage_writes[(addr, key, idx)] == pre_storage[(addr, key)], the write is converted to a read.

capture_pre_code (lines 159-178)

def capture_pre_code(
    tx_frame: StateChanges, address: Address, code: Bytes
) -> None:
    assert tx_frame.parent is None or tx_frame.parent.parent is None
    if address not in tx_frame.pre_code:
        tx_frame.pre_code[address] = code

Same pattern. Used for EIP-7702 delegation changes that might restore original code.

Frame Hierarchy Diagram

┌──────────────────────────────────────────────────────────┐
│ Block Frame (parent=None)                                │
│   block_access_index: managed here                       │
│   touched_addresses: accumulated from all txs            │
│   storage_reads/writes: final BAL data                   │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │ TX Frame (parent=block, parent.parent=None)        │  │
│  │   pre_balances, pre_storage, pre_code: captured    │  │
│  │   block_access_index: inherited from block         │  │
│  │                                                    │  │
│  │  ┌──────────────────────────────────────────────┐  │  │
│  │  │ Call Frame 1 (parent=tx)                     │  │  │
│  │  │   No pre-captures (delegated to tx frame)    │  │  │
│  │  │                                              │  │  │
│  │  │  ┌────────────────────────────────────────┐  │  │  │
│  │  │  │ Call Frame 2 (parent=call1)            │  │  │  │
│  │  │  │   Arbitrary nesting depth              │  │  │  │
│  │  │  └────────────────────────────────────────┘  │  │  │
│  │  └──────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

Cross-References

• Section 04: Recording functions (track_)
• Section 05: Frame management (merge_, commit_, filter_)
• Section 06-07: Builder consumes the block frame after all txs complete

Section 04: State Tracker - Recording Logic

Source

track_address (lines 188-201)

def track_address(state_changes: StateChanges, address: Address) -> None:
    state_changes.touched_addresses.add(address)

Called for every address access regardless of type. Even if no state changes, the address appears in the BAL.

• Transaction sender/recipient
• BALANCE, EXTCODESIZE, EXTCODECOPY, EXTCODEHASH targets
• CALL, DELEGATECALL, STATICCALL, CALLCODE targets
• CREATE, CREATE2 deployments
• Precompile calls
• System contract calls

track_storage_read (lines 204-220)

def track_storage_read(
    state_changes: StateChanges, address: Address, key: Bytes32
) -> None:
    state_changes.storage_reads.add((address, key))

Called on SLOAD. The slot goes into storage_reads initially. If the same slot is later written in the same tx, the final placement (reads vs writes) is determined by net-zero filtering at commit time.

track_storage_write (lines 223-243)

def track_storage_write(
    state_changes: StateChanges,
    address: Address,
    key: Bytes32,
    value: U256,
) -> None:
    idx = state_changes.block_access_index
    state_changes.storage_writes[(address, key, idx)] = value

Called on SSTORE. Note:

• Key includes block_access_index to track per-tx writes
• Value is the new value, not delta
• Same (addr, key, idx) overwrites previous (latest value wins within a tx)

track_balance_change (lines 246-265)

def track_balance_change(
    state_changes: StateChanges,
    address: Address,
    new_balance: U256,
) -> None:
    idx = state_changes.block_access_index
    state_changes.balance_changes[(address, idx)] = new_balance

Called when balance changes:

• Transaction value transfer
• Gas payment (sender)
• Gas refund (sender)
• Fee payment (COINBASE)
• SELFDESTRUCT balance transfer
• Withdrawals

track_nonce_change (lines 268-287)

def track_nonce_change(
    state_changes: StateChanges,
    address: Address,
    new_nonce: U64,
) -> None:
    idx = state_changes.block_access_index
    state_changes.nonce_changes.add((address, idx, new_nonce))

Called when:

• Transaction execution (sender nonce++)
• CREATE/CREATE2 (deployer nonce++)
• Newly deployed contract (nonce set to 1 per EIP-161)

track_code_change (lines 290-310)

def track_code_change(
    state_changes: StateChanges,
    address: Address,
    new_code: Bytes,
) -> None:
    idx = state_changes.block_access_index
    state_changes.code_changes[(address, idx)] = new_code

Called when:

• Contract deployment completes (CREATE/CREATE2 returns)
• EIP-7702 delegation set (0xef0100 + target)
• SELFDESTRUCT clears code (same-tx creation, new_code = b'')

track_selfdestruct (lines 313-365)

def track_selfdestruct(
    tx_frame: StateChanges,
    address: Address,
) -> None:
    assert tx_frame.parent is not None and tx_frame.parent.parent is None

    idx = tx_frame.block_access_index

    # Remove nonce changes from current transaction
    tx_frame.nonce_changes = {
        (addr, i, nonce)
        for addr, i, nonce in tx_frame.nonce_changes
        if not (addr == address and i == idx)
    }

    # Remove balance changes from current transaction
    if (address, idx) in tx_frame.balance_changes:
        pre_balance = tx_frame.pre_balances[address]
        if pre_balance == U256(0):
            del tx_frame.balance_changes[(address, idx)]

    # Remove code changes from current transaction
    if (address, idx) in tx_frame.code_changes:
        del tx_frame.code_changes[(address, idx)]

    # Convert storage writes from current transaction to reads
    for addr, key, i in list(tx_frame.storage_writes.keys()):
        if addr == address and i == idx:
            del tx_frame.storage_writes[(addr, key, i)]
            tx_frame.storage_reads.add((addr, key))

• Nonce: Removed (account ceases to exist)
• Balance: Kept only if pre-balance was non-zero (transfer to beneficiary is recorded)
• Code: Removed (no deployment in final state)
• Storage writes: Converted to reads (slots were accessed but final state is empty)

Recording Flow Example

TX 1: Alice (0xaaaa) sends 1 ETH to Bob (0xbbbb)

1. begin_transaction(block_frame) → tx_frame created
2. increment_block_access_index(block_frame) → idx = 1

3. track_address(tx_frame, ALICE)
4. capture_pre_balance(tx_frame, ALICE, 5 ETH)
5. track_balance_change(tx_frame, ALICE, 3.999 ETH)  # after value + gas
6. track_nonce_change(tx_frame, ALICE, 43)

7. track_address(tx_frame, BOB)
8. capture_pre_balance(tx_frame, BOB, 1 ETH)
9. track_balance_change(tx_frame, BOB, 2 ETH)

10. track_address(tx_frame, COINBASE)
11. capture_pre_balance(tx_frame, COINBASE, 100 ETH)
12. track_balance_change(tx_frame, COINBASE, 100.001 ETH)

13. commit_transaction_frame(tx_frame)  # filters net-zero, merges to block

Cross-References

• Section 03: StateChanges dataclass these functions populate
• Section 05: merge_ and commit_ that consume the recorded data
• Section 09: VM integration showing where track_* is called from EVM opcodes

Section 05: State Tracker - Frame Management

Source

merge_on_success (lines 368-412)

def merge_on_success(child_frame: StateChanges) -> None:
    assert child_frame.parent is not None
    parent_frame = child_frame.parent

    # Merge address accesses
    parent_frame.touched_addresses.update(child_frame.touched_addresses)

    # Merge storage: reads union, writes overwrite
    parent_frame.storage_reads.update(child_frame.storage_reads)
    for storage_key, storage_value in child_frame.storage_writes.items():
        parent_frame.storage_writes[storage_key] = storage_value

    # Merge balance changes: child overwrites parent
    for balance_key, balance_value in child_frame.balance_changes.items():
        parent_frame.balance_changes[balance_key] = balance_value

    # Merge nonce changes: keep highest nonce per address
    address_final_nonces: Dict[Address, Tuple[BlockAccessIndex, U64]] = {}
    for addr, idx, nonce in child_frame.nonce_changes:
        if addr not in address_final_nonces or nonce > address_final_nonces[addr][1]:
            address_final_nonces[addr] = (idx, nonce)
    for addr, (idx, final_nonce) in address_final_nonces.items():
        parent_frame.nonce_changes.add((addr, idx, final_nonce))

    # Merge code changes: child overwrites parent
    for code_key, code_value in child_frame.code_changes.items():
        parent_frame.code_changes[code_key] = code_value

Called when a call frame returns successfully (no revert).

• touched_addresses: Union (both parent and child addresses kept)
• storage_reads: Union
• storage_writes: Child overwrites (latest value wins)
• balance_changes: Child overwrites
• nonce_changes: Keep highest nonce per address
• code_changes: Child overwrites

merge_on_failure (lines 415-437)

def merge_on_failure(child_frame: StateChanges) -> None:
    assert child_frame.parent is not None
    parent_frame = child_frame.parent

    # Only merge reads and address accesses on failure
    parent_frame.touched_addresses.update(child_frame.touched_addresses)
    parent_frame.storage_reads.update(child_frame.storage_reads)

    # Convert writes to reads
    for address, key, _idx in child_frame.storage_writes.keys():
        parent_frame.storage_reads.add((address, key))

    # balance_changes, nonce_changes, code_changes: NOT merged

Called when a call frame reverts.

• touched_addresses: Merged (addresses were still accessed)
• storage_reads: Merged
• storage_writes: Converted to reads (write happened but was reverted)
• balance_changes: Discarded
• nonce_changes: Discarded
• code_changes: Discarded

commit_transaction_frame (lines 440-477)

def commit_transaction_frame(tx_frame: StateChanges) -> None:
    assert tx_frame.parent is not None
    block_frame = tx_frame.parent

    # Filter net-zero changes before committing
    filter_net_zero_frame_changes(tx_frame)

    # Merge all state to block frame
    block_frame.touched_addresses.update(tx_frame.touched_addresses)
    block_frame.storage_reads.update(tx_frame.storage_reads)
    for (addr, key, idx), value in tx_frame.storage_writes.items():
        block_frame.storage_writes[(addr, key, idx)] = value
    for (addr, idx), final_balance in tx_frame.balance_changes.items():
        block_frame.balance_changes[(addr, idx)] = final_balance
    for addr, idx, nonce in tx_frame.nonce_changes:
        block_frame.nonce_changes.add((addr, idx, nonce))
    for (addr, idx), final_code in tx_frame.code_changes.items():
        block_frame.code_changes[(addr, idx)] = final_code

Called after successful tx execution (or after rollback_transaction if failed).

create_child_frame (lines 480-504)

def create_child_frame(parent: StateChanges) -> StateChanges:
    return StateChanges(
        parent=parent,
        block_access_index=parent.block_access_index,
    )

Creates a new frame linked to parent. Inherits block_access_index so track functions don't need to walk up the hierarchy.

filter_net_zero_frame_changes (lines 507-558)

def filter_net_zero_frame_changes(tx_frame: StateChanges) -> None:
    idx = tx_frame.block_access_index

    # Filter storage: convert net-zero writes to reads
    addresses_to_check_storage = [
        (addr, key)
        for (addr, key, i) in tx_frame.storage_writes.keys()
        if i == idx
    ]
    for addr, key in addresses_to_check_storage:
        assert (addr, key) in tx_frame.pre_storage
        pre_value = tx_frame.pre_storage[(addr, key)]
        post_value = tx_frame.storage_writes[(addr, key, idx)]
        if pre_value == post_value:
            del tx_frame.storage_writes[(addr, key, idx)]
            tx_frame.storage_reads.add((addr, key))

    # Filter balance: remove if pre == post
    addresses_to_check_balance = [
        addr for (addr, i) in tx_frame.balance_changes.keys() if i == idx
    ]
    for addr in addresses_to_check_balance:
        assert addr in tx_frame.pre_balances
        pre_balance = tx_frame.pre_balances[addr]
        post_balance = tx_frame.balance_changes[(addr, idx)]
        if pre_balance == post_balance:
            del tx_frame.balance_changes[(addr, idx)]

    # Filter code: remove if pre == post
    addresses_to_check_code = [
        addr for (addr, i) in tx_frame.code_changes.keys() if i == idx
    ]
    for addr in addresses_to_check_code:
        assert addr in tx_frame.pre_code
        pre_code = tx_frame.pre_code[addr]
        post_code = tx_frame.code_changes[(addr, idx)]
        if pre_code == post_code:
            del tx_frame.code_changes[(addr, idx)]

    # Nonces: no filtering (only increment, never net-zero)

// Pre-tx: slot[0] = 100
function foo() {
    slot[0] = 200;  // track_storage_write(addr, 0, 200)
    slot[0] = 300;  // track_storage_write(addr, 0, 300) - overwrites
    slot[0] = 100;  // track_storage_write(addr, 0, 100) - overwrites
}
// Post-tx: slot[0] = 100

pre_storage[(addr, 0)] = 100
storage_writes[(addr, 0, idx)] = 100
pre == post → delete from storage_writes, add to storage_reads

begin_transaction():
    tx_frame = create_child_frame(block_frame)

execute_transaction():
    for each call:
        call_frame = create_child_frame(parent)
        execute_call()
        if success:
            merge_on_success(call_frame)
        else:
            merge_on_failure(call_frame)

end_transaction():
    if success:
        commit_transaction_frame(tx_frame)  # includes net-zero filter
    else:
        merge_on_failure(tx_frame)  # discards value changes
        commit_transaction_frame(tx_frame)  # commits reads only

• Section 03: StateChanges dataclass
• Section 04: track_ functions that populate frames
• Section 06-07: Builder consumes block_frame after all txs
• Section 08: blocks.py orchestrates this lifecycle

Section 06: BAL Builder - Construction

Source Files

• specs/execution-specs/src/ethereum/forks/amsterdam/block_access_lists/builder.py (lines 1-290)

Overview

The BAL builder sits between the state tracker (Sections 03-05) and the final BlockAccessList output. During block execution, the state tracker records every state access. After execution completes, those recorded changes are fed to the builder, which:

• Organizes changes by address, then by field type
• Deduplicates within-transaction writes (only final value matters)
• Prepares the data structure for sorting and finalization (Section 07)

Module Docstring (lines 1-14)

"""
Implements the Block Access List builder that tracks all account
and storage accesses during block execution and constructs the final
[`BlockAccessList`].

The builder follows a two-phase approach:

1. **Collection Phase**: During transaction execution, all state accesses are
   recorded via the tracking functions.
2. **Build Phase**: After block execution, the accumulated data is sorted
   and encoded into the final deterministic format.

[`BlockAccessList`]: ref:ethereum.forks.amsterdam.block_access_lists.rlp_types.BlockAccessList
"""

• Collection phase (this section): Fast, append-mostly operations during hot execution
• Build phase (Section 07): One-time sorting and encoding after execution

Imports (lines 15-31)

from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Dict, List, Set

from ethereum_types.bytes import Bytes
from ethereum_types.numeric import U64, U256

from ..fork_types import Address
from .rlp_types import (
    AccountChanges,
    BalanceChange,
    BlockAccessIndex,
    BlockAccessList,
    CodeChange,
    NonceChange,
    SlotChanges,
    StorageChange,
)

if TYPE_CHECKING:
    from ..state_tracker import StateChanges

rlp_types.py (pure data)
     ↑
builder.py (construction)
     ↑
state_tracker.py (recording during execution)

The builder can import from rlp_types but only type-check against state_tracker.

AccountData Dataclass (lines 33-62)

@dataclass
class AccountData:
    """
    Account data stored in the builder during block execution.

    This dataclass tracks all changes made to a single account throughout
    the execution of a block, organized by the type of change and the
    transaction index where it occurred.
    """

    storage_changes: Dict[U256, List[StorageChange]] = field(
        default_factory=dict
    )
    """
    Mapping from storage slot to list of changes made to that slot.
    Each change includes the transaction index and new value.
    """

    storage_reads: Set[U256] = field(default_factory=set)
    """
    Set of storage slots that were read but not modified.
    """

    balance_changes: List[BalanceChange] = field(default_factory=list)
    """
    List of balance changes for this account, ordered by transaction index.
    """

    nonce_changes: List[NonceChange] = field(default_factory=list)
    """
    List of nonce changes for this account, ordered by transaction index.
    """

    code_changes: List[CodeChange] = field(default_factory=list)
    """
    List of code changes (contract deployments) for this account,
    ordered by transaction index.
    """

Design Rationale

Storage changes need two levels of grouping:

• By slot (outer dict key)
• By transaction (inner list elements)

Lists preserve insertion order and allow append operations. Changes are typically added in transaction order. The final sorting happens in the build phase, not during collection.

Read tracking only cares about "was this slot read?" — the transaction index doesn't matter for reads. A set provides:

• O(1) membership testing
• Automatic deduplication
• Simpler data structure

Memory Layout

Each AccountData instance contains:

• 1 dict (storage_changes)
• 1 set (storage_reads)
• 3 lists (balance, nonce, code)

• Dict overhead: ~232 bytes (empty Python dict)
• Set overhead: ~216 bytes (empty Python set)
• List overhead: ~56 bytes × 3 = 168 bytes
• Total base: ~616 bytes per touched account

BlockAccessListBuilder Dataclass (lines 64-79)

@dataclass
class BlockAccessListBuilder:
    """
    Builder for constructing [`BlockAccessList`] efficiently during transaction
    execution.

    The builder accumulates all account and storage accesses during block
    execution and constructs a deterministic access list. Changes are tracked
    by address, field type, and transaction index to enable efficient
    reconstruction of state changes.

    [`BlockAccessList`]: ref:ethereum.forks.amsterdam.block_access_lists.rlp_types.BlockAccessList
    """

    accounts: Dict[Address, AccountData] = field(default_factory=dict)
    """
    Mapping from account address to its tracked changes during block execution.
    """

EELS follows a functional style. Functions operating on dataclasses are:

• Easier to test (pure functions)
• Easier to reason about (no hidden state)
• Consistent with the rest of the spec

ensure_account (lines 81-99)

def ensure_account(builder: BlockAccessListBuilder, address: Address) -> None:
    """
    Ensure an account exists in the builder's tracking structure.

    Creates an empty [`AccountData`] entry for the given address if it
    doesn't already exist. This function is idempotent and safe to call
    multiple times for the same address.

    Parameters
    ----------
    builder :
        The block access list builder instance.
    address :
        The account address to ensure exists.

    [`AccountData`] :
        ref:ethereum.forks.amsterdam.block_access_lists.builder.AccountData

    """
    if address not in builder.accounts:
        builder.accounts[address] = AccountData()

Every recording function needs this check. Factoring it out:

• Reduces code duplication
• Makes the intent clear ("ensure exists, then operate")
• Allows future changes (e.g., logging, metrics) in one place

# Could use defaultdict instead:
accounts: Dict[Address, AccountData] = field(
    default_factory=lambda: defaultdict(AccountData)
)

EELS prefers explicit checks over implicit defaultdict behavior. Explicit is clearer for spec-reading.

add_storage_write (lines 101-148)

def add_storage_write(
    builder: BlockAccessListBuilder,
    address: Address,
    slot: U256,
    block_access_index: BlockAccessIndex,
    new_value: U256,
) -> None:
    """
    Add a storage write operation to the block access list.

    Records a storage slot modification for a given address at a specific
    transaction index. If multiple writes occur to the same slot within the
    same transaction (same block_access_index), only the final value is kept.

    Parameters
    ----------
    builder :
        The block access list builder instance.
    address :
        The account address whose storage is being modified.
    slot :
        The storage slot being written to.
    block_access_index :
        The block access index for this change (0 for pre-execution,
        1..n for transactions, n+1 for post-execution).
    new_value :
        The new value being written to the storage slot.

    """
    ensure_account(builder, address)

    if slot not in builder.accounts[address].storage_changes:
        builder.accounts[address].storage_changes[slot] = []

    # Check if there's already an entry with the same block_access_index
    # If so, update it with the new value, keeping only the final write
    changes = builder.accounts[address].storage_changes[slot]
    for i, existing_change in enumerate(changes):
        if existing_change.block_access_index == block_access_index:
            # Update the existing entry with the new value
            changes[i] = StorageChange(
                block_access_index=block_access_index, new_value=new_value
            )
            return

    # No existing entry found, append new change
    change = StorageChange(
        block_access_index=block_access_index, new_value=new_value
    )
    builder.accounts[address].storage_changes[slot].append(change)

Same-Transaction Deduplication

Example:

# TX 3 writes slot 0x01 three times
add_storage_write(builder, addr, slot=0x01, index=3, value=0x100)
add_storage_write(builder, addr, slot=0x01, index=3, value=0x200)
add_storage_write(builder, addr, slot=0x01, index=3, value=0x300)
# Result: only StorageChange(index=3, value=0x300) stored

Cross-Transaction Preservation

Different transactions create separate entries:

# TX 2 and TX 5 both write slot 0x01
add_storage_write(builder, addr, slot=0x01, index=2, value=0xAAA)
add_storage_write(builder, addr, slot=0x01, index=5, value=0xBBB)
# Result: two entries
#   StorageChange(index=2, value=0xAAA)
#   StorageChange(index=5, value=0xBBB)

Both are preserved because they represent different states at different block heights (post-TX2, post-TX5).

Complexity Analysis

The linear scan for i, existing_change in enumerate(changes) looks slow, but:

• Most slots are written by 1-2 transactions per block
• Hot slots (like AMM pool reserves) might see ~10-50 writes
• At 50 writes per slot, linear scan is still fast enough

# Alternative structure (not used)
storage_changes: Dict[U256, Dict[BlockAccessIndex, U256]]

EELS prefers the simpler List for readability.

add_storage_read (lines 150-173)

def add_storage_read(
    builder: BlockAccessListBuilder, address: Address, slot: U256
) -> None:
    """
    Add a storage read operation to the block access list.

    Records that a storage slot was read during execution. Storage slots
    that are both read and written will only appear in the storage changes
    list, not in the storage reads list, as per [EIP-7928].

    Parameters
    ----------
    builder :
        The block access list builder instance.
    address :
        The account address whose storage is being read.
    slot :
        The storage slot being read.

    [EIP-7928]: https://eips.ethereum.org/EIPS/eip-7928

    """
    ensure_account(builder, address)
    builder.accounts[address].storage_reads.add(slot)

Read vs Write Exclusivity

The docstring notes: "Storage slots that are both read and written will only appear in the storage changes list."

This filtering happens in the build phase (Section 07), not here. During collection, we record both reads and writes. The build phase excludes reads for slots that also have writes.

Because writes might be reverted. A slot that was written in a failed call still needs to be tracked as a read (the read happened, even though the write didn't persist).

Example:

SLOAD(slot)    → recorded as read
CALL(...)      → nested call writes slot, then REVERTs
SLOAD(slot)    → slot appears in reads (write was discarded)

add_balance_change (lines 175-218)

def add_balance_change(
    builder: BlockAccessListBuilder,
    address: Address,
    block_access_index: BlockAccessIndex,
    post_balance: U256,
) -> None:
    """
    Add a balance change to the block access list.

    Records the post-transaction balance for an account after it has been
    modified. This includes changes from transfers, gas fees, block rewards,
    and any other balance-affecting operations.

    Parameters
    ----------
    builder :
        The block access list builder instance.
    address :
        The account address whose balance changed.
    block_access_index :
        The block access index for this change (0 for pre-execution,
        1..n for transactions, n+1 for post-execution).
    post_balance :
        The account balance after the change as U256.

    """
    ensure_account(builder, address)

    # Balance value is already U256
    balance_value = post_balance

    # Check if we already have a balance change for this tx_index and update it
    # This ensures we only track the final balance per transaction
    existing_changes = builder.accounts[address].balance_changes
    for i, existing in enumerate(existing_changes):
        if existing.block_access_index == block_access_index:
            # Update the existing balance change with the new balance
            existing_changes[i] = BalanceChange(
                block_access_index=block_access_index,
                post_balance=balance_value,
            )
            return

    # No existing change for this tx_index, add a new one
    change = BalanceChange(
        block_access_index=block_access_index, post_balance=balance_value
    )
    builder.accounts[address].balance_changes.append(change)

Same-Transaction Deduplication (Again)

Same pattern as storage writes: multiple balance changes within one transaction → keep only the final value.

A transaction can modify an account's balance multiple times:

• Gas deduction at start
• Value transfer (msg.value)
• Internal transfers via CALL
• Gas refund at end
• Priority fee payment to COINBASE

Example: COINBASE Balance Tracking

The block builder (COINBASE) receives fees from every transaction:

# TX 1: COINBASE balance → 1.0 ETH
add_balance_change(builder, COINBASE, index=1, post_balance=1e18)
# TX 2: COINBASE balance → 1.5 ETH
add_balance_change(builder, COINBASE, index=2, post_balance=1.5e18)
# TX 3: COINBASE balance → 2.2 ETH
add_balance_change(builder, COINBASE, index=3, post_balance=2.2e18)

Result: 3 separate BalanceChange entries (different indices).

No Pre-Balance Capture Here

Note that this function records post-balance, not the delta. Pre-balance capture happens in the state tracker (Section 04) via capture_pre_balance. The builder doesn't need to know the pre-state—it just records what the state tracker tells it.

add_nonce_change (lines 220-262)

def add_nonce_change(
    builder: BlockAccessListBuilder,
    address: Address,
    block_access_index: BlockAccessIndex,
    new_nonce: U64,
) -> None:
    """
    Add a nonce change to the block access list.

    Records a nonce increment for an account. This occurs when an EOA sends
    a transaction or when a contract performs [`CREATE`] or [`CREATE2`]
    operations.

    Parameters
    ----------
    builder :
        The block access list builder instance.
    address :
        The account address whose nonce changed.
    block_access_index :
        The block access index for this change (0 for pre-execution,
        1..n for transactions, n+1 for post-execution).
    new_nonce :
        The new nonce value after the change.

    [`CREATE`]: ref:ethereum.forks.amsterdam.vm.instructions.system.create
    [`CREATE2`]: ref:ethereum.forks.amsterdam.vm.instructions.system.create2

    """
    ensure_account(builder, address)

    # Check if we already have a nonce change for this tx_index and update it
    # This ensures we only track the final (highest) nonce per transaction
    existing_changes = builder.accounts[address].nonce_changes
    for i, existing in enumerate(existing_changes):
        if existing.block_access_index == block_access_index:
            # Keep the highest nonce value
            if new_nonce > existing.new_nonce:
                existing_changes[i] = NonceChange(
                    block_access_index=block_access_index, new_nonce=new_nonce
                )
            return

    # No existing change for this tx_index, add a new one
    change = NonceChange(
        block_access_index=block_access_index, new_nonce=new_nonce
    )
    builder.accounts[address].nonce_changes.append(change)

Highest-Nonce-Wins Semantics

Unlike balance and storage (which keep the last value), nonce keeps the highest value:

if new_nonce > existing.new_nonce:
    # Update only if new nonce is higher

Nonces only ever increase. If we see nonce=5 then nonce=3 for the same transaction, something is wrong. By keeping the highest, we're effectively keeping the final state (since nonce can only go up).

A factory contract deploying multiple contracts:

contract Factory {
    function deploy() external {
        new Child();  // nonce++ → 1
        new Child();  // nonce++ → 2
        new Child();  // nonce++ → 3
    }
}

All three increments happen in the same transaction. We want to record nonce=3, not nonce=1.

add_code_change (lines 264-306)

def add_code_change(
    builder: BlockAccessListBuilder,
    address: Address,
    block_access_index: BlockAccessIndex,
    new_code: Bytes,
) -> None:
    """
    Add a code change to the block access list.

    Records contract code deployment or modification. This typically occurs
    during contract creation via [`CREATE`], [`CREATE2`], or [`SETCODE`]
    operations.

    Parameters
    ----------
    builder :
        The block access list builder instance.
    address :
        The account address receiving new code.
    block_access_index :
        The block access index for this change (0 for pre-execution,
        1..n for transactions, n+1 for post-execution).
    new_code :
        The deployed contract bytecode.

    [`CREATE`]: ref:ethereum.forks.amsterdam.vm.instructions.system.create
    [`CREATE2`]: ref:ethereum.forks.amsterdam.vm.instructions.system.create2

    """
    ensure_account(builder, address)

    # Check if we already have a code change for this block_access_index
    # This handles the case of in-transaction selfdestructs where code is
    # first deployed and then cleared in the same transaction
    existing_changes = builder.accounts[address].code_changes
    for i, existing in enumerate(existing_changes):
        if existing.block_access_index == block_access_index:
            # Replace the existing code change with the new one
            # For selfdestructs, this ensures we only record the final state (empty code)
            existing_changes[i] = CodeChange(
                block_access_index=block_access_index, new_code=new_code
            )
            return

    # No existing change for this block_access_index, add a new one
    change = CodeChange(
        block_access_index=block_access_index, new_code=new_code
    )
    builder.accounts[address].code_changes.append(change)

The SELFDESTRUCT Edge Case

The comment is explicit:

# This handles the case of in-transaction selfdestructs where code is
# first deployed and then cleared in the same transaction

Scenario:

// In the same TX:
// 1. Deploy contract at address X → code = 0x6080...
// 2. Call X.selfdestruct() → code = 0x (empty)

Both operations have the same block_access_index. The BAL should record code = 0x (the final state), not code = 0x6080....

SETCODE (EIP-7702)

The docstring mentions SETCODE. This is the EIP-7702 delegation operation that allows EOAs to temporarily set code. The code change format is:

# EIP-7702 delegation code
new_code = b'\xef\x01\x00' + delegate_address  # 23 bytes total

The builder doesn't care about the format—it just records whatever new_code it receives.

add_touched_account (lines 308-334)

def add_touched_account(
    builder: BlockAccessListBuilder, address: Address
) -> None:
    """
    Add an account that was accessed but not modified.

    Records that an account was accessed during execution without any state
    changes. This is used for operations like [`EXTCODEHASH`], [`BALANCE`],
    [`EXTCODESIZE`], and [`EXTCODECOPY`] that read account data without
    modifying it.

    Parameters
    ----------
    builder :
        The block access list builder instance.
    address :
        The account address that was accessed.

    [`EXTCODEHASH`] :
        ref:ethereum.forks.amsterdam.vm.instructions.environment.extcodehash
    [`BALANCE`] :
        ref:ethereum.forks.amsterdam.vm.instructions.environment.balance
    [`EXTCODESIZE`] :
        ref:ethereum.forks.amsterdam.vm.instructions.environment.extcodesize
    [`EXTCODECOPY`] :
        ref:ethereum.forks.amsterdam.vm.instructions.environment.extcodecopy

    """
    ensure_account(builder, address)

An account that was accessed but not modified still appears in the BAL. This enables:

• Prefetching: Clients can load the account's state ahead of execution
• Proof generation: State proofs need to include accessed accounts
• Witness completeness: Stateless execution needs ALL accessed data

Cross-References

• Section 01 (RLP Types): The StorageChange, BalanceChange, NonceChange, CodeChange types used here
• Section 03-05 (State Tracker): The frame-based recording that feeds StateChanges to the builder
• Section 07 (Builder Finalization): The _build_from_builder and build_block_access_list functions that consume the builder
• Section 09 (VM Integration): Where the EVM calls these recording functions

Gotchas

1. Same-Transaction Semantics Vary by Field

2. Reads Are Not Per-Transaction

Storage reads go into a Set[U256], not a list of (index, slot) pairs. The BAL doesn't track which transaction read a slot—just that it was read.

3. Read/Write Filtering Is Deferred

A slot can be in BOTH storage_reads and storage_changes during collection. The filtering (exclude reads for written slots) happens in the build phase.

4. AccountData Is Mutable

Unlike the final AccountChanges (which uses tuples), AccountData uses mutable lists and dicts. This is intentional—collection needs mutation; finalization produces immutable output.

5. No Validation Here

The builder doesn't validate:

• Whether block_access_index is in range
• Whether new_code fits in MAX_CODE_SIZE
• Whether the slot/balance/nonce values are valid

6. Empty Accounts Are Still Tracked

An account touched but never modified results in an AccountData with all-empty collections. This is correct—the address still appears in the final BAL.

Complexity Summary

Section 07: BAL Builder - Finalization

Source Files

• specs/execution-specs/src/ethereum/forks/amsterdam/block_access_lists/builder.py (lines 336-475)

Overview

After block execution completes, the accumulated changes in the builder must be transformed into a deterministic BlockAccessList. This section covers the finalization phase:

• Sorting: All entries are sorted to ensure consensus-critical determinism
• Read/Write Filtering: Slots that were both read and written appear only in writes
• Flattening: The nested AccountData structure becomes flat AccountChanges tuples
• Integration: How StateChanges from the state tracker flows into the builder

add_touched_account (lines 336-369)

def add_touched_account(
    builder: BlockAccessListBuilder, address: Address
) -> None:
    """
    Add an account that was accessed but not modified.

    Records that an account was accessed during execution without any state
    changes. This is used for operations like [`EXTCODEHASH`], [`BALANCE`],
    [`EXTCODESIZE`], and [`EXTCODECOPY`] that read account data without
    modifying it.

    Parameters
    ----------
    builder :
        The block access list builder instance.
    address :
        The account address that was accessed.

    [`EXTCODEHASH`] :
        ref:ethereum.forks.amsterdam.vm.instructions.environment.extcodehash
    [`BALANCE`] :
        ref:ethereum.forks.amsterdam.vm.instructions.environment.balance
    [`EXTCODESIZE`] :
        ref:ethereum.forks.amsterdam.vm.instructions.environment.extcodesize
    [`EXTCODECOPY`] :
        ref:ethereum.forks.amsterdam.vm.instructions.environment.extcodecopy

    """
    ensure_account(builder, address)

An account that was accessed but not modified still appears in the BAL. Consider:

# TX reads BALANCE of address X
# X's balance doesn't change
# But X must appear in BAL so stateless clients can prefetch X's state

Use cases for touched accounts:

• Witness generation: Stateless execution needs all accessed data
• State prefetching: Clients can load accounts before replay
• Access pattern analysis: Understanding hot accounts without modifying them

_build_from_builder (lines 371-433)

This is the core finalization function. It transforms the mutable BlockAccessListBuilder into the immutable, sorted BlockAccessList.

def _build_from_builder(
    builder: BlockAccessListBuilder,
) -> BlockAccessList:
    """
    Build the final [`BlockAccessList`] from a builder (internal helper).

    Constructs a deterministic block access list by sorting all accumulated
    changes. The resulting list is ordered by:

    1. Account addresses (lexicographically)
    2. Within each account:
       - Storage slots (lexicographically)
       - Transaction indices (numerically) for each change type

    Parameters
    ----------
    builder :
        The block access list builder containing all tracked changes.

    Returns
    -------
    block_access_list :
        The final sorted and encoded block access list.

    [`BlockAccessList`]: ref:ethereum.forks.amsterdam.block_access_lists.rlp_types.BlockAccessList

    """

The Sorting Contract

The docstring specifies a three-level sorting hierarchy:

Level 1: Addresses (lexicographic)
    └── Level 2: Storage slots (lexicographic)
            └── Level 3: Transaction indices (numeric)

This ordering is consensus-critical. Every client must produce the exact same byte sequence. Different sort orders → different RLP encoding → different hash → consensus failure.

Implementation Walkthrough

Phase 1: Initialize and Iterate

block_access_list: BlockAccessList = []

    for address, changes in builder.accounts.items():

Iteration order of dict.items() is insertion order in Python 3.7+. But insertion order is execution order, which varies by transaction. We can't rely on it—hence the explicit sorting later.

Phase 2: Process Storage Changes

storage_changes = []
        for slot, slot_changes in changes.storage_changes.items():
            sorted_changes = tuple(
                sorted(slot_changes, key=lambda x: x.block_access_index)
            )
            storage_changes.append(
                SlotChanges(slot=slot, changes=sorted_changes)
            )

For each slot, sort changes by block_access_index (transaction number). This produces entries like:

Slot 0x01:
  - TX 2: value = 0xAAA
  - TX 5: value = 0xBBB
  - TX 8: value = 0xCCC

The BAL records state evolution. For witness verification, a client needs to:

• Start with pre-block state
• Apply TX 2's change
• Apply TX 5's change
• Apply TX 8's change
• Verify post-block state

Phase 3: Filter and Sort Reads

storage_reads = []
        for slot in changes.storage_reads:
            if slot not in changes.storage_changes:
                storage_reads.append(slot)

• Non-redundancy: If you have the write history, you implicitly know the slot was accessed
• Smaller encoding: No need to list the slot twice
• Spec requirement: EIP-7928 mandates this behavior

# TX flow:
SLOAD(slot)   # recorded as read
SSTORE(slot)  # recorded as write
SLOAD(slot)   # redundant read (already have write)

# Result: slot appears in storage_changes only
# storage_reads does NOT include this slot

# TX flow:
SLOAD(slot)           # recorded as read
CALL(target) →
    SSTORE(slot)      # recorded as write in child frame
    REVERT            # write discarded, converted to read
# Result: slot appears in storage_reads (write was reverted)

The state tracker (Section 05) handles this via merge_on_failure, converting writes to reads. By the time data reaches the builder, this conversion already happened.

Phase 4: Sort All Change Lists

balance_changes = tuple(
            sorted(changes.balance_changes, key=lambda x: x.block_access_index)
        )
        nonce_changes = tuple(
            sorted(changes.nonce_changes, key=lambda x: x.block_access_index)
        )
        code_changes = tuple(
            sorted(changes.code_changes, key=lambda x: x.block_access_index)
        )

        storage_changes.sort(key=lambda x: x.slot)
        storage_reads.sort()

Each change type is sorted by its respective ordering key:

• Changes within a field type: by block_access_index (numeric)
• Slots: by slot value (lexicographic on U256)
• Reads: by slot value (lexicographic)

• Inner changes are small (typically 1-5 entries per slot/field)
• Slots can be numerous (DeFi contract might touch 100+ slots)
• list.sort() is in-place, avoiding allocation

Phase 5: Assemble AccountChanges

account_change = AccountChanges(
            address=address,
            storage_changes=tuple(storage_changes),
            storage_reads=tuple(storage_reads),
            balance_changes=balance_changes,
            nonce_changes=nonce_changes,
            code_changes=code_changes,
        )

        block_access_list.append(account_change)

Everything is converted to tuple for immutability. The AccountChanges dataclass (from rlp_types.py) uses tuples for all collection fields.

Phase 6: Sort by Address

block_access_list.sort(key=lambda x: x.address)

    return block_access_list

Final sort: order all accounts lexicographically by address. This is the top-level determinism guarantee.

Complexity Analysis

For a worst-case block (many accounts, many slots):

• A = 10,000 addresses
• S = 10 slots per address average
• T = 2 txs per slot average

build_block_access_list (lines 435-475)

The public entry point. Converts StateChanges from the state tracker into a BlockAccessList.

def build_block_access_list(
    state_changes: "StateChanges",
) -> BlockAccessList:
    """
    Build a [`BlockAccessList`] from a StateChanges frame.

    Converts the accumulated state changes from the frame-based architecture
    into the final deterministic BlockAccessList format.

    Parameters
    ----------
    state_changes :
        The block-level StateChanges frame containing all changes from the block.

    Returns
    -------
    block_access_list :
        The final sorted and encoded block access list.

    [`BlockAccessList`]: ref:ethereum.forks.amsterdam.block_access_lists.rlp_types.BlockAccessList
    [`StateChanges`]: ref:ethereum.forks.amsterdam.state_tracker.StateChanges

    """

StateChanges Structure (from state_tracker.py)

The input StateChanges has this shape after block execution:

@dataclass
class StateChanges:
    touched_addresses: Set[Address]
    storage_reads: Set[Tuple[Address, Bytes32]]
    storage_writes: Dict[Tuple[Address, Bytes32, BlockAccessIndex], U256]
    balance_changes: Dict[Tuple[Address, BlockAccessIndex], U256]
    nonce_changes: Set[Tuple[Address, BlockAccessIndex, U64]]
    code_changes: Dict[Tuple[Address, BlockAccessIndex], Bytes]
    # ... pre-state captures (not used in build)

Key observations:

• Composite keys: Writes are keyed by (address, slot/field, tx_index)
• Already filtered: Net-zero changes were removed by filter_net_zero_frame_changes (Section 05)
• Flat structure: Frame hierarchy collapsed; this is block-level accumulation

Implementation Walkthrough

Step 1: Initialize Builder

builder = BlockAccessListBuilder()

Fresh builder. We don't reuse builders across blocks.

Step 2: Add Touched Addresses

# Add all touched addresses
    for address in state_changes.touched_addresses:
        add_touched_account(builder, address)

Every address that was accessed (even without modification) gets an entry.

Step 3: Add Storage Reads

# Add all storage reads
    for address, slot in state_changes.storage_reads:
        add_storage_read(builder, address, U256(int.from_bytes(slot)))

• State tracker uses Bytes32 because storage keys are 32-byte hashes
• Builder uses U256 because that's how slots are encoded in RLP
• Both represent the same value, different representations

Step 4: Add Storage Writes

# Add all storage writes
    # Net-zero filtering happens at transaction commit time, not here.
    # At block level, we track ALL writes at their respective indices.
    for (
        address,
        slot,
        block_access_index,
    ), value in state_changes.storage_writes.items():
        u256_slot = U256(int.from_bytes(slot))
        add_storage_write(
            builder, address, u256_slot, block_access_index, value
        )

The state tracker's filter_net_zero_frame_changes (Section 05) already removed writes where pre_value == post_value. By the time we're here, all remaining writes are actual state changes.

• Separation of concerns: State tracker knows pre-state; builder doesn't
• Performance: Filter once at commit, not multiple times
• Correctness: Pre-state must be compared at transaction boundary, not block boundary

TX 1: slot 0x01: 0 → 5
TX 2: slot 0x01: 5 → 0

Net result: 0 → 0 (no change at block level). But we DO want to record both changes because:

• Intermediate state (after TX 1) was slot = 5
• This matters for state proofs at different block heights
• Filtering at block level would incorrectly eliminate both

Step 5: Add Balance Changes

# Add all balance changes (balance_changes is keyed by (address, index))
    for (
        address,
        block_access_index,
    ), new_balance in state_changes.balance_changes.items():
        add_balance_change(builder, address, block_access_index, new_balance)

Balance changes are keyed by (address, block_access_index). Each transaction that modifies an account's balance gets one entry per transaction.

Step 6: Add Nonce Changes

# Add all nonce changes
    for address, block_access_index, new_nonce in state_changes.nonce_changes:
        add_nonce_change(builder, address, block_access_index, new_nonce)

Nonces are stored as a Set of tuples (address, index, new_nonce) rather than a Dict. This is because add_nonce_change uses highest-wins semantics internally.

Multiple nonce changes within a transaction (e.g., CREATE → CREATE → CREATE) would overwrite in a Dict. A Set preserves all observations, letting add_nonce_change pick the highest.

Actually, looking at the code more carefully: the Set design allows multiple (address, index, nonce) tuples where nonce differs. The add_nonce_change function handles deduplication by keeping the highest nonce per (address, index).

Step 7: Add Code Changes

# Add all code changes
    # Filtering happens at transaction level in eoa_delegation.py
    for (
        address,
        block_access_index,
    ), new_code in state_changes.code_changes.items():
        add_code_change(builder, address, block_access_index, new_code)

This refers to EIP-7702 delegation code. When an EOA sets delegation code, certain filtering rules apply:

• Temporary delegation shouldn't persist
• Same-transaction removal shouldn't appear in BAL

Step 8: Build and Return

return _build_from_builder(builder)

Delegate to the internal helper for sorting and finalization.

Data Flow Summary

┌─────────────────────────────────────────────────────────────────────┐
│                        Block Execution                               │
├─────────────────────────────────────────────────────────────────────┤
│  TX 1 Frame                                                          │
│    ├── SLOAD, SSTORE, CALL...                                       │
│    ├── track_storage_read, track_storage_write                      │
│    └── filter_net_zero_frame_changes → commit_transaction_frame     │
│                                                                      │
│  TX 2 Frame                                                          │
│    ├── ...                                                          │
│    └── filter_net_zero_frame_changes → commit_transaction_frame     │
│                                                                      │
│  ... more transactions ...                                          │
│                                                                      │
│  Block Frame (accumulated StateChanges)                              │
│    ├── touched_addresses: {0xA, 0xB, 0xC}                           │
│    ├── storage_writes: {(0xA, slot, 1): val, (0xB, slot, 2): val}  │
│    └── balance_changes: {(0xA, 1): 100, (0xA, 2): 150}             │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    build_block_access_list                           │
├─────────────────────────────────────────────────────────────────────┤
│  1. Create BlockAccessListBuilder                                    │
│  2. add_touched_account for each address                            │
│  3. add_storage_read for each (addr, slot)                          │
│  4. add_storage_write for each (addr, slot, idx) → value            │
│  5. add_balance_change for each (addr, idx) → balance               │
│  6. add_nonce_change for each (addr, idx, nonce)                    │
│  7. add_code_change for each (addr, idx) → code                     │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      _build_from_builder                             │
├─────────────────────────────────────────────────────────────────────┤
│  For each address in builder.accounts:                               │
│    1. Sort storage changes by slot, then by index                   │
│    2. Filter reads (exclude slots with writes)                       │
│    3. Sort balance/nonce/code changes by index                      │
│    4. Create AccountChanges tuple                                    │
│                                                                      │
│  Sort all AccountChanges by address                                  │
│  Return BlockAccessList                                              │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         BlockAccessList                              │
│   [AccountChanges(0xA, ...), AccountChanges(0xB, ...), ...]         │
│   Deterministically sorted, ready for RLP encoding                   │
└─────────────────────────────────────────────────────────────────────┘

Cross-References

Gotchas

1. Net-Zero Filtering Already Happened

Don't expect build_block_access_list to filter net-zero changes. That happened in filter_net_zero_frame_changes at transaction commit time. All data arriving here represents actual state modifications.

2. Read/Write Filtering Happens in _build_from_builder

The exclusion of reads for written slots is NOT done during recording. It's done during finalization:

if slot not in changes.storage_changes:
    storage_reads.append(slot)

This is correct because:

• Recording doesn't know what will be written later
• Filtering during finalization sees the complete picture

3. Type Conversions (Bytes32 ↔ U256)

Storage slots are Bytes32 in the state tracker but U256 in the builder. The conversion happens in build_block_access_list:

u256_slot = U256(int.from_bytes(slot))

Both represent the same 256-bit value. The RLP encoding uses U256's numeric representation.

4. Sorting Is Consensus-Critical

Every client MUST produce the exact same sorted order. The sort keys are:

• Addresses: lexicographic (Python bytes comparison)
• Slots: numeric (U256 comparison)
• Indices: numeric (BlockAccessIndex comparison)

5. Empty Accounts Are Preserved

An account that was touched but has no changes still appears in the BAL:

AccountChanges(
    address=0xDEAD...,
    storage_changes=(),
    storage_reads=(),
    balance_changes=(),
    nonce_changes=(),
    code_changes=(),
)

This is intentional—the address was accessed, so it's part of the witness.

6. BlockAccessIndex 0 Is Pre-Execution

System calls before transaction execution (e.g., beacon root update) use index 0. Regular transactions use indices 1..n. Post-execution calls use n+1.

The builder doesn't care about this—it just records whatever indices it receives. But the sorting ensures pre-execution changes come first.

7. Nonce Changes Use Set, Not Dict

Unlike other changes, nonce_changes is a Set[Tuple[Address, BlockAccessIndex, U64]] not a Dict. This preserves multiple observations of nonce changes within a transaction, allowing add_nonce_change to select the highest.

Performance Considerations

Why Defer Sorting?

Recording during execution is hot path—every SLOAD, SSTORE, balance transfer triggers it. Sorting is expensive (O(n log n)). Deferring sorting to finalization means:

• Recording: O(1) amortized (append/set-add)
• Finalization: O(n log n) once, after all execution

Memory Profile

For a block with:

• 10,000 touched accounts
• 50,000 total storage accesses
• 15,000 balance changes (including COINBASE)

• Builder dict overhead: ~1-2 MB
• AccountData per account: ~600 bytes × 10,000 = ~6 MB
• Total: ~10-15 MB

Parallelization Opportunity

The current implementation is single-threaded. A future optimization could:

• Shard accounts by address prefix
• Sort each shard in parallel
• Merge sorted shards

Testing Considerations

Determinism Tests

The sorting must be deterministic. Test cases should:

• Build BAL from scrambled input
• Verify output matches expected sorted order
• Verify RLP encoding matches expected bytes

Read/Write Exclusivity Tests

# Test: slot written → not in reads
builder.add_storage_read(addr, slot)
builder.add_storage_write(addr, slot, idx, value)
bal = _build_from_builder(builder)
assert slot not in bal[0].storage_reads
assert any(sc.slot == slot for sc in bal[0].storage_changes)

Empty Account Tests

# Test: touched-only account appears with empty changes
builder.add_touched_account(addr)
bal = _build_from_builder(builder)
assert len(bal) == 1
assert bal[0].address == addr
assert bal[0].storage_changes == ()

Multi-Transaction Tests

# Test: changes from different TXs are preserved and sorted
builder.add_storage_write(addr, slot, idx=3, value=100)
builder.add_storage_write(addr, slot, idx=1, value=50)
bal = _build_from_builder(builder)
changes = bal[0].storage_changes[0].changes
assert changes[0].block_access_index == 1  # sorted
assert changes[1].block_access_index == 3

Section 08: Block Processing

Source Files

• specs/execution-specs/src/ethereum/forks/amsterdam/blocks.py (lines 1-417)
• specs/execution-specs/src/ethereum/forks/amsterdam/fork.py (lines 207-1180)
• specs/execution-specs/src/ethereum/forks/amsterdam/vm/__init__.py (lines 36-97)

Overview

Block processing is where EIP-7928 becomes consensus-critical. This section covers:

• Header Extension: The new block_access_list_hash field in the block header
• State Transition: How blocks are validated, including BAL hash verification
• Block Execution: The apply_body function orchestrating BAL construction
• Transaction Processing: How each transaction contributes to the BAL
• Post-Execution Operations: Withdrawals and system transactions

Block Header Extension

Header.block_access_list_hash (blocks.py, lines 234-254)

@slotted_freezable
@dataclass
class Header:
    """
    Header portion of a block on the chain, containing metadata and
    cryptographic commitments to the block's contents.
    """
    # ... 17 existing fields ...
    
    parent_beacon_block_root: Root
    """
    Root hash of the corresponding beacon chain block.
    """

    requests_hash: Hash32
    """
    [SHA2-256] hash of all the collected requests in this block. Introduced in
    [EIP-7685]. See [`compute_requests_hash`][crh] for more details.
    """

    block_access_list_hash: Hash32
    """
    [`keccak256`] hash of the Block Access List containing all accounts and
    storage locations accessed during block execution. Introduced in
    [EIP-7928]. See [`compute_block_access_list_hash`][cbalh] for more
    details.

    [`keccak256`]: ref:ethereum.crypto.hash.keccak256
    [EIP-7928]: https://eips.ethereum.org/EIPS/eip-7928
    [cbalh]: ref:ethereum.forks.amsterdam.block_access_lists.rlp_utils.compute_block_access_list_hash
    """

The BAL hash uses keccak256 (not SHA2-256 like requests_hash). This is intentional:

• Consistency: keccak256 is the primary hash function in the EL
• EVM compatibility: Solidity's keccak256 can verify proofs on-chain
• Legacy alignment: State roots, transaction roots, receipts root all use keccak256

The field is added after requests_hash (the EIP-7685 field), maintaining chronological ordering of EIP additions:

• Pre-merge fields (parent_hash through nonce)
• EIP-1559: base_fee_per_gas
• EIP-4895: withdrawals_root
• EIP-4844: blob_gas_used, excess_blob_gas
• EIP-4788: parent_beacon_block_root
• EIP-7685: requests_hash
• EIP-7928: block_access_list_hash

Adding a field to the header changes:

• RLP encoding of headers
• Block hash computation (keccak256(rlp.encode(header)))
• All existing tooling that parses headers

Block Output Structure

BlockOutput (vm/__init__.py, lines 56-97)

@dataclass
class BlockOutput:
    """
    Output from applying the block body to the present state.

    Contains the following:
    # ... documentation ...
    block_access_list: `BlockAccessList`
        The block access list for the block.
    """

    block_gas_used: Uint = Uint(0)
    transactions_trie: Trie[Bytes, Optional[Bytes | LegacyTransaction]] = (
        field(default_factory=lambda: Trie(secured=False, default=None))
    )
    receipts_trie: Trie[Bytes, Optional[Bytes | Receipt]] = field(
        default_factory=lambda: Trie(secured=False, default=None)
    )
    receipt_keys: Tuple[Bytes, ...] = field(default_factory=tuple)
    block_logs: Tuple[Log, ...] = field(default_factory=tuple)
    withdrawals_trie: Trie[Bytes, Optional[Bytes | Withdrawal]] = field(
        default_factory=lambda: Trie(secured=False, default=None)
    )
    blob_gas_used: U64 = U64(0)
    requests: List[Bytes] = field(default_factory=list)
    block_access_list: BlockAccessList = field(default_factory=list)

The BAL is a derived artifact, not an input. It's computed as a side effect of execution and then validated. This differs from transaction-level access lists (EIP-2930), which are inputs to execution.

BlockEnvironment with State Tracking

BlockEnvironment (vm/__init__.py, lines 36-52)

@dataclass
class BlockEnvironment:
    """
    Items external to the virtual machine itself, provided by the environment.
    """

    chain_id: U64
    state: State
    block_gas_limit: Uint
    block_hashes: List[Hash32]
    coinbase: Address
    number: Uint
    base_fee_per_gas: Uint
    time: U256
    prev_randao: Bytes32
    excess_blob_gas: U64
    parent_beacon_block_root: Hash32
    state_changes: StateChanges

This is the block-level frame for state tracking. It's initialized in state_transition and passed through all execution:

# In state_transition (fork.py line 244)
block_env = vm.BlockEnvironment(
    # ... other fields ...
    state_changes=StateChanges(),  # Fresh block frame
)

Every transaction, system call, and withdrawal operation creates child frames from this root. At the end of execution, build_block_access_list aggregates all recorded changes from this hierarchy.

State Transition Function

state_transition (fork.py, lines 207-290)

This is the main entry point for block validation and application.

def state_transition(chain: BlockChain, block: Block) -> None:
    """
    Attempts to apply a block to an existing block chain.

    All parts of the block's contents need to be verified before being added
    to the chain. Blocks are verified by ensuring that the contents of the
    block make logical sense with the contents of the parent block. The
    information in the block's header must also match the corresponding
    information in the block.
    """
    if len(rlp.encode(block)) > MAX_RLP_BLOCK_SIZE:
        raise InvalidBlock("Block rlp size exceeds MAX_RLP_BLOCK_SIZE")

    validate_header(chain, block.header)
    if block.ommers != ():
        raise InvalidBlock

• Check RLP size limit (DoS protection)
• Validate header consistency (parent hash, timestamps, gas limits)
• Reject ommer blocks (post-merge)

block_env = vm.BlockEnvironment(
        chain_id=chain.chain_id,
        state=chain.state,
        block_gas_limit=block.header.gas_limit,
        block_hashes=get_last_256_block_hashes(chain),
        coinbase=block.header.coinbase,
        number=block.header.number,
        base_fee_per_gas=block.header.base_fee_per_gas,
        time=block.header.timestamp,
        prev_randao=block.header.prev_randao,
        excess_blob_gas=block.header.excess_blob_gas,
        parent_beacon_block_root=block.header.parent_beacon_block_root,
        state_changes=StateChanges(),
    )

block_output = apply_body(
        block_env=block_env,
        transactions=block.transactions,
        withdrawals=block.withdrawals,
    )

# ... compute various roots and hashes ...
    
    computed_block_access_list_hash = compute_block_access_list_hash(
        block_output.block_access_list
    )

# ... validate gas_used, transactions_root, state_root, etc. ...
    
    if computed_block_access_list_hash != block.header.block_access_list_hash:
        raise InvalidBlock("Invalid block access list hash")

The BAL hash is checked after state root and other validations. This isn't arbitrary:

• If state root is wrong, the block is invalid regardless of BAL
• If BAL is wrong but state root is correct, it's a commitment failure
• Checking BAL after state root makes debugging easier

Block Body Execution

apply_body (fork.py, lines 770-838)

This function orchestrates the entire block execution.

def apply_body(
    block_env: vm.BlockEnvironment,
    transactions: Tuple[LegacyTransaction | Bytes, ...],
    withdrawals: Tuple[Withdrawal, ...],
) -> vm.BlockOutput:
    """
    Executes a block.

    Many of the contents of a block are stored in data structures called
    tries. There is a transactions trie which is similar to a ledger of the
    transactions stored in the current block. There is also a receipts trie
    which stores the results of executing a transaction, like the post state
    and gas used. This function creates and executes the block that is to be
    added to the chain.
    """
    block_output = vm.BlockOutput()

    # EIP-7928: System contracts use block_access_index 0
    # The block frame already starts at index 0, so system transactions
    # naturally use that index through the block frame

process_unchecked_system_transaction(
        block_env=block_env,
        target_address=BEACON_ROOTS_ADDRESS,
        data=block_env.parent_beacon_block_root,
    )

    process_unchecked_system_transaction(
        block_env=block_env,
        target_address=HISTORY_STORAGE_ADDRESS,
        data=block_env.block_hashes[-1],  # The parent hash
    )

• EIP-4788: Beacon block roots in the EVM
• EIP-2935: Historical block hashes

for i, tx in enumerate(map(decode_transaction, transactions)):
        process_transaction(block_env, block_output, tx, Uint(i))

# EIP-7928: Increment block frame to post-execution index
    # After N transactions, block frame is at index N
    # Post-execution operations (withdrawals, etc.) use index N+1
    increment_block_access_index(block_env.state_changes)

process_withdrawals(block_env, block_output, withdrawals)

    process_general_purpose_requests(
        block_env=block_env,
        block_output=block_output,
    )

# Build block access list from block_env.state_changes
    block_output.block_access_list = build_block_access_list(
        block_env.state_changes
    )

    return block_output

Transaction Processing

process_transaction (fork.py, lines 880-1080)

This is where most BAL entries originate.

def process_transaction(
    block_env: vm.BlockEnvironment,
    block_output: vm.BlockOutput,
    tx: Transaction,
    index: Uint,
) -> None:
    """
    Execute a transaction against the provided environment.

    This function processes the actions needed to execute a transaction.
    It decrements the sender's account balance after calculating the gas fee
    and refunds them the proper amount after execution.
    """
    # EIP-7928: Create a transaction-level StateChanges frame
    # The frame will read the current block_access_index from the block frame
    increment_block_access_index(block_env.state_changes)
    tx_state_changes = create_child_frame(block_env.state_changes)

• Increment the block's access index (for attribution)
• Create a child frame that inherits the current index

• increment_block_access_index moves from 0 → 1
• Child frame inherits index 1
• Transaction 0's changes are attributed to index 1

# Capture coinbase pre-balance for net-zero filtering
    coinbase_pre_balance = get_account(
        block_env.state, block_env.coinbase
    ).balance
    track_address(tx_state_changes, block_env.coinbase)
    capture_pre_balance(
        tx_state_changes, block_env.coinbase, coinbase_pre_balance
    )

The coinbase receives priority fees. To detect net-zero changes (e.g., coinbase sends a transaction and pays fees equal to what it receives), we must capture pre-balance.

Coinbase balance: 10 ETH
Coinbase sends TX, pays 1 ETH in gas
TX tips coinbase 1 ETH
Final balance: 10 ETH (net-zero!)

Without pre-balance capture, we'd record coinbase as modified. With it, the net-zero filter removes coinbase from BAL.

# ... transaction validation and gas accounting ...
    
    # Track sender nonce increment
    increment_nonce(block_env.state, sender)
    sender_nonce_after = get_account(block_env.state, sender).nonce
    track_nonce_change(tx_state_changes, sender, U64(sender_nonce_after))

# Track sender balance deduction for gas fee
    sender_balance_before = get_account(block_env.state, sender).balance
    track_address(tx_state_changes, sender)
    capture_pre_balance(tx_state_changes, sender, sender_balance_before)

    sender_balance_after_gas_fee = (
        Uint(sender_account.balance) - effective_gas_fee - blob_gas_fee
    )
    set_account_balance(
        block_env.state, sender, U256(sender_balance_after_gas_fee)
    )
    track_balance_change(
        tx_state_changes,
        sender,
        U256(sender_balance_after_gas_fee),
    )

• Capture sender's pre-balance
• Deduct gas fee from balance
• Track the new balance

# ... create tx_env and message, execute ...
    
    tx_output = process_message_call(message)

# ... gas refund calculation ...
    
    # refund gas
    sender_balance_after_refund = get_account(
        block_env.state, sender
    ).balance + U256(gas_refund_amount)
    set_account_balance(block_env.state, sender, sender_balance_after_refund)
    track_balance_change(
        tx_env.state_changes,
        sender,
        sender_balance_after_refund,
    )

    coinbase_balance_after_mining_fee = get_account(
        block_env.state, block_env.coinbase
    ).balance + U256(transaction_fee)

    set_account_balance(
        block_env.state, block_env.coinbase, coinbase_balance_after_mining_fee
    )
    track_balance_change(
        tx_env.state_changes,
        block_env.coinbase,
        coinbase_balance_after_mining_fee,
    )

• Track gas refund to sender
• Track priority fee to coinbase

for address in tx_output.accounts_to_delete:
        destroy_account(block_env.state, address)
        track_selfdestruct(tx_env.state_changes, address)

    # EIP-7928: Commit transaction frame (includes net-zero filtering).
    # Must happen AFTER destroy_account so filtering sees correct state.
    commit_transaction_frame(tx_env.state_changes)

• Process SELFDESTRUCT accounts (deprecated but still tracked)
• Commit the transaction frame to the block frame

Withdrawal Processing

process_withdrawals (fork.py, lines 1083-1122)

Withdrawals are post-transaction balance credits from the consensus layer.

def process_withdrawals(
    block_env: vm.BlockEnvironment,
    block_output: vm.BlockOutput,
    withdrawals: Tuple[Withdrawal, ...],
) -> None:
    """
    Increase the balance of the withdrawing account.
    """
    # Capture pre-state for withdrawal balance filtering
    withdrawal_addresses = {wd.address for wd in withdrawals}
    for address in withdrawal_addresses:
        pre_balance = get_account(block_env.state, address).balance
        track_address(block_env.state_changes, address)
        capture_pre_balance(block_env.state_changes, address, pre_balance)

Why capture all addresses before processing any? Consider:

Withdrawal 1: 1 ETH to address A
Withdrawal 2: 1 ETH to address A

If we captured A's balance before withdrawal 1, then processed it, then captured before withdrawal 2, we'd capture the intermediate balance, not the pre-block balance. By gathering all addresses first, we capture true pre-state.

def increase_recipient_balance(recipient: Account) -> None:
        recipient.balance += wd.amount * U256(10**9)

    for i, wd in enumerate(withdrawals):
        trie_set(
            block_output.withdrawals_trie,
            rlp.encode(Uint(i)),
            rlp.encode(wd),
        )

        modify_state(block_env.state, wd.address, increase_recipient_balance)

        new_balance = get_account(block_env.state, wd.address).balance
        track_balance_change(
            block_env.state_changes,
            wd.address,
            new_balance,
        )

if account_exists_and_is_empty(block_env.state, wd.address):
            destroy_account(block_env.state, wd.address)

    # EIP-7928: Filter net-zero balance changes for withdrawals
    filter_net_zero_frame_changes(block_env.state_changes)

System Transaction Processing

process_system_transaction (fork.py, lines 610-680)

System transactions are internal calls that don't originate from a user signature.

def process_system_transaction(
    block_env: vm.BlockEnvironment,
    target_address: Address,
    system_contract_code: Bytes,
    data: Bytes,
) -> MessageCallOutput:
    """
    Process a system transaction with the given code.
    """
    # EIP-7928: Create a child frame for system transaction
    # This allows proper pre-state capture for net-zero filtering
    system_tx_state_changes = create_child_frame(block_env.state_changes)

• Changes are attributed to the correct index (0 for pre-execution)
• Net-zero filtering works within each system call

tx_env = vm.TransactionEnvironment(
        origin=SYSTEM_ADDRESS,
        gas_price=block_env.base_fee_per_gas,
        gas=SYSTEM_TRANSACTION_GAS,
        access_list_addresses=set(),
        access_list_storage_keys=set(),
        transient_storage=TransientStorage(),
        blob_versioned_hashes=(),
        authorizations=(),
        index_in_block=None,
        tx_hash=None,
        state_changes=system_tx_state_changes,
    )

# Create call frame as child of tx frame
    call_frame = create_child_frame(tx_env.state_changes)

    system_tx_message = Message(
        # ... populate message fields ...
        state_changes=call_frame,
    )

    system_tx_output = process_message_call(system_tx_message)

    # Commit system transaction changes to block frame
    # System transactions always succeed (or block is invalid)
    commit_transaction_frame(tx_env.state_changes)

    return system_tx_output

Validation Sequence Summary

The complete validation flow:

1. validate_header(chain, block.header)
   ├── Check parent hash
   ├── Check timestamps
   ├── Check gas limits
   ├── Check excess_blob_gas
   └── Check base_fee_per_gas

2. apply_body(block_env, transactions, withdrawals)
   ├── System transactions (index 0)
   │   ├── Beacon roots contract
   │   └── History storage contract
   ├── User transactions (indices 1..N)
   │   └── Each creates/commits transaction frame
   ├── Withdrawals (index N+1)
   └── Requests (index N+1)

3. Compute derived values
   ├── block_state_root
   ├── transactions_root
   ├── receipt_root
   ├── withdrawals_root
   ├── requests_hash
   └── computed_block_access_list_hash ← NEW

4. Validate commitments
   ├── gas_used == header.gas_used
   ├── transactions_root == header.transactions_root
   ├── state_root == header.state_root
   ├── receipt_root == header.receipt_root
   ├── bloom == header.bloom
   ├── withdrawals_root == header.withdrawals_root
   ├── blob_gas_used == header.blob_gas_used
   ├── requests_hash == header.requests_hash
   └── block_access_list_hash == header.block_access_list_hash ← NEW

5. If all valid: chain.blocks.append(block)

Gotchas and Edge Cases

Index Attribution

The increment_block_access_index call at the start of process_transaction increments from 0 to 1 before the first user transaction. Index 0 is reserved for system transactions.

Coinbase Edge Cases

• Pre-balance captured for gas deduction
• Priority fee added back to coinbase
• Net effect may be zero (no BAL entry)

• If coinbase receives zero fees and is empty, it's destroyed
• account_exists_and_is_empty check handles this

Withdrawal Batching

withdrawal_addresses = {wd.address for wd in withdrawals}
for address in withdrawal_addresses:
    pre_balance = get_account(...)

The set deduplication ensures we capture pre-state once, not per-withdrawal.

System Transaction Failures

• process_unchecked_system_transaction: Returns output even if execution fails
• process_checked_system_transaction: Raises InvalidBlock on failure

Cross-References

Implementation Notes

Why the BAL is Validated Last

The InvalidBlock exception for BAL mismatch is thrown after all other validations. This ordering:

• Ensures state root correctness before BAL check
• Makes debugging easier (wrong state → wrong BAL)
• Matches logical dependency (BAL depends on execution)

Performance Characteristics

BAL construction happens during execution (amortized). The final hash is O(n) where n is BAL size. For a 30M gas block with typical transactions:

• ~100-200 accounts modified
• ~500-1000 storage slots modified
• BAL size: 10-50 KB typically
• Hash time: <1ms

Determinism Requirements

Every operation must produce identical results across clients:

• Sorting: Lexicographic by bytes (not numeric interpretation)
• RLP encoding: Canonical form (no leading zeros except required)
• Hash function: keccak256 (as implemented in every client)

Section 09: VM Integration

Source Files

• specs/execution-specs/src/ethereum/forks/amsterdam/vm/__init__.py (lines 1-201)
• specs/execution-specs/src/ethereum/forks/amsterdam/vm/interpreter.py (lines 1-370)
• specs/execution-specs/src/ethereum/forks/amsterdam/vm/instructions/storage.py (lines 1-166)
• specs/execution-specs/src/ethereum/forks/amsterdam/vm/instructions/environment.py (lines 1-451)
• specs/execution-specs/src/ethereum/forks/amsterdam/vm/instructions/system.py (lines 1-670)
• specs/execution-specs/src/ethereum/forks/amsterdam/state_tracker.py (frame management functions)

Overview

VM integration is where EIP-7928's state tracking actually happens. This section covers:

• State Changes Threading: How StateChanges flows through Message → Evm → Instructions
• Evm Class Extension: The new state_changes field in the EVM dataclass
• Instruction-Level Hooks: Which opcodes trigger which tracking functions
• Child Frame Management: How CALL/CREATE spawn child frames and merge results
• Interpreter Hooks: Where the interpreter calls tracking functions for value transfers

State Changes Threading

Architecture Overview

State tracking flows through three layers:

BlockEnvironment.state_changes (block frame)
         ↓
TransactionEnvironment.state_changes (tx frame)
         ↓
Message.state_changes → Evm.state_changes (call frames)

Each layer holds a StateChanges instance linked to its parent. This mirrors EVM execution semantics: a CALL can revert without affecting the parent's state changes.

BlockEnvironment.state_changes (vm/__init__.py, lines 36-52)

@dataclass
class BlockEnvironment:
    """
    Items external to the virtual machine itself, provided by the environment.
    """

    chain_id: U64
    state: State
    block_gas_limit: Uint
    block_hashes: List[Hash32]
    coinbase: Address
    number: Uint
    base_fee_per_gas: Uint
    time: U256
    prev_randao: Bytes32
    excess_blob_gas: U64
    parent_beacon_block_root: Hash32
    state_changes: StateChanges

TransactionEnvironment.state_changes (vm/__init__.py, lines 92-107)

@dataclass
class TransactionEnvironment:
    """
    Items that are used by contract creation or message call.
    """

    origin: Address
    gas_price: Uint
    gas: Uint
    access_list_addresses: Set[Address]
    access_list_storage_keys: Set[Tuple[Address, Bytes32]]
    transient_storage: TransientStorage
    blob_versioned_hashes: Tuple[VersionedHash, ...]
    authorizations: Tuple[Authorization, ...]
    index_in_block: Optional[Uint]
    tx_hash: Optional[Hash32]
    state_changes: "StateChanges" = field(default_factory=StateChanges)

Message.state_changes (vm/__init__.py, lines 110-134)

@dataclass
class Message:
    """
    Items that are used by contract creation or message call.
    """

    block_env: BlockEnvironment
    tx_env: TransactionEnvironment
    caller: Address
    target: Bytes0 | Address
    current_target: Address
    gas: Uint
    value: U256
    data: Bytes
    code_address: Optional[Address]
    code: Bytes
    depth: Uint
    should_transfer_value: bool
    is_static: bool
    accessed_addresses: Set[Address]
    accessed_storage_keys: Set[Tuple[Address, Bytes32]]
    disable_precompiles: bool
    parent_evm: Optional["Evm"]
    is_create: bool
    state_changes: "StateChanges" = field(default_factory=StateChanges)

• message.state_changes — the current call's frame
• message.tx_env.state_changes — the transaction frame (for pre-captures)
• message.block_env.state_changes — the block frame (root)

Evm Class Extension

Evm.state_changes (vm/__init__.py, lines 137-157)

@dataclass
class Evm:
    """The internal state of the virtual machine."""

    pc: Uint
    stack: List[U256]
    memory: bytearray
    code: Bytes
    gas_left: Uint
    valid_jump_destinations: Set[Uint]
    logs: Tuple[Log, ...]
    refund_counter: int
    running: bool
    message: Message
    output: Bytes
    accounts_to_delete: Set[Address]
    return_data: Bytes
    error: Optional[EthereumException]
    accessed_addresses: Set[Address]
    accessed_storage_keys: Set[Tuple[Address, Bytes32]]
    state_changes: StateChanges

The Evm is the execution state; Message is the input parameters. By copying state_changes to Evm, instructions don't need to traverse evm.message.state_changes on every access.

def process_message(message: Message) -> Evm:
    """
    Move ether and execute the relevant code.
    """
    state = message.block_env.state
    transient_storage = message.tx_env.transient_storage
    if message.depth > STACK_DEPTH_LIMIT:
        raise StackDepthLimitError("Stack depth limit reached")

    code = message.code
    valid_jump_destinations = get_valid_jump_destinations(code)
    evm = Evm(
        pc=Uint(0),
        stack=[],
        memory=bytearray(),
        code=code,
        gas_left=message.gas,
        valid_jump_destinations=valid_jump_destinations,
        logs=(),
        refund_counter=0,
        running=True,
        message=message,
        output=b"",
        accounts_to_delete=set(),
        return_data=b"",
        error=None,
        accessed_addresses=message.accessed_addresses,
        accessed_storage_keys=message.accessed_storage_keys,
        state_changes=message.state_changes,  # <-- Copy from message
    )

The state_changes is copied from the message, establishing the frame hierarchy.

Instruction-Level Tracking

Storage Instructions (storage.py)

sload (lines 24-54)

def sload(evm: Evm) -> None:
    """
    Loads to the stack, the value corresponding to a certain key from the
    storage of the current account.
    """
    # STACK
    key = pop(evm.stack).to_be_bytes32()

    # GAS
    if (evm.message.current_target, key) in evm.accessed_storage_keys:
        charge_gas(evm, GAS_WARM_ACCESS)
    else:
        evm.accessed_storage_keys.add((evm.message.current_target, key))
        charge_gas(evm, GAS_COLD_SLOAD)

    # OPERATION
    value = get_storage(
        evm.message.block_env.state, evm.message.current_target, key
    )
    track_storage_read(
        evm.state_changes,
        evm.message.current_target,
        key,
    )

    push(evm.stack, value)

    # PROGRAM COUNTER
    evm.pc += Uint(1)

Reads prove which slots existed in pre-state. For stateless execution, the witness must include values for all read slots, even if unchanged.

sstore (lines 57-133)

def sstore(evm: Evm) -> None:
    """
    Stores a value at a certain key in the current context's storage.
    """
    if evm.message.is_static:
        raise WriteInStaticContext

    # STACK
    key = pop(evm.stack).to_be_bytes32()
    new_value = pop(evm.stack)

    # check we have at least the stipend gas
    check_gas(evm, GAS_CALL_STIPEND + Uint(1))

    state = evm.message.block_env.state
    original_value = get_storage_original(
        state, evm.message.current_target, key
    )
    current_value = get_storage(state, evm.message.current_target, key)

    gas_cost = Uint(0)

    if (evm.message.current_target, key) not in evm.accessed_storage_keys:
        evm.accessed_storage_keys.add((evm.message.current_target, key))
        gas_cost += GAS_COLD_SLOAD

    capture_pre_storage(
        evm.message.tx_env.state_changes,
        evm.message.current_target,
        key,
        current_value,
    )
    track_storage_read(
        evm.state_changes,
        evm.message.current_target,
        key,
    )

    # ... gas calculation using original_value and current_value ...

    charge_gas(evm, gas_cost)
    set_storage(state, evm.message.current_target, key, new_value)
    track_storage_write(
        evm.state_changes,
        evm.message.current_target,
        key,
        new_value,
    )

    # PROGRAM COUNTER
    evm.pc += Uint(1)

• capture_pre_storage() — Records pre-value at tx frame (first-write-wins)
• track_storage_read() — Records the read at call frame (SSTORE reads before writing)
• set_storage() — Actually modifies state
• track_storage_write() — Records the write at call frame

SSTORE semantically reads the current value (for gas calculation) before writing. If the call reverts, the write is discarded but the read persists. This is why merge_on_failure() converts writes to reads.

capture_pre_storage(
    evm.message.tx_env.state_changes,  # <-- tx frame, not call frame
    ...
)

Pre-values must survive nested call reversions. If a child CALL writes slot X, reverts, then the parent writes slot X, the pre-value captured by the child must still be available.

tload / tstore (lines 136-166)

def tload(evm: Evm) -> None:
    """
    Loads to the stack, the value corresponding to a certain key from the
    transient storage of the current account.
    """
    # STACK
    key = pop(evm.stack).to_be_bytes32()

    # GAS
    charge_gas(evm, GAS_WARM_ACCESS)

    # OPERATION
    value = get_transient_storage(
        evm.message.tx_env.transient_storage, evm.message.current_target, key
    )
    push(evm.stack, value)

    # PROGRAM COUNTER
    evm.pc += Uint(1)

Environment Instructions (environment.py)

balance (lines 47-73)

def balance(evm: Evm) -> None:
    """
    Pushes the balance of the given account onto the stack.
    """
    # STACK
    address = to_address_masked(pop(evm.stack))

    # GAS
    is_cold_access = address not in evm.accessed_addresses
    gas_cost = GAS_COLD_ACCOUNT_ACCESS if is_cold_access else GAS_WARM_ACCESS
    if is_cold_access:
        evm.accessed_addresses.add(address)

    charge_gas(evm, gas_cost)

    # OPERATION
    state = evm.message.block_env.state
    balance = get_account(state, address).balance
    track_address(evm.state_changes, address)

    push(evm.stack, balance)

    # PROGRAM COUNTER
    evm.pc += Uint(1)

For stateless execution, the prover must include account data for any address whose balance is read. This includes non-existent accounts (returns 0).

extcodesize / extcodecopy / extcodehash (lines 286-362)

def extcodesize(evm: Evm) -> None:
    """
    Push the code size of a given account onto the stack.
    """
    # STACK
    address = to_address_masked(pop(evm.stack))

    # GAS
    is_cold_access = address not in evm.accessed_addresses
    access_gas_cost = (
        GAS_COLD_ACCOUNT_ACCESS if is_cold_access else GAS_WARM_ACCESS
    )
    if is_cold_access:
        evm.accessed_addresses.add(address)

    charge_gas(evm, access_gas_cost)

    # OPERATION
    state = evm.message.block_env.state
    code = get_account(state, address).code
    track_address(evm.state_changes, address)

    codesize = U256(len(code))
    push(evm.stack, codesize)

All three EXTCODE opcodes follow the same pattern: track the address after gas charging.

def self_balance(evm: Evm) -> None:
    """
    Pushes the balance of the current address to the stack.
    """
    # STACK
    pass

    # GAS
    charge_gas(evm, GAS_FAST_STEP)

    # OPERATION
    balance = get_account(
        evm.message.block_env.state, evm.message.current_target
    ).balance

    push(evm.stack, balance)

    # PROGRAM COUNTER
    evm.pc += Uint(1)

def generic_create(
    evm: Evm,
    endowment: U256,
    contract_address: Address,
    memory_start_position: U256,
    memory_size: U256,
) -> None:
    """
    Core logic used by the `CREATE*` family of opcodes.
    """
    from ...vm.interpreter import (
        MAX_INIT_CODE_SIZE,
        STACK_DEPTH_LIMIT,
        process_create_message,
    )

    # Check static context first
    if evm.message.is_static:
        raise WriteInStaticContext

    # ... validation ...

    evm.accessed_addresses.add(contract_address)

    track_address(evm.state_changes, contract_address)
    if account_has_code_or_nonce(
        state, contract_address
    ) or account_has_storage(state, contract_address):
        increment_nonce(state, evm.message.current_target)
        nonce_after = get_account(state, evm.message.current_target).nonce
        track_nonce_change(
            evm.state_changes,
            evm.message.current_target,
            U64(nonce_after),
        )
        push(evm.stack, U256(0))
        return

    # Track nonce increment for CREATE
    increment_nonce(state, evm.message.current_target)
    nonce_after = get_account(state, evm.message.current_target).nonce
    track_nonce_change(
        evm.state_changes,
        evm.message.current_target,
        U64(nonce_after),
    )

    # Create call frame as child of parent EVM's frame
    child_state_changes = create_child_frame(evm.state_changes)

    child_message = Message(
        # ... other fields ...
        is_create=True,
        state_changes=child_state_changes,
    )
    child_evm = process_create_message(child_message)

    if child_evm.error:
        incorporate_child_on_error(evm, child_evm)
        evm.return_data = child_evm.output
        push(evm.stack, U256(0))
    else:
        incorporate_child_on_success(evm, child_evm)
        evm.return_data = b""
        push(evm.stack, U256.from_be_bytes(child_evm.message.current_target))

def generic_call(
    evm: Evm,
    gas: Uint,
    value: U256,
    caller: Address,
    to: Address,
    code_address: Address,
    should_transfer_value: bool,
    is_staticcall: bool,
    memory_input_start_position: U256,
    memory_input_size: U256,
    memory_output_start_position: U256,
    memory_output_size: U256,
    code: Bytes,
    disable_precompiles: bool,
) -> None:
    """
    Perform the core logic of the `CALL*` family of opcodes.
    """
    from ...vm.interpreter import STACK_DEPTH_LIMIT, process_message

    evm.return_data = b""

    if evm.message.depth + Uint(1) > STACK_DEPTH_LIMIT:
        evm.gas_left += gas
        push(evm.stack, U256(0))
        return

    call_data = memory_read_bytes(
        evm.memory, memory_input_start_position, memory_input_size
    )

    # Create call frame as child of parent EVM's frame
    child_state_changes = create_child_frame(evm.state_changes)

    child_message = Message(
        # ... other fields ...
        is_create=False,
        state_changes=child_state_changes,
    )

    child_evm = process_message(child_message)

    if child_evm.error:
        incorporate_child_on_error(evm, child_evm)
        evm.return_data = child_evm.output
        push(evm.stack, U256(0))
    else:
        incorporate_child_on_success(evm, child_evm)
        evm.return_data = child_evm.output
        push(evm.stack, U256(1))

parent.state_changes (tx frame or call frame)
         ↓ create_child_frame()
child.state_changes
         ↓ process_message()
    ... execution ...
         ↓ incorporate_child_on_success/error()
parent.state_changes (merged)

def selfdestruct(evm: Evm) -> None:
    """
    Halt execution and register account for later deletion.
    """
    if evm.message.is_static:
        raise WriteInStaticContext

    # STACK
    beneficiary = to_address_masked(pop(evm.stack))

    # ... gas handling ...

    track_address(evm.state_changes, beneficiary)

    # ... more gas ...

    state = evm.message.block_env.state
    originator = evm.message.current_target
    originator_balance = get_account(state, originator).balance
    beneficiary_balance = get_account(state, beneficiary).balance

    # Get tracking context
    tx_frame = evm.message.tx_env.state_changes

    # Capture pre-balances for net-zero filtering
    track_address(evm.state_changes, originator)
    capture_pre_balance(tx_frame, originator, originator_balance)
    capture_pre_balance(tx_frame, beneficiary, beneficiary_balance)

    # Transfer balance
    move_ether(state, originator, beneficiary, originator_balance)

    # Track balance changes
    originator_new_balance = get_account(state, originator).balance
    beneficiary_new_balance = get_account(state, beneficiary).balance
    track_balance_change(
        evm.state_changes,
        originator,
        originator_new_balance,
    )
    track_balance_change(
        evm.state_changes,
        beneficiary,
        beneficiary_new_balance,
    )

    # register account for deletion only if it was created
    # in the same transaction
    if originator in state.created_accounts:
        set_account_balance(state, originator, U256(0))
        track_balance_change(evm.state_changes, originator, U256(0))
        evm.accounts_to_delete.add(originator)

    evm.running = False

def process_message(message: Message) -> Evm:
    """
    Move ether and execute the relevant code.
    """
    # ... evm initialization ...

    # take snapshot of state before processing the message
    begin_transaction(state, transient_storage)

    track_address(message.state_changes, message.current_target)

    if message.should_transfer_value and message.value != 0:
        # Track value transfer
        sender_balance = get_account(state, message.caller).balance
        recipient_balance = get_account(state, message.current_target).balance

        track_address(message.state_changes, message.caller)
        capture_pre_balance(
            message.tx_env.state_changes, message.caller, sender_balance
        )
        capture_pre_balance(
            message.tx_env.state_changes,
            message.current_target,
            recipient_balance,
        )

        move_ether(
            state, message.caller, message.current_target, message.value
        )

        sender_new_balance = get_account(state, message.caller).balance
        recipient_new_balance = get_account(
            state, message.current_target
        ).balance

        track_balance_change(
            message.state_changes,
            message.caller,
            U256(sender_new_balance),
        )
        track_balance_change(
            message.state_changes,
            message.current_target,
            U256(recipient_new_balance),
        )

def process_create_message(message: Message) -> Evm:
    """
    Executes a call to create a smart contract.
    """
    state = message.block_env.state
    transient_storage = message.tx_env.transient_storage
    begin_transaction(state, transient_storage)

    destroy_storage(state, message.current_target)
    mark_account_created(state, message.current_target)

    increment_nonce(state, message.current_target)
    nonce_after = get_account(state, message.current_target).nonce
    track_nonce_change(
        message.state_changes,
        message.current_target,
        U64(nonce_after),
    )

    capture_pre_code(message.tx_env.state_changes, message.current_target, b"")

    evm = process_message(message)
    if not evm.error:
        contract_code = evm.output
        # ... code size validation ...
        try:
            # ... validation ...
            set_code(state, message.current_target, contract_code)
            if contract_code != b"":
                track_code_change(
                    message.state_changes,
                    message.current_target,
                    contract_code,
                )
            commit_transaction(state, transient_storage)
            merge_on_success(message.state_changes)
        except ExceptionalHalt as error:
            rollback_transaction(state, transient_storage)
            merge_on_failure(message.state_changes)
            # ... error handling ...
    else:
        rollback_transaction(state, transient_storage)
        merge_on_failure(message.state_changes)
    return evm

def incorporate_child_on_success(evm: Evm, child_evm: Evm) -> None:
    """
    Incorporate the state of a successful `child_evm` into the parent `evm`.
    """
    evm.gas_left += child_evm.gas_left
    evm.logs += child_evm.logs
    evm.refund_counter += child_evm.refund_counter
    evm.accounts_to_delete.update(child_evm.accounts_to_delete)
    evm.accessed_addresses.update(child_evm.accessed_addresses)
    evm.accessed_storage_keys.update(child_evm.accessed_storage_keys)

    merge_on_success(child_evm.state_changes)

def incorporate_child_on_error(evm: Evm, child_evm: Evm) -> None:
    """
    Incorporate the state of an unsuccessful `child_evm` into the parent `evm`.
    """
    evm.gas_left += child_evm.gas_left

    merge_on_failure(child_evm.state_changes)

def merge_on_failure(child_frame: StateChanges) -> None:
    # ...
    # Convert writes to reads (failed writes still accessed the slots)
    for address, key, _idx in child_frame.storage_writes.keys():
        parent_frame.storage_reads.add((address, key))

SSTORE(slot, 1)  // write (slot, 1) at index X
SSTORE(slot, 2)  // write (slot, 2) at index X (overwrites)

state_changes.storage_writes[(address, key, idx)] = value

track_address(evm.state_changes, contract_address)
if account_has_code_or_nonce(state, contract_address) or account_has_storage(...):
    track_nonce_change(...)  # Still track the sender nonce bump
    push(evm.stack, U256(0))
    return  # Early exit, no child frame

# EIP-7928: For CALLCODE with value transfer, capture pre-balance
# in transaction frame. CALLCODE transfers value from/to current_target
# (same address), affecting current storage context, not child frame
if value != 0 and sender_balance >= value:
    capture_pre_balance(
        evm.message.tx_env.state_changes,
        evm.message.current_target,
        sender_balance,
    )