ethereum-execution 2.18.0rc6.dev2__py3-none-any.whl

ethereum/forks/cancun/blocks.py

@@ -0,0 +1,389 @@
+"""
+A `Block` is a single link in the chain that is Ethereum. Each `Block` contains
+a `Header` and zero or more transactions. Each `Header` contains associated
+metadata like the block number, parent block hash, and how much gas was
+consumed by its transactions.
+
+Together, these blocks form a cryptographically secure journal recording the
+history of all state transitions that have happened since the genesis of the
+chain.
+"""
+
+from dataclasses import dataclass
+from typing import Tuple
+
+from ethereum_rlp import rlp
+from ethereum_types.bytes import Bytes, Bytes8, Bytes32
+from ethereum_types.frozen import slotted_freezable
+from ethereum_types.numeric import U64, U256, Uint
+
+from ethereum.crypto.hash import Hash32
+
+from .fork_types import Address, Bloom, Root
+from .transactions import (
+    AccessListTransaction,
+    BlobTransaction,
+    FeeMarketTransaction,
+    LegacyTransaction,
+    Transaction,
+)
+
+
+@slotted_freezable
+@dataclass
+class Withdrawal:
+    """
+    Withdrawals represent a transfer of ETH from the consensus layer (beacon
+    chain) to the execution layer, as validated by the consensus layer. Each
+    withdrawal is listed in the block's list of withdrawals. See [`block`].
+
+    [`block`]: ref:ethereum.forks.cancun.blocks.Block.withdrawals
+    """
+
+    index: U64
+    """
+    The unique index of the withdrawal, incremented for each withdrawal
+    processed.
+    """
+
+    validator_index: U64
+    """
+    The index of the validator on the consensus layer that is withdrawing.
+    """
+
+    address: Address
+    """
+    The execution-layer address receiving the withdrawn ETH.
+    """
+
+    amount: U256
+    """
+    The amount of ETH being withdrawn.
+    """
+
+
+@slotted_freezable
+@dataclass
+class Header:
+    """
+    Header portion of a block on the chain, containing metadata and
+    cryptographic commitments to the block's contents.
+    """
+
+    parent_hash: Hash32
+    """
+    Hash ([`keccak256`]) of the parent block's header, encoded with [RLP].
+
+    [`keccak256`]: ref:ethereum.crypto.hash.keccak256
+    [RLP]: https://ethereum.github.io/ethereum-rlp/src/ethereum_rlp/rlp.py.html
+    """
+
+    ommers_hash: Hash32
+    """
+    Hash ([`keccak256`]) of the ommers (uncle blocks) in this block, encoded
+    with [RLP]. However, in post merge forks `ommers_hash` is always
+    [`EMPTY_OMMER_HASH`].
+
+    [`keccak256`]: ref:ethereum.crypto.hash.keccak256
+    [RLP]: https://ethereum.github.io/ethereum-rlp/src/ethereum_rlp/rlp.py.html
+    [`EMPTY_OMMER_HASH`]: ref:ethereum.forks.cancun.fork.EMPTY_OMMER_HASH
+    """
+
+    coinbase: Address
+    """
+    Address of the miner (or validator) who mined this block.
+
+    The coinbase address receives the block reward and the priority fees (tips)
+    from included transactions. Base fees (introduced in [EIP-1559]) are burned
+    and do not go to the coinbase.
+
+    [EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559
+    """
+
+    state_root: Root
+    """
+    Root hash ([`keccak256`]) of the state trie after executing all
+    transactions in this block. It represents the state of the Ethereum Virtual
+    Machine (EVM) after all transactions in this block have been processed. It
+    is computed using the [`state_root()`] function, which computes the root
+    of the Merkle-Patricia [Trie] representing the Ethereum world state.
+
+    [`keccak256`]: ref:ethereum.crypto.hash.keccak256
+    [`state_root()`]: ref:ethereum.forks.cancun.state.state_root
+    [Trie]: ref:ethereum.forks.cancun.trie.Trie
+    """
+
+    transactions_root: Root
+    """
+    Root hash ([`keccak256`]) of the transactions trie, which contains all
+    transactions included in this block in their original order. It is computed
+    using the [`root()`] function over the Merkle-Patricia [trie] of
+    transactions as the parameter.
+
+    [`keccak256`]: ref:ethereum.crypto.hash.keccak256
+    [`root()`]: ref:ethereum.forks.cancun.trie.root
+    [Trie]: ref:ethereum.forks.cancun.trie.Trie
+    """
+
+    receipt_root: Root
+    """
+    Root hash ([`keccak256`]) of the receipts trie, which contains all receipts
+    for transactions in this block. It is computed using the [`root()`]
+    function over the Merkle-Patricia [trie] constructed from the receipts.
+
+    [`keccak256`]: ref:ethereum.crypto.hash.keccak256
+    [`root()`]: ref:ethereum.forks.cancun.trie.root
+    [Trie]: ref:ethereum.forks.cancun.trie.Trie
+    """
+
+    bloom: Bloom
+    """
+    Bloom filter for logs generated by transactions in this block.
+    Constructed from all logs in the block using the [logs bloom] mechanism.
+
+    [logs bloom]: ref:ethereum.forks.cancun.bloom.logs_bloom
+    """
+
+    difficulty: Uint
+    """
+    Difficulty of the block (pre-PoS), or a constant in PoS.
+    """
+
+    number: Uint
+    """
+    Block number, (height) in the chain.
+    """
+
+    gas_limit: Uint
+    """
+    Maximum gas allowed in this block. Pre [EIP-1559], this was the maximum
+    gas that could be consumed by all transactions in the block. Post
+    [EIP-1559], this is still the maximum gas limit, but the base fee per gas
+    is also considered when calculating the effective gas limit. This can be
+    [adjusted by a factor of 1/1024] from the previous block's gas limit, up
+    until a maximum of 30 million gas.
+
+    [EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559
+    [adjusted by a factor of 1/1024]:
+    https://ethereum.org/en/developers/docs/blocks/
+    """
+
+    gas_used: Uint
+    """
+    Total gas used by all transactions in this block.
+    """
+
+    timestamp: U256
+    """
+    Timestamp of when the block was mined, in seconds since the unix epoch.
+    """
+
+    extra_data: Bytes
+    """
+    Arbitrary data included by the miner.
+    """
+
+    prev_randao: Bytes32
+    """
+    Output of the RANDAO beacon for random validator selection.
+    """
+
+    nonce: Bytes8
+    """
+    Nonce used in the mining process (pre-PoS), set to zero in PoS.
+    """
+
+    base_fee_per_gas: Uint
+    """
+    Base fee per gas for transactions in this block, introduced in
+    [EIP-1559]. This is the minimum fee per gas that must be paid for a
+    transaction to be included in this block.
+
+    [EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559
+    """
+
+    withdrawals_root: Root
+    """
+    Root hash of the withdrawals trie, which contains all withdrawals in this
+    block.
+    """
+
+    blob_gas_used: U64
+    """
+    Total blob gas consumed by the transactions within this block. Introduced
+    in [EIP-4844].
+
+    [EIP-4844]: https://eips.ethereum.org/EIPS/eip-4844
+    """
+
+    excess_blob_gas: U64
+    """
+    Running total of blob gas consumed in excess of the target, prior to this
+    block. Blocks with above-target blob gas consumption increase this value,
+    while blocks with below-target blob gas consumption decrease it (to a
+    minimum of zero). Introduced in [EIP-4844].
+
+    [EIP-4844]: https://eips.ethereum.org/EIPS/eip-4844
+    """
+
+    parent_beacon_block_root: Root
+    """
+    Root hash of the corresponding beacon chain block.
+    """
+
+
+@slotted_freezable
+@dataclass
+class Block:
+    """
+    A complete block on Ethereum, which is composed of a block [`header`],
+    a list of transactions, a list of ommers (deprecated), and a list of
+    validator [withdrawals].
+
+    The block [`header`] includes fields relevant to the Proof-of-Stake
+    consensus, with deprecated Proof-of-Work fields such as `difficulty`,
+    `nonce`, and `ommersHash` set to constants. The `coinbase` field
+    denotes the address receiving priority fees from the block.
+
+    The header also contains commitments to the current state (`stateRoot`),
+    the transactions (`transactionsRoot`), the transaction receipts
+    (`receiptsRoot`), and `withdrawalsRoot` committing to the validator
+    withdrawals included in this block. It also includes a bloom filter which
+    summarizes log data from the transactions.
+
+    Withdrawals represent ETH transfers from validators to their recipients,
+    introduced by the consensus layer. Ommers remain deprecated and empty.
+
+    [`header`]: ref:ethereum.forks.cancun.blocks.Header
+    [withdrawals]: ref:ethereum.forks.cancun.blocks.Withdrawal
+    """
+
+    header: Header
+    """
+    The block header containing metadata and cryptographic commitments. Refer
+    [headers] for more details on the fields included in the header.
+
+    [headers]: ref:ethereum.forks.cancun.blocks.Header
+    """
+
+    transactions: Tuple[Bytes | LegacyTransaction, ...]
+    """
+    A tuple of transactions included in this block. Each transaction can be
+    any of a legacy transaction, an access list transaction, a fee market
+    transaction, or a blob transaction.
+    """
+
+    ommers: Tuple[Header, ...]
+    """
+    A tuple of ommers (uncle blocks) included in this block. Always empty in
+    Proof-of-Stake forks.
+    """
+
+    withdrawals: Tuple[Withdrawal, ...]
+    """
+    A tuple of withdrawals processed in this block.
+    """
+
+
+@slotted_freezable
+@dataclass
+class Log:
+    """
+    Data record produced during the execution of a transaction. Logs are used
+    by smart contracts to emit events (using the EVM log opcodes ([`LOG0`],
+    [`LOG1`], [`LOG2`], [`LOG3`] and [`LOG4`]), which can be efficiently
+    searched using the bloom filter in the block header.
+
+    [`LOG0`]: ref:ethereum.forks.cancun.vm.instructions.log.log0
+    [`LOG1`]: ref:ethereum.forks.cancun.vm.instructions.log.log1
+    [`LOG2`]: ref:ethereum.forks.cancun.vm.instructions.log.log2
+    [`LOG3`]: ref:ethereum.forks.cancun.vm.instructions.log.log3
+    [`LOG4`]: ref:ethereum.forks.cancun.vm.instructions.log.log4
+    """
+
+    address: Address
+    """
+    The address of the contract that emitted the log.
+    """
+
+    topics: Tuple[Hash32, ...]
+    """
+    A tuple of up to four topics associated with the log, used for filtering.
+    """
+
+    data: Bytes
+    """
+    The data payload of the log, which can contain any arbitrary data.
+    """
+
+
+@slotted_freezable
+@dataclass
+class Receipt:
+    """
+    Result of a transaction execution. Receipts are included in the receipts
+    trie.
+    """
+
+    succeeded: bool
+    """
+    Whether the transaction execution was successful.
+    """
+
+    cumulative_gas_used: Uint
+    """
+    Total gas used in the block up to and including this transaction.
+    """
+
+    bloom: Bloom
+    """
+    Bloom filter for logs generated by this transaction. This is a 2048-byte
+    bit array that allows for efficient filtering of logs.
+    """
+
+    logs: Tuple[Log, ...]
+    """
+    A tuple of logs generated by this transaction. Each log contains the
+    address of the contract that emitted it, a tuple of topics, and the data
+    payload.
+    """
+
+
+def encode_receipt(tx: Transaction, receipt: Receipt) -> Bytes | Receipt:
+    r"""
+    Encodes a transaction receipt based on the transaction type.
+
+    The encoding follows the same format as transactions encoding, where:
+    - AccessListTransaction receipts are prefixed with `b"\x01"`.
+    - FeeMarketTransaction receipts are prefixed with `b"\x02"`.
+    - BlobTransaction receipts are prefixed with `b"\x03"`.
+    - LegacyTransaction receipts are returned as is.
+    """
+    if isinstance(tx, AccessListTransaction):
+        return b"\x01" + rlp.encode(receipt)
+    elif isinstance(tx, FeeMarketTransaction):
+        return b"\x02" + rlp.encode(receipt)
+    elif isinstance(tx, BlobTransaction):
+        return b"\x03" + rlp.encode(receipt)
+    else:
+        return receipt
+
+
+def decode_receipt(receipt: Bytes | Receipt) -> Receipt:
+    r"""
+    Decodes a receipt from its serialized form.
+
+    The decoding follows the same format as transactions decoding, where:
+    - Receipts prefixed with `b"\x01"` are decoded as AccessListTransaction
+    receipts.
+    - Receipts prefixed with `b"\x02"` are decoded as FeeMarketTransaction
+    receipts.
+    - Receipts prefixed with `b"\x03"` are decoded as BlobTransaction
+    receipts.
+    - LegacyTransaction receipts are returned as is.
+    """
+    if isinstance(receipt, Bytes):
+        assert receipt[0] in (1, 2, 3)
+        return rlp.decode_to(Receipt, receipt[1:])
+    else:
+        return receipt

