ethereum.forks.amsterdam.fork

Ethereum Specification.

.. contents:: Table of Contents :backlinks: none :local:

Introduction

Entry point for the Ethereum specification.

BASE_FEE_MAX_CHANGE_DENOMINATOR

115
BASE_FEE_MAX_CHANGE_DENOMINATOR = Uint(8)

ELASTICITY_MULTIPLIER

116
ELASTICITY_MULTIPLIER = Uint(2)

EMPTY_OMMER_HASH

117
EMPTY_OMMER_HASH = keccak256(rlp.encode([]))

SYSTEM_ADDRESS

118
SYSTEM_ADDRESS = hex_to_address("0xfffffffffffffffffffffffffffffffffffffffe")

BEACON_ROOTS_ADDRESS

119
BEACON_ROOTS_ADDRESS = hex_to_address(
120
    "0x000F3df6D732807Ef1319fB7B8bB8522d0Beac02"
121
)

SYSTEM_TRANSACTION_GAS

122
SYSTEM_TRANSACTION_GAS = Uint(30000000)

SYSTEM_MAX_SSTORES_PER_CALL

Upper bound on the number of new storage slots a single system call is expected to write.

123
SYSTEM_MAX_SSTORES_PER_CALL = Uint(16)

MAX_BLOB_GAS_PER_BLOCK

128
MAX_BLOB_GAS_PER_BLOCK: Final[U64] = (
129
    GasCosts.BLOB_SCHEDULE_MAX * GasCosts.PER_BLOB
130
)

VERSIONED_HASH_VERSION_KZG

131
VERSIONED_HASH_VERSION_KZG = b"\x01"

GWEI_TO_WEI

132
GWEI_TO_WEI = U256(10**9)

WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS

134
WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS = hex_to_address(
135
    "0x00000961Ef480Eb55e80D19ad83579A64c007002"
136
)

CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS

137
CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS = hex_to_address(
138
    "0x0000BBdDc7CE488642fb579F8B00f3a590007251"
139
)

BUILDER_DEPOSIT_CONTRACT_ADDRESS

140
BUILDER_DEPOSIT_CONTRACT_ADDRESS = hex_to_address(
141
    "0x0000BFF46984E3725691FA540A8C7589300D8282"
142
)

BUILDER_EXIT_CONTRACT_ADDRESS

143
BUILDER_EXIT_CONTRACT_ADDRESS = hex_to_address(
144
    "0x000064D678505AD48F8CCB093BC65613800E8282"
145
)

HISTORY_STORAGE_ADDRESS

146
HISTORY_STORAGE_ADDRESS = hex_to_address(
147
    "0x0000F90827F1C53a10cb7A02335B175320002935"
148
)

MAX_BLOCK_SIZE

149
MAX_BLOCK_SIZE = 10_485_760

SAFETY_MARGIN

150
SAFETY_MARGIN = 2_097_152

MAX_RLP_BLOCK_SIZE

151
MAX_RLP_BLOCK_SIZE = MAX_BLOCK_SIZE - SAFETY_MARGIN

BLOB_COUNT_LIMIT

152
BLOB_COUNT_LIMIT = 6

ChainContext

Chain context needed for block execution.

155
@final
156
@slotted_freezable
157
@dataclass
class ChainContext:

chain_id

Identify the chain for transaction signature recovery.

163
    chain_id: U64

block_hashes

Recent ancestor hashes (up to 256) for the BLOCKHASH opcode.

166
    block_hashes: List[Hash32]

parent_header

Parent header used for header validation and system contracts.

169
    parent_header: Header | PreviousHeader

BlockChain

History and current state of the block chain.

173
@final
174
@dataclass
class BlockChain:

blocks

180
    blocks: List[Block]

state

181
    state: State

chain_id

182
    chain_id: U64

apply_fork

Transforms the state from the previous hard fork (old) into the block chain object for this hard fork and returns it.

When forks need to implement an irregular state transition, this function is used to handle the irregularity. See the :ref:DAO Fork <dao-fork> for an example.

Parameters

old : Previous block chain object.

Returns

new : BlockChain Upgraded block chain object for this hard fork.

def apply_fork(old: BlockChain) -> BlockChain:
186
    <snip>
205
    return old

get_last_256_block_hashes

Obtain the list of hashes of the previous 256 blocks in order of increasing block number.

This function will return less hashes for the first 256 blocks.

The BLOCKHASH opcode needs to access the latest hashes on the chain, therefore this function retrieves them.

Parameters

chain : History and current state.

Returns

recent_block_hashes : List[Hash32] Hashes of the recent 256 blocks in order of increasing block number.

def get_last_256_block_hashes(chain: BlockChain) -> List[Hash32]:
209
    <snip>
