refactor(ssz): move hex-string parsing into BaseBytes and Container schemas (leanEthereum#795)

Four field validators across the codebase each rebuilt the same
"if str, decode hex" logic on top of a Pydantic field. Promote the
parsing to the schema layer so it happens once per type.

- BaseBytes.__get_pydantic_core_schema__: add a str branch that
  routes any string through the constructor.
- Container: add a model_validator(mode="wrap") that decodes a hex
  string input via from_hex, with other shapes passing through
  field-by-field validation.

Removes:
- validator/registry.py parse_pubkey — covered by the Bytes52 schema.
- xmss/containers.py _decode_public_key, _decode_secret_key — covered
  by the Container wrap validator.

Simplifies:
- genesis/config.py keeps only the YAML quirk where an unquoted
  0x-prefixed value is parsed as an int.

Adds TestHexStringValidator in test_container.py covering every
branch of the new wrap validator: hex success paths with prefix and
case variants, empty-hex edge case, dict and instance pass-through,
the class-name-tagged error on wrong length, and the nested-container
field case.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: tcoratger

src/lean_spec/node/genesis/config.py

@@ -36,15 +36,16 @@ class GenesisValidatorEntry(StrictBaseModel):
 
     @field_validator("attestation_pubkey", "proposal_pubkey", mode="before")
     @classmethod
-    def parse_hex_pubkey(cls, v: Any) -> Bytes52:
+    def _yaml_int_to_hex(cls, v: Any) -> Any:
         """
-        Convert hex strings or integers to validated Bytes52 pubkeys.
+        Re-encode integer inputs as hex strings before standard validation.
 
-        YAML parsers may interpret 0x-prefixed values as integers.
+        A YAML parser may interpret an unquoted 0x-prefixed value as an int.
+        Converting it back to a hex string lets the byte-array schema handle it.
         """
         if isinstance(v, int):
-            v = f"0x{v:0104x}"
-        return Bytes52(v)
+            return f"0x{v:0104x}"
+        return v
 
 
 class GenesisConfig(StrictBaseModel):

src/lean_spec/node/validator/registry.py

@@ -30,7 +30,7 @@
 from pathlib import Path
 
 import yaml
-from pydantic import BaseModel, field_validator
+from pydantic import BaseModel
 
 from lean_spec.spec.crypto.xmss import SecretKey
 from lean_spec.spec.forks import ValidatorIndex, ValidatorIndices
@@ -60,21 +60,6 @@ class ValidatorManifestEntry(BaseModel):
     proposal_privkey_file: str
     """Filename of the proposal private key file."""
 
-    @field_validator("attestation_pubkey_hex", "proposal_pubkey_hex", mode="before")
-    @classmethod
-    def parse_pubkey(cls, v: object) -> Bytes52:
-        """
-        Convert hex strings to validated Bytes52 pubkeys.
-
-        Only accepts hex strings and existing Bytes52 instances.
-        Integers and other types are rejected.
-        """
-        if isinstance(v, Bytes52):
-            return v
-        if isinstance(v, str):
-            return Bytes52(v)
-        raise TypeError(f"Expected hex string or Bytes52, got {type(v).__name__}")
-
 
 class ValidatorManifest(BaseModel):
     """

src/lean_spec/spec/crypto/xmss/containers.py

@@ -2,13 +2,12 @@
 
 from typing import override
 
-from pydantic import field_serializer, field_validator, model_serializer
+from pydantic import field_serializer, model_serializer
 
 from lean_spec.base import StrictBaseModel
 from lean_spec.spec.forks.lstar.containers import Slot
 from lean_spec.spec.ssz import Uint64
 from lean_spec.spec.ssz.container import Container
-from lean_spec.spec.ssz.exceptions import SSZError
 
 from .constants import TARGET_CONFIG
 from .merkle import HashSubTree
@@ -143,34 +142,6 @@ class KeyPair(StrictBaseModel):
     secret_key: SecretKey
     """Secret key."""
 
-    @field_validator("public_key", mode="before")
-    @classmethod
-    def _decode_public_key(cls, value: object) -> object:
-        """Decode hex strings to a public key.
-
-        Other input shapes pass through unchanged.
-        """
-        if not isinstance(value, str):
-            return value
-        try:
-            return PublicKey.from_hex(value)
-        except SSZError as err:
-            raise ValueError(f"invalid public key hex: {err}") from err
-
-    @field_validator("secret_key", mode="before")
-    @classmethod
-    def _decode_secret_key(cls, value: object) -> object:
-        """Decode hex strings to a secret key.
-
-        Other input shapes pass through unchanged.
-        """
-        if not isinstance(value, str):
-            return value
-        try:
-            return SecretKey.from_hex(value)
-        except SSZError as err:
-            raise ValueError(f"invalid secret key hex: {err}") from err
-
     @field_serializer("public_key", "secret_key", when_used="json")
     def _encode_hex(self, value: PublicKey | SecretKey) -> str:
         """Emit each half as plain hex in JSON mode only."""

src/lean_spec/spec/ssz/byte_arrays.py

@@ -159,30 +159,41 @@ def __get_pydantic_core_schema__(
 
         - Already-typed instances pass through.
         - Plain bytes inputs go through length-checked validation, then get wrapped.
+        - Hex string inputs (with an optional 0x prefix) go through the constructor.
         - JSON serialization converts the bytes to a 0x-prefixed hex string.
         """
-        # Validator that wraps a verified bytes object into a typed instance.
-        from_bytes_validator = core_schema.no_info_plain_validator_function(cls)
+        # Shared validator that runs the constructor on a verified input.
+        # The constructor handles bytes, bytearray, hex strings, or iterables of ints.
+        # It also enforces the declared length.
+        from_input_validator = core_schema.no_info_plain_validator_function(cls)
 
-        # Two-step input validation:
-        #
-        #   - bytes_schema enforces the exact declared length.
-        #   - wrapping validator turns the validated bytes into a typed instance.
-        python_schema = core_schema.chain_schema(
+        # Bytes path enforces the exact declared length, then wraps into a typed instance.
+        bytes_path = core_schema.chain_schema(
             [
                 core_schema.bytes_schema(min_length=cls.LENGTH, max_length=cls.LENGTH),
-                from_bytes_validator,
+                from_input_validator,
+            ]
+        )
+
+        # Hex string path routes any string through the constructor.
+        # The constructor strips an optional 0x prefix, decodes hex, and length-checks.
+        str_path = core_schema.chain_schema(
+            [
+                core_schema.str_schema(),
+                from_input_validator,
             ]
         )
 
-        # Final union accepts either branch and serializes back to a 0x-prefixed hex string:
+        # Final union accepts any branch and serializes back to a 0x-prefixed hex string:
         #
         #   - Branch 1: input is already a typed instance, pass through.
         #   - Branch 2: input is bytes that need length-checking and wrapping.
+        #   - Branch 3: input is a hex string that goes through the constructor.
         return core_schema.union_schema(
             [
                 core_schema.is_instance_schema(cls),
-                python_schema,
+                bytes_path,
+                str_path,
             ],
             serialization=core_schema.plain_serializer_function_ser_schema(
                 lambda x: "0x" + x.hex()

src/lean_spec/spec/ssz/container.py

@@ -2,16 +2,35 @@
 
 import io
 from itertools import pairwise
-from typing import IO, Self, override
+from typing import IO, Any, Self, override
 
-from .exceptions import SSZSerializationError, SSZTypeError
+from pydantic import model_validator
+from pydantic.functional_validators import ModelWrapValidatorHandler
+
+from .exceptions import SSZError, SSZSerializationError, SSZTypeError
 from .ssz_base import BYTES_PER_LENGTH_OFFSET, SSZModel, SSZType
 from .uint import Uint32
 
 
 class Container(SSZModel):
     """Ordered struct of named heterogeneous SSZ fields."""
 
+    @model_validator(mode="wrap")
+    @classmethod
+    def _accept_hex_string(cls, value: Any, handler: ModelWrapValidatorHandler[Self]) -> Self:
+        """
+        Reconstruct the container from a hex-encoded SSZ payload.
+
+        - Other input shapes pass through to field-by-field validation.
+        - Hex strings accept an optional 0x prefix.
+        """
+        if isinstance(value, str):
+            try:
+                return cls.from_hex(value)
+            except SSZError as err:
+                raise ValueError(f"invalid {cls.__name__} hex: {err}") from err
+        return handler(value)
+
     @classmethod
     @override
     def is_fixed_size(cls) -> bool:

tests/lean_spec/spec/crypto/xmss/test_containers.py

@@ -238,7 +238,7 @@ def test_keypair_decodes_public_and_secret_hex(keypair_a: KeyPair) -> None:
 
 def test_keypair_rejects_invalid_public_key_hex(keypair_a: KeyPair) -> None:
     """A malformed public-key hex string surfaces as a validation error."""
-    with pytest.raises(ValidationError, match="invalid public key hex"):
+    with pytest.raises(ValidationError, match="invalid PublicKey hex"):
         KeyPair.model_validate(
             {
                 "public_key": "deadbeef",
@@ -249,7 +249,7 @@ def test_keypair_rejects_invalid_public_key_hex(keypair_a: KeyPair) -> None:
 
 def test_keypair_rejects_invalid_secret_key_hex(keypair_a: KeyPair) -> None:
     """A malformed secret-key hex string surfaces as a validation error."""
-    with pytest.raises(ValidationError, match="invalid secret key hex"):
+    with pytest.raises(ValidationError, match="invalid SecretKey hex"):
         KeyPair.model_validate(
             {
                 "public_key": keypair_a.public_key.encode_bytes().hex(),

tests/lean_spec/spec/ssz/test_container.py

@@ -3,6 +3,7 @@
 import io
 
 import pytest
+from pydantic import ValidationError
 
 from lean_spec.spec.ssz.collections import SSZList
 from lean_spec.spec.ssz.container import Container
@@ -380,3 +381,50 @@ def test_from_hex_bad_hex_raises_value_error(self) -> None:
         """Non-hex characters surface a ValueError from the underlying parser."""
         with pytest.raises(ValueError, match="non-hexadecimal number"):
             OneByte.from_hex("zz")
+
+
+class TestHexStringValidator:
+    """Pydantic validation accepts hex strings via the wrap validator."""
+
+    @pytest.mark.parametrize(
+        "hex_input",
+        [
+            pytest.param("0xab", id="with_prefix"),
+            pytest.param("ab", id="without_prefix"),
+            pytest.param("0xAB", id="uppercase_with_prefix"),
+        ],
+    )
+    def test_validates_hex_string(self, hex_input: str) -> None:
+        """Pydantic validation tolerates the 0x prefix and mixed case alike."""
+        assert OneByte.model_validate(hex_input) == OneByte(a=Uint8(0xAB))
+
+    def test_validates_empty_string_as_empty_container(self) -> None:
+        """An empty hex string validates to a zero-field container."""
+        assert EmptyContainer.model_validate("") == EmptyContainer()
+
+    def test_dict_input_routes_to_field_validation(self) -> None:
+        """A dict input goes through field-by-field validation, not hex decoding."""
+        assert OneByte.model_validate({"a": Uint8(0xAB)}) == OneByte(a=Uint8(0xAB))
+
+    def test_instance_input_passes_through(self) -> None:
+        """An existing instance input is returned unchanged."""
+        instance = OneByte(a=Uint8(0xAB))
+        assert OneByte.model_validate(instance) == instance
+
+    def test_wrong_length_hex_raises_with_class_name(self) -> None:
+        """Hex with too many bytes raises a validation error tagged by the class name."""
+        # 2 hex bytes ("abcd") cannot fit a 1-byte container; trailing bytes trigger the error.
+        with pytest.raises(ValidationError, match="invalid OneByte hex"):
+            OneByte.model_validate("abcd")
+
+    def test_nested_container_field_accepts_hex_string(self) -> None:
+        """A nested container field accepts a hex string for its own SSZ encoding."""
+        # Fixture state:
+        #   inner.x (Uint64) = 1, inner.y (Uint64) = 2 -> 16 little-endian bytes
+        outer = OuterFixedNested.model_validate(
+            {
+                "z": Uint64(7),
+                "inner": "01000000000000000200000000000000",
+            }
+        )
+        assert outer == OuterFixedNested(z=Uint64(7), inner=InnerFixed(x=Uint64(1), y=Uint64(2)))