ethereum.istanbul.fork

Ethereum Specification ^^^^^^^^^^^^^^^^^^^^^^

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

Introduction

Entry point for the Ethereum specification.

BLOCK_REWARD

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

GAS_LIMIT_ADJUSTMENT_FACTOR

53
GAS_LIMIT_ADJUSTMENT_FACTOR = Uint(1024)

GAS_LIMIT_MINIMUM

54
GAS_LIMIT_MINIMUM = Uint(5000)

MINIMUM_DIFFICULTY

55
MINIMUM_DIFFICULTY = Uint(131072)

MAX_OMMER_DEPTH

56
MAX_OMMER_DEPTH = Uint(6)

BOMB_DELAY_BLOCKS

57
BOMB_DELAY_BLOCKS = 5000000

EMPTY_OMMER_HASH

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

BlockChain

History and current state of the block chain.

61
@dataclass
class BlockChain:

blocks

67
    blocks: List[Block]

state

68
    state: State

chain_id

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

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

header : Header to check for correctness. parent_header : Parent Header of the header to check for correctness

def validate_header(header: Header, ​​parent_header: Header) -> None:
192
    """
193
    Verifies a block header.
194
195
    In order to consider a block's header valid, the logic for the
196
    quantities in the header should match the logic for the block itself.
197
    For example the header timestamp should be greater than the block's parent
198
    timestamp because the block was created *after* the parent block.
199
    Additionally, the block's number should be directly following the parent
200
    block's number since it is the next block in the sequence.
201
202
    Parameters
203
    ----------
204
    header :
205
        Header to check for correctness.
206
    parent_header :
207
        Parent Header of the header to check for correctness
208
    """
209
    parent_has_ommers = parent_header.ommers_hash != EMPTY_OMMER_HASH
210
    if header.timestamp <= parent_header.timestamp:
211
        raise InvalidBlock
212
    if header.number != parent_header.number + Uint(1):
213
        raise InvalidBlock
214
    if not check_gas_limit(header.gas_limit, parent_header.gas_limit):
215
        raise InvalidBlock
216
    if len(header.extra_data) > 32:
217
        raise InvalidBlock
218
219
    block_difficulty = calculate_block_difficulty(
220
        header.number,
221
        header.timestamp,
222
        parent_header.timestamp,
223
        parent_header.difficulty,
224
        parent_has_ommers,
225
    )
226
    if header.difficulty != block_difficulty:
227
        raise InvalidBlock
228
229
    block_parent_hash = keccak256(rlp.encode(parent_header))
230
    if header.parent_hash != block_parent_hash:
231
        raise InvalidBlock
232
233
    validate_proof_of_work(header)

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:
237
    """
238
    Generate rlp hash of the header which is to be used for Proof-of-Work
239
    verification.
240
241
    In other words, the PoW artefacts `mix_digest` and `nonce` are ignored
242
    while calculating this hash.
243
244
    A particular PoW is valid for a single hash, that hash is computed by
245
    this function. The `nonce` and `mix_digest` are omitted from this hash
246
    because they are being changed by miners in their search for a sufficient
247
    proof-of-work.
248
249
    Parameters
250
    ----------
251
    header :
252
        The header object for which the hash is to be generated.
253
254
    Returns
255
    -------
256
    hash : `Hash32`
257
        The PoW valid rlp hash of the passed in header.
258
    """
259
    header_data_without_pow_artefacts = (
260
        header.parent_hash,
261
        header.ommers_hash,
262
        header.coinbase,
263
        header.state_root,
264
        header.transactions_root,
265
        header.receipt_root,
266
        header.bloom,
267
        header.difficulty,
268
        header.number,
269
        header.gas_limit,
270
        header.gas_used,
271
        header.timestamp,
272
        header.extra_data,
273
    )