ethereum/forks/cancun/bloom.py

@@ -0,0 +1,87 @@
+"""
+Ethereum Logs Bloom.
+
+.. contents:: Table of Contents
+    :backlinks: none
+    :local:
+
+Introduction
+------------
+
+This modules defines functions for calculating bloom filters of logs. For the
+general theory of bloom filters see e.g. `Wikipedia
+<https://en.wikipedia.org/wiki/Bloom_filter>`_. Bloom filters are used to allow
+for efficient searching of logs by address and/or topic, by rapidly
+eliminating blocks and receipts from their search.
+"""
+
+from typing import Tuple
+
+from ethereum_types.bytes import Bytes
+from ethereum_types.numeric import Uint
+
+from ethereum.crypto.hash import keccak256
+
+from .blocks import Log
+from .fork_types import Bloom
+
+
+def add_to_bloom(bloom: bytearray, bloom_entry: Bytes) -> None:
+    """
+    Add a bloom entry to the bloom filter (`bloom`).
+
+    The number of hash functions used is 3. They are calculated by taking the
+    least significant 11 bits from the first 3 16-bit words of the
+    `keccak_256()` hash of `bloom_entry`.
+
+    Parameters
+    ----------
+    bloom :
+        The bloom filter.
+    bloom_entry :
+        An entry which is to be added to bloom filter.
+
+    """
+    hashed = keccak256(bloom_entry)
+
+    for idx in (0, 2, 4):
+        # Obtain the least significant 11 bits from the pair of bytes
+        # (16 bits), and set this bit in bloom bytearray.
+        # The obtained bit is 0-indexed in the bloom filter from the least
+        # significant bit to the most significant bit.
+        bit_to_set = Uint.from_be_bytes(hashed[idx : idx + 2]) & Uint(0x07FF)
+        # Below is the index of the bit in the bytearray (where 0-indexed
+        # byte is the most significant byte)
+        bit_index = 0x07FF - int(bit_to_set)
+
+        byte_index = bit_index // 8
+        bit_value = 1 << (7 - (bit_index % 8))
+        bloom[byte_index] = bloom[byte_index] | bit_value
+
+
+def logs_bloom(logs: Tuple[Log, ...]) -> Bloom:
+    """
+    Obtain the logs bloom from a list of log entries.
+
+    The address and each topic of a log are added to the bloom filter.
+
+    Parameters
+    ----------
+    logs :
+        List of logs for which the logs bloom is to be obtained.
+
+    Returns
+    -------
+    logs_bloom : `Bloom`
+        The logs bloom obtained which is 256 bytes with some bits set as per
+        the caller address and the log topics.
+
+    """
+    bloom: bytearray = bytearray(b"\x00" * 256)
+
+    for log in logs:
+        add_to_bloom(bloom, log.address)
+        for topic in log.topics:
+            add_to_bloom(bloom, topic)
+
+    return Bloom(bloom)