229
    recent_blocks = chain.blocks[-255:]
230
    # TODO: This function has not been tested rigorously
231
    if len(recent_blocks) == 0:
232
        return []
233
234
    recent_block_hashes = []
235
236
    for block in recent_blocks:
237
        prev_block_hash = block.header.parent_hash
238
        recent_block_hashes.append(prev_block_hash)
239
240
    # We are computing the hash only for the most recent block and not for
241
    # the rest of the blocks as they have successors which have the hash of
242
    # the current block as parent hash.
243
    most_recent_block_hash = keccak256(rlp.encode(recent_blocks[-1].header))
244
    recent_block_hashes.append(most_recent_block_hash)
245
246
    return recent_block_hashes

state_transition

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.

To implement Ethereum, in theory clients are only required to store the most recent 255 blocks of the chain since as far as execution is concerned, only those blocks are accessed. Practically, however, clients should store more blocks to handle reorgs.

Parameters

chain : History and current state. block : Block to apply to chain.

def state_transition(chain: BlockChain, ​​block: Block) -> None:
250
    <snip>
272
    chain_context = ChainContext(
273
        chain_id=chain.chain_id,
274
        block_hashes=get_last_256_block_hashes(chain),
275
        parent_header=chain.blocks[-1].header,
276
    )
277
278
    block_diff = execute_block(block, chain.state, chain_context)
279
280
    apply_changes_to_state(chain.state, block_diff)
281
    chain.blocks.append(block)
282
    if len(chain.blocks) > 255:
283
        # Real clients have to store more blocks to deal with reorgs, but the
284
        # protocol only requires the last 255
285
        chain.blocks = chain.blocks[-255:]

execute_block

Execute a block and validate the resulting roots against the header.

This method is idempotent.

Parameters

block : Block to validate and execute. pre_state : Pre-execution state provider. chain_context : Chain context that the block may need during execution.

Returns

block_diff : BlockDiff Account, storage, and code changes produced by block execution.

def execute_block(block: Block, ​​pre_state: State, ​​chain_context: ChainContext) -> BlockDiff:
293
    <snip>
313
    if len(rlp.encode(block)) > MAX_RLP_BLOCK_SIZE:
314
        raise InvalidBlock("Block rlp size exceeds MAX_RLP_BLOCK_SIZE")
315
316
    parent_header = chain_context.parent_header
317
    validate_header(parent_header, block.header)
318
319
    if block.ommers != ():
320
        raise InvalidBlock
321
322
    block_state = BlockState(pre_state=pre_state)
323
324
    block_env = vm.BlockEnvironment(
325
        chain_id=chain_context.chain_id,
326
        state=block_state,
327
        block_gas_limit=block.header.gas_limit,
328
        block_hashes=chain_context.block_hashes,
329
        coinbase=block.header.coinbase,
330
        number=block.header.number,
331
        base_fee_per_gas=block.header.base_fee_per_gas,
332
        time=block.header.timestamp,
333
        prev_randao=block.header.prev_randao,
334
        excess_blob_gas=block.header.excess_blob_gas,
335
        parent_beacon_block_root=block.header.parent_beacon_block_root,
336
        block_access_list_builder=BlockAccessListBuilder(),
337
        slot_number=block.header.slot_number,
338
    )
339
340
    block_output = apply_body(
341
        block_env=block_env,
342
        transactions=block.transactions,
343
        withdrawals=block.withdrawals,
344
    )
345
    block_diff = extract_block_diff(block_state)
346
    block_state_root, _ = pre_state.compute_state_root_and_trie_changes(
347
        block_diff.account_changes, block_diff.storage_changes
348
    )
349
    transactions_root = root(block_output.transactions_trie)
350
    receipt_root = root(block_output.receipts_trie)
351
    block_logs_bloom = logs_bloom(block_output.block_logs)
352
    withdrawals_root = root(block_output.withdrawals_trie)
353
    requests_hash = compute_requests_hash(block_output.requests)
354
    computed_block_access_list_hash = hash_block_access_list(
355
        block_output.block_access_list
356
    )
357
358
    block_gas_used = max(
359
        block_output.block_gas_used,
360
        block_output.block_state_gas_used,
361
    )
362
    if block_gas_used != block.header.gas_used:
363
        raise InvalidBlock(f"{block_gas_used} != {block.header.gas_used}")
364
    if transactions_root != block.header.transactions_root:
365
        raise InvalidBlock
366
    if block_state_root != block.header.state_root:
367
        raise InvalidBlock
368
    if receipt_root != block.header.receipt_root:
369
        raise InvalidBlock
370
    if block_logs_bloom != block.header.bloom:
371
        raise InvalidBlock
372
    if withdrawals_root != block.header.withdrawals_root:
