Skip to content

docs: refactor docstrings to md #1297

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

docs: refactor docstrings to md #1297

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
297d92c
update utils to md
souradeep-das Jun 23, 2025
a505338
arrow_glacier reST to md
souradeep-das Jun 26, 2025
2787c3b
rem ignored files
souradeep-das Jun 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 75 additions & 85 deletions src/ethereum/arrow_glacier/blocks.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,85 +36,82 @@ class Header:

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
Hash
([`keccak256`](../crypto/hash.py.html#ethereum.crypto.hash.keccak256:0))
of the parent block's header, encoded with
[RLP](https://ethereum.github.io/ethereum-rlp/src/ethereum_rlp/rlp.py.html).
Comment on lines -39 to +42
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like these docstrings got converted from markdown back into markdown, while losing the docc features (eg. ref:ethereum.crypto.hash.keccak256)? I'm pretty sure you already did blocks.py and transactions.py in #1263.

"""

ommers_hash: Hash32
"""
Hash ([`keccak256`]) of the ommers (uncle blocks) in this block, encoded
with [RLP].

[`keccak256`]: ref:ethereum.crypto.hash.keccak256
[RLP]: https://ethereum.github.io/ethereum-rlp/src/ethereum_rlp/rlp.py.html
Hash
([`keccak256`](../crypto/hash.py.html#ethereum.crypto.hash.keccak256:0))
of the ommers (uncle blocks) in this block, encoded with
[RLP](https://ethereum.github.io/ethereum-rlp/src/ethereum_rlp/rlp.py.html).
"""

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
from included transactions. Base fees (introduced in
[EIP-1559](https://eips.ethereum.org/EIPS/eip-1559)) are burned and do not
go to the coinbase.
Comment on lines +58 to +60
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should try to avoid making changes without material effect because it makes tracing history (like with git blame) more difficult. Here we're just changing from footnote style links to inline, but the rendered output would be the same.

"""

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.arrow_glacier.state.state_root
[Trie]: ref:ethereum.arrow_glacier.trie.Trie
Root hash
([`keccak256`](../crypto/hash.py.html#ethereum.crypto.hash.keccak256:0))
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()`](./state.py.html#ethereum.arrow_glacier.state.state_root:0)
function, which computes the root of the Merkle-Patricia
[Trie](./trie.py.html#ethereum.arrow_glacier.trie.Trie:0) representing the
Ethereum world state.
"""

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.arrow_glacier.trie.root
[Trie]: ref:ethereum.arrow_glacier.trie.Trie
Root hash
([`keccak256`](../crypto/hash.py.html#ethereum.crypto.hash.keccak256:0))
of the transactions trie, which contains all transactions included in this
block in their original order. It is computed using the
[`root()`](./trie.py.html#ethereum.arrow_glacier.trie.root:0) function
over the Merkle-Patricia
[trie](./trie.py.html#ethereum.arrow_glacier.trie.Trie:0) of transactions
as the parameter.
"""

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.arrow_glacier.trie.root
[Trie]: ref:ethereum.arrow_glacier.trie.Trie
Root hash
([`keccak256`](../crypto/hash.py.html#ethereum.crypto.hash.keccak256:0))
of the receipts trie, which contains all receipts for transactions in this
block. It is computed using the
[`root()`](./trie.py.html#ethereum.arrow_glacier.trie.root:0) function
over the Merkle-Patricia
[trie](./trie.py.html#ethereum.arrow_glacier.trie.Trie:0) constructed from
the receipts.
"""

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.arrow_glacier.bloom.logs_bloom
Constructed from all logs in the block using the
[logs bloom](./bloom.py.html#ethereum.arrow_glacier.bloom.logs_bloom:0)
mechanism.
"""

difficulty: Uint
"""
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.

[`calculate_block_difficulty()`]:
ref:ethereum.arrow_glacier.fork.calculate_block_difficulty
[`calculate_block_difficulty()`](./fork.py.html#ethereum.arrow_glacier.fork.calculate_block_difficulty:0)
function.
"""

number: Uint
Expand All @@ -124,16 +121,14 @@ class Header:

gas_limit: Uint
"""
Maximum gas allowed in this block. Pre [EIP-1559], this was the maximum
Maximum gas allowed in this block. Pre
[EIP-1559](https://eips.ethereum.org/EIPS/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/
[EIP-1559](https://eips.ethereum.org/EIPS/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](https://ethereum.org/en/developers/docs/blocks/)
from the previous block's gas limit, up until a maximum of 30 million gas.
"""

gas_used: Uint
Expand All @@ -154,42 +149,40 @@ class Header:
mix_digest: Bytes32
"""
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.

[validates]: ref:ethereum.arrow_glacier.fork.validate_proof_of_work
to the block's contents. It
[validates](./fork.py.html#ethereum.arrow_glacier.fork.validate_proof_of_work:0)
that PoW was done on the correct block.
"""

nonce: Bytes8
"""
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.

[validate]: ref:ethereum.arrow_glacier.fork.validate_proof_of_work
increment to find a valid block hash. This is also used to
[validate](./fork.py.html#ethereum.arrow_glacier.fork.validate_proof_of_work:0)
the proof-of-work for this block.
"""

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
[EIP-1559](https://eips.ethereum.org/EIPS/eip-1559). This is the minimum
fee per gas that must be paid for a transaction to be included in this
block.
"""


@slotted_freezable
@dataclass
class 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).
A complete block on Ethereum, which is composed of a block
[`header`](#ethereum.arrow_glacier.blocks.Header:0), 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 block [`header`](#ethereum.arrow_glacier.blocks.Header:0) 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
Expand All @@ -198,16 +191,13 @@ class Block:

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

[`header`]: ref:ethereum.arrow_glacier.blocks.Header
"""

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.arrow_glacier.blocks.Header
[headers](#ethereum.arrow_glacier.blocks.Header:0) for more details on the
fields included in the header.
"""

transactions: Tuple[Union[Bytes, LegacyTransaction], ...]
Expand All @@ -230,15 +220,15 @@ class Block:
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.arrow_glacier.vm.instructions.log.log0
[`LOG1`]: ref:ethereum.arrow_glacier.vm.instructions.log.log1
[`LOG2`]: ref:ethereum.arrow_glacier.vm.instructions.log.log2
[`LOG3`]: ref:ethereum.arrow_glacier.vm.instructions.log.log3
[`LOG4`]: ref:ethereum.arrow_glacier.vm.instructions.log.log4
by smart contracts to emit events (using the EVM log opcodes
([`LOG0`](./vm/instructions/log.py.html#ethereum.arrow_glacier.vm.instructions.log.log0:0),
[`LOG1`](./vm/instructions/log.py.html#ethereum.arrow_glacier.vm.instructions.log.log1:0),
[`LOG2`](./vm/instructions/log.py.html#ethereum.arrow_glacier.vm.instructions.log.log2:0),
[`LOG3`](./vm/instructions/log.py.html#ethereum.arrow_glacier.vm.instructions.log.log3:0)
and
[`LOG4`](./vm/instructions/log.py.html#ethereum.arrow_glacier.vm.instructions.log.log4:0)),
which can be efficiently searched using the bloom filter in the block
header.
"""

address: Address
Expand Down
42 changes: 15 additions & 27 deletions src/ethereum/arrow_glacier/bloom.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,13 @@
"""
Ethereum Logs Bloom
^^^^^^^^^^^^^^^^^^^
# Ethereum Logs Bloom
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because docc automatically adds a header with the module name, we can omit these manual ones.

Suggested change
# Ethereum Logs Bloom


.. contents:: Table of Contents
:backlinks: none
:local:

Introduction
------------
## Introduction
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Until we have need for more subsections, how about we drop this one too and go directly into the content?

Suggested change
## 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.
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.
Comment on lines -2 to +10
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is definitely more what I had in mind for this issue!

"""

from typing import Tuple
Expand All @@ -35,12 +29,9 @@ def add_to_bloom(bloom: bytearray, bloom_entry: Bytes) -> None:
least significant 11 bits from the first 3 16-bit words of the
`keccak_256()` hash of `bloom_entry`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While we're here, we could fix the name and maybe add a link?

Suggested change
`keccak_256()` hash of `bloom_entry`.
[`keccak256`] hash of `bloom_entry`.
[`keccak256`]: ref:ethereum.crypto.hash.keccak256


Parameters
----------
bloom :
The bloom filter.
bloom_entry :
An entry which is to be added to bloom filter.
#### Parameters
- bloom: The bloom filter.
- bloom_entry: An entry which is to be added to bloom filter.
Comment on lines +32 to +34
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#### Parameters
- bloom: The bloom filter.
- bloom_entry: An entry which is to be added to bloom filter.

I'm okay just dropping the parameters sections and adding some prose if the parameters are confusing. Most of the time the meaning of the parameter is obvious from the name anyway.

"""
hash = keccak256(bloom_entry)

Expand All @@ -65,16 +56,13 @@ def logs_bloom(logs: Tuple[Log, ...]) -> Bloom:

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.
#### 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.
#### 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.
Comment on lines +62 to +65
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar to the parameters section, I think we can drop returns and incorporate the text. Something like:

Obtain the logs bloom from a list of log entries.

The address and each topic of a log are collected into a bloom filter and returned.

"""
bloom: bytearray = bytearray(b"\x00" * 256)

Expand Down
5 changes: 2 additions & 3 deletions src/ethereum/arrow_glacier/exceptions.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,8 @@

class TransactionTypeError(InvalidTransaction):
"""
Unknown [EIP-2718] transaction type byte.

[EIP-2718]: https://eips.ethereum.org/EIPS/eip-2718
Unknown [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) transaction
type byte.
Comment on lines +14 to +15
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another unintentional markdown -> markdown?

"""

transaction_type: Final[int]
Expand Down
Loading