refactor: refactor type factories (leanEthereum#64)

* WIP: Review pydantic approach for List and Vector

* refactor: List -> SSZList as a pydantic model

* refactor: Bitlist refactor for SSZModel

* refactor: More sweeping refactors; rename specific types appropriately

* refactor: reassign types to specific properties for containers

* cleanup: Fix failing tests after refactor

* fix: implement abstract method for Union type

* cleanup: fix failing tests for refactored types

* refactor: draw explicit line between SSZType (is data) and SSZModel (has data)

* refactor: properly type MockState and abstract into fixture for general use

* fix: cleanup some AI slop and tighten up casts

* remove claude iteration / planning doc

* refactor: abstract HISTORICAL_ROOTS_LIMIT

* Use SSZModel for Container

* refactor: address comments from PR leanEthereum#64

* refactor: {ClassName}Base -> Base{ClassName} for consistency with BaseBytes / BaseUint

Author: fselmo

CLAUDE.md

@@ -100,3 +100,81 @@ uv run tox
 2. All models should use Pydantic for automatic validation.
 3. Keep things simple, readable, and clear. These are meant to be clear specifications.
 4. The repository is `leanSpec` not `lean-spec`.
+
+## SSZ Type Design Patterns
+
+When creating SSZ types, follow these established patterns:
+
+### Domain-Specific Types (Preferred)
+- Use meaningful names that describe the purpose: `JustificationValidators`, `HistoricalBlockHashes`, `Attestations`
+- Define domain-specific types in modular structure (see Architecture section below)
+- Avoid generic names with numbers like `Bitlist68719476736` or `SignedVoteList4096`
+
+### SSZType vs SSZModel Design Decision
+
+**SSZType (IS-A pattern)**: Use for types that *are* data
+- Primitive scalars: `Uint64`, `Boolean`, `Bytes32`
+- These inherit directly from their underlying Python types
+- Example: `Uint64(42)` *is* the integer 42 with SSZ serialization
+
+**SSZModel (HAS-A pattern)**: Use for types that *have* data
+- Collections: `SSZList`, `SSZVector`, bitfields
+- Containers: `State`, `Block`, etc.
+- These use Pydantic models with a `data` field for contents
+- Example: `MyList(data=[1, 2, 3])` *has* a list of data with SSZ serialization
+
+**Key principle**: If the type conceptually *holds* or *contains* other data, use SSZModel for consistent validation and immutability.
+
+### Modular Architecture
+
+Containers should be organized into modules with clear separation:
+
+```
+src/lean_spec/subspecs/containers/
+├── state/
+│   ├── __init__.py      # Exports State and related types
+│   ├── state.py         # Main State container class
+│   └── types.py         # State-specific types: JustifiedSlots, HistoricalBlockHashes, etc.
+├── block/
+│   ├── __init__.py      # Exports Block classes
+│   ├── block.py         # Main Block container classes
+│   └── types.py         # Block-specific types: Attestations, etc.
+└── ...
+```
+
+**Key principles:**
+- **Base types** (BaseBitlist, SSZList, etc.) stay in general scope (`src/lean_spec/types/`)
+- **Spec-specific types** go in their respective modules (`state/types.py`, `block/types.py`)
+- **Public API** exposed through `__init__.py` files for backward compatibility
+- **Domain-specific types** defined close to where they're used
+
+### Examples
+
+**Good domain-specific types:**
+```python
+# In state/types.py
+HISTORICAL_ROOTS_LIMIT = 262144
+
+class JustificationValidators(BaseBitlist):
+    """Bitlist for tracking validator justifications."""
+    LIMIT = HISTORICAL_ROOTS_LIMIT * HISTORICAL_ROOTS_LIMIT
+
+# In block/types.py
+class Attestations(SSZList):
+    """List of signed votes (attestations) included in a block."""
+    ELEMENT_TYPE = SignedVote
+    LIMIT = 4096  # VALIDATOR_REGISTRY_LIMIT
+```
+
+**Avoid generic types:**
+```python
+# Don't do this:
+class Bitlist68719476736(BaseBitlist): ...
+class SignedVoteList4096(SSZList): ...
+```
+
+### API Compatibility
+
+When refactoring, maintain backward compatibility:
+- Keep existing import paths working through `__init__.py` exports
+- Preserve method signatures and behavior

pyproject.toml

@@ -91,6 +91,7 @@ plugins = ["pydantic.mypy"]
 strict = true
 warn_return_any = true
 warn_unused_configs = true
+warn_unused_ignores = true
 no_implicit_reexport = true
 namespace_packages = false
 explicit_package_bases = false

src/lean_spec/subspecs/containers/block/__init__.py

@@ -0,0 +1,12 @@
+"""Block containers and related types for the Lean Ethereum consensus specification."""
+
+from .block import Block, BlockBody, BlockHeader, SignedBlock
+from .types import Attestations
+
+__all__ = [
+    "Block",
+    "BlockBody",
+    "BlockHeader",
+    "SignedBlock",
+    "Attestations",
+]

…c/lean_spec/subspecs/containers/block.py …_spec/subspecs/containers/block/block.pysrc/lean_spec/subspecs/containers/block.py renamed to src/lean_spec/subspecs/containers/block/block.py src/lean_spec/subspecs/containers/block.py renamed to src/lean_spec/subspecs/containers/block/block.py

@@ -1,17 +1,16 @@
-"""Block Containers."""
+"""Block Containers for the Lean Ethereum consensus specification."""
 
 from lean_spec.subspecs.containers.slot import Slot
-from lean_spec.types import Bytes32, List, Uint64
+from lean_spec.types import Bytes32, Uint64
 from lean_spec.types.container import Container
 
-from ..chain import config
-from .vote import SignedVote
+from .types import Attestations
 
 
 class BlockBody(Container):
     """The body of a block, containing payload data."""
 
-    attestations: List[SignedVote, config.VALIDATOR_REGISTRY_LIMIT.as_int()]  # type: ignore
+    attestations: Attestations
     """
     A list of votes included in the block.
 
@@ -32,14 +31,14 @@ class BlockHeader(Container):
     """The root of the parent block."""
 
     state_root: Bytes32
-    """The root of the state after processing the block."""
+    """The root of the state after applying transactions in this block."""
 
     body_root: Bytes32
-    """The root of the block's body."""
+    """The root of the block body."""
 
 
 class Block(Container):
-    """Represents a single block in the chain."""
+    """A complete block including header and body."""
 
     slot: Slot
     """The slot in which the block was proposed."""
@@ -61,11 +60,10 @@ class SignedBlock(Container):
     """A container for a block and the proposer's signature."""
 
     message: Block
-    """The block data that was signed."""
+    """The block being signed."""
 
     signature: Bytes32
     """
     The proposer's signature of the block message.
-
     Note: Bytes32 is a placeholder; the actual signature is much larger.
     """

src/lean_spec/subspecs/containers/block/types.py

@@ -0,0 +1,13 @@
+"""Block-specific SSZ types for the Lean Ethereum consensus specification."""
+
+from lean_spec.types import SSZList
+
+from ...chain.config import VALIDATOR_REGISTRY_LIMIT
+from ..vote import SignedVote
+
+
+class Attestations(SSZList):
+    """List of signed votes (attestations) included in a block."""
+
+    ELEMENT_TYPE = SignedVote
+    LIMIT = int(VALIDATOR_REGISTRY_LIMIT)