ethereum.forks.gray_glacier.forkethereum.forks.paris.fork

Ethereum Specification.

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

Introduction

Entry point for the Ethereum specification.

BLOCK_REWARD

66
BLOCK_REWARD = U256(2 * 10**18)

BASE_FEE_MAX_CHANGE_DENOMINATOR

62
BASE_FEE_MAX_CHANGE_DENOMINATOR = Uint(8)

ELASTICITY_MULTIPLIER

63
ELASTICITY_MULTIPLIER = Uint(2)

GAS_LIMIT_ADJUSTMENT_FACTOR

64
GAS_LIMIT_ADJUSTMENT_FACTOR = Uint(1024)

GAS_LIMIT_MINIMUM

65
GAS_LIMIT_MINIMUM = Uint(5000)

MINIMUM_DIFFICULTY

71
MINIMUM_DIFFICULTY = Uint(131072)

MAX_OMMER_DEPTH

72
MAX_OMMER_DEPTH = Uint(6)

BOMB_DELAY_BLOCKS

73
BOMB_DELAY_BLOCKS = 11400000

EMPTY_OMMER_HASH

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

BlockChain

History and current state of the block chain.

69
@dataclass
class BlockChain:

blocks

75
    blocks: List[Block]

state

76
    state: State

chain_id

77
    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:
81
    """
82
    Transforms the state from the previous hard fork (`old`) into the block
83
    chain object for this hard fork and returns it.
84
85
    When forks need to implement an irregular state transition, this function
86
    is used to handle the irregularity. See the :ref:`DAO Fork <dao-fork>` for
87
    an example.
88
89
    Parameters
90
    ----------
91
    old :
92
        Previous block chain object.
93
94
    Returns
95
    -------
96
    new : `BlockChain`
97
        Upgraded block chain object for this hard fork.
98
99
    """
100
    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]:
104
    """
105
    Obtain the list of hashes of the previous 256 blocks in order of
106
    increasing block number.
107
108
    This function will return less hashes for the first 256 blocks.
109
110
    The ``BLOCKHASH`` opcode needs to access the latest hashes on the chain,
111
    therefore this function retrieves them.
112
113
    Parameters
114
    ----------
115
    chain :
116
        History and current state.
117
118
    Returns
119
    -------
120
    recent_block_hashes : `List[Hash32]`
121
        Hashes of the recent 256 blocks in order of increasing block number.
122
123
    """
124
    recent_blocks = chain.blocks[-255:]
125
    # TODO: This function has not been tested rigorously
126
    if len(recent_blocks) == 0:
127
        return []
128
129
    recent_block_hashes = []
130
131
    for block in recent_blocks:
132
        prev_block_hash = block.header.parent_hash
133
        recent_block_hashes.append(prev_block_hash)
134
135
    # We are computing the hash only for the most recent block and not for
136
    # the rest of the blocks as they have successors which have the hash of
137
    # the current block as parent hash.
138
    most_recent_block_hash = keccak256(rlp.encode(recent_blocks[-1].header))
139
    recent_block_hashes.append(most_recent_block_hash)
140
141
    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:
145
    """
146
    Attempts to apply a block to an existing block chain.
147
148
    All parts of the block's contents need to be verified before being added
149
    to the chain. Blocks are verified by ensuring that the contents of the
150
    block make logical sense with the contents of the parent block. The
151
    information in the block's header must also match the corresponding
152
    information in the block.
153
154
    To implement Ethereum, in theory clients are only required to store the
155
    most recent 255 blocks of the chain since as far as execution is
156
    concerned, only those blocks are accessed. Practically, however, clients
157
    should store more blocks to handle reorgs.
158
159
    Parameters
160
    ----------
161
    chain :
162
        History and current state.
163
    block :
164
        Block to apply to `chain`.
165
166
    """
167
    validate_header(chain, block.header)
176
    validate_ommers(block.ommers, block.header, chain)
168
    if block.ommers != ():
169
        raise InvalidBlock
170
171
    block_env = vm.BlockEnvironment(
172
        chain_id=chain.chain_id,
173
        state=chain.state,
174
        block_gas_limit=block.header.gas_limit,
175
        block_hashes=get_last_256_block_hashes(chain),
176
        coinbase=block.header.coinbase,
177
        number=block.header.number,
178
        base_fee_per_gas=block.header.base_fee_per_gas,
179
        time=block.header.timestamp,
187
        difficulty=block.header.difficulty,
180
        prev_randao=block.header.prev_randao,
181
    )