274
275
    return rlp.rlp_hash(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:
279
    """
280
    Validates the Proof of Work constraints.
281
282
    In order to verify that a miner's proof-of-work is valid for a block, a
283
    ``mix-digest`` and ``result`` are calculated using the ``hashimoto_light``
284
    hash function. The mix digest is a hash of the header and the nonce that
285
    is passed through and it confirms whether or not proof-of-work was done
286
    on the correct block. The result is the actual hash value of the block.
287
288
    Parameters
289
    ----------
290
    header :
291
        Header of interest.
292
    """
293
    header_hash = generate_header_hash_for_pow(header)
294
    # TODO: Memoize this somewhere and read from that data instead of
295
    # calculating cache for every block validation.
296
    cache = generate_cache(header.number)
297
    mix_digest, result = hashimoto_light(
298
        header_hash, header.nonce, cache, dataset_size(header.number)
299
    )
300
    if mix_digest != header.mix_digest:
301
        raise InvalidBlock
302
303
    limit = Uint(U256.MAX_VALUE) + Uint(1)
304
    if Uint.from_be_bytes(result) > (limit // header.difficulty):
305
        raise InvalidBlock

check_transaction

Check if the transaction is includable in the block.

Parameters

tx : The transaction. gas_available : The gas remaining in the block. chain_id : The ID of the current chain.

Returns

sender_address : The sender of the transaction.

Raises

InvalidBlock : If the transaction is not includable.

def check_transaction(tx: Transaction, ​​gas_available: Uint, ​​chain_id: U64) -> Address:
313
    """
314
    Check if the transaction is includable in the block.
315
316
    Parameters
317
    ----------
318
    tx :
319
        The transaction.
320
    gas_available :
321
        The gas remaining in the block.
322
    chain_id :
323
        The ID of the current chain.
324
325
    Returns
326
    -------
327
    sender_address :
328
        The sender of the transaction.
329
330
    Raises
331
    ------
332
    InvalidBlock :
333
        If the transaction is not includable.
334
    """
335
    if tx.gas > gas_available:
336
        raise InvalidBlock
337
    sender_address = recover_sender(chain_id, tx)
338
339
    return sender_address

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[Exception], ​​cumulative_gas_used: Uint, ​​logs: Tuple[Log, ...]) -> Receipt:
348
    """
349
    Make the receipt for a transaction that was executed.
350
351
    Parameters
352
    ----------
353
    tx :
354
        The executed transaction.
355
    error :
356
        Error in the top level frame of the transaction, if any.
357
    cumulative_gas_used :
358
        The total gas used so far in the block after the transaction was
359
        executed.
360
    logs :
361
        The logs produced by the transaction.
362
363
    Returns
364
    -------
365
    receipt :
366
        The receipt for the transaction.
367
    """
368
    receipt = Receipt(
369
        succeeded=error is None,
370
        cumulative_gas_used=cumulative_gas_used,
371
        bloom=logs_bloom(logs),
372
        logs=logs,
373
    )
374
375
    return receipt

ApplyBodyOutput

Output from applying the block body to the present state.

Contains the following:

block_gas_used : ethereum.base_types.Uint Gas used for executing all transactions. transactions_root : ethereum.fork_types.Root Trie root of all the transactions in the block. receipt_root : ethereum.fork_types.Root Trie root of all the receipts in the block. block_logs_bloom : Bloom Logs bloom of all the logs included in all the transactions of the block. state_root : ethereum.fork_types.Root State root after all transactions have been executed.

378
@dataclass
class ApplyBodyOutput:

block_gas_used

398
    block_gas_used: Uint

transactions_root

399
    transactions_root: Root

receipt_root

400
    receipt_root: Root

block_logs_bloom

401
    block_logs_bloom: Bloom

state_root

402
    state_root: Root

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

state : Current account state. block_hashes : List of hashes of the previous 256 blocks in the order of increasing block number. coinbase : Address of account which receives block reward and transaction fees. block_number : Position of the block within the chain. block_gas_limit : Initial amount of gas available for execution in this block. block_time : Time the block was produced, measured in seconds since the epoch. block_difficulty : Difficulty of the block. transactions : Transactions included in the block. ommers : Headers of ancestor blocks which are not direct parents (formerly uncles.) chain_id : ID of the executing chain.

Returns

apply_body_output : ApplyBodyOutput Output of applying the block body to the state.

def apply_body(state: State, ​​block_hashes: List[Hash32], ​​coinbase: Address, ​​block_number: Uint, ​​block_gas_limit: Uint, ​​block_time: U256, ​​block_difficulty: Uint, ​​transactions: Tuple[Transaction, ...], ​​ommers: Tuple[Header, ...], ​​chain_id: U64) -> ApplyBodyOutput:
417
    """
418
    Executes a block.
419
420
    Many of the contents of a block are stored in data structures called
421
    tries. There is a transactions trie which is similar to a ledger of the
422
    transactions stored in the current block. There is also a receipts trie
423
    which stores the results of executing a transaction, like the post state
424
    and gas used. This function creates and executes the block that is to be
425
    added to the chain.
426
427
    Parameters
428
    ----------
429
    state :
430
        Current account state.
431
    block_hashes :
432
        List of hashes of the previous 256 blocks in the order of
433
        increasing block number.
434
    coinbase :
435
        Address of account which receives block reward and transaction fees.
436
    block_number :
437
        Position of the block within the chain.
438
    block_gas_limit :
439
        Initial amount of gas available for execution in this block.
440
    block_time :
441
        Time the block was produced, measured in seconds since the epoch.
442
    block_difficulty :
443
        Difficulty of the block.
444
    transactions :
445
        Transactions included in the block.
446
    ommers :
447
        Headers of ancestor blocks which are not direct parents (formerly
448
        uncles.)
449
    chain_id :
450
        ID of the executing chain.
451
452
    Returns
453
    -------
454
    apply_body_output : `ApplyBodyOutput`
455
        Output of applying the block body to the state.
456
    """
457
    gas_available = block_gas_limit
458
    transactions_trie: Trie[Bytes, Optional[Transaction]] = Trie(
459
        secured=False, default=None
460
    )
461
    receipts_trie: Trie[Bytes, Optional[Receipt]] = Trie(
462
        secured=False, default=None
463
    )
464
    block_logs: Tuple[Log, ...] = ()
465
466
    for i, tx in enumerate(transactions):
467
        trie_set(transactions_trie, rlp.encode(Uint(i)), tx)
468
469
        sender_address = check_transaction(tx, gas_available, chain_id)
470
471
        env = vm.Environment(
472
            caller=sender_address,
473
            origin=sender_address,
474
            block_hashes=block_hashes,
475
            coinbase=coinbase,
476
            number=block_number,
477
            gas_limit=block_gas_limit,
478
            gas_price=tx.gas_price,
479
            time=block_time,
480
            difficulty=block_difficulty,
481
            state=state,
482
            chain_id=chain_id,
483
            traces=[],
484
        )
485
486
        gas_used, logs, error = process_transaction(env, tx)
487
        gas_available -= gas_used
488
489
        receipt = make_receipt(
490
            tx, error, (block_gas_limit - gas_available), logs
491
        )
492
493
        trie_set(
494
            receipts_trie,
495
            rlp.encode(Uint(i)),
496
            receipt,
497
        )
498
499
        block_logs += logs
500
501
    pay_rewards(state, block_number, coinbase, ommers)
502
503
    block_gas_used = block_gas_limit - gas_available
504
505
    block_logs_bloom = logs_bloom(block_logs)
506
507
    return ApplyBodyOutput(
508
        block_gas_used,
509
        root(transactions_trie),
510
        root(receipts_trie),
511
        block_logs_bloom,
512
        state_root(state),
513
    )

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:
519
    """
520
    Validates the ommers mentioned in the block.
521
522
    An ommer block is a block that wasn't canonically added to the
523
    blockchain because it wasn't validated as fast as the canonical block
524
    but was mined at the same time.
525
526
    To be considered valid, the ommers must adhere to the rules defined in
527
    the Ethereum protocol. The maximum amount of ommers is 2 per block and
528
    there cannot be duplicate ommers in a block. Many of the other ommer
529
    constraints are listed in the in-line comments of this function.
530
531
    Parameters
532
    ----------
533
    ommers :
534
        List of ommers mentioned in the current block.
535
    block_header:
536
        The header of current block.
537
    chain :
538
        History and current state.
539
    """
540
    block_hash = rlp.rlp_hash(block_header)
541
    if rlp.rlp_hash(ommers) != block_header.ommers_hash:
542
        raise InvalidBlock
543
544
    if len(ommers) == 0:
545
        # Nothing to validate
546
        return
547
548
    # Check that each ommer satisfies the constraints of a header
549
    for ommer in ommers:
550
        if Uint(1) > ommer.number or ommer.number >= block_header.number:
551
            raise InvalidBlock
552
        ommer_parent_header = chain.blocks[
553
            -(block_header.number - ommer.number) - 1
554
        ].header
555
        validate_header(ommer, ommer_parent_header)
556
    if len(ommers) > 2:
557
        raise InvalidBlock
558
559
    ommers_hashes = [rlp.rlp_hash(ommer) for ommer in ommers]
560
    if len(ommers_hashes) != len(set(ommers_hashes)):
561
        raise InvalidBlock
562
563
    recent_canonical_blocks = chain.blocks[-(MAX_OMMER_DEPTH + Uint(1)) :]
564
    recent_canonical_block_hashes = {
565
        rlp.rlp_hash(block.header) for block in recent_canonical_blocks
566
    }
567
    recent_ommers_hashes: Set[Hash32] = set()
568
    for block in recent_canonical_blocks:
569
        recent_ommers_hashes = recent_ommers_hashes.union(
570
            {rlp.rlp_hash(ommer) for ommer in block.ommers}
571
        )
572
573
    for ommer_index, ommer in enumerate(ommers):
574
        ommer_hash = ommers_hashes[ommer_index]
575
        if ommer_hash == block_hash:
576
            raise InvalidBlock
577
        if ommer_hash in recent_canonical_block_hashes:
578
            raise InvalidBlock
579
        if ommer_hash in recent_ommers_hashes:
580
            raise InvalidBlock
581
582
        # Ommer age with respect to the current block. For example, an age of
583
        # 1 indicates that the ommer is a sibling of previous block.
584
        ommer_age = block_header.number - ommer.number
585
        if Uint(1) > ommer_age or ommer_age > MAX_OMMER_DEPTH:
586
            raise InvalidBlock
587
        if ommer.parent_hash not in recent_canonical_block_hashes:
588
            raise InvalidBlock
589
        if ommer.parent_hash == block_header.parent_hash:
590
            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:
599
    """
600
    Pay rewards to the block miner as well as the ommers miners.
601
602
    The miner of the canonical block is rewarded with the predetermined
603
    block reward, ``BLOCK_REWARD``, plus a variable award based off of the
604
    number of ommer blocks that were mined around the same time, and included
605
    in the canonical block's header. An ommer block is a block that wasn't
606
    added to the canonical blockchain because it wasn't validated as fast as
607
    the accepted block but was mined at the same time. Although not all blocks
608
    that are mined are added to the canonical chain, miners are still paid a
609
    reward for their efforts. This reward is called an ommer reward and is
610
    calculated based on the number associated with the ommer block that they
611
    mined.
612
613
    Parameters
614
    ----------
615
    state :
616
        Current account state.
617
    block_number :
618
        Position of the block within the chain.
619
    coinbase :
620
        Address of account which receives block reward and transaction fees.
621
    ommers :
622
        List of ommers mentioned in the current block.
623
    """
624
    ommer_count = U256(len(ommers))
625
    miner_reward = BLOCK_REWARD + (ommer_count * (BLOCK_REWARD // U256(32)))
626
    create_ether(state, coinbase, miner_reward)
627
628
    for ommer in ommers:
629
        # Ommer age with respect to the current block.
630
        ommer_age = U256(block_number - ommer.number)
631
        ommer_miner_reward = ((U256(8) - ommer_age) * BLOCK_REWARD) // U256(8)
632
        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 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

env : Environment for the Ethereum Virtual Machine. tx : Transaction to execute.

Returns

gas_left : ethereum.base_types.U256 Remaining gas after execution. logs : Tuple[ethereum.blocks.Log, ...] Logs generated during execution.

def process_transaction(env: ethereum.istanbul.vm.Environment, ​​tx: Transaction) -> Tuple[Uint, Tuple[Log, ...], Optional[Exception]]:
638
    """
639
    Execute a transaction against the provided environment.
640
641
    This function processes the actions needed to execute a transaction.
642
    It decrements the sender's account after calculating the gas fee and
643
    refunds them the proper amount after execution. Calling contracts,
644
    deploying code, and incrementing nonces are all examples of actions that
645
    happen within this function or from a call made within this function.
646
647
    Accounts that are marked for deletion are processed and destroyed after
648
    execution.
649
650
    Parameters
651
    ----------
652
    env :
653
        Environment for the Ethereum Virtual Machine.
654
    tx :
655
        Transaction to execute.
656
657
    Returns
658
    -------
659
    gas_left : `ethereum.base_types.U256`
660
        Remaining gas after execution.
661
    logs : `Tuple[ethereum.blocks.Log, ...]`
662
        Logs generated during execution.
663
    """
664
    if not validate_transaction(tx):
665
        raise InvalidBlock
666
667
    sender = env.origin
668
    sender_account = get_account(env.state, sender)
669
    gas_fee = tx.gas * tx.gas_price
670
    if sender_account.nonce != tx.nonce:
671
        raise InvalidBlock
672
    if Uint(sender_account.balance) < gas_fee + Uint(tx.value):
673
        raise InvalidBlock
674
    if sender_account.code != bytearray():
675
        raise InvalidSenderError("not EOA")
676
677
    gas = tx.gas - calculate_intrinsic_cost(tx)
678
    increment_nonce(env.state, sender)
679
    sender_balance_after_gas_fee = Uint(sender_account.balance) - gas_fee
680
    set_account_balance(env.state, sender, U256(sender_balance_after_gas_fee))
681
682
    message = prepare_message(
683
        sender,
684
        tx.to,
685
        tx.value,
686
        tx.data,
687
        gas,
688
        env,
689
    )
690
691
    output = process_message_call(message, env)
692
693
    gas_used = tx.gas - output.gas_left
694
    gas_refund = min(gas_used // Uint(2), Uint(output.refund_counter))
695
    gas_refund_amount = (output.gas_left + gas_refund) * tx.gas_price
696
    transaction_fee = (tx.gas - output.gas_left - gas_refund) * tx.gas_price
697
    total_gas_used = gas_used - gas_refund
698
699
    # refund gas
700
    sender_balance_after_refund = get_account(
701
        env.state, sender
702
    ).balance + U256(gas_refund_amount)
703
    set_account_balance(env.state, sender, sender_balance_after_refund)
704
705
    # transfer miner fees
706
    coinbase_balance_after_mining_fee = get_account(
707
        env.state, env.coinbase
708
    ).balance + U256(transaction_fee)
709
    if coinbase_balance_after_mining_fee != 0:
710
        set_account_balance(
711
            env.state, env.coinbase, coinbase_balance_after_mining_fee
712
        )
713
    elif account_exists_and_is_empty(env.state, env.coinbase):
714
        destroy_account(env.state, env.coinbase)
715
716
    for address in output.accounts_to_delete:
717
        destroy_account(env.state, address)
718
719
    for address in output.touched_accounts:
720
        if account_exists_and_is_empty(env.state, address):
721
            destroy_account(env.state, address)
722
723
    return total_gas_used, output.logs, output.error

validate_transaction

Verifies a transaction.

The gas in a transaction gets used to pay for the intrinsic cost of operations, therefore if there is insufficient gas then it would not be possible to execute a transaction and it will be declared invalid.

Additionally, the nonce of a transaction must not equal or exceed the limit defined in EIP-2681 <https://eips.ethereum.org/EIPS/eip-2681>_. In practice, defining the limit as 2**64-1 has no impact because sending 2**64-1 transactions is improbable. It's not strictly impossible though, 2**64-1 transactions is the entire capacity of the Ethereum blockchain at 2022 gas limits for a little over 22 years.

Parameters

tx : Transaction to validate.

Returns

verified : bool True if the transaction can be executed, or False otherwise.

def validate_transaction(tx: Transaction) -> bool:
727
    """
728
    Verifies a transaction.
729
730
    The gas in a transaction gets used to pay for the intrinsic cost of
731
    operations, therefore if there is insufficient gas then it would not
732
    be possible to execute a transaction and it will be declared invalid.
733
734
    Additionally, the nonce of a transaction must not equal or exceed the
735
    limit defined in `EIP-2681 <https://eips.ethereum.org/EIPS/eip-2681>`_.
736
    In practice, defining the limit as ``2**64-1`` has no impact because
737
    sending ``2**64-1`` transactions is improbable. It's not strictly
738
    impossible though, ``2**64-1`` transactions is the entire capacity of the
739
    Ethereum blockchain at 2022 gas limits for a little over 22 years.
740
741
    Parameters
742
    ----------
743
    tx :
744
        Transaction to validate.
745
746
    Returns
747
    -------
748
    verified : `bool`
749
        True if the transaction can be executed, or False otherwise.
750
    """
751
    if calculate_intrinsic_cost(tx) > Uint(tx.gas):
752
        return False
753
    if tx.nonce >= U256(U64.MAX_VALUE):
754
        return False
755
    return True

calculate_intrinsic_cost

Calculates the gas that is charged before execution is started.

The intrinsic cost of the transaction is charged before execution has begun. Functions/operations in the EVM cost money to execute so this intrinsic cost is for the operations that need to be paid for as part of the transaction. Data transfer, for example, is part of this intrinsic cost. It costs ether to send data over the wire and that ether is accounted for in the intrinsic cost calculated in this function. This intrinsic cost must be calculated and paid for before execution in order for all operations to be implemented.

Parameters

tx : Transaction to compute the intrinsic cost of.

Returns

verified : ethereum.base_types.Uint The intrinsic cost of the transaction.

def calculate_intrinsic_cost(tx: Transaction) -> Uint:
759
    """
760
    Calculates the gas that is charged before execution is started.
761
762
    The intrinsic cost of the transaction is charged before execution has
763
    begun. Functions/operations in the EVM cost money to execute so this
764
    intrinsic cost is for the operations that need to be paid for as part of
765
    the transaction. Data transfer, for example, is part of this intrinsic
766
    cost. It costs ether to send data over the wire and that ether is
767
    accounted for in the intrinsic cost calculated in this function. This
768
    intrinsic cost must be calculated and paid for before execution in order
769
    for all operations to be implemented.
770
771
    Parameters
772
    ----------
773
    tx :
774
        Transaction to compute the intrinsic cost of.
775
776
    Returns
777
    -------
778
    verified : `ethereum.base_types.Uint`
779
        The intrinsic cost of the transaction.
780
    """
781
    data_cost = 0
782
783
    for byte in tx.data:
784
        if byte == 0:
785
            data_cost += TX_DATA_COST_PER_ZERO
786
        else:
787
            data_cost += TX_DATA_COST_PER_NON_ZERO
788
789
    if tx.to == Bytes0(b""):
790
        create_cost = TX_CREATE_COST
791
    else:
792
        create_cost = 0
793
794
    return Uint(TX_BASE_COST + data_cost + create_cost)

recover_sender

Extracts the sender address from a transaction.

The v, r, and s values are the three parts that make up the signature of a transaction. In order to recover the sender of a transaction the two components needed are the signature (v, r, and s) and the signing hash of the transaction. The sender's public key can be obtained with these two values and therefore the sender address can be retrieved.

Parameters

tx : Transaction of interest. chain_id : ID of the executing chain.

Returns

sender : ethereum.fork_types.Address The address of the account that signed the transaction.

def recover_sender(chain_id: U64, ​​tx: Transaction) -> Address:
798
    """
799
    Extracts the sender address from a transaction.
800
801
    The v, r, and s values are the three parts that make up the signature
802
    of a transaction. In order to recover the sender of a transaction the two
803
    components needed are the signature (``v``, ``r``, and ``s``) and the
804
    signing hash of the transaction. The sender's public key can be obtained
805
    with these two values and therefore the sender address can be retrieved.
806
807
    Parameters
808
    ----------
809
    tx :
810
        Transaction of interest.
811
    chain_id :
812
        ID of the executing chain.
813
814
    Returns
815
    -------
816
    sender : `ethereum.fork_types.Address`
817
        The address of the account that signed the transaction.
818
    """
819
    v, r, s = tx.v, tx.r, tx.s
820
    if U256(0) >= r or r >= SECP256K1N:
821
        raise InvalidBlock
822
    if U256(0) >= s or s > SECP256K1N // U256(2):
823
        raise InvalidBlock
824
825
    if v == 27 or v == 28:
826
        public_key = secp256k1_recover(
827
            r, s, v - U256(27), signing_hash_pre155(tx)
828
        )
829
    else:
830
        chain_id_x2 = U256(chain_id) * U256(2)
831
        if v != U256(35) + chain_id_x2 and v != U256(36) + chain_id_x2:
832
            raise InvalidBlock
833
        public_key = secp256k1_recover(
834
            r, s, v - U256(35) - chain_id_x2, signing_hash_155(tx, chain_id)
835
        )
836
    return Address(keccak256(public_key)[12:32])

signing_hash_pre155

Compute the hash of a transaction used in a legacy (pre EIP 155) signature.

Parameters

tx : Transaction of interest.

Returns

hash : ethereum.crypto.hash.Hash32 Hash of the transaction.

def signing_hash_pre155(tx: Transaction) -> Hash32:
840
    """
841
    Compute the hash of a transaction used in a legacy (pre EIP 155) signature.
842
843
    Parameters
844
    ----------
845
    tx :
846
        Transaction of interest.
847
848
    Returns
849
    -------
850
    hash : `ethereum.crypto.hash.Hash32`
851
        Hash of the transaction.
852
    """
853
    return keccak256(
854
        rlp.encode(
855
            (
856
                tx.nonce,
857
                tx.gas_price,
858
                tx.gas,
859
                tx.to,
860
                tx.value,
861
                tx.data,
862
            )
863
        )
864
    )

signing_hash_155

Compute the hash of a transaction used in a EIP 155 signature.

Parameters

tx : Transaction of interest. chain_id : The id of the current chain.

Returns

hash : ethereum.crypto.hash.Hash32 Hash of the transaction.

def signing_hash_155(tx: Transaction, ​​chain_id: U64) -> Hash32:
868
    """
869
    Compute the hash of a transaction used in a EIP 155 signature.
870
871
    Parameters
872
    ----------
873
    tx :
874
        Transaction of interest.
875
    chain_id :
876
        The id of the current chain.
877
878
    Returns
879
    -------
880
    hash : `ethereum.crypto.hash.Hash32`
881
        Hash of the transaction.
882
    """
883
    return keccak256(
884
        rlp.encode(
885
            (
886
                tx.nonce,
887
                tx.gas_price,
888
                tx.gas,
889
                tx.to,
890
                tx.value,
891
                tx.data,
892
                chain_id,
893
                Uint(0),
894
                Uint(0),
895
            )
896
        )
897
    )

compute_header_hash

Computes the hash of a block header.

The header hash of a block is the canonical hash that is used to refer to a specific block and completely distinguishes a block from another.

keccak256 is a function that produces a 256 bit hash of any input. It also takes in any number of bytes as an input and produces a single hash for them. A hash is a completely unique output for a single input. So an input corresponds to one unique hash that can be used to identify the input exactly.

Prior to using the keccak256 hash function, the header must be encoded using the Recursive-Length Prefix. See :ref:rlp. RLP encoding the header converts it into a space-efficient format that allows for easy transfer of data between nodes. The purpose of RLP is to encode arbitrarily nested arrays of binary data, and RLP is the primary encoding method used to serialize objects in Ethereum's execution layer. The only purpose of RLP is to encode structure; encoding specific data types (e.g. strings, floats) is left up to higher-order protocols.

Parameters

header : Header of interest.

Returns

hash : ethereum.crypto.hash.Hash32 Hash of the header.

def compute_header_hash(header: Header) -> Hash32:
901
    """
902
    Computes the hash of a block header.
903
904
    The header hash of a block is the canonical hash that is used to refer
905
    to a specific block and completely distinguishes a block from another.
906
907
    ``keccak256`` is a function that produces a 256 bit hash of any input.
908
    It also takes in any number of bytes as an input and produces a single
909
    hash for them. A hash is a completely unique output for a single input.
910
    So an input corresponds to one unique hash that can be used to identify
911
    the input exactly.
912
913
    Prior to using the ``keccak256`` hash function, the header must be
914
    encoded using the Recursive-Length Prefix. See :ref:`rlp`.
915
    RLP encoding the header converts it into a space-efficient format that
916
    allows for easy transfer of data between nodes. The purpose of RLP is to
917
    encode arbitrarily nested arrays of binary data, and RLP is the primary
918
    encoding method used to serialize objects in Ethereum's execution layer.
919
    The only purpose of RLP is to encode structure; encoding specific data
920
    types (e.g. strings, floats) is left up to higher-order protocols.
921
922
    Parameters
923
    ----------
924
    header :
925
        Header of interest.
926
927
    Returns
928
    -------
929
    hash : `ethereum.crypto.hash.Hash32`
930
        Hash of the header.
931
    """
932
    return keccak256(rlp.encode(header))

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:
936
    """
937
    Validates the gas limit for a block.
938
939
    The bounds of the gas limit, ``max_adjustment_delta``, is set as the
940
    quotient of the parent block's gas limit and the
941
    ``GAS_LIMIT_ADJUSTMENT_FACTOR``. Therefore, if the gas limit that is
942
    passed through as a parameter is greater than or equal to the *sum* of
943
    the parent's gas and the adjustment delta then the limit for gas is too
944
    high and fails this function's check. Similarly, if the limit is less
945
    than or equal to the *difference* of the parent's gas and the adjustment
946
    delta *or* the predefined ``GAS_LIMIT_MINIMUM`` then this function's
947
    check fails because the gas limit doesn't allow for a sufficient or
948
    reasonable amount of gas to be used on a block.
949
950
    Parameters
951
    ----------
952
    gas_limit :
953
        Gas limit to validate.
954
955
    parent_gas_limit :
956
        Gas limit of the parent block.
957
958
    Returns
959
    -------
960
    check : `bool`
961
        True if gas limit constraints are satisfied, False otherwise.
962
    """
963
    max_adjustment_delta = parent_gas_limit // GAS_LIMIT_ADJUSTMENT_FACTOR
964
    if gas_limit >= parent_gas_limit + max_adjustment_delta:
965
        return False
966
    if gas_limit <= parent_gas_limit - max_adjustment_delta:
967
        return False
968
    if gas_limit < GAS_LIMIT_MINIMUM:
969
        return False
970
971
    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:
981
    """
982
    Computes difficulty of a block using its header and parent header.
983
984
    The difficulty is determined by the time the block was created after its
985
    parent. The ``offset`` is calculated using the parent block's difficulty,
986
    ``parent_difficulty``, and the timestamp between blocks. This offset is
987
    then added to the parent difficulty and is stored as the ``difficulty``
988
    variable. If the time between the block and its parent is too short, the
989
    offset will result in a positive number thus making the sum of
990
    ``parent_difficulty`` and ``offset`` to be a greater value in order to
991
    avoid mass forking. But, if the time is long enough, then the offset
992
    results in a negative value making the block less difficult than
993
    its parent.
994
995
    The base standard for a block's difficulty is the predefined value
996
    set for the genesis block since it has no parent. So, a block
997
    can't be less difficult than the genesis block, therefore each block's
998
    difficulty is set to the maximum value between the calculated
999
    difficulty and the ``GENESIS_DIFFICULTY``.
1000
1001
    Parameters
1002
    ----------
1003
    block_number :
1004
        Block number of the block.
1005
    block_timestamp :
1006
        Timestamp of the block.
1007
    parent_timestamp :
1008
        Timestamp of the parent block.
1009
    parent_difficulty :
1010
        difficulty of the parent block.
1011
    parent_has_ommers:
1012
        does the parent have ommers.
1013
1014
    Returns
1015
    -------
1016
    difficulty : `ethereum.base_types.Uint`
1017
        Computed difficulty for a block.
1018
    """
1019
    offset = (
1020
        int(parent_difficulty)
1021
        // 2048
1022
        * max(
1023
            (2 if parent_has_ommers else 1)
1024
            - int(block_timestamp - parent_timestamp) // 9,
1025
            -99,
1026
        )
1027
    )
1028
    difficulty = int(parent_difficulty) + offset
1029
    # Historical Note: The difficulty bomb was not present in Ethereum at the
1030
    # start of Frontier, but was added shortly after launch. However since the
1031
    # bomb has no effect prior to block 200000 we pretend it existed from
1032
    # genesis.
1033
    # See https://github.com/ethereum/go-ethereum/pull/1588
1034
    num_bomb_periods = ((int(block_number) - BOMB_DELAY_BLOCKS) // 100000) - 2
1035
    if num_bomb_periods >= 0:
1036
        difficulty += 2**num_bomb_periods
1037
1038
    # Some clients raise the difficulty to `MINIMUM_DIFFICULTY` prior to adding
1039
    # the bomb. This bug does not matter because the difficulty is always much
1040
    # greater than `MINIMUM_DIFFICULTY` on Mainnet.
1041
    return Uint(max(difficulty, int(MINIMUM_DIFFICULTY)))