ethereum.paris.blocksethereum.shanghai.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
29 | @slotted_freezable |
---|
30 | @dataclass |
---|
class Withdrawal:
index
The unique index of the withdrawal, incremented for each withdrawal processed.
40 | index: U64 |
---|
validator_index
The index of the validator on the consensus layer that is withdrawing.
46 | validator_index: U64 |
---|
address
The execution-layer address receiving the withdrawn ETH.
51 | address: Address |
---|
amount
The amount of ETH being withdrawn.
56 | amount: U256 |
---|
Header
Header portion of a block on the chain, containing metadata and cryptographic commitments to the block's contents.
62 | @slotted_freezable |
---|
63 | @dataclass |
---|
class Header:
parent_hash
70 | 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
.
78 | 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.
89 | 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.
100 | state_root: Root |
---|
transactions_root
113 | transactions_root: Root |
---|
receipt_root
125 | 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.
136 | bloom: Bloom |
---|
difficulty
Difficulty of the block (pre-PoS), or a constant in PoS.
144 | difficulty: Uint |
---|
number
Block number, (height) in the chain.
149 | 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.
154 | gas_limit: Uint |
---|
gas_used
Total gas used by all transactions in this block.
168 | gas_used: Uint |
---|
timestamp
Timestamp of when the block was mined, in seconds since the unix epoch.
173 | timestamp: U256 |
---|
extra_data
Arbitrary data included by the miner.
178 | extra_data: Bytes |
---|
prev_randao
Output of the RANDAO beacon for random validator selection.
183 | prev_randao: Bytes32 |
---|
nonce
Nonce used in the mining process (pre-PoS), set to zero in PoS.
188 | 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.
193 | base_fee_per_gas: Uint |
---|
withdrawals_root
Root hash of the withdrawals trie, which contains all withdrawals in this block.
202 | withdrawals_root: Root |
---|
Block
A complete block on Ethereum, which is composed of a block header
,
a list of transactions, and a list of ommers (deprecated).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
), and the transaction receipts), the transaction receipts
(receiptsRoot
). It also includes a bloom filter which summarizes log), and withdrawalsRoot
committing to the validator
data from the transactions.withdrawals included in this block. It also includes a bloom filter which
summarizes log data from the transactions.
Ommers are deprecated and maintained only for compatibility.Withdrawals represent ETH transfers from validators to their recipients,
introduced by the consensus layer. Ommers remain deprecated and empty.
209 | @slotted_freezable |
---|
210 | @dataclass |
---|
class Block:
header
The block header containing metadata and cryptographic commitments. Refer headers for more details on the fields included in the header.
235 | header: Header |
---|
transactions
A tuple of transactions included in this block. Each transaction can be any of a legacy transaction, an access list transaction, or a fee market transaction.
243 | transactions: Tuple[Bytes | LegacyTransaction, ...] |
---|
ommers
A tuple of ommers (uncle blocks) included in this block. Always empty in Proof-of-Stake forks.
250 | ommers: Tuple[Header, ...] |
---|
withdrawals
A tuple of withdrawals processed in this block.
256 | withdrawals: Tuple[Withdrawal, ...] |
---|
Log
262 | @slotted_freezable |
---|
263 | @dataclass |
---|
class Log:
address
The address of the contract that emitted the log.
278 | address: Address |
---|
topics
A tuple of up to four topics associated with the log, used for filtering.
283 | topics: Tuple[Hash32, ...] |
---|
data
The data payload of the log, which can contain any arbitrary data.
288 | data: Bytes |
---|
Receipt
Result of a transaction execution. Receipts are included in the receipts trie.
294 | @slotted_freezable |
---|
295 | @dataclass |
---|
class Receipt:
succeeded
Whether the transaction execution was successful.
302 | succeeded: bool |
---|
cumulative_gas_used
Total gas used in the block up to and including this transaction.
307 | 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.
312 | 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.
318 | 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:
327 | r""" |
---|---|
328 | Encodes a transaction receipt based on the transaction type. |
329 |
|
330 | The encoding follows the same format as transactions encoding, where: |
331 | - AccessListTransaction receipts are prefixed with `b"\x01"`. |
332 | - FeeMarketTransaction receipts are prefixed with `b"\x02"`. |
333 | - LegacyTransaction receipts are returned as is. |
334 | """ |
335 | if isinstance(tx, AccessListTransaction): |
336 | return b"\x01" + rlp.encode(receipt) |
337 | elif isinstance(tx, FeeMarketTransaction): |
338 | return b"\x02" + rlp.encode(receipt) |
339 | else: |
340 | 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:
344 | r""" |
---|---|
345 | Decodes a receipt from its serialized form. |
346 |
|
347 | The decoding follows the same format as transactions decoding, where: |
348 | - Receipts prefixed with `b"\x01"` are decoded as AccessListTransaction |
349 | receipts. |
350 | - Receipts prefixed with `b"\x02"` are decoded as FeeMarketTransaction |
351 | receipts. |
352 | - LegacyTransaction receipts are returned as is. |
353 | """ |
354 | if isinstance(receipt, Bytes): |
355 | assert receipt[0] in (1, 2) |
356 | return rlp.decode_to(Receipt, receipt[1:]) |
357 | else: |
358 | return receipt |