182
183
    block_output = apply_body(
184
        block_env=block_env,
185
        transactions=block.transactions,
193
        ommers=block.ommers,
186
    )
187
    block_state_root = state_root(block_env.state)
188
    transactions_root = root(block_output.transactions_trie)
189
    receipt_root = root(block_output.receipts_trie)
190
    block_logs_bloom = logs_bloom(block_output.block_logs)
191
192
    if block_output.block_gas_used != block.header.gas_used:
193
        raise InvalidBlock(
194
            f"{block_output.block_gas_used} != {block.header.gas_used}"
195
        )
196
    if transactions_root != block.header.transactions_root:
197
        raise InvalidBlock
198
    if block_state_root != block.header.state_root:
199
        raise InvalidBlock
200
    if receipt_root != block.header.receipt_root:
201
        raise InvalidBlock
202
    if block_logs_bloom != block.header.bloom:
203
        raise InvalidBlock
204
205
    chain.blocks.append(block)
206
    if len(chain.blocks) > 255:
207
        # Real clients have to store more blocks to deal with reorgs, but the
208
        # protocol only requires the last 255
209
        chain.blocks = chain.blocks[-255:]

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:
218
    """
219
    Calculates the base fee per gas for the block.
220
221
    Parameters
222
    ----------
223
    block_gas_limit :
224
        Gas limit of the block for which the base fee is being calculated.
225
    parent_gas_limit :
226
        Gas limit of the parent block.
227
    parent_gas_used :
228
        Gas used in the parent block.
229
    parent_base_fee_per_gas :
230
        Base fee per gas of the parent block.
231
232
    Returns
233
    -------
234
    base_fee_per_gas : `Uint`
235
        Base fee per gas for the block.
236
237
    """
238
    parent_gas_target = parent_gas_limit // ELASTICITY_MULTIPLIER
239
    if not check_gas_limit(block_gas_limit, parent_gas_limit):
240
        raise InvalidBlock
241
242
    if parent_gas_used == parent_gas_target:
243
        expected_base_fee_per_gas = parent_base_fee_per_gas
244
    elif parent_gas_used > parent_gas_target:
245
        gas_used_delta = parent_gas_used - parent_gas_target
246
247
        parent_fee_gas_delta = parent_base_fee_per_gas * gas_used_delta
248
        target_fee_gas_delta = parent_fee_gas_delta // parent_gas_target
249
250
        base_fee_per_gas_delta = max(
251
            target_fee_gas_delta // BASE_FEE_MAX_CHANGE_DENOMINATOR,
252
            Uint(1),
253
        )
254
255
        expected_base_fee_per_gas = (
256
            parent_base_fee_per_gas + base_fee_per_gas_delta
257
        )
258
    else:
259
        gas_used_delta = parent_gas_target - parent_gas_used
260
261
        parent_fee_gas_delta = parent_base_fee_per_gas * gas_used_delta
262
        target_fee_gas_delta = parent_fee_gas_delta // parent_gas_target
263
264
        base_fee_per_gas_delta = (
265
            target_fee_gas_delta // BASE_FEE_MAX_CHANGE_DENOMINATOR
266
        )
267
268
        expected_base_fee_per_gas = (
269
            parent_base_fee_per_gas - base_fee_per_gas_delta
270
        )
271
272
    return Uint(expected_base_fee_per_gas)

validate_header

Verifies a block header.

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

chain : History and current state. header : Header to check for correctness.

def validate_header(chain: BlockChain, ​​header: Header) -> None:
276
    """
277
    Verifies a block header.
278
279
    In order to consider a block's header valid, the logic for the
280
    quantities in the header should match the logic for the block itself.
281
    For example the header timestamp should be greater than the block's parent
282
    timestamp because the block was created *after* the parent block.
283
    Additionally, the block's number should be directly following the parent
284
    block's number since it is the next block in the sequence.
285
286
    Parameters
287
    ----------
288
    chain :
289
        History and current state.
290
    header :
291
        Header to check for correctness.
292
293
    """
294
    if header.number < Uint(1):
295
        raise InvalidBlock
304
    parent_header_number = header.number - Uint(1)
305
    first_block_number = chain.blocks[0].header.number
306
    last_block_number = chain.blocks[-1].header.number
296
308
    if (
309
        parent_header_number < first_block_number
310
        or parent_header_number > last_block_number
311
    ):
312
        raise InvalidBlock
313
314
    parent_header = chain.blocks[
315
        parent_header_number - first_block_number
316
    ].header
297
    parent_header = chain.blocks[-1].header
298
299
    if header.gas_used > header.gas_limit:
300
        raise InvalidBlock
301
302
    expected_base_fee_per_gas = calculate_base_fee_per_gas(
303
        header.gas_limit,
304
        parent_header.gas_limit,
305
        parent_header.gas_used,
306
        parent_header.base_fee_per_gas,
307
    )
308
    if expected_base_fee_per_gas != header.base_fee_per_gas:
309
        raise InvalidBlock
329
330
    parent_has_ommers = parent_header.ommers_hash != EMPTY_OMMER_HASH
310
    if header.timestamp <= parent_header.timestamp:
311
        raise InvalidBlock
312
    if header.number != parent_header.number + Uint(1):
313
        raise InvalidBlock
314
    if len(header.extra_data) > 32:
315
        raise InvalidBlock
337
338
    block_difficulty = calculate_block_difficulty(
339
        header.number,
340
        header.timestamp,
341
        parent_header.timestamp,
342
        parent_header.difficulty,
343
        parent_has_ommers,
344
    )
345
    if header.difficulty != block_difficulty:
316
    if header.difficulty != 0:
317
        raise InvalidBlock
318
    if header.nonce != b"\x00\x00\x00\x00\x00\x00\x00\x00":
319
        raise InvalidBlock
320
    if header.ommers_hash != EMPTY_OMMER_HASH:
321
        raise InvalidBlock
322
323
    block_parent_hash = keccak256(rlp.encode(parent_header))
324
    if header.parent_hash != block_parent_hash:
350
        raise InvalidBlock
351
352
    validate_proof_of_work(header)
325
        raise InvalidBlock

generate_header_hash_for_pow

Generate rlp hash of the header which is to be used for Proof-of-Work verification.

In other words, the PoW artefacts mix_digest and nonce are ignored while calculating this hash.

A particular PoW is valid for a single hash, that hash is computed by this function. The nonce and mix_digest are omitted from this hash because they are being changed by miners in their search for a sufficient proof-of-work.

Parameters

header : The header object for which the hash is to be generated.

Returns

hash : Hash32 The PoW valid rlp hash of the passed in header.

def generate_header_hash_for_pow(header: Header) -> Hash32:
356
    """
357
    Generate rlp hash of the header which is to be used for Proof-of-Work
358
    verification.
359
360
    In other words, the PoW artefacts `mix_digest` and `nonce` are ignored
361
    while calculating this hash.
362
363
    A particular PoW is valid for a single hash, that hash is computed by
364
    this function. The `nonce` and `mix_digest` are omitted from this hash
365
    because they are being changed by miners in their search for a sufficient
366
    proof-of-work.
367
368
    Parameters
369
    ----------
370
    header :
371
        The header object for which the hash is to be generated.
372
373
    Returns
374
    -------
375
    hash : `Hash32`
376
        The PoW valid rlp hash of the passed in header.
377
378
    """
379
    header_data_without_pow_artefacts = (
380
        header.parent_hash,
381
        header.ommers_hash,
382
        header.coinbase,
383
        header.state_root,
384
        header.transactions_root,
385
        header.receipt_root,
386
        header.bloom,
387
        header.difficulty,
388
        header.number,
389
        header.gas_limit,
390
        header.gas_used,
391
        header.timestamp,
392
        header.extra_data,
393
        header.base_fee_per_gas,
394
    )
395
396
    return keccak256(rlp.encode(header_data_without_pow_artefacts))

validate_proof_of_work

Validates the Proof of Work constraints.

In order to verify that a miner's proof-of-work is valid for a block, a mix-digest and result are calculated using the hashimoto_light hash function. The mix digest is a hash of the header and the nonce that is passed through and it confirms whether or not proof-of-work was done on the correct block. The result is the actual hash value of the block.

Parameters

header : Header of interest.

def validate_proof_of_work(header: Header) -> None:
400
    """
401
    Validates the Proof of Work constraints.
402
403
    In order to verify that a miner's proof-of-work is valid for a block, a
404
    ``mix-digest`` and ``result`` are calculated using the ``hashimoto_light``
405
    hash function. The mix digest is a hash of the header and the nonce that
406
    is passed through and it confirms whether or not proof-of-work was done
407
    on the correct block. The result is the actual hash value of the block.
408
409
    Parameters
410
    ----------
411
    header :
412
        Header of interest.
413
414
    """
415
    header_hash = generate_header_hash_for_pow(header)
416
    # TODO: Memoize this somewhere and read from that data instead of
417
    # calculating cache for every block validation.
418
    cache = generate_cache(header.number)