373
        raise InvalidBlock
374
    if block_output.blob_gas_used != block.header.blob_gas_used:
375
        raise InvalidBlock
376
    if requests_hash != block.header.requests_hash:
377
        raise InvalidBlock
378
    if computed_block_access_list_hash != block.header.block_access_list_hash:
379
        raise InvalidBlock("Invalid block access list hash")
380
381
    return block_diff

calculate_base_fee_per_gas

Calculates the base fee per gas for the block.

Parameters

block_gas_limit : Gas limit of the block for which the base fee is being calculated. parent_gas_limit : Gas limit of the parent block. parent_gas_used : Gas used in the parent block. parent_base_fee_per_gas : Base fee per gas of the parent block.

Returns

base_fee_per_gas : Uint Base fee per gas for the block.

def calculate_base_fee_per_gas(block_gas_limit: Uint, ​​parent_gas_limit: Uint, ​​parent_gas_used: Uint, ​​parent_base_fee_per_gas: Uint) -> Uint:
390
    <snip>
410
    parent_gas_target = parent_gas_limit // ELASTICITY_MULTIPLIER
411
    if not check_gas_limit(block_gas_limit, parent_gas_limit):
412
        raise InvalidBlock
413
414
    if parent_gas_used == parent_gas_target:
415
        expected_base_fee_per_gas = parent_base_fee_per_gas
416
    elif parent_gas_used > parent_gas_target:
417
        gas_used_delta = parent_gas_used - parent_gas_target
418
419
        parent_fee_gas_delta = parent_base_fee_per_gas * gas_used_delta
420
        target_fee_gas_delta = parent_fee_gas_delta // parent_gas_target
421
422
        base_fee_per_gas_delta = max(
423
            target_fee_gas_delta // BASE_FEE_MAX_CHANGE_DENOMINATOR,
424
            Uint(1),
425
        )
426
427
        expected_base_fee_per_gas = (
428
            parent_base_fee_per_gas + base_fee_per_gas_delta
429
        )
430
    else:
431
        gas_used_delta = parent_gas_target - parent_gas_used
432
433
        parent_fee_gas_delta = parent_base_fee_per_gas * gas_used_delta
434
        target_fee_gas_delta = parent_fee_gas_delta // parent_gas_target
435
436
        base_fee_per_gas_delta = (
437
            target_fee_gas_delta // BASE_FEE_MAX_CHANGE_DENOMINATOR
438
        )
439
440
        expected_base_fee_per_gas = (
441
            parent_base_fee_per_gas - base_fee_per_gas_delta
442
        )
443
444
    return Uint(expected_base_fee_per_gas)

validate_header

Verify a block header against its parent.

In order to consider a block's header valid, the logic for the quantities in the header should match the logic for the block itself. For example the header timestamp should be greater than the block's parent timestamp because the block was created after the parent block. Additionally, the block's number should be directly following the parent block's number since it is the next block in the sequence.

Parameters

parent_header : Header of the parent block. header : Header to check for correctness.

def validate_header(parent_header: Header | PreviousHeader, ​​header: Header) -> None:
450
    <snip>
468
    if header.number < Uint(1):
469
        raise InvalidBlock
470
471
    excess_blob_gas = calculate_excess_blob_gas(parent_header)
472
    if header.excess_blob_gas != excess_blob_gas:
473
        raise InvalidBlock
474
475
    if header.gas_used > header.gas_limit:
476
        raise InvalidBlock
477
478
    expected_base_fee_per_gas = calculate_base_fee_per_gas(
479
        header.gas_limit,
480
        parent_header.gas_limit,
481
        parent_header.gas_used,
482
        parent_header.base_fee_per_gas,
483
    )
484
    if expected_base_fee_per_gas != header.base_fee_per_gas:
485
        raise InvalidBlock
486
    if header.timestamp <= parent_header.timestamp:
487
        raise InvalidBlock
488
    if header.number != parent_header.number + Uint(1):
489
        raise InvalidBlock
490
    if len(header.extra_data) > 32:
491
        raise InvalidBlock
492
    if header.difficulty != 0:
493
        raise InvalidBlock
494
    if header.nonce != b"\x00\x00\x00\x00\x00\x00\x00\x00":
495
        raise InvalidBlock
496
    if header.ommers_hash != EMPTY_OMMER_HASH:
497
        raise InvalidBlock
498
499
    block_parent_hash = keccak256(rlp.encode(parent_header))
500
    if header.parent_hash != block_parent_hash:
501
        raise InvalidBlock

check_transaction

Check if the transaction is includable in the block.

Parameters

block_env : The block scoped environment. block_output : The block output for the current block. tx : The transaction. sender : The recovered sender address of the transaction. tx_state : The transaction state tracker.

