ethereum.forks.amsterdam.state_tracker
State Tracking for Block Execution.
Track state changes on top of a read-only PreState. At block end,
accumulated diffs feed into
PreState.compute_state_root().
.. contents:: Table of Contents :backlinks: none :local:
Introduction
Replace the mutable State class with lightweight state trackers that
record diffs. BlockState accumulates committed transaction
changes across a block. TransactionState tracks in-flight changes
within a single transaction and supports copy-on-write rollback.
BlockState ¶
Accumulate committed transaction-level changes across a block.
Read chain: block writes -> pre_state.
account_reads and storage_reads accumulate across all
transactions for BAL generation.
| 42 | @final |
|---|
| 43 | @dataclass |
|---|
class BlockState:
pre_state¶
| 54 | pre_state: PreState |
|---|
account_reads¶
| 55 | account_reads: Set[Address] = field(default_factory=set) |
|---|
account_writes¶
| 56 | account_writes: Dict[Address, Optional[Account]] = field( |
|---|---|
| 57 | default_factory=dict |
| 58 | ) |
storage_reads¶
| 59 | storage_reads: Set[Tuple[Address, Bytes32]] = field(default_factory=set) |
|---|
storage_writes¶
| 60 | storage_writes: Dict[Address, Dict[Bytes32, U256]] = field( |
|---|---|
| 61 | default_factory=dict |
| 62 | ) |
code_writes¶
| 63 | code_writes: Dict[Hash32, Bytes] = field(default_factory=dict) |
|---|
TransactionState ¶
Track in-flight state changes within a single transaction.
Read chain: tx writes -> block writes -> pre_state.
storage_reads and account_reads are shared references
that survive rollback (reads from failed calls still appear in the
Block Access List).
| 66 | @final |
|---|
| 67 | @dataclass |
|---|
class TransactionState:
parent¶
| 79 | parent: BlockState |
|---|
account_reads¶
| 80 | account_reads: Set[Address] = field(default_factory=set) |
|---|
account_writes¶
| 81 | account_writes: Dict[Address, Optional[Account]] = field( |
|---|---|
| 82 | default_factory=dict |
| 83 | ) |
storage_reads¶
| 84 | storage_reads: Set[Tuple[Address, Bytes32]] = field(default_factory=set) |
|---|
storage_writes¶
| 85 | storage_writes: Dict[Address, Dict[Bytes32, U256]] = field( |
|---|---|
| 86 | default_factory=dict |
| 87 | ) |
code_writes¶
| 88 | code_writes: Dict[Hash32, Bytes] = field(default_factory=dict) |
|---|
created_accounts¶
| 89 | created_accounts: Set[Address] = field(default_factory=set) |
|---|
transient_storage¶
| 90 | transient_storage: Dict[Tuple[Address, Bytes32], U256] = field( |
|---|---|
| 91 | default_factory=dict |
| 92 | ) |
get_pre_state_account_optional ¶
Get the Account object at an address that existed before the current
transaction, or None (rather than EMPTY_ACCOUNT) if there was no
account at the address at that point.
Use get_pre_state_account() if the difference between a
non-existent account and EMPTY_ACCOUNT isn't important.
Parameters
tx_state : The transaction state. address : Address to look up.
Returns
account : Optional[Account]
Account at address before the current transaction.
def get_pre_state_account_optional(tx_state: TransactionState, address: Address) -> Optional[Account]:
| 98 | <snip> |
|---|---|
| 122 | tx_state.account_reads.add(address) |
| 123 | if address in tx_state.parent.account_writes: |
| 124 | return tx_state.parent.account_writes[address] |
| 125 | return tx_state.parent.pre_state.get_account_optional(address) |
get_pre_state_account ¶
Get the Account object at an address that existed before the current
transaction, or EMPTY_ACCOUNT) if there was no account at the address
at that point.
Use get_pre_state_account_optional() if the difference between a
non-existent account and EMPTY_ACCOUNT is material.
Parameters
tx_state : The transaction state. address : Address to look up.
Returns
account : Account
Account at address before the current transaction.
def get_pre_state_account(tx_state: TransactionState, address: Address) -> Account:
| 131 | <snip> # noqa: E501 |
|---|---|
| 155 | account = get_pre_state_account_optional(tx_state, address) |
| 156 | if account is None: |
| 157 | return EMPTY_ACCOUNT |
| 158 | else: |
| 159 | return account |
get_account_optional ¶
Get the Account object at an address. Return None (rather than
EMPTY_ACCOUNT) if there is no account at the address.
Parameters
tx_state : The transaction state. address : Address to look up.
Returns
account : Optional[Account]
Account at address.
def get_account_optional(tx_state: TransactionState, address: Address) -> Optional[Account]:
| 165 | <snip> |
|---|---|
| 182 | tx_state.account_reads.add(address) |
| 183 | if address in tx_state.account_writes: |
| 184 | return tx_state.account_writes[address] |
| 185 | return get_pre_state_account_optional(tx_state, address) |
get_account ¶
Get the Account object at an address. Return EMPTY_ACCOUNT
if there is no account at the address.
Use get_account_optional() if you care about the difference
between a non-existent account and EMPTY_ACCOUNT.
Parameters
tx_state : The transaction state. address : Address to look up.
Returns
account : Account
Account at address.
def get_account(tx_state: TransactionState, address: Address) -> Account:
| 189 | <snip> |
|---|---|
| 209 | account = get_account_optional(tx_state, address) |
| 210 | if account is None: |
| 211 | return EMPTY_ACCOUNT |
| 212 | else: |
| 213 | return account |
get_code ¶
Get the bytecode for a given code hash.
Read chain: tx code_writes -> block code_writes -> pre_state.
Parameters
tx_state : The transaction state. code_hash : Hash of the code to look up.
Returns
code : Bytes
The bytecode.
def get_code(tx_state: TransactionState, code_hash: Hash32) -> Bytes:
| 217 | <snip> |
|---|---|
| 235 | if code_hash == EMPTY_CODE_HASH: |
| 236 | return b"" |
| 237 | if code_hash in tx_state.code_writes: |
| 238 | return tx_state.code_writes[code_hash] |
| 239 | if code_hash in tx_state.parent.code_writes: |
| 240 | return tx_state.parent.code_writes[code_hash] |
| 241 | return tx_state.parent.pre_state.get_code(code_hash) |
get_storage ¶
Get a value at a storage key on an account. Return U256(0) if
the storage key has not been set previously.
Parameters
tx_state : The transaction state. address : Address of the account. key : Key to look up.
Returns
value : U256
Value at the key.
def get_storage(tx_state: TransactionState, address: Address, key: Bytes32) -> U256:
| 247 | <snip> |
|---|---|
| 266 | tx_state.storage_reads.add((address, key)) |
| 267 | if address in tx_state.storage_writes: |
| 268 | if key in tx_state.storage_writes[address]: |
| 269 | return tx_state.storage_writes[address][key] |
| 270 | if address in tx_state.parent.storage_writes: |
| 271 | if key in tx_state.parent.storage_writes[address]: |
| 272 | return tx_state.parent.storage_writes[address][key] |
| 273 | return tx_state.parent.pre_state.get_storage(address, key) |
get_storage_original ¶
Get the original value in a storage slot i.e. the value before the
current transaction began. Read from block-level writes, then
pre_state. Return U256(0) for accounts created in the current
transaction.
Parameters
tx_state : The transaction state. address : Address of the account to read the value from. key : Key of the storage slot.
def get_storage_original(tx_state: TransactionState, address: Address, key: Bytes32) -> U256:
| 279 | <snip> |
|---|---|
| 295 | if address in tx_state.created_accounts: |
| 296 | return U256(0) |
| 297 | if address in tx_state.parent.storage_writes: |
| 298 | if key in tx_state.parent.storage_writes[address]: |
| 299 | return tx_state.parent.storage_writes[address][key] |
| 300 | return tx_state.parent.pre_state.get_storage(address, key) |
get_transient_storage ¶
Get a value at a storage key on an account from transient storage.
Return U256(0) if the storage key has not been set previously.
Parameters
tx_state : The transaction state. address : Address of the account. key : Key to look up.
Returns
value : U256
Value at the key.
def get_transient_storage(tx_state: TransactionState, address: Address, key: Bytes32) -> U256:
| 306 | <snip> |
|---|---|
| 325 | return tx_state.transient_storage.get((address, key), U256(0)) |
account_exists ¶
Check if an account exists in the state trie.
Parameters
tx_state : The transaction state. address : Address of the account that needs to be checked.
Returns
account_exists : bool
True if account exists in the state trie, False otherwise.
def account_exists(tx_state: TransactionState, address: Address) -> bool:
| 329 | <snip> |
|---|---|
| 345 | return get_account_optional(tx_state, address) is not None |
account_deployable ¶
Check if an account's code can be written to.
def account_deployable(tx_state: TransactionState, address: Address) -> bool:
| 349 | <snip> |
|---|---|
| 352 | account = get_account(tx_state, address) |
| 353 | if account.nonce != Uint(0) or account.code_hash != EMPTY_CODE_HASH: |
| 354 | return False |
| 355 | |
| 356 | return True |
account_exists_and_is_empty ¶
Check if an account exists and has zero nonce, empty code and zero balance.
Parameters
tx_state : The transaction state. address : Address of the account that needs to be checked.
Returns
exists_and_is_empty : bool
True if an account exists and has zero nonce, empty code and
zero balance, False otherwise.
def account_exists_and_is_empty(tx_state: TransactionState, address: Address) -> bool:
| 362 | <snip> |
|---|---|
| 380 | account = get_account_optional(tx_state, address) |
| 381 | return ( |
| 382 | account is not None |
| 383 | and account.nonce == Uint(0) |
| 384 | and account.code_hash == EMPTY_CODE_HASH |
| 385 | and account.balance == 0 |
| 386 | ) |
is_account_alive ¶
Check whether an account is both in the state and non-empty.
Parameters
tx_state : The transaction state. address : Address of the account that needs to be checked.
Returns
is_alive : bool
True if the account is alive.
def is_account_alive(tx_state: TransactionState, address: Address) -> bool:
| 390 | <snip> |
|---|---|
| 406 | account = get_account_optional(tx_state, address) |
| 407 | return account is not None and account != EMPTY_ACCOUNT |
set_account ¶
Set the Account object at an address. Setting to None
deletes the account (but not its storage, see
destroy_account()).
Parameters
tx_state : The transaction state. address : Address to set. account : Account to set at address.
def set_account(tx_state: TransactionState, address: Address, account: Optional[Account]) -> None:
| 415 | <snip> |
|---|---|
| 430 | tx_state.account_writes[address] = account |
set_storage ¶
Set a value at a storage key on an account.
Parameters
tx_state : The transaction state. address : Address of the account. key : Key to set. value : Value to set at the key.
def set_storage(tx_state: TransactionState, address: Address, key: Bytes32, value: U256) -> None:
| 439 | <snip> |
|---|---|
| 454 | assert get_account_optional(tx_state, address) is not None |
| 455 | if address not in tx_state.storage_writes: |
| 456 | tx_state.storage_writes[address] = {} |
| 457 | tx_state.storage_writes[address][key] = value |
destroy_account ¶
Completely remove the account at address and all of its storage.
Invoked by modify_state (and the coinbase fee-credit path) to
clean up an account that has become empty (zero nonce, empty
code, and zero balance) so it does not appear in the post-state.
Parameters
tx_state : The transaction state. address : Address of account to destroy.
def destroy_account(tx_state: TransactionState, address: Address) -> None:
| 461 | <snip> |
|---|---|
| 476 | destroy_storage(tx_state, address) |
| 477 | set_account(tx_state, address, None) |
clear_account_preserving_balance ¶
Clear an account's nonce, code, and storage while preserving its balance.
Parameters
tx_state : The transaction state. address : Address of the account to modify.
def clear_account_preserving_balance(tx_state: TransactionState, address: Address) -> None:
| 483 | <snip> |
|---|---|
| 495 | |
| 496 | def clear_account(account: Account) -> None: |
| 497 | account.nonce = Uint(0) |
| 498 | account.code_hash = EMPTY_CODE_HASH |
| 499 | |
| 500 | destroy_storage(tx_state, address) |
| 501 | modify_state(tx_state, address, clear_account) |
destroy_storage ¶
Completely remove the storage at address.
Convert storage writes to reads before deleting so that accesses from created-then-destroyed accounts appear in the Block Access List. Only supports same transaction destruction.
Parameters
tx_state : The transaction state. address : Address of account whose storage is to be deleted.
mark_account_created ¶
Mark an account as having been created in the current transaction.
This information is used by get_storage_original() to handle an
obscure edgecase, and to respect the constraints added to
SELFDESTRUCT by EIP-6780.
The marker is not removed even if the account creation reverts.
Since the account cannot have had code prior to its creation and
can't call get_storage_original(), this is harmless.
Parameters
tx_state : The transaction state. address : Address of the account that has been created.
def mark_account_created(tx_state: TransactionState, address: Address) -> None:
| 527 | <snip> |
|---|---|
| 545 | tx_state.created_accounts.add(address) |
set_transient_storage ¶
Set a value at a storage key on an account in transient storage.
Parameters
tx_state : The transaction state. address : Address of the account. key : Key to set. value : Value to set at the key.
modify_state ¶
Modify an Account in the state. If, after modification, the
account exists and has zero nonce, empty code, and zero balance, it
is destroyed.
def modify_state(tx_state: TransactionState, address: Address, f: Callable[[Account], None]) -> None:
| 580 | <snip> |
|---|---|
| 585 | set_account(tx_state, address, modify(get_account(tx_state, address), f)) |
| 586 | if account_exists_and_is_empty(tx_state, address): |
| 587 | destroy_account(tx_state, address) |
move_ether ¶
Move funds between accounts.
Parameters
tx_state : The transaction state. sender_address : Address of the sender. recipient_address : Address of the recipient. amount : The amount to transfer.
def move_ether(tx_state: TransactionState, sender_address: Address, recipient_address: Address, amount: U256) -> None:
| 596 | <snip> |
|---|---|
| 611 | |
| 612 | def reduce_sender_balance(sender: Account) -> None: |
| 613 | if sender.balance < amount: |
| 614 | raise AssertionError |
| 615 | sender.balance -= amount |
| 616 | |
| 617 | def increase_recipient_balance(recipient: Account) -> None: |
| 618 | recipient.balance += amount |
| 619 | |
| 620 | modify_state(tx_state, sender_address, reduce_sender_balance) |
| 621 | modify_state(tx_state, recipient_address, increase_recipient_balance) |
create_ether ¶
Add newly created ether to an account.
Parameters
tx_state : The transaction state. address : Address of the account to which ether is added. amount : The amount of ether to be added to the account of interest.
def create_ether(tx_state: TransactionState, address: Address, amount: U256) -> None:
| 627 | <snip> |
|---|---|
| 640 | |
| 641 | def increase_balance(account: Account) -> None: |
| 642 | account.balance += amount |
| 643 | |
| 644 | modify_state(tx_state, address, increase_balance) |
set_account_balance ¶
Set the balance of an account.
Parameters
tx_state : The transaction state. address : Address of the account whose balance needs to be set. amount : The amount that needs to be set in the balance.
def set_account_balance(tx_state: TransactionState, address: Address, amount: U256) -> None:
| 650 | <snip> |
|---|---|
| 663 | |
| 664 | def set_balance(account: Account) -> None: |
| 665 | account.balance = amount |
| 666 | |
| 667 | modify_state(tx_state, address, set_balance) |
increment_nonce ¶
Increment the nonce of an account.
Parameters
tx_state : The transaction state. address : Address of the account whose nonce needs to be incremented.
def increment_nonce(tx_state: TransactionState, address: Address) -> None:
| 671 | <snip> |
|---|---|
| 682 | |
| 683 | def increase_nonce(sender: Account) -> None: |
| 684 | sender.nonce += Uint(1) |
| 685 | |
| 686 | modify_state(tx_state, address, increase_nonce) |
set_code ¶
Set Account code.
Parameters
tx_state : The transaction state. address : Address of the account whose code needs to be updated. code : The bytecode that needs to be set.
def set_code(tx_state: TransactionState, address: Address, code: Bytes) -> None:
| 692 | <snip> |
|---|---|
| 705 | code_hash = keccak256(code) |
| 706 | if code_hash != EMPTY_CODE_HASH: |
| 707 | tx_state.code_writes[code_hash] = code |
| 708 | |
| 709 | def write_code_hash(sender: Account) -> None: |
| 710 | sender.code_hash = code_hash |
| 711 | |
| 712 | modify_state(tx_state, address, write_code_hash) |
copy_tx_state ¶
Create a snapshot of the transaction state for rollback.
Deep-copy writes and transient storage. The parent reference,
created_accounts, storage_reads, and account_reads
are shared (not rolled back).
Parameters
tx_state : The transaction state to snapshot.
Returns
snapshot : TransactionState
A copy of the transaction state.
def copy_tx_state(tx_state: TransactionState) -> TransactionState:
| 719 | <snip> |
|---|---|
| 737 | return TransactionState( |
| 738 | parent=tx_state.parent, |
| 739 | account_writes=dict(tx_state.account_writes), |
| 740 | storage_writes={ |
| 741 | addr: dict(slots) |
| 742 | for addr, slots in tx_state.storage_writes.items() |
| 743 | }, |
| 744 | code_writes=dict(tx_state.code_writes), |
| 745 | created_accounts=tx_state.created_accounts, |
| 746 | transient_storage=dict(tx_state.transient_storage), |
| 747 | storage_reads=tx_state.storage_reads, |
| 748 | account_reads=tx_state.account_reads, |
| 749 | ) |
restore_tx_state ¶
Restore transaction state from a snapshot (rollback on failure).
Parameters
tx_state : The transaction state to restore. snapshot : The snapshot to restore from.
def restore_tx_state(tx_state: TransactionState, snapshot: TransactionState) -> None:
| 755 | <snip> |
|---|---|
| 766 | tx_state.account_writes = snapshot.account_writes |
| 767 | tx_state.storage_writes = snapshot.storage_writes |
| 768 | tx_state.code_writes = snapshot.code_writes |
| 769 | tx_state.transient_storage = snapshot.transient_storage |
incorporate_tx_into_block ¶
Merge transaction writes into the block state and clear for reuse.
Update the BAL builder incrementally by diffing this transaction's writes against the block's cumulative state. Merge reads and touches into block-level sets.
Parameters
tx_state : The transaction state to commit. builder : The BAL builder for incremental updates.
def incorporate_tx_into_block(tx_state: TransactionState, builder: "BlockAccessListBuilder") -> None:
| 779 | <snip> |
|---|---|
| 794 | from .block_access_lists import update_builder_from_tx |
| 795 | |
| 796 | block = tx_state.parent |
| 797 | |
| 798 | # Update BAL builder before merging writes into block state |
| 799 | update_builder_from_tx(builder, tx_state) |
| 800 | |
| 801 | # Merge reads and touches into block-level sets |
| 802 | block.storage_reads.update(tx_state.storage_reads) |
| 803 | block.account_reads.update(tx_state.account_reads) |
| 804 | |
| 805 | # Merge cumulative writes |
| 806 | for address, account in tx_state.account_writes.items(): |
| 807 | block.account_writes[address] = account |
| 808 | |
| 809 | for address, slots in tx_state.storage_writes.items(): |
| 810 | if address not in block.storage_writes: |
| 811 | block.storage_writes[address] = {} |
| 812 | block.storage_writes[address].update(slots) |
| 813 | |
| 814 | block.code_writes.update(tx_state.code_writes) |
| 815 | |
| 816 | tx_state.account_writes.clear() |
| 817 | tx_state.storage_writes.clear() |
| 818 | tx_state.code_writes.clear() |
| 819 | tx_state.created_accounts.clear() |
| 820 | tx_state.transient_storage.clear() |
| 821 | tx_state.storage_reads = set() |
| 822 | tx_state.account_reads = set() |
extract_block_diff ¶
Extract account, storage, and code diff from the block state.
Parameters
block_state : The block state.
Returns
diff : BlockDiff
Account, storage, and code changes accumulated during block execution.