419
    mix_digest, result = hashimoto_light(
420
        header_hash, header.nonce, cache, dataset_size(header.number)
421
    )
422
    if mix_digest != header.mix_digest:
423
        raise InvalidBlock
424
425
    limit = Uint(U256.MAX_VALUE) + Uint(1)
426
    if Uint.from_be_bytes(result) > (limit // header.difficulty):
427
        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.

Returns

sender_address : The sender of the transaction. effective_gas_price : The price to charge for gas when the transaction is executed.

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: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.

def check_transaction(block_env: ethereum.forks.gray_glacier.vm.BlockEnvironmentethereum.forks.paris.vm.BlockEnvironment, ​​block_output: ethereum.forks.gray_glacier.vm.BlockOutputethereum.forks.paris.vm.BlockOutput, ​​tx: Transaction) -> Tuple[Address, Uint]:
333
    """
334
    Check if the transaction is includable in the block.
335
336
    Parameters
337
    ----------
338
    block_env :
339
        The block scoped environment.
340
    block_output :
341
        The block output for the current block.
342
    tx :
343
        The transaction.
344
345
    Returns
346
    -------
347
    sender_address :
348
        The sender of the transaction.
349
    effective_gas_price :
350
        The price to charge for gas when the transaction is executed.
351
352
    Raises
353
    ------
354
    InvalidBlock :
355
        If the transaction is not includable.
356
    GasUsedExceedsLimitError :
357
        If the gas used by the transaction exceeds the block's gas limit.
358
    NonceMismatchError :
359
        If the nonce of the transaction is not equal to the sender's nonce.
360
    InsufficientBalanceError :
361
        If the sender's balance is not enough to pay for the transaction.
362
    InvalidSenderError :
363
        If the transaction is from an address that does not exist anymore.
466
    PriorityFeeGreaterThanMaxFeeError:
364
    PriorityFeeGreaterThanMaxFeeError :
365
        If the priority fee is greater than the maximum fee per gas.
366
    InsufficientMaxFeePerGasError :
367
        If the maximum fee per gas is insufficient for the transaction.
368
369
    """
370
    gas_available = block_env.block_gas_limit - block_output.block_gas_used
371
    if tx.gas > gas_available:
372
        raise GasUsedExceedsLimitError("gas used exceeds limit")
373
    sender_address = recover_sender(block_env.chain_id, tx)
374
    sender_account = get_account(block_env.state, sender_address)
375
376
    if isinstance(tx, FeeMarketTransaction):
377
        if tx.max_fee_per_gas < tx.max_priority_fee_per_gas:
378
            raise PriorityFeeGreaterThanMaxFeeError(
379
                "priority fee greater than max fee"
380
            )
381
        if tx.max_fee_per_gas < block_env.base_fee_per_gas:
382
            raise InsufficientMaxFeePerGasError(
383
                tx.max_fee_per_gas, block_env.base_fee_per_gas
384
            )
385
386
        priority_fee_per_gas = min(
387
            tx.max_priority_fee_per_gas,
388
            tx.max_fee_per_gas - block_env.base_fee_per_gas,
389
        )
390
        effective_gas_price = priority_fee_per_gas + block_env.base_fee_per_gas
391
        max_gas_fee = tx.gas * tx.max_fee_per_gas
392
    else:
393
        if tx.gas_price < block_env.base_fee_per_gas:
394
            raise InvalidBlock
395
        effective_gas_price = tx.gas_price
396
        max_gas_fee = tx.gas * tx.gas_price
397
398
    if sender_account.nonce > Uint(tx.nonce):
399
        raise NonceMismatchError("nonce too low")
400
    elif sender_account.nonce < Uint(tx.nonce):
401
        raise NonceMismatchError("nonce too high")
402
    if Uint(sender_account.balance) < max_gas_fee + Uint(tx.value):
403
        raise InsufficientBalanceError("insufficient sender balance")
404
    if sender_account.code:
405
        raise InvalidSenderError("not EOA")
406
407
    return sender_address, effective_gas_price

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. 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:
416
    """
417
    Make the receipt for a transaction that was executed.
418
419
    Parameters
420
    ----------
421
    tx :
422
        The executed transaction.
423
    error :
424
        Error in the top level frame of the transaction, if any.
425
    cumulative_gas_used :
426
        The total gas used so far in the block after the transaction was
427
        executed.
428
    logs :
429
        The logs produced by the transaction.
430
431
    Returns
432
    -------
433
    receipt :
434
        The receipt for the transaction.
435
436
    """
437
    receipt = Receipt(
438
        succeeded=error is None,
439
        cumulative_gas_used=cumulative_gas_used,
440
        bloom=logs_bloom(logs),
441
        logs=logs,
442
    )
443
444
    return encode_receipt(tx, receipt)

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. ommers : Headers of ancestor blocks which are not direct parents (formerly uncles.)

Returns

block_output : The block output for the current block.

def apply_body(block_env: ethereum.forks.gray_glacier.vm.BlockEnvironmentethereum.forks.paris.vm.BlockEnvironment, ​​transactions: Tuple[LegacyTransaction | Bytes, ...], ​​ommers: Tuple[Header, ...]) -> ethereum.forks.gray_glacier.vm.BlockOutputethereum.forks.paris.vm.BlockOutput:
451
    """
452
    Executes a block.
453
454
    Many of the contents of a block are stored in data structures called
455
    tries. There is a transactions trie which is similar to a ledger of the
456
    transactions stored in the current block. There is also a receipts trie
457
    which stores the results of executing a transaction, like the post state
458
    and gas used. This function creates and executes the block that is to be
459
    added to the chain.
460
461
    Parameters
462
    ----------
463
    block_env :
464
        The block scoped environment.
465
    transactions :
466
        Transactions included in the block.
570
    ommers :
571
        Headers of ancestor blocks which are not direct parents (formerly
572
        uncles.)
467
468
    Returns
469
    -------
470
    block_output :
471
        The block output for the current block.
472
473
    """
474
    block_output = vm.BlockOutput()
475
476
    for i, tx in enumerate(map(decode_transaction, transactions)):
477
        process_transaction(block_env, block_output, tx, Uint(i))
478
585
    pay_rewards(block_env.state, block_env.number, block_env.coinbase, ommers)
586
479
    return block_output

validate_ommers

Validates the ommers mentioned in the block.

An ommer block is a block that wasn't canonically added to the blockchain because it wasn't validated as fast as the canonical block but was mined at the same time.

To be considered valid, the ommers must adhere to the rules defined in the Ethereum protocol. The maximum amount of ommers is 2 per block and there cannot be duplicate ommers in a block. Many of the other ommer constraints are listed in the in-line comments of this function.

Parameters

ommers : List of ommers mentioned in the current block. block_header: The header of current block. chain : History and current state.

def validate_ommers(ommers: Tuple[Header, ...], ​​block_header: Header, ​​chain: BlockChain) -> None:
593
    """
594
    Validates the ommers mentioned in the block.
595
596
    An ommer block is a block that wasn't canonically added to the
597
    blockchain because it wasn't validated as fast as the canonical block
598
    but was mined at the same time.
599
600
    To be considered valid, the ommers must adhere to the rules defined in
601
    the Ethereum protocol. The maximum amount of ommers is 2 per block and
602
    there cannot be duplicate ommers in a block. Many of the other ommer
603
    constraints are listed in the in-line comments of this function.
604
605
    Parameters
606
    ----------
607
    ommers :
608
        List of ommers mentioned in the current block.
609
    block_header:
610
        The header of current block.
611
    chain :
612
        History and current state.
613
614
    """
615
    block_hash = keccak256(rlp.encode(block_header))
616
    if keccak256(rlp.encode(ommers)) != block_header.ommers_hash:
617
        raise InvalidBlock
618
619
    if len(ommers) == 0:
620
        # Nothing to validate
621
        return
622
623
    # Check that each ommer satisfies the constraints of a header
624
    for ommer in ommers:
625
        if Uint(1) > ommer.number or ommer.number >= block_header.number:
626
            raise InvalidBlock
627
        validate_header(chain, ommer)
628
    if len(ommers) > 2:
629
        raise InvalidBlock
630
631
    ommers_hashes = [keccak256(rlp.encode(ommer)) for ommer in ommers]
632
    if len(ommers_hashes) != len(set(ommers_hashes)):
633
        raise InvalidBlock
634
635
    recent_canonical_blocks = chain.blocks[-(MAX_OMMER_DEPTH + Uint(1)) :]
636
    recent_canonical_block_hashes = {
637
        keccak256(rlp.encode(block.header))
638
        for block in recent_canonical_blocks
639
    }
640
    recent_ommers_hashes: Set[Hash32] = set()
641
    for block in recent_canonical_blocks:
642
        recent_ommers_hashes = recent_ommers_hashes.union(
643
            {keccak256(rlp.encode(ommer)) for ommer in block.ommers}
644
        )
645
646
    for ommer_index, ommer in enumerate(ommers):
647
        ommer_hash = ommers_hashes[ommer_index]
648
        if ommer_hash == block_hash:
649
            raise InvalidBlock
650
        if ommer_hash in recent_canonical_block_hashes:
651
            raise InvalidBlock
652
        if ommer_hash in recent_ommers_hashes:
653
            raise InvalidBlock
654
655
        # Ommer age with respect to the current block. For example, an age of
656
        # 1 indicates that the ommer is a sibling of previous block.
657
        ommer_age = block_header.number - ommer.number
658
        if Uint(1) > ommer_age or ommer_age > MAX_OMMER_DEPTH:
659
            raise InvalidBlock
660
        if ommer.parent_hash not in recent_canonical_block_hashes:
661
            raise InvalidBlock
662
        if ommer.parent_hash == block_header.parent_hash:
663
            raise InvalidBlock

pay_rewards

Pay rewards to the block miner as well as the ommers miners.

The miner of the canonical block is rewarded with the predetermined block reward, BLOCK_REWARD, plus a variable award based off of the number of ommer blocks that were mined around the same time, and included in the canonical block's header. An ommer block is a block that wasn't added to the canonical blockchain because it wasn't validated as fast as the accepted block but was mined at the same time. Although not all blocks that are mined are added to the canonical chain, miners are still paid a reward for their efforts. This reward is called an ommer reward and is calculated based on the number associated with the ommer block that they mined.

Parameters

state : Current account state. block_number : Position of the block within the chain. coinbase : Address of account which receives block reward and transaction fees. ommers : List of ommers mentioned in the current block.

def pay_rewards(state: State, ​​block_number: Uint, ​​coinbase: Address, ​​ommers: Tuple[Header, ...]) -> None:
672
    """
673
    Pay rewards to the block miner as well as the ommers miners.
674
675
    The miner of the canonical block is rewarded with the predetermined
676
    block reward, ``BLOCK_REWARD``, plus a variable award based off of the
677
    number of ommer blocks that were mined around the same time, and included
678
    in the canonical block's header. An ommer block is a block that wasn't
679
    added to the canonical blockchain because it wasn't validated as fast as
680
    the accepted block but was mined at the same time. Although not all blocks
681
    that are mined are added to the canonical chain, miners are still paid a
682
    reward for their efforts. This reward is called an ommer reward and is
683
    calculated based on the number associated with the ommer block that they
684
    mined.
685
686
    Parameters
687
    ----------
688
    state :
689
        Current account state.
690
    block_number :
691
        Position of the block within the chain.
692
    coinbase :
693
        Address of account which receives block reward and transaction fees.
694
    ommers :
695
        List of ommers mentioned in the current block.
696
697
    """
698
    ommer_count = U256(len(ommers))
699
    miner_reward = BLOCK_REWARD + (ommer_count * (BLOCK_REWARD // U256(32)))
700
    create_ether(state, coinbase, miner_reward)
701
702
    for ommer in ommers:
703
        # Ommer age with respect to the current block.
704
        ommer_age = U256(block_number - ommer.number)
705
        ommer_miner_reward = ((U256(8) - ommer_age) * BLOCK_REWARD) // U256(8)
706
        create_ether(state, ommer.coinbase, ommer_miner_reward)

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.gray_glacier.vm.BlockEnvironmentethereum.forks.paris.vm.BlockEnvironment, ​​block_output: ethereum.forks.gray_glacier.vm.BlockOutputethereum.forks.paris.vm.BlockOutput, ​​tx: Transaction, ​​index: Uint) -> None:
488
    """
489
    Execute a transaction against the provided environment.
490
491
    This function processes the actions needed to execute a transaction.
492
    It decrements the sender's account balance after calculating the gas fee
493
    and refunds them the proper amount after execution. Calling contracts,
494
    deploying code, and incrementing nonces are all examples of actions that
495
    happen within this function or from a call made within this function.
496
497
    Accounts that are marked for deletion are processed and destroyed after
498
    execution.
499
500
    Parameters
501
    ----------
502
    block_env :
503
        Environment for the Ethereum Virtual Machine.
504
    block_output :
505
        The block output for the current block.
506
    tx :
507
        Transaction to execute.
508
    index:
509
        Index of the transaction in the block.
510
511
    """
512
    trie_set(
513
        block_output.transactions_trie,
514
        rlp.encode(index),
515
        encode_transaction(tx),
516
    )
517
518
    intrinsic_gas = validate_transaction(tx)
519
520
    (
521
        sender,
522
        effective_gas_price,
523
    ) = check_transaction(
524
        block_env=block_env,
525
        block_output=block_output,
526
        tx=tx,
527
    )
528
529
    sender_account = get_account(block_env.state, sender)
530
531
    effective_gas_fee = tx.gas * effective_gas_price
532
533
    gas = tx.gas - intrinsic_gas
534
    increment_nonce(block_env.state, sender)
535
536
    sender_balance_after_gas_fee = (
537
        Uint(sender_account.balance) - effective_gas_fee
538
    )
539
    set_account_balance(
540
        block_env.state, sender, U256(sender_balance_after_gas_fee)
541
    )
542
543
    access_list_addresses = set()
544
    access_list_storage_keys = set()
545
    if isinstance(tx, (AccessListTransaction, FeeMarketTransaction)):
546
        for access in tx.access_list:
547
            access_list_addresses.add(access.account)
548
            for slot in access.slots:
549
                access_list_storage_keys.add((access.account, slot))
550
551
    tx_env = vm.TransactionEnvironment(
552
        origin=sender,
553
        gas_price=effective_gas_price,
554
        gas=gas,
555
        access_list_addresses=access_list_addresses,
556
        access_list_storage_keys=access_list_storage_keys,
557
        index_in_block=index,
558
        tx_hash=get_transaction_hash(encode_transaction(tx)),
559
    )
560
561
    message = prepare_message(block_env, tx_env, tx)
562
563
    tx_output = process_message_call(message)
564
565
    tx_gas_used_before_refund = tx.gas - tx_output.gas_left
566
    tx_gas_refund = min(
567
        tx_gas_used_before_refund // Uint(5), Uint(tx_output.refund_counter)
568
    )
569
    tx_gas_used_after_refund = tx_gas_used_before_refund - tx_gas_refund
570
    tx_gas_left = tx.gas - tx_gas_used_after_refund
571
    gas_refund_amount = tx_gas_left * effective_gas_price
572
573
    # For non-1559 transactions effective_gas_price == tx.gas_price
574
    priority_fee_per_gas = effective_gas_price - block_env.base_fee_per_gas
575
    transaction_fee = tx_gas_used_after_refund * priority_fee_per_gas
576
577
    # refund gas
578
    sender_balance_after_refund = get_account(
579
        block_env.state, sender
580
    ).balance + U256(gas_refund_amount)
581
    set_account_balance(block_env.state, sender, sender_balance_after_refund)
582
583
    # transfer miner fees
584
    coinbase_balance_after_mining_fee = get_account(
585
        block_env.state, block_env.coinbase
586
    ).balance + U256(transaction_fee)
814
    if coinbase_balance_after_mining_fee != 0:
815
        set_account_balance(
816
            block_env.state,
817
            block_env.coinbase,
818
            coinbase_balance_after_mining_fee,
819
        )
820
    elif account_exists_and_is_empty(block_env.state, block_env.coinbase):
821
        destroy_account(block_env.state, block_env.coinbase)
587
    set_account_balance(
588
        block_env.state,
589
        block_env.coinbase,
590
        coinbase_balance_after_mining_fee,
591
    )
592
593
    for address in tx_output.accounts_to_delete:
594
        destroy_account(block_env.state, address)
825
826
    destroy_touched_empty_accounts(block_env.state, tx_output.touched_accounts)
595
596
    block_output.block_gas_used += tx_gas_used_after_refund
597
598
    receipt = make_receipt(
599
        tx, tx_output.error, block_output.block_gas_used, tx_output.logs
600
    )
601
602
    receipt_key = rlp.encode(Uint(index))
603
    block_output.receipt_keys += (receipt_key,)
604
605
    trie_set(
606
        block_output.receipts_trie,
607
        receipt_key,
608
        receipt,
609
    )
610
611
    block_output.block_logs += tx_output.logs

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 GAS_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 GAS_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:
615
    """
616
    Validates the gas limit for a block.
617
618
    The bounds of the gas limit, ``max_adjustment_delta``, is set as the
619
    quotient of the parent block's gas limit and the
620
    ``GAS_LIMIT_ADJUSTMENT_FACTOR``. Therefore, if the gas limit that is
621
    passed through as a parameter is greater than or equal to the *sum* of
622
    the parent's gas and the adjustment delta then the limit for gas is too
623
    high and fails this function's check. Similarly, if the limit is less
624
    than or equal to the *difference* of the parent's gas and the adjustment
625
    delta *or* the predefined ``GAS_LIMIT_MINIMUM`` then this function's
626
    check fails because the gas limit doesn't allow for a sufficient or
627
    reasonable amount of gas to be used on a block.
628
629
    Parameters
630
    ----------
631
    gas_limit :
632
        Gas limit to validate.
633
634
    parent_gas_limit :
635
        Gas limit of the parent block.
636
637
    Returns
638
    -------
639
    check : `bool`
640
        True if gas limit constraints are satisfied, False otherwise.
641
642
    """
643
    max_adjustment_delta = parent_gas_limit // GAS_LIMIT_ADJUSTMENT_FACTOR
644
    if gas_limit >= parent_gas_limit + max_adjustment_delta:
645
        return False
646
    if gas_limit <= parent_gas_limit - max_adjustment_delta:
647
        return False
648
    if gas_limit < GAS_LIMIT_MINIMUM:
649
        return False
650
651
    return True

calculate_block_difficulty

Computes difficulty of a block using its header and parent header.

The difficulty is determined by the time the block was created after its parent. The offset is calculated using the parent block's difficulty, parent_difficulty, and the timestamp between blocks. This offset is then added to the parent difficulty and is stored as the difficulty variable. If the time between the block and its parent is too short, the offset will result in a positive number thus making the sum of parent_difficulty and offset to be a greater value in order to avoid mass forking. But, if the time is long enough, then the offset results in a negative value making the block less difficult than its parent.

The base standard for a block's difficulty is the predefined value set for the genesis block since it has no parent. So, a block can't be less difficult than the genesis block, therefore each block's difficulty is set to the maximum value between the calculated difficulty and the GENESIS_DIFFICULTY.

Parameters

block_number : Block number of the block. block_timestamp : Timestamp of the block. parent_timestamp : Timestamp of the parent block. parent_difficulty : difficulty of the parent block. parent_has_ommers: does the parent have ommers.

Returns

difficulty : ethereum.base_types.Uint Computed difficulty for a block.

def calculate_block_difficulty(block_number: Uint, ​​block_timestamp: U256, ​​parent_timestamp: U256, ​​parent_difficulty: Uint, ​​parent_has_ommers: bool) -> Uint:
893
    """
894
    Computes difficulty of a block using its header and parent header.
895
896
    The difficulty is determined by the time the block was created after its
897
    parent. The ``offset`` is calculated using the parent block's difficulty,
898
    ``parent_difficulty``, and the timestamp between blocks. This offset is
899
    then added to the parent difficulty and is stored as the ``difficulty``
900
    variable. If the time between the block and its parent is too short, the
901
    offset will result in a positive number thus making the sum of
902
    ``parent_difficulty`` and ``offset`` to be a greater value in order to
903
    avoid mass forking. But, if the time is long enough, then the offset
904
    results in a negative value making the block less difficult than
905
    its parent.
906
907
    The base standard for a block's difficulty is the predefined value
908
    set for the genesis block since it has no parent. So, a block
909
    can't be less difficult than the genesis block, therefore each block's
910
    difficulty is set to the maximum value between the calculated
911
    difficulty and the ``GENESIS_DIFFICULTY``.
912
913
    Parameters
914
    ----------
915
    block_number :
916
        Block number of the block.
917
    block_timestamp :
918
        Timestamp of the block.
919
    parent_timestamp :
920
        Timestamp of the parent block.
921
    parent_difficulty :
922
        difficulty of the parent block.
923
    parent_has_ommers:
924
        does the parent have ommers.
925
926
    Returns
927
    -------
928
    difficulty : `ethereum.base_types.Uint`
929
        Computed difficulty for a block.
930
931
    """
932
    offset = (
933
        int(parent_difficulty)
934
        // 2048
935
        * max(
936
            (2 if parent_has_ommers else 1)
937
            - int(block_timestamp - parent_timestamp) // 9,
938
            -99,
939
        )
940
    )
941
    difficulty = int(parent_difficulty) + offset
942
    # Historical Note: The difficulty bomb was not present in Ethereum at the
943
    # start of Frontier, but was added shortly after launch. However since the
944
    # bomb has no effect prior to block 200000 we pretend it existed from
945
    # genesis.
946
    # See https://github.com/ethereum/go-ethereum/pull/1588
947
    num_bomb_periods = ((int(block_number) - BOMB_DELAY_BLOCKS) // 100000) - 2
948
    if num_bomb_periods >= 0:
949
        difficulty += 2**num_bomb_periods
950
951
    # Some clients raise the difficulty to `MINIMUM_DIFFICULTY` prior to adding
952
    # the bomb. This bug does not matter because the difficulty is always much
953
    # greater than `MINIMUM_DIFFICULTY` on Mainnet.
954
    return Uint(max(difficulty, int(MINIMUM_DIFFICULTY)))