Returns

effective_gas_price : The price to charge for gas when the transaction is executed. blob_versioned_hashes : The blob versioned hashes of the transaction. tx_blob_gas_used: The blob gas used by the transaction.

Raises

InvalidBlock : If the transaction is not includable. GasUsedExceedsLimitError : If the gas used by the transaction exceeds the block's gas limit. NonceMismatchError : If the nonce of the transaction is not equal to the sender's nonce. InsufficientBalanceError : If the sender's balance is not enough to pay for the transaction. InvalidSenderError : If the transaction is from an address that does not exist anymore. PriorityFeeGreaterThanMaxFeeError : If the priority fee is greater than the maximum fee per gas. InsufficientMaxFeePerGasError : If the maximum fee per gas is insufficient for the transaction. InsufficientMaxFeePerBlobGasError : If the maximum fee per blob gas is insufficient for the transaction. BlobGasLimitExceededError : If the blob gas used by the transaction exceeds the block's blob gas limit. InvalidBlobVersionedHashError : If the transaction contains a blob versioned hash with an invalid version. NoBlobDataError : If the transaction is a type 3 but has no blobs. BlobCountExceededError : If the transaction is a type 3 and has more blobs than the limit. TransactionTypeContractCreationError: If the transaction type is not allowed to create contracts. EmptyAuthorizationListError : If the transaction is a SetCodeTransaction and the authorization list is empty.

def check_transaction(block_env: ethereum.forks.amsterdam.vm.BlockEnvironment, ​​block_output: ethereum.forks.amsterdam.vm.BlockOutput, ​​tx: Transaction, ​​sender: Address, ​​tx_state: TransactionState) -> Tuple[Uint, Tuple[VersionedHash, ...], U64]:
511
    <snip>
571
    regular_gas_available = (
572
        block_env.block_gas_limit - block_output.block_gas_used
573
    )
574
    state_gas_available = (
575
        block_env.block_gas_limit - block_output.block_state_gas_used
576
    )
577
    blob_gas_available = MAX_BLOB_GAS_PER_BLOCK - block_output.blob_gas_used
578
579
    # EIP-8037 per-dimension inclusion check.
580
    if min(TX_MAX_GAS_LIMIT, tx.gas) > regular_gas_available:
581
        raise GasUsedExceedsLimitError("regular gas used exceeds limit")
582
583
    if tx.gas > state_gas_available:
584
        raise GasUsedExceedsLimitError("state gas used exceeds limit")
585
586
    tx_blob_gas_used = calculate_total_blob_gas(tx)
587
    if tx_blob_gas_used > blob_gas_available:
588
        raise BlobGasLimitExceededError("blob gas limit exceeded")
589
590
    sender_account = get_account(tx_state, sender)
591
592
    if isinstance(tx, FeeMarketCapableTransaction):
593
        if tx.max_fee_per_gas < tx.max_priority_fee_per_gas:
594
            raise PriorityFeeGreaterThanMaxFeeError(
595
                "priority fee greater than max fee"
596
            )
597
        if tx.max_fee_per_gas < block_env.base_fee_per_gas:
598
            raise InsufficientMaxFeePerGasError(
599
                tx.max_fee_per_gas, block_env.base_fee_per_gas
600
            )
601
602
        priority_fee_per_gas = min(
603
            tx.max_priority_fee_per_gas,
604
            tx.max_fee_per_gas - block_env.base_fee_per_gas,
605
        )
606
        effective_gas_price = priority_fee_per_gas + block_env.base_fee_per_gas
607
        max_gas_fee = tx.gas * tx.max_fee_per_gas
608
    else:
609
        if tx.gas_price < block_env.base_fee_per_gas:
610
            raise InvalidBlock
611
        effective_gas_price = tx.gas_price
612
        max_gas_fee = tx.gas * tx.gas_price
613
614
    if isinstance(tx, BlobTransaction):
615
        blob_count = len(tx.blob_versioned_hashes)
616
        if blob_count == 0:
617
            raise NoBlobDataError("no blob data in transaction")
618
        if blob_count > BLOB_COUNT_LIMIT:
619
            raise BlobCountExceededError(
620
                f"Tx has {blob_count} blobs. Max allowed: {BLOB_COUNT_LIMIT}"
621
            )
622
        for blob_versioned_hash in tx.blob_versioned_hashes:
623
            if blob_versioned_hash[0:1] != VERSIONED_HASH_VERSION_KZG:
624
                raise InvalidBlobVersionedHashError(
625
                    "invalid blob versioned hash"
626
                )
627
628
        blob_gas_price = calculate_blob_gas_price(block_env.excess_blob_gas)
629
        if Uint(tx.max_fee_per_blob_gas) < blob_gas_price:
630
            raise InsufficientMaxFeePerBlobGasError(
631
                "insufficient max fee per blob gas"
632
            )
633
634
        max_gas_fee += Uint(calculate_total_blob_gas(tx)) * Uint(
635
            tx.max_fee_per_blob_gas
636
        )
637
        blob_versioned_hashes = tx.blob_versioned_hashes
638
    else:
639
        blob_versioned_hashes = ()
640
641
    if isinstance(tx, (BlobTransaction, SetCodeTransaction)):
642
        if not isinstance(tx.to, Address):
643
            raise TransactionTypeContractCreationError(tx)
644
645
    if isinstance(tx, SetCodeTransaction):
646
        if not any(tx.authorizations):
647
            raise EmptyAuthorizationListError("empty authorization list")
648
649
    if sender_account.nonce > Uint(tx.nonce):
650
        raise NonceMismatchError("nonce too low")
651
    elif sender_account.nonce < Uint(tx.nonce):
652
        raise NonceMismatchError("nonce too high")
653
654
    if Uint(sender_account.balance) < max_gas_fee + Uint(tx.value):
655
        raise InsufficientBalanceError("insufficient sender balance")
656
    sender_code = get_code(tx_state, sender_account.code_hash)
657
    if sender_account.code_hash != EMPTY_CODE_HASH and not is_valid_delegation(
658
        sender_code
659
    ):
660
        raise InvalidSenderError("not EOA")
661
662
    return (
663
        effective_gas_price,
664
        blob_versioned_hashes,
665
        tx_blob_gas_used,
666
    )

make_receipt

Make the receipt for a transaction that was executed.

Parameters

tx : The executed transaction. error : Error in the top level frame of the transaction, if any. cumulative_gas_used : The total gas used so far in the block after the transaction was executed. This is the gas used after refunds. logs : The logs produced by the transaction.

Returns

receipt : The receipt for the transaction.

def make_receipt(tx: Transaction, ​​error: Optional[EthereumException], ​​cumulative_gas_used: Uint, ​​logs: Tuple[Log, ...]) -> Bytes | Receipt:
675
    <snip>
696
    receipt = Receipt(
697
        succeeded=error is None,
698
        cumulative_gas_used=cumulative_gas_used,
699
        bloom=logs_bloom(logs),
700
        logs=logs,
701
    )
702
703
    return encode_receipt(tx, receipt)

process_checked_system_transaction

Process a system transaction and raise an error if the contract does not contain code or if the transaction fails.

Parameters

block_env : The block scoped environment. target_address : Address of the contract to call. data : Data to pass to the contract.

Returns

system_tx_output : MessageCallOutput Output of processing the system transaction.

def process_checked_system_transaction(block_env: ethereum.forks.amsterdam.vm.BlockEnvironment, ​​target_address: Address, ​​data: Bytes) -> MessageCallOutput:
711
    <snip>
730
    # Pre-check that the system contract has code. We use a throwaway
731
    # TransactionState here that is *never* propagated back to BlockState
732
    # (no incorporate_tx_into_block call); the same get_account / get_code
733
    # lookups are performed and properly tracked by
734
    # process_unchecked_system_transaction below, which this function
735
    # always calls. Reading via a TransactionState (rather than directly
736
    # against pre_state) lets us see system contracts deployed earlier in
737
    # the same block — see EIP-7002 and EIP-7251 for this edge case.
738
    untracked_state = TransactionState(parent=block_env.state)
739
    system_contract_code = get_code(
740
        untracked_state,
741
        get_account(untracked_state, target_address).code_hash,
742
    )
743
744
    if len(system_contract_code) == 0:
745
        raise InvalidBlock(
746
            f"System contract address {target_address.hex()} does not "
747
            "contain code"
748
        )
749
750
    system_tx_output = process_unchecked_system_transaction(
751
        block_env,
752
        target_address,
753
        data,
754
    )
755
756
    if system_tx_output.error:
757
        raise InvalidBlock(
758
            f"System contract ({target_address.hex()}) call failed: "
759
            f"{system_tx_output.error}"
760
        )
761
762
    return system_tx_output

process_unchecked_system_transaction

Process a system transaction without checking if the contract contains code or if the transaction fails.

Parameters

block_env : The block scoped environment. target_address : Address of the contract to call. data : Data to pass to the contract.

Returns

system_tx_output : MessageCallOutput Output of processing the system transaction.

def process_unchecked_system_transaction(block_env: ethereum.forks.amsterdam.vm.BlockEnvironment, ​​target_address: Address, ​​data: Bytes) -> MessageCallOutput:
770
    <snip>
789
    system_tx_state = TransactionState(parent=block_env.state)