ethereum/forks/cancun/exceptions.py

@@ -0,0 +1,109 @@
+"""
+Exceptions specific to this fork.
+"""
+
+from typing import TYPE_CHECKING, Final
+
+from ethereum_types.numeric import Uint
+
+from ethereum.exceptions import InvalidTransaction
+
+if TYPE_CHECKING:
+    from .transactions import Transaction
+
+
+class TransactionTypeError(InvalidTransaction):
+    """
+    Unknown [EIP-2718] transaction type byte.
+
+    [EIP-2718]: https://eips.ethereum.org/EIPS/eip-2718
+    """
+
+    transaction_type: Final[int]
+    """
+    The type byte of the transaction that caused the error.
+    """
+
+    def __init__(self, transaction_type: int):
+        super().__init__(f"unknown transaction type `{transaction_type}`")
+        self.transaction_type = transaction_type
+
+
+class TransactionTypeContractCreationError(InvalidTransaction):
+    """
+    Contract creation is not allowed for a transaction type.
+    """
+
+    transaction: "Transaction"
+    """
+    The transaction that caused the error.
+    """
+
+    def __init__(self, transaction: "Transaction"):
+        super().__init__(
+            f"transaction type `{type(transaction).__name__}` not allowed to "
+            "create contracts"
+        )
+        self.transaction = transaction
+
+
+class BlobGasLimitExceededError(InvalidTransaction):
+    """
+    The blob gas limit for the transaction exceeds the maximum allowed.
+    """
+
+
+class InsufficientMaxFeePerBlobGasError(InvalidTransaction):
+    """
+    The maximum fee per blob gas is insufficient for the transaction.
+    """
+
+
+class InsufficientMaxFeePerGasError(InvalidTransaction):
+    """
+    The maximum fee per gas is insufficient for the transaction.
+    """
+
+    transaction_max_fee_per_gas: Final[Uint]
+    """
+    The maximum fee per gas specified in the transaction.
+    """
+
+    block_base_fee_per_gas: Final[Uint]
+    """
+    The base fee per gas of the block in which the transaction is included.
+    """
+
+    def __init__(
+        self, transaction_max_fee_per_gas: Uint, block_base_fee_per_gas: Uint
+    ):
+        super().__init__(
+            f"Insufficient max fee per gas "
+            f"({transaction_max_fee_per_gas} < {block_base_fee_per_gas})"
+        )
+        self.transaction_max_fee_per_gas = transaction_max_fee_per_gas
+        self.block_base_fee_per_gas = block_base_fee_per_gas
+
+
+class InvalidBlobVersionedHashError(InvalidTransaction):
+    """
+    The versioned hash of the blob is invalid.
+    """
+
+
+class NoBlobDataError(InvalidTransaction):
+    """
+    The transaction does not contain any blob data.
+    """
+
+
+class PriorityFeeGreaterThanMaxFeeError(InvalidTransaction):
+    """
+    The priority fee is greater than the maximum fee per gas.
+    """
+
+
+class InitCodeTooLargeError(InvalidTransaction):
+    """
+    The init code of the transaction is too large.
+    """