eth-ssz-specs 0.0.1.dev1__tar.gz → 0.0.1.dev2__tar.gz

{eth_ssz_specs-0.0.1.dev1 → eth_ssz_specs-0.0.1.dev2}/CONTRIBUTING.md

@@ -46,7 +46,7 @@ If anything fails before the release job, no tag was created: fix and re-dispatc
 only the PyPI publish fails, re-run the failed job on the same run instead.
 
 Before the first release: add a PyPI trusted publisher (project `eth-ssz-specs`, owner
-`leanEthereum`, repository `ssz-specs`, workflow `release.yaml`, environment `pypi`)
+`ethereum`, repository `ssz-specs`, workflow `release.yaml`, environment `pypi`)
 and create the `pypi` environment in the GitHub repository settings.
 
 Reproduce the artifacts locally with `just build` and `just pack-fixtures <tag>`

{eth_ssz_specs-0.0.1.dev1 → eth_ssz_specs-0.0.1.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eth-ssz-specs
-Version: 0.0.1.dev1
+Version: 0.0.1.dev2
 Summary: Ethereum SSZ (Simple Serialize) specification and Merkleization
 Project-URL: Homepage, https://github.com/ethereum/ssz-specs
 Project-URL: Source, https://github.com/ethereum/ssz-specs
@@ -65,7 +65,7 @@ implementations can run to ensure compliance with the specifications.
 ## Releases
 
 Each release ships the `eth-ssz-specs` package on PyPI and the reference tests on the
-[releases page](https://github.com/leanEthereum/ssz-specs/releases), both built from
+[releases page](https://github.com/ethereum/ssz-specs/releases), both built from
 the tagged commit.
 
 ```bash
@@ -74,8 +74,8 @@ pip install eth-ssz-specs
 
 ```bash
 TAG=v0.1.0
-curl -sSLO "https://github.com/leanEthereum/ssz-specs/releases/download/$TAG/ssz-test-vectors-$TAG.tar.gz"
-curl -sSLO "https://github.com/leanEthereum/ssz-specs/releases/download/$TAG/ssz-test-vectors-$TAG.tar.gz.sha256"
+curl -sSLO "https://github.com/ethereum/ssz-specs/releases/download/$TAG/ssz-test-vectors-$TAG.tar.gz"
+curl -sSLO "https://github.com/ethereum/ssz-specs/releases/download/$TAG/ssz-test-vectors-$TAG.tar.gz.sha256"
 sha256sum --check "ssz-test-vectors-$TAG.tar.gz.sha256"
 tar -xzf "ssz-test-vectors-$TAG.tar.gz"   # extracts fixtures/
 ```

{eth_ssz_specs-0.0.1.dev1 → eth_ssz_specs-0.0.1.dev2}/README.md

@@ -24,7 +24,7 @@ implementations can run to ensure compliance with the specifications.
 ## Releases
 
 Each release ships the `eth-ssz-specs` package on PyPI and the reference tests on the
-[releases page](https://github.com/leanEthereum/ssz-specs/releases), both built from
+[releases page](https://github.com/ethereum/ssz-specs/releases), both built from
 the tagged commit.
 
 ```bash
@@ -33,8 +33,8 @@ pip install eth-ssz-specs
 
 ```bash
 TAG=v0.1.0
-curl -sSLO "https://github.com/leanEthereum/ssz-specs/releases/download/$TAG/ssz-test-vectors-$TAG.tar.gz"
-curl -sSLO "https://github.com/leanEthereum/ssz-specs/releases/download/$TAG/ssz-test-vectors-$TAG.tar.gz.sha256"
+curl -sSLO "https://github.com/ethereum/ssz-specs/releases/download/$TAG/ssz-test-vectors-$TAG.tar.gz"
+curl -sSLO "https://github.com/ethereum/ssz-specs/releases/download/$TAG/ssz-test-vectors-$TAG.tar.gz.sha256"
 sha256sum --check "ssz-test-vectors-$TAG.tar.gz.sha256"
 tar -xzf "ssz-test-vectors-$TAG.tar.gz"   # extracts fixtures/
 ```

{eth_ssz_specs-0.0.1.dev1 → eth_ssz_specs-0.0.1.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "eth-ssz-specs"
-version = "0.0.1.dev1"
+version = "0.0.1.dev2"
 description = "Ethereum SSZ (Simple Serialize) specification and Merkleization"
 readme = "README.md"
 authors = [

{eth_ssz_specs-0.0.1.dev1 → eth_ssz_specs-0.0.1.dev2}/src/ssz/__init__.py

@@ -24,7 +24,7 @@ from ssz.exceptions import (
     SSZUnionOptionsError,
     SSZValueError,
 )
-from ssz.merkleization import ZERO_ROOT, Chunk, Root
+from ssz.merkleization import ZERO_ROOT, Chunk, Root, hash_tree_root
 from ssz.proofs import (
     ACTIVE_FIELDS_KEY,
     LENGTH_KEY,
@@ -110,6 +110,7 @@ __all__ = [
     "gindex_length",
     "gindex_parent",
     "gindex_sibling",
+    "hash_tree_root",
     "item_length",
     "verify_merkle_multiproof",
     "verify_merkle_proof",

{eth_ssz_specs-0.0.1.dev1 → eth_ssz_specs-0.0.1.dev2}/src/ssz/bitfields.py

@@ -72,7 +72,7 @@ class BitVector(SSZCollection[Boolean]):
         """
         super().__pydantic_init_subclass__(**kwargs)
 
-        if not hasattr(cls, "LENGTH"):
+        if cls.LENGTH is None:
             return
 
         length = cls.LENGTH
@@ -100,7 +100,7 @@ class BitVector(SSZCollection[Boolean]):
     def _coerce_and_validate(cls, bits_input: Any) -> list[Boolean]:
         """Enforce the exact bit count and coerce inputs into booleans."""
         # Subclasses must declare LENGTH before any instances can be validated.
-        if not hasattr(cls, "LENGTH"):
+        if cls.LENGTH is None:
             raise SSZDefinitionError(cls.__name__, "LENGTH")
 
         # Materialize generic iterables into a tuple so the length check works.
@@ -264,14 +264,14 @@ class _SSZBitList(SSZCollection[Boolean]):
 
     def append(self, value: Boolean) -> None:
         """Add one bit at the end, validating it and the resulting length."""
-        self._require_mutable()
+        self._begin_mutation()
         element = self._validate_element(value)
         self._validate_length(len(self.data) + 1)
         cast("list[Boolean]", self.data).append(element)
 
     def pop(self) -> Boolean:
         """Remove and return the last bit, validating the resulting length."""
-        self._require_mutable()
+        self._begin_mutation()
         self._validate_length(len(self.data) - 1)
         return cast("list[Boolean]", self.data).pop()
 
@@ -495,7 +495,7 @@ class BitList(_SSZBitList):
     def _coerce_and_validate(cls, bits_input: Any) -> list[Boolean]:
         """Enforce the maximum bit count and coerce inputs into booleans."""
         # Subclasses must declare LIMIT before any instances can be validated.
-        if not hasattr(cls, "LIMIT"):
+        if cls.LIMIT is None:
             raise SSZDefinitionError(cls.__name__, "LIMIT")
 
         # Accept the natural input shapes:

{eth_ssz_specs-0.0.1.dev1 → eth_ssz_specs-0.0.1.dev2}/src/ssz/boolean.py

@@ -18,7 +18,7 @@ class Boolean(int, SSZType):
     - Inherits from int so true/false work natively in truthiness checks.
     - Arithmetic (+ - * /) is disabled to prevent ambiguous operations.
     - Bitwise ops (& | ^) reject operands of any other type.
-    - Equality rejects comparisons with anything but another boolean.
+    - Equality rejects comparisons with anything but another boolean, and hashing agrees.
 
     Wire format:
 
@@ -211,7 +211,15 @@ class Boolean(int, SSZType):
         return self.__xor__(other)
 
     def __eq__(self, other: object) -> bool:
-        """Strict equality — only another boolean compares; anything else raises."""
+        """
+        Strict equality — only another boolean compares; anything else raises.
+
+        Invariant: the bit is the whole of the value, so the hash below is the bit's hash.
+        A raw bool is still refused, which is the point of wrapping the bit at all.
+
+        Raises:
+            TypeError: If other is not a Boolean.
+        """
         if not isinstance(other, Boolean):
             raise TypeError(
                 f"Unsupported operand type(s) for ==: "
@@ -225,6 +233,9 @@ class Boolean(int, SSZType):
 
         Defined explicitly because the parent class's not-equal would otherwise
         bypass the strict equality above.
+
+        Raises:
+            TypeError: If other is not a Boolean.
         """
         if not isinstance(other, Boolean):
             raise TypeError(
@@ -241,9 +252,12 @@ class Boolean(int, SSZType):
         """Return the user-facing form: True or False."""
         return str(bool(self))
 
-    def __hash__(self) -> int:
-        """Return a hash distinct from the equivalent raw bool, matching strict equality."""
-        return hash((type(self), int(self)))
+    # A boolean hashes as the bit it holds, because equality compares the bit alone.
+    # Defining equality would otherwise clear the inherited hash, so it is spelled out.
+    #
+    # A raw bool now shares a bucket, so a membership test reaches the refusal instead of
+    # answering False from an empty one.
+    __hash__ = int.__hash__
 
 
 Bit: TypeAlias = Boolean

{eth_ssz_specs-0.0.1.dev1 → eth_ssz_specs-0.0.1.dev2}/src/ssz/byte_arrays.py

@@ -13,7 +13,7 @@ Both flavors serialize as the raw bytes themselves — no length prefix, no deli
 
 from collections.abc import Iterable, Sequence
 from enum import Enum
-from typing import IO, Any, ClassVar, Self, override
+from typing import IO, TYPE_CHECKING, Any, ClassVar, Self, override
 
 from pydantic import Field, field_serializer, field_validator
 from pydantic.annotated_handlers import GetCoreSchemaHandler
@@ -49,7 +49,7 @@ class ByteVector(bytes, SSZType):
 
     - Inherits from bytes so the instance is usable wherever a bytes value is expected.
     - Subclasses pin the byte count by setting the class-level length.
-    - Equality is strict — only another byte-array instance compares.
+    - Equality relates a type only to its ancestors and descendants; hashing agrees.
 
     The spec reads a fixed byte array as a vector of single bytes, so its default is every
     byte zero.
@@ -110,7 +110,7 @@ class ByteVector(bytes, SSZType):
             SSZValueError: If the coerced byte count differs from the declared length.
             TypeError: If a value is passed that no coercion accepts.
         """
-        if not hasattr(cls, "LENGTH"):
+        if cls.LENGTH is None:
             raise SSZDefinitionError(cls.__name__, "LENGTH")
 
         # An omitted value is the default, which is every byte zero.
@@ -130,6 +130,25 @@ class ByteVector(bytes, SSZType):
             raise SSZLengthError(cls.__name__, cls.LENGTH, len(coerced_bytes), unit="bytes")
         return super().__new__(cls, coerced_bytes)
 
+    @classmethod
+    def _trusted(cls, data: bytes) -> Self:
+        """
+        Wrap bytes of an already-established length, skipping every check.
+
+        # Safety
+
+        The byte count must follow from how the value was built, never from a caller.
+        A wrong width yields an instance.
+        It merkleizes to a wrong root rather than failing.
+
+        Args:
+            data: Exactly the declared number of bytes.
+
+        Returns:
+            An instance wrapping those bytes, unvalidated.
+        """
+        return bytes.__new__(cls, data)
+
     @classmethod
     def zero(cls) -> Self:
         """Return a new instance filled with zero bytes, which is also the default."""
@@ -176,8 +195,8 @@ class ByteVector(bytes, SSZType):
         serialized_bytes = stream.read(scope)
         if len(serialized_bytes) != scope:
             raise SSZScopeError(cls.__name__, scope, len(serialized_bytes))
-        # Length already verified — bypass __new__'s coerce + revalidation.
-        return bytes.__new__(cls, serialized_bytes)
+        # The read delivered exactly the checked count, which the guard above pinned.
+        return cls._trusted(serialized_bytes)
 
     @override
     def encode_bytes(self) -> bytes:
@@ -246,8 +265,34 @@ class ByteVector(bytes, SSZType):
         return f"{type_name}({self.hex()})"
 
     def __eq__(self, other: object) -> bool:
-        """Strict equality — only another byte-array instance compares; anything else raises."""
-        if not isinstance(other, ByteVector):
+        r"""
+        Equality between two byte arrays whose types are related by inheritance.
+
+        One of the two types must derive from the other, and nothing but a byte array may
+        meet one at all. A root is declared a kind of chunk so it is usable where a chunk
+        is expected, and this comparison honours that:
+
+            x = b"\x11" * 32
+
+            Root(x) == Chunk(x)    ->  True     a root is a kind of chunk
+            Bytes32(x) == Root(x)  ->  refused  siblings, neither derives from the other
+            Bytes32(x) == x        ->  refused  raw bytes are not a byte array at all
+
+        Invariant: whenever this returns True, __hash__ agrees. Python requires that of
+        every type, because dict and set find a value by its hash before they compare
+        it. That requirement is what fixes the hash below: Root(x) and Chunk(x) are one
+        value here, so no hash that named the concrete type could keep step.
+
+        Args:
+            other: The value to compare against.
+
+        Raises:
+            TypeError: If other is not a byte array, or is one whose type is a sibling
+                of this one rather than an ancestor or a descendant.
+        """
+        if not isinstance(other, ByteVector) or not (
+            isinstance(other, type(self)) or isinstance(self, type(other))
+        ):
             raise TypeError(
                 f"Unsupported operand type(s) for ==: "
                 f"'{type(self).__name__}' and '{type(other).__name__}'"
@@ -256,21 +301,31 @@ class ByteVector(bytes, SSZType):
 
     def __ne__(self, other: object) -> bool:
         """
-        Strict inequality — only another byte-array instance compares; anything else raises.
+        Inequality under the same relation as equality; anything else raises.
 
         Defined explicitly because the parent bytes class has its own not-equal
-        that would otherwise bypass the strict type contract.
+        that would otherwise bypass the type rule above.
+
+        Raises:
+            TypeError: If other is not a byte array, or is one whose type is a sibling
+                of this one rather than an ancestor or a descendant.
         """
-        if not isinstance(other, ByteVector):
+        if not isinstance(other, ByteVector) or not (
+            isinstance(other, type(self)) or isinstance(self, type(other))
+        ):
             raise TypeError(
                 f"Unsupported operand type(s) for !=: "
                 f"'{type(self).__name__}' and '{type(other).__name__}'"
             )
         return bytes.__ne__(self, other)
 
-    def __hash__(self) -> int:
-        """Return a hash distinct from raw bytes — matches the strict equality contract."""
-        return hash((type(self), bytes(self)))
+    # A byte array hashes as the bytes it holds, because equality calls a root and a chunk
+    # of the same bytes one value, which leaves the concrete type no room in the hash.
+    #
+    # Two types the comparison refuses to relate now share a bucket when their bytes agree,
+    # so a lookup reaches the refusal instead of missing in silence. When the bytes differ
+    # so do the hashes, and absent is the right answer whatever the types were.
+    __hash__ = bytes.__hash__
 
 
 class ByteList(SSZCollection[int]):
@@ -279,7 +334,7 @@ class ByteList(SSZCollection[int]):
 
     - Subclasses pin the maximum byte count by setting the class-level limit.
     - Serialization writes the raw bytes; the length is recovered from the wrapping context.
-    - Equality is strict — only another byte-list instance compares.
+    - Equality relates a type only to its ancestors and descendants; hashing agrees.
 
     For example, a 4-byte payload under a limit of 10:
 
@@ -299,7 +354,7 @@ class ByteList(SSZCollection[int]):
     def _validate_byte_list_data(cls, value: Any) -> bytes:
         """Enforce the maximum byte count and coerce inputs into a plain bytes object."""
         # Subclasses must declare LIMIT before any instances can be validated.
-        if not hasattr(cls, "LIMIT"):
+        if cls.LIMIT is None:
             raise SSZDefinitionError(cls.__name__, "LIMIT")
 
         # Coerce the input first, then enforce the upper bound.
@@ -313,27 +368,46 @@ class ByteList(SSZCollection[int]):
         """Serialize the raw bytes to a 0x-prefixed hex string for JSON output."""
         return "0x" + value.hex()
 
+    def _store(self, working: bytearray) -> None:
+        """
+        Store mutated bytes, checking the byte count and nothing else.
+
+        Assigning to the field would re-coerce a payload that is already bytes.
+
+        Raises:
+            SSZLimitError: When the mutation leaves more bytes than the limit allows.
+        """
+        self._validate_length(len(working))
+        payload = bytes(working)
+        # A type checker reads this field through an inherited sequence declaration, so the
+        # assignment spelling is kept for it and the dictionary write for the runtime.
+        if not TYPE_CHECKING:
+            self.__dict__["data"] = payload
+            self.__pydantic_fields_set__.add("data")
+        else:  # pragma: no cover
+            self.data = payload
+
     @override
     def __setitem__(self, index: int | slice, value: int | Sequence[int]) -> None:
         """Replace the byte(s) at ``index``, revalidating the stored payload."""
-        self._require_mutable()
+        self._begin_mutation()
         working = bytearray(self.data)
         working[index] = value  # ty: ignore[invalid-assignment]
-        self.data = bytes(working)
+        self._store(working)
 
     def append(self, value: int) -> None:
         """Add one byte at the end, revalidating the stored payload."""
-        self._require_mutable()
+        self._begin_mutation()
         working = bytearray(self.data)
         working.append(value)
-        self.data = bytes(working)
+        self._store(working)
 
     def pop(self) -> int:
         """Remove and return the last byte, revalidating the stored payload."""
-        self._require_mutable()
+        self._begin_mutation()
         working = bytearray(self.data)
         last = working.pop()
-        self.data = bytes(working)
+        self._store(working)
         return last
 
     @classmethod
@@ -418,8 +492,25 @@ class ByteList(SSZCollection[int]):
         return f"{type_name}({self.data.hex()})"
 
     def __eq__(self, other: object) -> bool:
-        """Strict equality — only another byte-list instance compares; anything else raises."""
-        if not isinstance(other, ByteList):
+        """
+        Equality between two byte lists whose types are related by inheritance.
+
+        One of the two types must derive from the other, and nothing but a byte list may
+        meet one at all. Two unrelated limits are refused even when the payloads match,
+        because a payload under one limit is not the same value as under another.
+
+        Invariant: whenever this returns True, the hash agrees.
+
+        Args:
+            other: The value to compare against.
+
+        Raises:
+            TypeError: If other is not a byte list, or is one whose type is a sibling
+                of this one rather than an ancestor or a descendant.
+        """
+        if not isinstance(other, ByteList) or not (
+            isinstance(other, type(self)) or isinstance(self, type(other))
+        ):
             raise TypeError(
                 f"Unsupported operand type(s) for ==: "
                 f"'{type(self).__name__}' and '{type(other).__name__}'"
@@ -428,11 +519,17 @@ class ByteList(SSZCollection[int]):
 
     def __ne__(self, other: object) -> bool:
         """
-        Strict inequality — only another byte-list instance compares; anything else raises.
+        Inequality under the same relation as equality; anything else raises.
 
-        Mirrors the strict equality contract — both operators require a matching type.
+        Mirrors the equality contract — both operators apply one type rule.
+
+        Raises:
+            TypeError: If other is not a byte list, or is one whose type is a sibling
+                of this one rather than an ancestor or a descendant.
         """
-        if not isinstance(other, ByteList):
+        if not isinstance(other, ByteList) or not (
+            isinstance(other, type(self)) or isinstance(self, type(other))
+        ):
             raise TypeError(
                 f"Unsupported operand type(s) for !=: "
                 f"'{type(self).__name__}' and '{type(other).__name__}'"
@@ -440,8 +537,8 @@ class ByteList(SSZCollection[int]):
         return self.data != other.data
 
     def __hash__(self) -> int:
-        """Return a hash that ties the value to its concrete type."""
-        return hash((type(self), self.data))
+        """Return the hash of the payload alone — the one thing equality above compares."""
+        return hash(self.data)
 
     def hex(self) -> str:
         """Return the hexadecimal string representation of the underlying bytes."""

{eth_ssz_specs-0.0.1.dev1 → eth_ssz_specs-0.0.1.dev2}/src/ssz/collections.py

@@ -109,19 +109,25 @@ def _coerce_elements(element_type: type[SSZType], elements: Sequence[Any]) -> li
     - Ancestor-class values go through the element type's constructor.
     - A coercion failure re-raises with the high-level expectation in the message.
     - The chained cause preserves the underlying coercion detail.
+
+    An element of exactly the declared class is settled first, before the ancestor test.
+    A class is a subclass of itself, so the test that order skips is one that could only
+    have passed. What changes is the cost of the common case: an identity check on two type
+    objects, rather than a walk of an abstract base class's registry.
     """
     coerced: list[SSZType] = []
     for element in elements:
-        if not issubclass(element_type, type(element)):
-            raise SSZTypeMismatch(element_type.__name__, type(element))
-        if type(element) is element_type:
+        element_class = type(element)
+        if element_class is element_type:
             coerced.append(element)
             continue
+        if not issubclass(element_type, element_class):
+            raise SSZTypeMismatch(element_type.__name__, element_class)
         try:
             coerced.append(cast(Any, element_type)(element))
         except (SSZTypeError, SSZValueError, TypeError, ValueError) as exception:
             raise SSZTypeMismatch(
-                element_type.__name__, type(element), detail=str(exception)
+                element_type.__name__, element_class, detail=str(exception)
             ) from exception
     return coerced
 
@@ -343,18 +349,28 @@ class Vector[T: SSZType](_SSZSequence[T]):
         """
         Give the elements their default, which is the element default at every position.
 
-        Each element is built when the elements are left out, never shared: one instance
-        placed at every position would alias, and an element is mutable.
+        One instance is shared across every position when the element type cannot be
+        mutated, and built per position otherwise, since two positions holding one mutable
+        element would alias.
         """
         super().__pydantic_init_subclass__(**kwargs)
 
         # A shape that declared neither keeps its inherited default, and fails its own
         # declaration check instead.
-        if not (hasattr(cls, "ELEMENT_TYPE") and hasattr(cls, "LENGTH")):
+        if not hasattr(cls, "ELEMENT_TYPE") or cls.LENGTH is None:
             return
 
         element_type, length = cls.ELEMENT_TYPE, cls.LENGTH
-        cls.model_fields["data"].default_factory = lambda: [element_type() for _ in range(length)]
+        # A uint, a boolean and a fixed byte array each subclass an immutable builtin, so
+        # no position can alter what another holds. The bitfield default already shares one
+        # boolean on that argument, and it holds for every such element type.
+        if issubclass(element_type, (int, bytes)):
+            shared = element_type()
+            cls.model_fields["data"].default_factory = lambda: [shared] * length
+        else:
+            cls.model_fields["data"].default_factory = lambda: [
+                element_type() for _ in range(length)
+            ]
         cls.model_rebuild(force=True)
 
     @field_validator("data", mode="before")
@@ -374,7 +390,7 @@ class Vector[T: SSZType](_SSZSequence[T]):
         The chained cause preserves the underlying coercion detail.
         """
         # Subclasses must declare both annotations before any instance can validate.
-        if not hasattr(cls, "ELEMENT_TYPE") or not hasattr(cls, "LENGTH"):
+        if not hasattr(cls, "ELEMENT_TYPE") or cls.LENGTH is None:
             raise SSZDefinitionError(cls.__name__, "ELEMENT_TYPE and LENGTH")
 
         # Reject strings and non-iterables, then materialize into a sequence.
@@ -501,14 +517,14 @@ class _SSZList[T: SSZType](_SSZSequence[T]):
 
     def append(self, value: T) -> None:
         """Add one element at the end, validating it and the resulting length."""
-        self._require_mutable()
+        self._begin_mutation()
         element = self._validate_element(value)
         self._validate_length(len(self.data) + 1)
         cast("list[T]", self.data).append(element)
 
     def pop(self) -> T:
         """Remove and return the last element, validating the resulting length."""
-        self._require_mutable()
+        self._begin_mutation()
         self._validate_length(len(self.data) - 1)
         return cast("list[T]", self.data).pop()
 
@@ -653,7 +669,14 @@ class List[T: SSZType](_SSZList[T]):
     - Variable-size elements use an offset table that also reveals the count.
 
     The hash tree root mixes in the element count alongside the chunked data.
-    Two lists with identical contents but different LIMITs hash differently.
+
+    A declared capacity reaches the root only through the width of the tree it bounds.
+
+    - That width is the next power of two at or above the capacity counted in chunks.
+    - Two capacities that round to the same width bound the same tree.
+    - The same contents then root identically under both.
+    - Eight-byte elements pack four to a chunk, so a capacity of three roots as four does.
+    - So do twelve and sixteen, whose three chunks and four fill one four-leaf tree.
 
     Subclasses declare LIMIT directly in the class body.
     The element type is inferred from the generic parameter.
@@ -692,7 +715,7 @@ class List[T: SSZType](_SSZList[T]):
         The chained cause preserves the underlying coercion detail.
         """
         # Subclasses must declare both annotations before any instance can validate.
-        if not hasattr(cls, "ELEMENT_TYPE") or not hasattr(cls, "LIMIT"):
+        if not hasattr(cls, "ELEMENT_TYPE") or cls.LIMIT is None:
             raise SSZDefinitionError(cls.__name__, "ELEMENT_TYPE and LIMIT")
 
         # Reject strings and non-iterables, then materialize into a sequence.

{eth_ssz_specs-0.0.1.dev1 → eth_ssz_specs-0.0.1.dev2}/src/ssz/container.py

@@ -11,6 +11,7 @@ Both encode identically: fixed-size fields inline, variable-size fields behind o
 """
 
 import io
+from functools import cache
 from itertools import pairwise
 from typing import IO, Any, ClassVar, Final, Self, override
 
@@ -85,10 +86,7 @@ def active_fields(width: int, gaps: tuple[int, ...] = ()) -> tuple[int, ...]:
     # Narrow before anything reads the value.
     #
     # A width may be written with a uint.
-    # A uint refuses a plain integer operand.
-    # The comparison below would therefore raise rather than answer.
-    # A uint left among the positions would also miss the plain position it names.
-    # The two hash apart.
+    # Narrowing keeps the positions below plain, as well as the messages naming them.
     width = int(width)
     if width < 1:
         raise SSZValueError(f"a layout holds at least one position, got a width of {width}")
@@ -136,10 +134,7 @@ class _SSZContainer(SSZModel):
 
     def __hash__(self) -> int:
         """Hash by Merkle tree root — equal containers hash equally."""
-        # Deferred import: the merkleization module imports the SSZ types.
-        from ssz.merkleization import hash_tree_root
-
-        return hash(hash_tree_root(self))
+        return hash(self.hash_tree_root())
 
     @model_validator(mode="wrap")
     @classmethod
@@ -220,8 +215,7 @@ class _SSZContainer(SSZModel):
         bytes_read = 0
 
         # Phase 1: each slot is either the field itself or an offset to its tail payload.
-        for name, field_definition in cls.model_fields.items():
-            field_type: type[SSZType] = field_definition.annotation
+        for name, field_type in _field_types(cls):
             if field_type.is_fixed_size():
                 width = field_type.get_byte_length()
                 fields[name] = field_type.deserialize(stream, width)
@@ -394,3 +388,18 @@ class ProgressiveContainer(_SSZContainer):
                 f"the layout sets {active_count} positions, "
                 f"and the struct declares {len(cls.model_fields)}",
             )
+
+
+type _FieldType = tuple[str, type[SSZType]]
+"""One field: its name and the type it declares."""
+
+
+@cache
+def _field_types(cls: type[_SSZContainer]) -> tuple[_FieldType, ...]:
+    """
+    Each field's declared type, in the declaration order the wire format follows.
+
+    Only what the declaration settles is kept. A width is asked of the type each time,
+    because the attributes a type derives one from stay writable for as long as the type does.
+    """
+    return tuple((name, field.annotation) for name, field in cls.model_fields.items())

{eth_ssz_specs-0.0.1.dev1 → eth_ssz_specs-0.0.1.dev2}/src/ssz/exceptions.py

@@ -43,10 +43,10 @@ class SSZTypeMismatch(SSZTypeError):  # noqa: N818
 
 
 class SSZDefinitionError(SSZTypeError):
-    """An SSZ subclass omits an attribute its base needs to operate."""
+    """An SSZ subclass declares its attributes in a way its base cannot operate on."""
 
     def __init__(self, type_name: str, requirement: str) -> None:
-        """Record the type and the attribute it failed to declare."""
+        """Record the type and what its declaration failed to satisfy."""
         self.type_name = type_name
         self.requirement = requirement
         super().__init__(f"{type_name} must define {requirement}")