790
    system_contract_code = get_code(
791
        system_tx_state,
792
        get_account(system_tx_state, target_address).code_hash,
793
    )
794
795
    tx_env = vm.TransactionEnvironment(
796
        origin=SYSTEM_ADDRESS,
797
        recipient=target_address,
798
        value=U256(0),
799
        gas_price=block_env.base_fee_per_gas,
800
        gas=SYSTEM_TRANSACTION_GAS,
801
        state_gas_reservoir=(
802
            StateGasCosts.STORAGE_SET * SYSTEM_MAX_SSTORES_PER_CALL
803
        ),
804
        access_list_addresses=set(),
805
        access_list_storage_keys=set(),
806
        state=system_tx_state,
807
        blob_versioned_hashes=(),
808
        authorizations=(),
809
        index_in_block=None,
810
        tx_hash=None,
811
    )
812
813
    system_tx_message = Message(
814
        block_env=block_env,
815
        tx_env=tx_env,
816
        caller=SYSTEM_ADDRESS,
817
        target=target_address,
818
        gas=SYSTEM_TRANSACTION_GAS,
819
        state_gas_reservoir=(
820
            StateGasCosts.STORAGE_SET * SYSTEM_MAX_SSTORES_PER_CALL
821
        ),
822
        value=U256(0),
823
        data=data,
824
        code=system_contract_code,
825
        depth=Uint(0),
826
        current_target=target_address,
827
        code_address=target_address,
828
        should_transfer_value=False,
829
        is_static=False,
830
        accessed_addresses=set(),
831
        accessed_storage_keys=set(),
832
        disable_precompiles=False,
833
        parent_evm=None,
834
    )
835
836
    system_tx_output = process_message_call(system_tx_message)
837
838
    incorporate_tx_into_block(
839
        system_tx_state, block_env.block_access_list_builder
840
    )
841
842
    return system_tx_output

apply_body

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.

Parameters

block_env : The block scoped environment. transactions : Transactions included in the block. withdrawals : Withdrawals to be processed in the current block.

Returns

block_output : The block output for the current block.

def apply_body(block_env: ethereum.forks.amsterdam.vm.BlockEnvironment, ​​transactions: Tuple[LegacyTransaction | Bytes, ...], ​​withdrawals: Tuple[Withdrawal, ...]) -> ethereum.forks.amsterdam.vm.BlockOutput:
850
    <snip>
875
    block_output = vm.BlockOutput()
876
877
    process_unchecked_system_transaction(
878
        block_env=block_env,
879
        target_address=BEACON_ROOTS_ADDRESS,
880
        data=block_env.parent_beacon_block_root,
881
    )
882
883
    process_unchecked_system_transaction(
884
        block_env=block_env,
885
        target_address=HISTORY_STORAGE_ADDRESS,
886
        data=block_env.block_hashes[-1],  # The parent hash
887
    )
888
889
    for i, tx in enumerate(map(decode_transaction, transactions)):
890
        process_transaction(block_env, block_output, tx, Uint(i))
891
892
    # EIP-7928: Post-execution operations use index N+1
893
    block_env.block_access_list_builder.block_access_index = BlockAccessIndex(
894
        ulen(transactions) + Uint(1)
895
    )
896
897
    process_withdrawals(block_env, block_output, withdrawals)
898
899
    process_general_purpose_requests(
900
        block_env=block_env,
901
        block_output=block_output,
902
    )
903
904
    block_output.block_access_list = build_block_access_list(
905
        block_env.block_access_list_builder, block_env.state
906
    )
907
908
    # Validate block access list gas limit constraint (EIP-7928)
909
    validate_block_access_list_gas_limit(
910
        block_access_list=block_output.block_access_list,
911
        block_gas_limit=block_env.block_gas_limit,
912
    )
913
914
    return block_output

process_general_purpose_requests

Process all the requests in the block.

Parameters

block_env : The execution environment for the Block. block_output : The block output for the current block.

def process_general_purpose_requests(block_env: ethereum.forks.amsterdam.vm.BlockEnvironment, ​​block_output: ethereum.forks.amsterdam.vm.BlockOutput) -> None:
921
    <snip>
932
    # Requests are to be in ascending order of request type
933
    deposit_requests = parse_deposit_requests(block_output)
934
    requests_from_execution = block_output.requests
935
    if len(deposit_requests) > 0:
936
        requests_from_execution.append(DEPOSIT_REQUEST_TYPE + deposit_requests)
937
938
    system_withdrawal_tx_output = process_checked_system_transaction(
939
        block_env=block_env,
940
        target_address=WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS,
941
        data=b"",
942
    )
943
944
    if len(system_withdrawal_tx_output.return_data) > 0:
