ethereum.berlin.blocksethereum.london.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.

Header

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

29
@slotted_freezable
30
@dataclass
class Header:

parent_hash

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

37
    parent_hash: Hash32

ommers_hash

Hash (keccak256) of the ommers (uncle blocks) in this block, encoded with RLP.

45
    ommers_hash: Hash32

coinbase

Address of the miner who mined this block.Address of the miner (or validator) who mined this block.

The coinbase address receives the block reward and all transaction feesThe coinbase address receives the block reward and the priority fees (tips) (gas price * gas used) from included transactions in the block.from included transactions. Base fees (introduced in EIP-1559) are burned and do not go to the coinbase.

54
    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 the state_root() function, which computes the root of the Merkle-Patricia Trie representing the Ethereum world state.

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

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

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

101
    bloom: Bloom

difficulty

Difficulty of the block, used in Proof-of-Work to determine the effort required to mine the block. This value adjusts over time to maintain a relatively constant block time and is computed using the calculate_block_difficulty() function.

109
    difficulty: Uint

number

Block number, (height) in the chain.

120
    number: Uint

gas_limit

Maximum gas allowed in this block. Pre EIP-1559, this is the maximum, this was the maximum gas that could be consumed by all transactions in the block.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.

125
    gas_limit: Uint

gas_used

Total gas used by all transactions in this block.

139
    gas_used: Uint

timestamp

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

144
    timestamp: U256

extra_data

Arbitrary data included by the miner.

149
    extra_data: Bytes

mix_digest

Mix hash used in the mining process, which is a cryptographic commitment to the block's contents. It validates that PoW was done on the correct block.

154
    mix_digest: Bytes32

nonce

Nonce used in the mining process, which is a value that miners increment to find a valid block hash. This is also used to validate the proof-of-work for this block.

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

172
    base_fee_per_gas: Uint

Block

A complete block on Ethereum, which is composed of a block header, a list of transactions, and a list of ommers (also known as uncle blocks).

The block header includes PoW-specific fields such as difficulty, nonce, and ommersHash, which relate to the mining process. The coinbase field denotes the address receiving mining and transaction fees.

The header also contains commitments to the current state (stateRoot), the transactions (transactionsRoot), and the transaction receipts (receiptsRoot). It also includes a bloom filter which summarizes log data from the transactions.

Ommers are used to provide rewards for near-valid mined blocks that didn't become part of the canonical chain.

182
@slotted_freezable
183
@dataclass
class Block:

header

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

205
    header: Header

transactions

A tuple of transactions included in this block, which can be either legacyA tuple of transactions included in this block. Each transaction can be transactions, or access list transactions.any of a legacy transaction, an access list transaction, or a fee market transaction.

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

ommers

A tuple of ommers (uncle blocks) included in this block. Ommers are blocks that were mined at the same time as this block but were not included in the main chain.

220
    ommers: Tuple[Header, ...]

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.

228
@slotted_freezable
229
@dataclass
class Log:

address

The address of the contract that emitted the log.

244
    address: Address

topics

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

249
    topics: Tuple[Hash32, ...]

data

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

254
    data: Bytes

Receipt

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

260
@slotted_freezable
261
@dataclass
class Receipt:

succeeded

Whether the transaction execution was successful.

268
    succeeded: bool

cumulative_gas_used

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

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

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

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

  • LegacyTransaction receipts are returned as is.

def encode_receipt(​tx: Transaction, ​​receipt: Receipt​) -> Bytes | Receipt:
293
    r"""
294
    Encodes a transaction receipt based on the transaction type.
295
296
    The encoding follows the same format as transactions encoding, where:
297
    - AccessListTransaction receipts are prefixed with `b"\x01"`.
298
    - FeeMarketTransaction receipts are prefixed with `b"\x02"`.
299
    - LegacyTransaction receipts are returned as is.
300
    """
301
    if isinstance(tx, AccessListTransaction):
302
        return b"\x01" + rlp.encode(receipt)
278
    else:
279
        return receipt
303
    elif isinstance(tx, FeeMarketTransaction):
304
        return b"\x02" + rlp.encode(receipt)
305
    else:
306
        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.

  • LegacyTransaction receipts are returned as is.

def decode_receipt(​receipt: Bytes | Receipt​) -> Receipt:
310
    r"""
311
    Decodes a receipt from its serialized form.
312
313
    The decoding follows the same format as transactions decoding, where:
314
    - Receipts prefixed with `b"\x01"` are decoded as AccessListTransaction
315
    receipts.
316
    - Receipts prefixed with `b"\x02"` are decoded as FeeMarketTransaction
317
    receipts.
318
    - LegacyTransaction receipts are returned as is.
319
    """
320
    if isinstance(receipt, Bytes):
292
        assert receipt[0] == 1
321
        assert receipt[0] in (1, 2)
322
        return rlp.decode_to(Receipt, receipt[1:])
323
    else:
324
        return receipt