ethereum.forks.amsterdam.blocks

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.

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.

34
@slotted_freezable
35
@dataclass
class Withdrawal:

index

The unique index of the withdrawal, incremented for each withdrawal processed.

45
    index: U64

validator_index

The index of the validator on the consensus layer that is withdrawing.

51
    validator_index: U64

address

The execution-layer address receiving the withdrawn ETH.

56
    address: Address

amount

The amount of ETH being withdrawn.

61
    amount: U256

Header

Header portion of a block on the chain, containing metadata and cryptographic commitments to the block's contents.

67
@slotted_freezable
68
@dataclass
class Header:

parent_hash

Hash (keccak256) of the parent block's header, encoded with RLP.

75
    parent_hash: Hash32

ommers_hash

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.

83
    ommers_hash: Hash32

coinbase

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.

94
    coinbase: Address

state_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 compute_state_root_and_trie_changes(), which computes the root of the Merkle-Patricia Trie representing the Ethereum world state after applying the block's state changes.

105
    state_root: Root

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

119
    transactions_root: Root

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

131
    receipt_root: Root

bloom

Bloom filter for logs generated by transactions in this block. Constructed from all logs in the block using the logs bloom mechanism.

142
    bloom: Bloom

difficulty

Difficulty of the block (pre-PoS), or a constant in PoS.

150
    difficulty: Uint

number

Block number (height) in the chain.

155
    number: Uint

gas_limit

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.

160
    gas_limit: Uint

gas_used

Total gas used by all transactions in this block.

174
    gas_used: Uint

timestamp

Timestamp of when the block was mined, in seconds since the unix epoch.

179
    timestamp: U256

extra_data

Arbitrary data included by the miner.

184
    extra_data: Bytes

prev_randao

Output of the RANDAO beacon for random validator selection.

189
    prev_randao: Bytes32

nonce

Nonce used in the mining process (pre-PoS), set to zero in PoS.

194
    nonce: Bytes8

base_fee_per_gas

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.

199
    base_fee_per_gas: Uint

withdrawals_root

Root hash of the withdrawals trie, which contains all withdrawals in this block.

208
    withdrawals_root: Root

blob_gas_used

Total blob gas consumed by the transactions within this block. Introduced in EIP-4844.

214
    blob_gas_used: U64

excess_blob_gas

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.

222
    excess_blob_gas: U64

parent_beacon_block_root

Root hash of the corresponding beacon chain block.

232
    parent_beacon_block_root: Root

requests_hash

SHA2-256 hash of all the collected requests in this block. Introduced in EIP-7685. See compute_requests_hash for more details.

237
    requests_hash: Hash32

block_access_list_hash

keccak256 hash of the Block Access List containing all accounts and storage locations accessed during block execution. Introduced in EIP-7928. See compute_block_access_list_hash for more details.

247
    block_access_list_hash: Hash32

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.

260
@slotted_freezable
261
@dataclass
class Block:

header

The block header containing metadata and cryptographic commitments. Refer to headers for more details on the fields included in the header.

286
    header: Header

transactions

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, a blob transaction, or a set code transaction.

294
    transactions: Tuple[Bytes | LegacyTransaction, ...]

ommers

A tuple of ommers (uncle blocks) included in this block. Always empty in Proof-of-Stake forks.

301
    ommers: Tuple[Header, ...]

withdrawals

A tuple of withdrawals processed in this block.

307
    withdrawals: Tuple[Withdrawal, ...]

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.

313
@slotted_freezable
314
@dataclass
class Log:

address

The address of the contract that emitted the log.

329
    address: Address

topics

A tuple of up to four topics associated with the log, used for filtering.

334
    topics: Tuple[Hash32, ...]

data

The data payload of the log, which can contain any arbitrary data.

339
    data: Bytes

Receipt

Result of a transaction execution. Receipts are included in the receipts trie.

345
@slotted_freezable
346
@dataclass
class Receipt:

succeeded

Whether the transaction execution was successful.

353
    succeeded: bool

cumulative_gas_used

Total gas used in the block up to and including this transaction.

358
    cumulative_gas_used: Uint

bloom

Bloom filter for logs generated by this transaction. This is a 2048-byte bit array that allows for efficient filtering of logs.

363
    bloom: Bloom

logs

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.

369
    logs: Tuple[Log, ...]

encode_receipt

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

  • SetCodeTransaction receipts are prefixed with b"\x04".

  • LegacyTransaction receipts are returned as is.

def encode_receipt(​tx: Transaction, ​​receipt: Receipt​) -> Bytes | Receipt:
378
    r"""
379
    Encodes a transaction receipt based on the transaction type.
380
381
    The encoding follows the same format as transactions encoding, where:
382
    - AccessListTransaction receipts are prefixed with `b"\x01"`.
383
    - FeeMarketTransaction receipts are prefixed with `b"\x02"`.
384
    - BlobTransaction receipts are prefixed with `b"\x03"`.
385
    - SetCodeTransaction receipts are prefixed with `b"\x04"`.
386
    - LegacyTransaction receipts are returned as is.
387
    """
388
    if isinstance(tx, AccessListTransaction):
389
        return b"\x01" + rlp.encode(receipt)
390
    elif isinstance(tx, FeeMarketTransaction):
391
        return b"\x02" + rlp.encode(receipt)
392
    elif isinstance(tx, BlobTransaction):
393
        return b"\x03" + rlp.encode(receipt)
394
    elif isinstance(tx, SetCodeTransaction):
395
        return b"\x04" + rlp.encode(receipt)
396
    else:
397
        return receipt

decode_receipt

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.

  • Receipts prefixed with b"\x04" are decoded as SetCodeTransaction receipts.

  • LegacyTransaction receipts are returned as is.

def decode_receipt(​receipt: Bytes | Receipt​) -> Receipt:
401
    r"""
402
    Decodes a receipt from its serialized form.
403
404
    The decoding follows the same format as transactions decoding, where:
405
    - Receipts prefixed with `b"\x01"` are decoded as AccessListTransaction
406
    receipts.
407
    - Receipts prefixed with `b"\x02"` are decoded as FeeMarketTransaction
408
    receipts.
409
    - Receipts prefixed with `b"\x03"` are decoded as BlobTransaction
410
    receipts.
411
    - Receipts prefixed with `b"\x04"` are decoded as SetCodeTransaction
412
    receipts.
413
    - LegacyTransaction receipts are returned as is.
414
    """
415
    if isinstance(receipt, Bytes):
416
        assert receipt[0] in (1, 2, 3, 4)
417
        return rlp.decode_to(Receipt, receipt[1:])
418
    else:
419
        return receipt