945
        requests_from_execution.append(
946
            WITHDRAWAL_REQUEST_TYPE + system_withdrawal_tx_output.return_data
947
        )
948
949
    system_consolidation_tx_output = process_checked_system_transaction(
950
        block_env=block_env,
951
        target_address=CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS,
952
        data=b"",
953
    )
954
955
    if len(system_consolidation_tx_output.return_data) > 0:
956
        requests_from_execution.append(
957
            CONSOLIDATION_REQUEST_TYPE
958
            + system_consolidation_tx_output.return_data
959
        )
960
961
    system_builder_deposit_tx_output = process_checked_system_transaction(
962
        block_env=block_env,
963
        target_address=BUILDER_DEPOSIT_CONTRACT_ADDRESS,
964
        data=b"",
965
    )
966
967
    if len(system_builder_deposit_tx_output.return_data) > 0:
968
        requests_from_execution.append(
969
            BUILDER_DEPOSIT_REQUEST_TYPE
970
            + system_builder_deposit_tx_output.return_data
971
        )
972
973
    system_builder_exit_tx_output = process_checked_system_transaction(
974
        block_env=block_env,
975
        target_address=BUILDER_EXIT_CONTRACT_ADDRESS,
976
        data=b"",
977
    )
978
979
    if len(system_builder_exit_tx_output.return_data) > 0:
980
        requests_from_execution.append(
981
            BUILDER_EXIT_REQUEST_TYPE
982
            + system_builder_exit_tx_output.return_data
983
        )

process_transaction

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. Calling contracts, deploying code, and incrementing nonces are all examples of actions that happen within this function or from a call made within this function.

Accounts that are marked for deletion are processed and destroyed after execution.

Parameters

block_env : Environment for the Ethereum Virtual Machine. block_output : The block output for the current block. tx : Transaction to execute. index: Index of the transaction in the block.

def process_transaction(block_env: ethereum.forks.amsterdam.vm.BlockEnvironment, ​​block_output: ethereum.forks.amsterdam.vm.BlockOutput, ​​tx: Transaction, ​​index: Uint) -> None:
992
    <snip>
1016
    block_env.block_access_list_builder.block_access_index = BlockAccessIndex(
1017
        index + Uint(1)
1018
    )
1019
    tx_state = TransactionState(parent=block_env.state)
1020
1021
    trie_set(
1022
        block_output.transactions_trie,
1023
        rlp.encode(index),
1024
        encode_transaction(tx),
1025
    )
1026
1027
    tx_chain_id = chain_id(tx)
1028
    if tx_chain_id is not None and tx_chain_id != block_env.chain_id:
1029
        raise WrongChainIdError(
1030
            expected=block_env.chain_id,
1031
            actual=tx_chain_id,
1032
        )
1033
1034
    sender = recover_sender(tx)
1035
    intrinsic = validate_transaction(tx, sender)
1036
1037
    (
1038
        effective_gas_price,
1039
        blob_versioned_hashes,
1040
        tx_blob_gas_used,
1041
    ) = check_transaction(
1042
        block_env=block_env,
1043
        block_output=block_output,
1044
        tx=tx,
1045
        sender=sender,
1046
        tx_state=tx_state,
1047
    )
1048
1049
    sender_account = get_account(tx_state, sender)
1050
1051
    if isinstance(tx, BlobTransaction):
1052
        blob_gas_fee = calculate_data_fee(block_env.excess_blob_gas, tx)
1053
    else:
1054
        blob_gas_fee = Uint(0)
1055
1056
    effective_gas_fee = tx.gas * effective_gas_price
1057
1058
    # Split execution gas into a regular grant (capped by the remaining
1059
    # regular-gas budget) and a state gas reservoir.
1060
    allocation = allocate_execution_gas(tx.gas, intrinsic)
1061
1062
    increment_nonce(tx_state, sender)
1063
1064
    sender_balance_after_gas_fee = (
1065
        Uint(sender_account.balance) - effective_gas_fee - blob_gas_fee
1066
    )
1067
    set_account_balance(tx_state, sender, U256(sender_balance_after_gas_fee))
1068
1069
    access_list_addresses = set()
1070
    access_list_storage_keys = set()
1071
    access_list_addresses.add(block_env.coinbase)
1072
    if has_access_list(tx):
1073
        for access in tx.access_list:
1074
            access_list_addresses.add(access.account)
1075
            for slot in access.slots:
1076
                access_list_storage_keys.add((access.account, slot))
1077
1078
    authorizations: Tuple[Authorization, ...] = ()
1079
    if isinstance(tx, SetCodeTransaction):
1080
        authorizations = tx.authorizations
