ethereum.shanghai.blocksethereum.cancun.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

30
@slotted_freezable
31
@dataclass
class Withdrawal:

index

41
    index: U64

validator_index

47
    validator_index: U64

address

52
    address: Address

amount

57
    amount: U256

Header

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

63
@slotted_freezable
64
@dataclass
class Header:

parent_hash

71
    parent_hash: Hash32

ommers_hash

79
    ommers_hash: Hash32

coinbase

90
    coinbase: Address

state_root

101
    state_root: Root

transactions_root

114
    transactions_root: Root

receipt_root

126
    receipt_root: Root

bloom

137
    bloom: Bloom

difficulty

145
    difficulty: Uint

number

150
    number: Uint

gas_limit

155
    gas_limit: Uint

gas_used

169
    gas_used: Uint

timestamp

174
    timestamp: U256

extra_data

179
    extra_data: Bytes

prev_randao

184
    prev_randao: Bytes32

nonce

189
    nonce: Bytes8

base_fee_per_gas

194
    base_fee_per_gas: Uint

withdrawals_root

203
    withdrawals_root: Root

blob_gas_used

209
    blob_gas_used: U64

excess_blob_gas

217
    excess_blob_gas: U64

parent_beacon_block_root

227
    parent_beacon_block_root: Root

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.

233
@slotted_freezable
234
@dataclass
class Block:

header

259
    header: Header

transactions

267
    transactions: Tuple[Union[Bytes, LegacyTransaction], ...]

ommers

274
    ommers: Tuple[Header, ...]

withdrawals

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

286
@slotted_freezable
287
@dataclass
class Log:

address

302
    address: Address

topics

307
    topics: Tuple[Hash32, ...]

data

312
    data: Bytes

Receipt

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

318
@slotted_freezable
319
@dataclass
class Receipt:

succeeded

326
    succeeded: bool

cumulative_gas_used

331
    cumulative_gas_used: Uint

bloom

336
    bloom: Bloom

logs

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

  • LegacyTransaction receipts are returned as is.

def encode_receipt(​tx: Transaction, ​​receipt: Receipt​) -> Union[Bytes, Receipt]:
351
    r"""
352
    Encodes a transaction receipt based on the transaction type.
353
354
    The encoding follows the same format as transactions encoding, where:
355
    - AccessListTransaction receipts are prefixed with `b"\x01"`.
356
    - FeeMarketTransaction receipts are prefixed with `b"\x02"`.
357
    - BlobTransaction receipts are prefixed with `b"\x03"`.
358
    - LegacyTransaction receipts are returned as is.
359
    """
360
    if isinstance(tx, AccessListTransaction):
361
        return b"\x01" + rlp.encode(receipt)
362
    elif isinstance(tx, FeeMarketTransaction):
363
        return b"\x02" + rlp.encode(receipt)
339
    else:
340
        return receipt
364
    elif isinstance(tx, BlobTransaction):
365
        return b"\x03" + rlp.encode(receipt)
366
    else:
367
        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.

  • LegacyTransaction receipts are returned as is.

def decode_receipt(​receipt: Union[Bytes, Receipt]​) -> Receipt:
371
    r"""
372
    Decodes a receipt from its serialized form.
373
374
    The decoding follows the same format as transactions decoding, where:
375
    - Receipts prefixed with `b"\x01"` are decoded as AccessListTransaction
376
    receipts.
377
    - Receipts prefixed with `b"\x02"` are decoded as FeeMarketTransaction
378
    receipts.
379
    - Receipts prefixed with `b"\x03"` are decoded as BlobTransaction
380
    receipts.
381
    - LegacyTransaction receipts are returned as is.
382
    """
383
    if isinstance(receipt, Bytes):
355
        assert receipt[0] in (1, 2)
384
        assert receipt[0] in (1, 2, 3)
385
        return rlp.decode_to(Receipt, receipt[1:])
386
    else:
387
        return receipt