1081
1082
    tx_env = vm.TransactionEnvironment(
1083
        origin=sender,
1084
        recipient=tx.to,
1085
        value=tx.value,
1086
        gas_price=effective_gas_price,
1087
        gas=allocation.regular_gas,
1088
        state_gas_reservoir=allocation.state_gas_reservoir,
1089
        access_list_addresses=access_list_addresses,
1090
        access_list_storage_keys=access_list_storage_keys,
1091
        state=tx_state,
1092
        blob_versioned_hashes=blob_versioned_hashes,
1093
        authorizations=authorizations,
1094
        index_in_block=index,
1095
        tx_hash=get_transaction_hash(encode_transaction(tx)),
1096
    )
1097
1098
    message = prepare_message(block_env, tx_env, tx)
1099
1100
    tx_output = process_message_call(message)
1101
1102
    settlement = settle_transaction_gas(
1103
        tx.gas,
1104
        intrinsic,
1105
        tx_output.gas_left,
1106
        tx_output.state_gas_left,
1107
        tx_output.refund_counter,
1108
        tx_output.state_gas_used,
1109
    )
1110
1111
    gas_refund_amount = settlement.gas_left * effective_gas_price
1112
1113
    # For non-1559 transactions effective_gas_price == tx.gas_price
1114
    priority_fee_per_gas = effective_gas_price - block_env.base_fee_per_gas
1115
    transaction_fee = settlement.gas_used * priority_fee_per_gas
1116
1117
    # refund gas
1118
    create_ether(tx_state, sender, U256(gas_refund_amount))
1119
1120
    # transfer miner fees
1121
    create_ether(tx_state, block_env.coinbase, U256(transaction_fee))
1122
1123
    block_output.block_gas_used += settlement.regular_gas_used
1124
    block_output.block_state_gas_used += settlement.state_gas_used
1125
    block_output.blob_gas_used += tx_blob_gas_used
1126
1127
    block_output.cumulative_gas_used += settlement.gas_used
1128
    receipt = make_receipt(
1129
        tx, tx_output.error, block_output.cumulative_gas_used, tx_output.logs
1130
    )
1131
1132
    receipt_key = rlp.encode(Uint(index))
1133
    block_output.receipt_keys += (receipt_key,)
1134
1135
    trie_set(
1136
        block_output.receipts_trie,
1137
        receipt_key,
1138
        receipt,
1139
    )
1140
1141
    block_output.block_logs += tx_output.logs
1142
1143
    for address in tx_output.accounts_to_delete:
1144
        clear_account_preserving_balance(tx_state, address)
1145
1146
    incorporate_tx_into_block(tx_state, block_env.block_access_list_builder)

process_withdrawals

Increase the balance of the withdrawing account.

def process_withdrawals(block_env: ethereum.forks.amsterdam.vm.BlockEnvironment, ​​block_output: ethereum.forks.amsterdam.vm.BlockOutput, ​​withdrawals: Tuple[Withdrawal, ...]) -> None:
1154
    <snip>
1157
    wd_state = TransactionState(parent=block_env.state)
1158
1159
    for i, wd in enumerate(withdrawals):
1160
        trie_set(
1161
            block_output.withdrawals_trie,
1162
            rlp.encode(Uint(i)),
1163
            rlp.encode(wd),
1164
        )
1165
1166
        create_ether(wd_state, wd.address, wd.amount * GWEI_TO_WEI)
1167
1168
    incorporate_tx_into_block(wd_state, block_env.block_access_list_builder)

check_gas_limit

Validates the gas limit for a block.

The bounds of the gas limit, max_adjustment_delta, is set as the quotient of the parent block's gas limit and the LIMIT_ADJUSTMENT_FACTOR. Therefore, if the gas limit that is passed through as a parameter is greater than or equal to the sum of the parent's gas and the adjustment delta then the limit for gas is too high and fails this function's check. Similarly, if the limit is less than or equal to the difference of the parent's gas and the adjustment delta or the predefined LIMIT_MINIMUM then this function's check fails because the gas limit doesn't allow for a sufficient or reasonable amount of gas to be used on a block.

Parameters

gas_limit : Gas limit to validate.

parent_gas_limit : Gas limit of the parent block.

Returns

check : bool True if gas limit constraints are satisfied, False otherwise.

def check_gas_limit(gas_limit: Uint, ​​parent_gas_limit: Uint) -> bool:
1172
    <snip>
1200
    max_adjustment_delta = parent_gas_limit // GasCosts.LIMIT_ADJUSTMENT_FACTOR
1201
    if gas_limit >= parent_gas_limit + max_adjustment_delta:
1202
        return False
1203
    if gas_limit <= parent_gas_limit - max_adjustment_delta:
1204
        return False
1205
    if gas_limit < GasCosts.LIMIT_MINIMUM:
1206
        return False
1207
1208
    return True